Deploy local JSON or YAML templates into AWS Emulator with a provisioning check before the task connects. The plugin rejects resource types that emulator 1.0.385 would merely record as successful without creating service resources.
Start With The Runnable Example
./gradlew -p examples/cloudformation validateCloudFormationTemplate
./gradlew -p examples/cloudformation integrationTest --configuration-cache
./gradlew -p examples/cloudformation integrationTest --configuration-cache
Validation runs locally without Docker. The integration example deploys an S3 bucket, SQS queue, and DynamoDB table, then writes and reads through their service APIs. Each managed run creates a fresh emulator and removes it after the participating tasks finish, including ordinary failures.
See the runnable example for persistent deployment, parameter updates, output consumption, and an intentionally rejected template.
Provision Before Tests
import io.github.gregwhitaker.awsemulator.aws.cloudformation.DeployCloudFormationStackTask
plugins {
java
id("io.github.gregwhitaker.aws-emulator") version "0.3.0"
}
val stack = tasks.register<DeployCloudFormationStackTask>("deployTestStack") {
stackName.set("application-tests")
templateFile.set(layout.projectDirectory.file("infra/test-stack.yaml"))
parameters.put("QueueName", "application-events")
tags.put("environment", "test")
}
val tests = tasks.named<Test>("test") {
dependsOn(stack)
inputs.file(stack.flatMap { it.outputsFile })
systemProperty("stack.outputs", stack.flatMap { it.outputsFile }.get().asFile.absolutePath)
}
awsEmulator { useWith(tests) }
For example, infra/test-stack.yaml can contain:
AWSTemplateFormatVersion: '2010-09-09'
Parameters:
QueueName:
Type: String
Resources:
Events:
Type: AWS::SQS::Queue
Properties:
QueueName: !Ref QueueName
Outputs:
QueueUrl:
Value: !Ref Events
The task waits for stack completion and writes a JSON object mapping output keys to values. This template produces {"QueueUrl":"https://…"}; read the file in your test or application. Output values are not printed. Files are replaced atomically where supported and use owner-only permissions on POSIX filesystems.
Groovy DSL uses the same task types and properties:
import io.github.gregwhitaker.awsemulator.aws.cloudformation.DeployCloudFormationStackTask
def stack = tasks.register('deployTestStack', DeployCloudFormationStackTask) {
stackName.set('application-tests')
templateFile.set(layout.projectDirectory.file('infra/test-stack.yaml'))
parameters.put('QueueName', 'application-events')
}
tasks.named('test') { dependsOn(stack) }
awsEmulator { useWith(tasks.named('test')) }
Provisioning Guard
The support catalogue is audited against AWS Emulator v1.0.385, commit 813af480bf7f16d5418b64e4f5644a74a7da11c5. It follows the upstream 221 exact native provisioning type names and source references. Nested stacks are excluded from deployment, leaving 220 accepted native types. See the release audit for the dispatch comparison and compatibility checks.
AWS::CDK::Metadata is also accepted as stack metadata, and AWS::CloudFormation::WaitCondition is accepted for the emulator’s signal-handling behavior. Neither represents a separate service resource. AWS::CloudFormation::WaitConditionHandle remains outside the accepted catalogue. Version 1.0.385 adds a signed signal-URL implementation, but this audit does not certify its URL reachability, expiry, or signal lifecycle for plugin consumers.
Supported native examples include AWS::S3::Bucket, AWS::SQS::Queue, AWS::SNS::Topic, AWS::DynamoDB::Table, AWS::IAM::Role, AWS::Lambda::Function, AWS::EC2::Instance, AWS::Logs::LogGroup, AWS::CloudWatch::Alarm, AWS::Cognito::UserPool, AWS::AppSync::GraphQLApi, AWS::ACMPCA::Permission, AWS::Redshift::SnapshotCopyGrant, and AWS::XRay::Group. A handler indicates that creation reaches service provisioning; it does not guarantee complete AWS property coverage or data-plane behavior.
| Template feature | Behavior |
|---|---|
Declaration-only or unknown type |
Rejected with its logical ID and exact type. For example: |
Conditional resources |
Every declaration is checked, including resources under false conditions. Parameter values cannot disable the guard. |
Transforms and macros |
Root |
Nested stacks |
|
Custom providers |
|
Ambiguous documents |
Duplicate keys, multiple YAML documents, anchors, aliases, merge keys, nonliteral types, and unsupported YAML tags are rejected. |
Different emulator version |
Deployment and offline validation reject any configured |
There is no option to disable the guard or add unchecked resource types. An available service API does not imply a working CloudFormation handler: for rejected types, use the plugin’s service-specific tasks where available.
The check validates resource support and document structure, not every CloudFormation property or intrinsic expression. The emulator performs the remaining template validation. Stack failures and rollbacks fail the deployment task; request acceptance alone is insufficient. The earlier 1.0.367 audit observed a failed update when renaming a Cognito user pool with dependent app clients/resource servers. The current lifecycle regression keeps the pool name stable; pool renaming remains uncertified. See the release audit for the tested scope.
Service readiness is checked independently of stack status. Use the service’s readiness waiter before item operations, as the runnable example does. Stack deletion can similarly finish before a table disappears.
For AppSync, the lifecycle regression verifies schema updates while keeping the API name stable. Renaming an API with dependent resources was observed to roll the stack back in 1.0.385; the plugin reports that failure and preserves the last successful outputs. Other AppSync property updates remain uncertified.
The selected runtime’s configured version determines the catalogue. For external emulators or a custom image, ensure the actual emulator is 1.0.385 too; the plugin cannot establish the remote binary version from that setting. Inspect templates locally with:
./gradlew validateCloudFormationTemplate --templateFile=infra/test-stack.yaml
Deployment always performs the same check itself before acquiring its connection or submitting a stack. A rejected template does not start that task’s emulator; other dependencies in the build may independently use Docker.
Tasks And Properties
All task classes are in io.github.gregwhitaker.awsemulator.aws.cloudformation.
| Task type | Properties and behavior |
|---|---|
|
|
|
|
|
|
|
Lists names and statuses across all result pages, excluding deleted stacks. |
Stack names begin with a letter and contain up to 128 letters, digits, or hyphens. Parameter names begin with a letter and contain letters or digits. Supply the desired parameter values on each deployment; omitted parameters use template defaults rather than an explicit UsePreviousValue request. Tags are sent as the complete set, with at most 50 entries. Capabilities accept only CAPABILITY_IAM and CAPABILITY_NAMED_IAM; set them explicitly when your template needs IAM acknowledgement.
Create/update/delete waits use waitTimeoutSeconds (default 120). Each SDK call uses apiCallTimeoutSeconds (default 30); a call already in progress can extend the overall wait. Timeouts fail the task and do not cancel the server operation. Busy, failed, or rolled-back stacks require inspection before retrying; the deploy task updates only CREATE_COMPLETE, UPDATE_COMPLETE, and UPDATE_ROLLBACK_COMPLETE stacks. Changing an existing template or parameters can replace resources.
templateFile may come from a generating task’s flatMap provider. It is read at execution, including on configuration-cache reuse. Input and output files must differ. Templates are submitted inline; remote TemplateURL inputs and change sets are not exposed.
Lifetimes And Spring Boot
Custom deployment, deletion, and listing tasks inherit awsEmulator.defaultMode, initially MANAGED. They use the existing mode, runtimeName, verified TLS, and credential handling. Tasks that access live stack state always execute, even if template inputs and output files are unchanged; build-cache reuse is disabled.
Register deployment tasks explicitly with a template and stack name, as above. The registered deleteCloudFormationStack and listCloudFormationStacks convenience tasks use DEVELOPMENT. To deploy the earlier task into the persistent runtime:
./gradlew deployTestStack --mode=DEVELOPMENT
./gradlew listCloudFormationStacks
./gradlew deleteCloudFormationStack --stackName=application-tests
./gradlew stopAwsEmulator
Set parameters and other advanced properties on the task in your build script. CLI options include --stackName, --templateFile, --mode, and --runtime where applicable. validateCloudFormationTemplate is always local and has no mode.
Deployment is marked as an emulator setup task, so it participates in resource sets and the Spring Boot companion’s automatic setup discovery. Managed cleanup removes the emulator after participating tasks finish; persistent and external runtimes retain their state until explicitly changed or stopped.