This chapter covers CloudFormation cfn-init and cfn-signal, two helper scripts that enable automated configuration and status reporting for EC2 instances during stack creation or update. Understanding these tools is critical for the DVA-C02 exam because they are central to creating reliable, self-configuring infrastructure. Approximately 5-8% of exam questions touch on CloudFormation helper scripts, often in the context of bootstrapping, rolling updates, and troubleshooting failed stacks.
Jump to a section
Imagine you're building a hotel with 200 rooms. You hire a general contractor (CloudFormation) to oversee the project. The contractor sends a foreman (cfn-init) to each room with a detailed checklist: install the bed, hang the curtains, connect the TV. The foreman works through the list step by step. Meanwhile, the contractor waits outside with a walkie-talkie (cfn-signal). The foreman must radio back "Room 101 complete" before the contractor moves on to the next phase. If the foreman doesn't call within the agreed time (say, 2 hours), the contractor assumes something went wrong and abandons the project, rolling back to the foundation. The foreman's checklist is the metadata in the CloudFormation template; the walkie-talkie is the cfn-signal call. The contractor doesn't check if the work is done correctly—it just waits for the signal. If the foreman calls too early, the contractor might proceed with unfinished rooms. This mirrors how CloudFormation uses cfn-init to configure EC2 instances and cfn-signal to report success, with a CreationPolicy or WaitCondition controlling the timeout and rollback behavior.
What Are cfn-init and cfn-signal?
cfn-init and cfn-signal are part of the CloudFormation helper scripts suite, which also includes cfn-hup, cfn-get-metadata, and cfn-elect-cmd-leader. These scripts are installed on Amazon Linux and Windows AMIs by default; on other operating systems, you must install them manually using the aws-cfn-bootstrap package.
cfn-init: A script that reads metadata from a CloudFormation stack and applies configuration steps (e.g., installing packages, writing files, starting services). It is typically run as part of the UserData of an EC2 instance.
cfn-signal: A script that sends a success or failure signal to CloudFormation, indicating that the instance has completed its configuration. This signal is used with a CreationPolicy or WaitCondition to control stack resource creation order and detect failures.
How They Work Internally
When CloudFormation creates a resource (e.g., an EC2 instance), it can wait for a signal before marking the resource as CREATE_COMPLETE. The workflow is:
CloudFormation sends a Create request to EC2 to launch an instance, with UserData containing the cfn-init and cfn-signal commands.
The instance boots and runs UserData, which executes cfn-init. cfn-init fetches metadata from the CloudFormation stack (via the instance's metadata endpoint or the cfn-get-metadata script). It processes the metadata in order: packages, groups, users, sources, files, commands, services.
After cfn-init completes successfully, the UserData runs cfn-signal, which calls the CloudFormation API (SignalResource) to report success.
CloudFormation receives the signal and waits for the number of expected signals (specified in CreationPolicy) before marking the resource as CREATE_COMPLETE. If the signal is not received within the timeout, CloudFormation marks the resource as CREATE_FAILED and initiates a rollback.
Key Components and Defaults
- CreationPolicy: Attached to a resource (e.g., EC2 instance, Auto Scaling group) to specify the number of success signals and the timeout. Example:
MyInstance:
Type: AWS::EC2::Instance
CreationPolicy:
ResourceSignal:
Count: 1
Timeout: PT10M- Count: Number of success signals required (default 1). For an Auto Scaling group, set Count to the desired capacity. - Timeout: ISO 8601 duration (e.g., PT10M = 10 minutes, PT1H = 1 hour). Default is 1 hour if not specified. - WaitCondition: An older alternative to CreationPolicy, still supported. It uses a separate WaitCondition resource and a WaitHandle to generate a pre-signed URL for signaling. Exam prefers CreationPolicy for EC2 instances and Auto Scaling groups. - cfn-signal command syntax:
/opt/aws/bin/cfn-signal -e 0 --stack <stack-name> --resource <logical-resource-id> --region <region> - -e 0: Exit code 0 indicates success; non-zero indicates failure.
- --resource: The logical ID of the resource (e.g., MyInstance).
- cfn-init command syntax:
/opt/aws/bin/cfn-init -v --stack <stack-name> --resource <logical-resource-id> --region <region> --configsets <config-set-name> - -v: Verbose output.
- --configsets: Optional, to specify a named set of config keys.
Metadata Configuration
The metadata for cfn-init is defined in the CloudFormation template under the resource's Metadata key. The structure is:
Metadata:
AWS::CloudFormation::Init:
config:
packages:
yum:
httpd: []
files:
"/var/www/html/index.html":
content: "Hello World"
mode: '000644'
commands:
test:
command: "echo $HOME"
services:
sysvinit:
httpd:
enabled: 'true'
ensureRunning: 'true'packages: Install packages via yum, rpm, apt, etc. For yum, list package names; empty brackets mean no version specified.
files: Write files with content, source (URL), or inline. Mode is in octal.
commands: Run arbitrary commands in order. Each command can have env, cwd, test (run only if test succeeds), ignoreErrors.
services: Manage system services (sysvinit, windows). enabled sets start on boot; ensureRunning starts/stops the service.
groups/users: Create local groups/users (not for domain).
sources: Download and extract archives (tar, zip) to a directory.
configSets: Group multiple config keys into a named set. cfn-init can then reference the configSet name instead of the default 'config'.
Interaction with CloudFormation Lifecycle
During stack creation, if an instance fails to signal within the timeout, CloudFormation rolls back the entire stack. The instance may still be running, but the stack is in ROLLBACK_COMPLETE state.
During stack update, if the instance's launch configuration or metadata changes, CloudFormation may replace the instance (if the property requires replacement). cfn-init runs again on the new instance. cfn-signal is used with an UpdatePolicy (e.g., AutoScalingRollingUpdate) to control the update process.
For Auto Scaling groups, the CreationPolicy must have Count equal to the desired capacity. Signals can come from any instance in the group; CloudFormation waits for exactly Count signals.
Verification Commands
To debug cfn-init:
Check /var/log/cfn-init.log for detailed output.
Check /var/log/cloud-init.log for overall UserData execution.
Run cfn-init manually with --region and --stack to see errors.
Use cfn-get-metadata to verify the metadata the instance sees.
Common Patterns
- Combined UserData:
#!/bin/bash
/opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource MyInstance --region ${AWS::Region}
/opt/aws/bin/cfn-signal -e 0 --stack ${AWS::StackName} --resource MyInstance --region ${AWS::Region}Conditional signaling: Use a script that checks the exit code of cfn-init and signals appropriately.
Multiple configSets: Useful for separating base configuration from application-specific config.
Important Defaults and Timers
cfn-init timeout: No built-in timeout; it runs until completion or failure.
cfn-signal timeout: Set via CreationPolicy; default 1 hour if omitted.
Number of signals: Default 1 for CreationPolicy.
Signal format: CloudFormation expects a JSON payload with Status (SUCCESS/FAILURE) and UniqueId (optional). cfn-signal sends this automatically.
Exam Relevance
The DVA-C02 exam tests your ability to:
Identify the correct syntax for cfn-init and cfn-signal in UserData.
Determine when to use CreationPolicy vs. WaitCondition.
Troubleshoot failed signals (e.g., timeout, wrong resource ID, missing permissions).
Understand that cfn-init runs on the instance, not in the CloudFormation service.
Recognize that cfn-signal must be called explicitly; CloudFormation does not automatically detect completion.
Define Metadata in Template
In your CloudFormation template, under the EC2 instance resource, add a Metadata key with AWS::CloudFormation::Init. Inside, define the config with packages, files, commands, and services. This metadata is stored in the stack and retrieved by cfn-init at runtime. For example, to install Apache and create a simple web page, you would specify the 'yum' package list and the 'files' section. The metadata can also include configSets to group multiple configurations.
Add CreationPolicy to Resource
Attach a CreationPolicy to the EC2 instance resource. This tells CloudFormation to wait for a signal before marking the resource as created. Specify Count (number of signals) and Timeout (ISO 8601 duration). For a single instance, Count is 1. Timeout should be long enough for the instance to boot and run cfn-init; a typical value is PT10M (10 minutes). If you omit CreationPolicy, CloudFormation will not wait and will mark the resource as CREATE_COMPLETE immediately after the instance is launched.
Write UserData to Run Scripts
In the instance's UserData property, write a script (bash or PowerShell) that calls cfn-init first, then cfn-signal. Use CloudFormation intrinsic functions like Ref and AWS::Region to pass stack and resource names. The script must include the full path to the helper scripts (e.g., /opt/aws/bin/cfn-init). If the script fails, cfn-signal should not be called, or should be called with a non-zero exit code to signal failure.
Instance Boots and Runs UserData
When CloudFormation launches the instance, the UserData script executes during boot. cfn-init connects to the CloudFormation API to fetch the metadata for the resource. It processes each section in order: packages, groups, users, sources, files, commands, services. If any step fails (e.g., package not found, command returns non-zero), cfn-init exits with an error. The script should check the exit code and only call cfn-signal on success.
cfn-signal Sends Status to CloudFormation
After cfn-init completes successfully, cfn-signal is called. It sends an HTTP request to the CloudFormation API endpoint, specifying the stack name, logical resource ID, region, and exit code. The API returns a success response. CloudFormation increments the signal count for that resource. Once the count equals the Count specified in CreationPolicy, CloudFormation marks the resource as CREATE_COMPLETE. If the timeout expires before receiving enough signals, CloudFormation marks the resource as CREATE_FAILED and starts stack rollback.
Enterprise Scenario 1: Web Application Auto Scaling Group
A company deploys a web application using an Auto Scaling group with a launch template. The CloudFormation template includes a CreationPolicy on the Auto Scaling group with Count equal to the desired capacity (e.g., 3). Each instance's UserData runs cfn-init to install Apache, PHP, and the application code from an S3 bucket. cfn-signal reports success. If one instance fails to bootstrap (e.g., S3 bucket access denied), the stack creation times out and rolls back, preventing a partial deployment. In production, the timeout is set to 15 minutes to account for variable boot times. Common misconfiguration: forgetting to set Count to the desired capacity; if Count is 1, CloudFormation proceeds after the first instance signals, leaving the other two instances unverified.
Enterprise Scenario 2: Database Server with Custom Configuration
A financial services company deploys an EC2 instance running Oracle Database. The CloudFormation template uses cfn-init to install Oracle software, apply configuration files, and start the listener. Because database setup can take 30 minutes, the CreationPolicy timeout is set to PT45M. The UserData script includes retry logic: if cfn-init fails, it logs the error and calls cfn-signal with exit code 1 to trigger a rollback. The operations team monitors cfn-init logs in CloudWatch (shipped by the CloudWatch agent) to detect failures. A common issue: the instance's IAM role lacks permissions to call cfn-signal (cloudformation:SignalResource), causing a silent timeout.
Enterprise Scenario 3: Blue/Green Deployment with Rolling Updates
A SaaS provider uses CloudFormation to manage a fleet of EC2 instances behind an Application Load Balancer. During stack updates, they use an UpdatePolicy with AutoScalingRollingUpdate. Each new instance runs cfn-init to apply updated configuration. cfn-signal is used with a WaitOnResourceSignals flag in the UpdatePolicy to ensure each new instance is healthy before the next one is terminated. The timeout per instance is set to 10 minutes. If an instance fails to signal, the update pauses and eventually rolls back. This pattern prevents downtime by ensuring only healthy instances serve traffic.
What DVA-C02 Tests
Objective 3.2: "Implement resource lifecycle management using AWS CloudFormation." The exam specifically tests:
Correct syntax for cfn-init and cfn-signal in UserData.
Understanding of CreationPolicy vs. WaitCondition.
How to set Count and Timeout for Auto Scaling groups.
Troubleshooting failed signals: common causes are wrong resource ID, missing IAM permissions, timeout too short, or cfn-init errors.
The fact that cfn-init processes metadata in a specific order: packages, groups, users, sources, files, commands, services.
Most Common Wrong Answers
"cfn-init sends the signal automatically." Wrong. cfn-init only applies configuration; cfn-signal must be called explicitly. Candidates often confuse the two.
"CreationPolicy is only for EC2 instances." Wrong. It works for any resource that supports signaling, including Auto Scaling groups and Lambda-backed custom resources.
"Timeout defaults to 5 minutes." Wrong. Default is 1 hour if not specified. The exam may test the ISO 8601 format (PT10M).
"WaitCondition is the only way to signal." Wrong. CreationPolicy is preferred for EC2 and ASG; WaitCondition is older but still valid.
Specific Numbers and Terms
The ISO 8601 duration format: PT#H#M (e.g., PT15M).
cfn-init log location: /var/log/cfn-init.log.
cfn-signal exit code: 0 for success, non-zero for failure.
Count default: 1.
Timeout default: 1 hour (3600 seconds).
The helper scripts are installed at /opt/aws/bin/ on Linux.
Edge Cases
If you omit CreationPolicy, CloudFormation does not wait for a signal; it marks the resource as CREATE_COMPLETE immediately after the instance is launched. This can lead to stacks that appear successful but have misconfigured instances.
If you set Count higher than the number of instances, CloudFormation will wait indefinitely until the timeout expires.
cfn-init can be run multiple times; the second run will overwrite files and reinstall packages.
cfn-signal can be called from a different instance than the one being configured (e.g., a separate test instance), but this is uncommon.
How to Eliminate Wrong Answers
If a question asks about signaling completion, look for the explicit call to cfn-signal. If the answer says "cfn-init sends a signal," it's wrong.
If the question involves Auto Scaling groups, the Count must match the desired capacity. Any answer with Count=1 for an ASG with desired=3 is wrong.
If the question mentions a timeout, check the format. ISO 8601 uses PT prefix; plain numbers like "10" are invalid.
If the question asks about the order of operations in cfn-init, remember: packages first, services last.
cfn-init applies configuration from Metadata; it does not signal CloudFormation.
cfn-signal must be called explicitly in UserData after cfn-init completes.
CreationPolicy with Count and Timeout controls how CloudFormation waits for signals.
Default timeout for CreationPolicy is 1 hour if not specified.
For Auto Scaling groups, set Count equal to desired capacity.
cfn-init processes metadata in order: packages, groups, users, sources, files, commands, services.
Logs for cfn-init are at /var/log/cfn-init.log.
The helper scripts are located at /opt/aws/bin/ on Linux.
If using a WaitCondition, the pre-signed URL is generated by the WaitHandle.
A non-zero exit code from cfn-signal causes CloudFormation to mark the resource as CREATE_FAILED.
These come up on the exam all the time. Here's how to tell them apart.
CreationPolicy
Attached directly to a resource (EC2, ASG).
Simpler syntax: just Count and Timeout.
No separate resource required.
Recommended for EC2 and Auto Scaling groups.
Signals are counted automatically via cfn-signal.
WaitCondition
Requires a WaitCondition resource and a WaitHandle.
More complex: generates a pre-signed URL.
Older pattern; still supported.
Can be used with any resource that supports signaling.
Signals are sent via HTTP PUT to the pre-signed URL.
Mistake
cfn-init automatically signals CloudFormation when it finishes.
Correct
cfn-init only applies configuration; it does not send any signal. You must explicitly call cfn-signal in UserData after cfn-init completes to notify CloudFormation of success or failure.
Mistake
CreationPolicy and WaitCondition are identical and interchangeable.
Correct
CreationPolicy is a simpler, preferred approach attached directly to a resource. WaitCondition requires a separate WaitCondition resource and a WaitHandle to generate a pre-signed URL. CreationPolicy is more modern and is the recommended pattern for EC2 and Auto Scaling groups.
Mistake
The default timeout for CreationPolicy is 10 minutes.
Correct
The default timeout is 1 hour (3600 seconds) if not specified. The exam often tests this value, and candidates mistakenly assume shorter timeouts.
Mistake
cfn-signal must be called from the same instance that ran cfn-init.
Correct
cfn-signal can be called from any machine that has the necessary permissions and knows the stack name, resource ID, and region. However, the common pattern is to call it from the same instance during bootstrapping.
Mistake
If cfn-init fails, CloudFormation automatically rolls back the stack.
Correct
CloudFormation only rolls back if the CreationPolicy timeout expires without receiving the expected number of success signals. If cfn-init fails but cfn-signal is still called with exit code 0 (due to a bug in UserData), CloudFormation will consider it a success. The UserData script must check the exit code of cfn-init and call cfn-signal with the appropriate exit code.
Reveal each answer, then mark whether you got it right. Score 60%+ to unlock the next chapter.
cfn-init reads metadata from the CloudFormation stack and applies configuration (install packages, write files, start services). cfn-signal sends a success or failure notification to CloudFormation, telling it that the instance has completed its bootstrapping. They work together: cfn-init configures, cfn-signal reports. Both are typically called in UserData.
You set the timeout in the CreationPolicy of the resource. Use the Timeout property with an ISO 8601 duration, e.g., PT15M for 15 minutes. If you omit Timeout, the default is 1 hour. The timeout starts when CloudFormation initiates the resource creation. If the signal is not received within the timeout, CloudFormation marks the resource as CREATE_FAILED and rolls back the stack.
CloudFormation will consider the resource creation successful because it received the expected number of success signals. However, the instance may be misconfigured. To avoid this, your UserData script should check the exit code of cfn-init and only call cfn-signal with exit code 0 if cfn-init succeeded. If cfn-init fails, call cfn-signal with a non-zero exit code (e.g., -e 1) to signal failure.
Yes. Attach a CreationPolicy to the Auto Scaling group resource. Set Count to the desired capacity of the group. Each instance in the group runs cfn-init and cfn-signal. CloudFormation waits for exactly Count signals before marking the group as CREATE_COMPLETE. During updates, you can use an UpdatePolicy with AutoScalingRollingUpdate and WaitOnResourceSignals to ensure each new instance is healthy before proceeding.
The instance must have an IAM role that allows the cloudformation:SignalResource action. The policy can be scoped to the specific stack. Without this permission, cfn-signal will fail, and CloudFormation will time out. The cfn-init script also needs permissions to call cloudformation:DescribeStackResource to fetch metadata.
First, check /var/log/cfn-init.log on the instance for errors. Second, verify that the UserData script is correct and that cfn-signal is being called with the correct stack name, resource ID, and region. Third, check the IAM role for the required permissions. Fourth, ensure the CreationPolicy timeout is long enough. Finally, check CloudTrail for SignalResource API calls to see if any signals were sent.
cfn-init processes metadata in the following order: packages, groups, users, sources, files, commands, services. This order is fixed. If you need to run a command after a service starts, you may need to use multiple configSets or a separate script. The exam may ask you to identify which step runs first or last.
You've just covered CloudFormation cfn-init and cfn-signal — now see how well it sticks with free DVA-C02 practice questions. Full explanations included, no account needed.
Done with this chapter?