Overcast is alpha — behaviour and APIs may change between releases. Pin your version and read the changelog before upgrading.

overcast

CloudFormation — AWS CloudFormation

Quick start, template and intrinsic coverage, the stack lifecycle and change sets, per-resource drift on update, and where an Overcast-prefixed status reason comes from.

Stacks, change sets and a provisioner that creates real resources by dispatching through the emulator’s own router — the entry point for CDK deploys.

Status: ⚠️ Partial

Quick start

export AWS_ENDPOINT_URL=http://localhost:4566

cat > bucket.yaml <<'YAML'
Resources:
  Data:
    Type: AWS::S3::Bucket
Outputs:
  Name: { Value: !Ref Data }
YAML

aws cloudformation create-stack --stack-name demo \
  --template-body file://bucket.yaml
aws cloudformation wait stack-create-complete --stack-name demo
aws cloudformation describe-stacks --stack-name demo --query 'Stacks[0].Outputs'

Any credentials work; with none configured, run eval "$(overcast env)" first — see Using AWS SDKs and CLI.

What works

AreaBehaviour
TemplatesJSON and YAML, including the short-form tags (!Ref, !Sub, !GetAtt). Both of AWS’s size quotas are enforced — 51,200 bytes inline, 1,000,000 via TemplateURL.
Resource types137 registered types — 128 provisioned for real, 9 recognised as deliberate stubs — plus custom resources and nested stacks. The list is in CDK resource type coverage.
ProvisioningResources are created through internal HTTP requests to the emulated services, so anything implemented can be orchestrated. DependsOn and reference ordering are resolved by topological sort.
Stack lifecycleThe full AWS status machine, including both cleanup states, and enforced transitions — a create is refused while the name exists, an update only from a last-known-stable state.
Change setsCreate, describe, execute and list. ExecuteChangeSet advances ExecutionStatus to EXECUTE_COMPLETE/EXECUTE_FAILED when the stack reaches a terminal status.
UpdatesPer-resource drift by hash of the resolved properties. Unchanged resources are skipped; changed ones are updated in place where the handler supports it, and replaced otherwise.
RollbackAutomatic on failure, plus RollbackStack and ContinueUpdateRollback (including ResourcesToSkip, with AWS’s nested Stack.Logical paths). An update rollback restores the template, parameters and tags as well as the resources.
Resources that waitTwelve types stabilise before completing — RDS instances and clusters, ECS services, three ElastiCache types, MSK, EKS, three EFS types and Lambda functions — so CREATE_COMPLETE means settled, not merely accepted.
Nested stacks and custom resourcesAWS::CloudFormation::Stack fetches and provisions the child synchronously; Custom::* invokes the Lambda named by ServiceToken and reads back PhysicalResourceId and Data.
Cross-stack referencesFn::ImportValue resolves exports from other active stacks in the same region, and ListExports and ListImports return the index; Fn::GetStackOutput reads any output of a stack in any region, exported or not — see Cross-stack references in CDK.

Intrinsics: Ref, Fn::Sub, Fn::Join, Fn::Select, Fn::GetAtt, Fn::If, Fn::Split, Fn::GetAZs, Fn::ImportValue, Fn::GetStackOutput, Fn::FindInMap, Fn::Base64, Fn::Cidr, Fn::Equals, Fn::Not, Fn::And, Fn::Or. Pseudo-parameters: AWS::Region, AWS::AccountId, AWS::StackId, AWS::StackName, AWS::URLSuffix, AWS::Partition, AWS::NotificationARNs, AWS::NoValue.

Differences from AWS

AreaOn AWSOvercast
AWS::NoValueRemoves the propertySubstitutes the empty string
{{resolve:s3:...}}ResolvedNot resolved; fails the resource
SSM dynamic-reference versionsVersion-selectedAn explicit version resolves to the current value, with a warning
Unknown resource typesRejectedAccepted with a synthetic stub ID, a warning, and an Overcast:-prefixed ResourceStatusReason
DeleteStack’s RetainResourcesSupportedNot implemented
DeletionPolicy: SnapshotSnapshotsTreated as Retain; no snapshot is taken
Drift detection, StackSets, stack policies, importsSupportedNot implemented
Fn::GetStackOutput where AWS does not yet allow itInternalFailure as a direct output value or inside Fn::Sub variables, Fn::Base64, Fn::Equals, Fn::ImportValueResolved wherever it appears
Fn::GetStackOutput with a RoleArnAssumes the role to read another account’s stackShape-checked only; the one emulated account is read

The full list is in Limitations, with the status machine and the waits. Behind it: stack updates, teardown and dynamic references.

Gotchas

Important

A stack can reach CREATE_COMPLETE while parts of it do nothing — an unregistered type, a deliberate no-op handler, or a real resource whose owning service is registered at inert or stub tier. Each says so in its ResourceStatusReason, prefixed Overcast:, on the event a cdk deploy is already polling. The console colours those as notices and badges the stack “N of M stub or inert”.

A stack that fails outright leaves a separate trail.

Tip

When a deploy fails, the rollback destroys the evidence. Overcast reads it first — GET /_overcast/cloudformation/stacks/{stackName}/diagnostics returns the CloudFormation reason plus what the failing resource’s own service knew, each pane tagged with where it came from. AWS::ECS::Service is the resource type covered today; a healthy stack answers 404.

Operations

25 of 53 listed operations are implemented. Per-operation status, notes and AWS API links: CloudFormation operations.