AWS CloudFormation
User Guide (API Version 2010-05-15)
Did this page help you?  Yes | No |  Tell us about it...
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.

cfn-init

Description

The cfn-init helper script reads template metadata from the AWS::CloudFormation::Init key and acts accordingly to:

  • Fetch and parse metadata from CloudFormation

  • Install packages

  • Write files to disk

  • Enable/disable and start/stop services

Note

If you use cfn-init to update an existing file, it creates a backup copy of the original file in the same directory with a .bak extension. For example, if you update /path/to/file_name, the action produces two files: /path/to/file_name.bak contains the original file's contents and /path/to/file_name contains the updated contents.

For information about the template metadata, see AWS::CloudFormation::Init.

Note

cfn-init does not require credentials, so you do not need to use the --access-key, --secret-key, --role, or --credential-file options.

Syntax

cfn-init --stack|-s stack.name.or.id \
         --resource|-r logical.resource.id \
         --region region
         --access-key access.key \
         --secret-key secret.key \
         --role rolename\
         --credential-file|-f credential.file \
         --configsets|-c config.sets \
         --url|-u service.url \
         -v

Options

NameDescriptionRequired

-s, --stack

Name of the Stack.

Type: String

Default: None

Example: -s { "Ref" : "AWS::StackName" },

Yes

-r, --resource

The logical resource ID of the resource that contains the metadata.

Type: String

Example: -r WebServerHost

Yes

--region

The AWS CloudFormation regional endpoint to use.

Type: String

Default: None

Example: --region ", { "Ref" : "AWS::Region" },

No

--access-key

AWS access key for an account with permission to call DescribeStackResource on CloudFormation. The credential file parameter supersedes this parameter.

Type: String

No

--secret-key

AWS secret access key that corresponds to the specified AWS access key.

Type: String

No

--role

The name of an IAM role that is associated with the instance.

Type: String

Condition: The credential file parameter supersedes this parameter.

No

-f, --credential-file

A file that contains both a secret access key and an access key. The credential file parameter supersedes the --role, --access-key, and --secret-key parameters.

Type: String

No

-c, --configsets

A comma-separated list of configsets to run (in order).

Type: String

Default: default

No

-u, --url

The AWS CloudFormation endpoint to use.

Type: String

No

-v

Verbose output. This is useful for debugging cases where cfn-init is failing to initialize.

Note

To debug initialization events, you should turn DisableRollback on. You can do this by using the CloudFormation console, selecting Show Advanced Options, and then setting "Rollback on failure" to "No". You can then SSH into the console and read the logs at /var/log/cfn-init.log.

No

Examples

The following snippet is associated with a resource named WebServer.

"/opt/aws/bin/cfn-init -s ", { "Ref" : "AWS::StackName" },
"    -r WebServer ",
"    --region ", { "Ref" : "AWS::Region" }, "\n",

Several AWS CloudFormation sample templates use cfn-init, including the following templates.