cfn-init - AWS CloudFormation (original) (raw)

In a CloudFormation template, you can use AWS::CloudFormation::Init within theMetadata section of an Amazon EC2 resource to define initialization tasks. For more information, see AWS::CloudFormation::Init in the AWS CloudFormation User Guide.

The cfn-init helper script reads template metadata from theAWS::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

The cfn-init helper script is typically run from an Amazon EC2 instance's or launch template's user data.

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.

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 \
         --http-proxy HTTP.proxy \
         --https-proxy HTTPS.proxy \
         --verbose|-v

Note

cfn-init doesn't require credentials, so you don't need to use the--access-key, --secret-key, --role, or--credential-file options. However, if no credentials are specified, CloudFormation checks for stack membership and limits the scope of the call to the stack that the instance belongs to. For more information, see Permissions for helper scripts.

Options

Name	Description	Required
-s, --stack	Stack name or stack ID. Type: String Default: None Example: --stack { "Ref" : "AWS::StackName" },	Yes
-r, --resource	The logical resource ID of the resource that contains the metadata. Type: String Example: --resource WebServerHost	Yes
--region	The CloudFormation regional endpoint to use. Type: String Default: us-east-1 Example:--region ", { "Ref" : "AWS::Region" },	No
--access-key	AWS access key for an account with permission to callDescribeStackResource 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's 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 CloudFormation endpoint to use. Type: String	No
--http-proxy	An HTTP proxy (non-SSL). Use the following format:http://user:password@host:port Type: String	No
--https-proxy	An HTTPS proxy. Use the following format:https://user:password@host:port Type: String	No
-v, --verbose	Verbose output. This is useful for debugging cases wherecfn-init is failing to initialize. NoteTo debug initialization events, you should turnDisableRollback on. You can then SSH into the console and read the logs at /var/log/cfn-init.log. For more information, see Choose how to handle failures when provisioning resources in the_AWS CloudFormation User Guide_.	No
-h, --help	Shows the help message and exits.	No

Examples

Amazon Linux examples

The following examples show the UserData property of an EC2 instance, which runs the InstallAndRun configset that's associated with theWebServerInstance resource.

To include the latest version, add yum install -y aws-cfn-bootstrap to the UserData.

JSON

UserData property using the Fn::Join intrinsic function.

{
    "UserData": {
        "Fn::Base64": {
            "Fn::Join": [
                "",
                [
                    "#!/bin/bash -xe\n",
                    "",
                    "yum install -y aws-cfn-bootstrap",
                    "/opt/aws/bin/cfn-init -v ",
                    "         --stack ",
                    {
                        "Ref": "AWS::StackName"
                    },
                    "         --resource WebServerInstance ",
                    "         --configsets InstallAndRun ",
                    "         --region ",
                    {
                        "Ref": "AWS::Region"
                    },
                    "\n"
                ]
            ]
        }
    }
}

YAML

UserData property using the Fn::Join intrinsic function.

UserData: !Base64 
  'Fn::Join':
    - ''
    - - |
        #!/bin/bash -xe
      - ''
      - yum install -y aws-cfn-bootstrap
      - '/opt/aws/bin/cfn-init -v '
      - '         --stack '
      - !Ref 'AWS::StackName'
      - '         --resource WebServerInstance '
      - '         --configsets InstallAndRun '
      - '         --region '
      - !Ref 'AWS::Region'
      - |+

JSON

UserData property using the Fn::Sub intrinsic function.

{
    "UserData": {
        "Fn::Base64": {
            "Fn::Sub": [
                "#!/bin/bash -x\n# Install the files and packages from the metadata\n/opt/aws/bin/cfn-init -v --stack <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mrow><mi>A</mi><mi>W</mi><mi>S</mi><mo>:</mo><mo>:</mo><mi>S</mi><mi>t</mi><mi>a</mi><mi>c</mi><mi>k</mi><mi>N</mi><mi>a</mi><mi>m</mi><mi>e</mi></mrow><mo>−</mo><mo>−</mo><mi>r</mi><mi>e</mi><mi>s</mi><mi>o</mi><mi>u</mi><mi>r</mi><mi>c</mi><mi>e</mi><mi>M</mi><mi>y</mi><mi>I</mi><mi>n</mi><mi>s</mi><mi>t</mi><mi>a</mi><mi>n</mi><mi>c</mi><mi>e</mi><mo>−</mo><mo>−</mo><mi>r</mi><mi>e</mi><mi>g</mi><mi>i</mi><mi>o</mi><mi>n</mi></mrow><annotation encoding="application/x-tex">{AWS::StackName} --resource MyInstance --region </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mord"><span class="mord mathnormal">A</span><span class="mord mathnormal" style="margin-right:0.13889em;">W</span><span class="mord mathnormal" style="margin-right:0.05764em;">S</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">::</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mord mathnormal">St</span><span class="mord mathnormal">a</span><span class="mord mathnormal">c</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span><span class="mord mathnormal" style="margin-right:0.10903em;">N</span><span class="mord mathnormal">am</span><span class="mord mathnormal">e</span></span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.8778em;vertical-align:-0.1944em;"></span><span class="mord">−</span><span class="mord mathnormal">reso</span><span class="mord mathnormal">u</span><span class="mord mathnormal">rce</span><span class="mord mathnormal" style="margin-right:0.10903em;">M</span><span class="mord mathnormal" style="margin-right:0.03588em;">y</span><span class="mord mathnormal" style="margin-right:0.07847em;">I</span><span class="mord mathnormal">n</span><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">an</span><span class="mord mathnormal">ce</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.854em;vertical-align:-0.1944em;"></span><span class="mord">−</span><span class="mord mathnormal">re</span><span class="mord mathnormal" style="margin-right:0.03588em;">g</span><span class="mord mathnormal">i</span><span class="mord mathnormal">o</span><span class="mord mathnormal">n</span></span></span></span>{AWS::Region}\n\n# Signal the status from cfn-init\n/opt/aws/bin/cfn-signal -e <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo stretchy="false">?</mo><mo>−</mo><mo>−</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>c</mi><mi>k</mi></mrow><annotation encoding="application/x-tex">? --stack </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mclose">?</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mord">−</span><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">c</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span></span></span></span>{AWS::StackName} --resource MyInstance --region ${AWS::Region}\n",
                {}
            ]
        }
    }
}

YAML

UserData property using the Fn::Sub intrinsic function.

UserData: !Base64 
  'Fn::Sub':
    - >
      #!/bin/bash -x

      # Install the files and packages from the metadata

      /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource MyInstance
      --region ${AWS::Region}


      # Signal the status from cfn-init

      /opt/aws/bin/cfn-signal -e <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mo stretchy="false">?</mo><mo>−</mo><mo>−</mo><mi>s</mi><mi>t</mi><mi>a</mi><mi>c</mi><mi>k</mi></mrow><annotation encoding="application/x-tex">? --stack </annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mclose">?</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:0.7778em;vertical-align:-0.0833em;"></span><span class="mord">−</span><span class="mord mathnormal">s</span><span class="mord mathnormal">t</span><span class="mord mathnormal">a</span><span class="mord mathnormal">c</span><span class="mord mathnormal" style="margin-right:0.03148em;">k</span></span></span></span>{AWS::StackName} --resource
      MyInstance --region ${AWS::Region}
    - {}

You can also visit our GitHub repository to download sample templates that use cfn-init, including the following templates.

For Windows templates, see Working with Microsoft Windows stack templates in the AWS CloudFormation User Guide.