Study guide

Technical reference and lesson notes

AWS CloudFormation Helper Scripts: cfn-init and cfn-signal

Purpose of This Lesson

This lesson explains how the CloudFormation helper scripts cfn-init and cfn-signal support EC2 instance configuration during stack creation or update. The key workflow is to use cfn-init to install and configure software from CloudFormation metadata, then use cfn-signal to tell CloudFormation whether the instance is ready.

Key Concepts

`cfn-init`

cfn-init reads configuration from the AWS::CloudFormation::Init metadata key associated with an EC2 instance. It can perform several configuration tasks:

Fetch and process CloudFormation metadata
Install packages
Write files to disk
Enable or disable services
Start or stop services

The cfn-init log is written to:

/var/log/cfn-init.log

A template commonly combines EC2 UserData with the AWS::CloudFormation::Init metadata section. User data invokes cfn-init, while the metadata describes the files, packages, and service actions to perform.

`cfn-signal`

cfn-signal sends a status signal to CloudFormation indicating whether an instance has been successfully created or updated. It is typically run after software installation and service configuration finish.

The signal commonly reports success or failure using the command’s exit status. A success signal should be sent only after the required applications and services are configured and started successfully.

Readiness controls

cfn-signal is used with CloudFormation readiness controls, including:

A CloudFormation CreationPolicy
An Auto Scaling group using resource signals and an appropriate update policy

These controls allow CloudFormation to wait for the required signal before treating the resource or deployment step as ready. This helps prevent an incompletely configured application from entering production.

EC2 Configuration Workflow with CloudFormation Helper Scripts

A typical deployment sequence is:

CloudFormation launches or updates the EC2 instance.
User data runs during instance initialization.
User data invokes cfn-init.
cfn-init reads the instance’s AWS::CloudFormation::Init metadata.
Packages are installed, files are written, and services are enabled or started as specified.
User data invokes cfn-signal after configuration completes.
CloudFormation uses the signal and its configured readiness policy to determine whether the instance or deployment can proceed.

The important distinction is that cfn-init performs configuration, whereas cfn-signal reports the outcome of configuration.

Exam- or Assessment-Relevant Takeaways

Choose cfn-init when the task is to install packages, create files, or manage services based on CloudFormation metadata.
Choose cfn-signal when CloudFormation must be told whether instance setup completed successfully.
cfn-init is normally invoked from EC2 user data and reads the AWS::CloudFormation::Init metadata.
cfn-signal should run after the application has been installed and services have been configured and started.
Resource signals work with a CreationPolicy; Auto Scaling deployments can also use signals with an update policy.
If helper-script behavior fails, verify that the AMI includes the CloudFormation helper scripts and that both commands actually ran successfully.
Use /var/log/cfn-init.log when investigating cfn-init configuration problems.

Tool / Feature Decision Guide

Requirement	Appropriate feature	Reason
Install packages during instance provisioning	`cfn-init`	It processes CloudFormation metadata and installs packages.
Create or modify configuration files	`cfn-init`	It writes files specified in the initialization metadata.
Enable, disable, start, or stop services	`cfn-init`	Service state is one of its configuration responsibilities.
Tell CloudFormation that setup succeeded or failed	`cfn-signal`	It sends the instance’s configuration status to CloudFormation.
Prevent a resource from being considered ready before initialization finishes	`cfn-signal` with a suitable readiness policy	CloudFormation can wait for the required resource signal.
Investigate initialization activity	`/var/log/cfn-init.log`	This is the specified log location for `cfn-init`.

Common Traps / Misconceptions

Confusing configuration with status reporting: cfn-init performs the setup; it does not replace the readiness signal. cfn-signal reports whether setup completed.
Signaling too early: Calling cfn-signal before packages are installed and services are started can report readiness for an instance that is not actually usable.
Assuming every AMI has the scripts: The AMI must include the CloudFormation helper scripts. Their absence can cause user data commands to fail.
Ignoring command results: A script appearing in user data does not prove it executed successfully. Check command results and logs.
Looking in the wrong log: For cfn-init troubleshooting, begin with /var/log/cfn-init.log.
Omitting the readiness policy: A signal is useful when CloudFormation is configured to use it through a creation policy or the relevant Auto Scaling deployment configuration.

Real-World Engineer / Analyst Notes

Keep the responsibilities visibly separate in templates: place initialization logic in AWS::CloudFormation::Init, invoke it from user data, and send the readiness signal only after the required setup steps succeed.

When troubleshooting, work from the instance outward. First confirm that the AMI contains the helper scripts, then verify that user data invoked the expected commands, inspect /var/log/cfn-init.log, and confirm that the signal command returned the intended status. A successful instance launch alone does not prove that the application is configured and ready.

Quick Reference Summary

cfn-init: Reads AWS::CloudFormation::Init metadata and configures the EC2 instance.
Capabilities: Installs packages, writes files, and manages service state.
Log: /var/log/cfn-init.log
cfn-signal: Reports successful or unsuccessful instance configuration to CloudFormation.
Correct order: Run cfn-init, verify configuration and service startup, then run cfn-signal.
Readiness integration: Use with a CreationPolicy or relevant Auto Scaling resource-signal/update configuration.
Troubleshooting: Confirm helper scripts exist in the AMI and both commands executed successfully.

Flashcards

Q: An EC2 instance must install packages and start services from configuration stored in a CloudFormation template. Which helper script should user data invoke?

A: Use cfn-init. It reads the instance’s AWS::CloudFormation::Init metadata and can install packages and manage services.

Q: What is the primary role of cfn-signal in an EC2 CloudFormation deployment?

A: It reports whether instance creation or update completed successfully, allowing CloudFormation to evaluate readiness.

Q: When should cfn-signal run relative to cfn-init?

A: It should run after cfn-init has completed the required installation and configuration and the services have started successfully.

Q: A stack must wait until an EC2 application is ready before considering resource creation successful. Which two elements are involved?

A: The instance sends a cfn-signal, and CloudFormation uses a suitable readiness policy such as a CreationPolicy to wait for that signal.

Q: What is the difference between EC2 user data and AWS::CloudFormation::Init metadata in this workflow?

A: User data invokes the helper script, while AWS::CloudFormation::Init contains the configuration that cfn-init processes.

Q: Where should you look first for cfn-init activity and errors?

A: Check /var/log/cfn-init.log.

Q: An initialization script contains cfn-init, but the command is not found on the instance. What should you verify first?

A: Verify that the AMI includes the CloudFormation helper scripts. Their presence is required for the command to run.

Q: Which helper script writes files and manages whether services are enabled, disabled, started, or stopped?

A: cfn-init performs those configuration actions from CloudFormation metadata.

Q: Why is a success signal sent only after services start successfully?

A: The signal tells CloudFormation that the instance is ready; sending it earlier can allow an incompletely configured application to proceed.

Q: An Auto Scaling group launches instances and must use instance readiness signals during deployment. What capability should be incorporated?

A: Use cfn-signal with the Auto Scaling resource-signal and update-policy configuration so CloudFormation can use instance signals during the deployment.

Q: Does cfn-init itself tell CloudFormation that an instance is ready?

A: No. cfn-init performs setup. cfn-signal is the helper used to report the setup result.

Q: What two execution checks are important when helper-script provisioning fails?

A: Confirm that cfn-init and cfn-signal actually ran successfully, and inspect the initialization log for configuration errors.

Practice Questions

Question 1

A CloudFormation-launched EC2 instance must install application packages, write configuration files, and start a service based on template-defined settings. Which approach is most appropriate?

A. Invoke cfn-signal from user data and place the settings in the signal command

B. Invoke cfn-init from user data and define the setup in AWS::CloudFormation::Init metadata

C. Use only a CreationPolicy without running an instance command

D. Write the setup only to /var/log/cfn-init.log

Correct answer: B

cfn-init processes AWS::CloudFormation::Init metadata and performs package, file, and service configuration.

Question 2

An instance finishes installing its application, but CloudFormation continues waiting for the resource to become ready. The template expects an instance readiness signal. What is the most likely missing step?

A. The instance must write another file using cfn-init

B. User data must invoke cfn-signal after successful configuration

C. The AMI must be replaced with an Auto Scaling group

D. The cfn-init log must be copied to CloudFormation

Correct answer: B

CloudFormation is waiting for the status report. cfn-signal must be run after installation and service startup, with the readiness policy configured to use the signal.

Question 3

A deployment reports that the application is ready, but the service has not actually started because the success signal was sent immediately after package installation. What is the correct improvement?

A. Send cfn-signal before installing packages

B. Replace cfn-init with a creation policy

C. Move cfn-signal until after service configuration and successful startup

D. Remove all CloudFormation metadata

Correct answer: C

The signal should represent application readiness, so it must be sent only after the required configuration and service startup succeed.

Question 4

A user data script fails when it attempts to run both CloudFormation helper commands. Which initial troubleshooting sequence is best supported by the lesson?

A. Check the AMI for the helper scripts, verify command execution, and inspect /var/log/cfn-init.log

B. Delete the CloudFormation stack immediately and recreate it without metadata

C. Replace cfn-signal with a package manager command

D. Inspect only the application load balancer health check

Correct answer: A

The first checks are whether the AMI includes the scripts, whether cfn-init and cfn-signal ran successfully, and what the cfn-init log reports.

WordPress Metadata

Suggested Slug:
aws-cloudformation-helper-scripts-cfn-init-cfn-signal

Meta Description:
Study how AWS CloudFormation cfn-init and cfn-signal configure EC2 instances, report readiness, and support reliable stack and Auto Scaling deployments.

Tags:
AWS CloudFormation, cfn-init, cfn-signal, EC2, User Data, CloudFormation Metadata, CreationPolicy, UpdatePolicy, Auto Scaling Groups, AWS Certified CloudOps Engineer