CloudFormation Lifecycle and Custom Resources

What it is

Creating an EC2 instance is quick, but configuring the software on it takes longer. By default CloudFormation marks the instance complete as soon as the API call succeeds, long before your application works.

This page covers the features that manage the full lifecycle: waiting for real readiness, configuring instances, rolling updates of fleets, protecting resources from updates, and extending CloudFormation with your own code.

How it works

Helper scripts and signals

The helper scripts are installed by the aws-cfn-bootstrap package. cfn-init reads the AWS::CloudFormation::Init metadata and configures the instance.

cfn-signal reports success or failure to CloudFormation, and cfn-hup watches for metadata changes and reapplies them on stack updates.

A creation policy makes CloudFormation wait for the signals before it marks the resource complete. If the count is not reached before the timeout, the resource fails and the stack rolls back.

WebServer:
  Type: AWS::EC2::Instance
  CreationPolicy:
    ResourceSignal:
      Count: 1
      Timeout: PT10M
  Metadata:
    AWS::CloudFormation::Init:
      config:
        packages:
          yum:
            httpd: []
        services:
          sysvinit:
            httpd:
              enabled: true
              ensureRunning: true
  Properties:
    ImageId: !Ref LatestAmi
    InstanceType: t3.micro
    UserData:
      Fn::Base64: !Sub |
        #!/bin/bash
        /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource WebServer --region ${AWS::Region}
        /opt/aws/bin/cfn-signal -e $? --stack ${AWS::StackName} --resource WebServer --region ${AWS::Region}

Timeout uses ISO 8601 duration format, so PT10M is ten minutes. A wait condition with a wait handle does the same job for signals that come from outside a single resource.

Update policies for fleets

An UpdatePolicy on an Auto Scaling group controls how instances are replaced when the launch template changes.

UpdatePolicy:
  AutoScalingRollingUpdate:
    MinInstancesInService: 2
    MaxBatchSize: 1
    PauseTime: PT5M
    WaitOnResourceSignals: true

With WaitOnResourceSignals set, each new batch must signal success, so a bad launch template stops the roll and triggers a rollback.

Protecting resources during updates

A stack policy is a JSON document that restricts which resources an update may touch. Once a policy is set, any action not explicitly allowed is denied.

{
  "Statement": [
    {"Effect": "Allow", "Action": "Update:*", "Principal": "*", "Resource": "*"},
    {"Effect": "Deny", "Action": ["Update:Replace", "Update:Delete"],
     "Principal": "*", "Resource": "LogicalResourceId/ProdDatabase"}
  ]
}

A stack policy is a guard against accidental updates, not an access control list for users. IAM controls who can run the update at all.

Custom resources

A custom resource lets a template call your own logic, for example to look up a value, call a third party API or clean out a bucket before deletion. The usual form is Lambda backed.

LookupAmi:
  Type: Custom::AmiLookup
  Properties:
    ServiceToken: !GetAtt LookupFunction.Arn
    Region: !Ref AWS::Region

CloudFormation invokes the function with a request type of Create, Update or Delete, plus a pre signed S3 ResponseURL. The function must send a JSON response with a status of SUCCESS or FAILED to that URL, and may return data that the template reads with !GetAtt.

If the function never responds, the stack waits until the timeout and then fails. Always handle the Delete request, even if it does nothing, and wrap the logic so an exception still sends a response.

Macros, hooks and the registry

Macros transform the template before processing, and modules package reusable resource groups. CloudFormation Hooks check resources before they are created or changed and can fail the operation, which supports compliance checks.

Alarm based rollback and debugging

A rollback configuration attaches CloudWatch alarms to a stack operation, with an optional monitoring time after it finishes. If an alarm enters the ALARM state in that window, CloudFormation rolls the update back.

To debug, set the stack to keep failed resources instead of rolling them back. The CLI option --disable-rollback on create does this, and the instance logs /var/log/cfn-init.log and /var/log/cloud-init-output.log show why a signal never arrived.