这是新的《Amazon CloudFormation 模板参考指南》**。请更新您的书签和链接。有关开始使用 CloudFormation 的帮助，请参阅《Amazon CloudFormation 用户指南》[https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/Welcome.html](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/Welcome.html)。

# cfn-init
<a name="cfn-init"></a>

在 CloudFormation 模板中，您可以在 Amazon EC2 资源的 `Metadata` 部分中使用 `AWS::CloudFormation::Init` 来定义初始化任务。有关更多信息，请参阅 [`AWS::CloudFormation::Init`](aws-resource-init.md)。

`cfn-init` 帮助程序脚本会读取来自 `AWS::CloudFormation::Init` 键的模板元数据并进行相应操作：
+ 提取和解析来自 CloudFormation 的元数据
+ 安装软件包
+ 将文件写入磁盘
+ 启用/禁用以及启动/停止服务

`cfn-init` 帮助程序脚本通常通过 Amazon EC2 实例或启动模板的用户数据运行。

如果您不熟悉如何使用帮助程序脚本，建议您先完成《Amazon CloudFormation 用户指南》**中的[在 Amazon EC2 上部署应用程序](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/deploying.applications.html)教程。

**Topics**
+ [语法](#cfn-init-Syntax)
+ [选项](#cfn-init-options)
+ [示例](#cfn-init-examples)
+ [相关资源](#cfn-init-related-resources)

**注意**  
如果您使用 `cfn-init` 来更新现有文件，则它将在同一目录下为原始文件创建一个扩展名为 .bak 的备份副本。例如，如果更新 `/path/to/file_name`，则操作生成两个文件：`/path/to/file_name.bak` 包含原始文件的内容，而 `/path/to/file_name` 包含更新的内容。

## 语法
<a name="cfn-init-Syntax"></a>

```
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
```

**注意**  
`cfn-init` 不需要凭证，因此您不需要使用 `--access-key`、`--secret-key`、`--role` 或 `--credential-file` 选项。但是，如果不指定证书，则 CloudFormation 会检查堆栈成员并将调用范围限制为实例所属的堆栈。有关更多信息，请参阅 [帮助程序脚本的权限](cfn-helper-scripts-reference.md#cfn-helper-scripts-reference-permissions)。

## 选项
<a name="cfn-init-options"></a>


| 名称 | 描述 | 必填 | 
| --- | --- | --- | 
|   `-s, --stack`   |  堆栈名称或堆栈 ID。 *类型*：字符串 *默认值*：无 *示例*：`--stack { "Ref" : "AWS::StackName" },`  |  是  | 
|   `-r, --resource `   |  包含元数据的资源的逻辑资源 ID。 *类型*：字符串 *示例*：`--resource WebServerHost`  |  是  | 
|   `--region`   |  要使用的 CloudFormation 区域端点。 *类型*：字符串 *默认值*：`us-east-1` *示例*：`--region ", { "Ref" : "AWS::Region" },`  |  否  | 
|   `--access-key`   |  针对有权在 CloudFormation 上调用 `DescribeStackResource` 的账户的 Amazon 访问密钥。凭证文件参数取代该参数。 *类型*：字符串  |  否  | 
|   `--secret-key`   |  对应于指定的 Amazon 访问密钥的 Amazon 秘密访问密钥。 *类型*：字符串  |  否  | 
|   `--role`   |  与实例关联的 IAM 角色的名称。 *类型*：字符串 条件：凭证文件参数替代该参数。  |  否  | 
|   `-f, --credential-file`   |  同时包含秘密访问密钥和访问密钥的文件。凭证文件参数取代 --role、--access-key 和 --secret-key 参数。 *类型*：字符串  |  否  | 
|   `-c, --configsets`   |  待运行逗号分隔 configsets 列表 (按顺序)。 *类型*：字符串 *默认值*：`default`  |  否  | 
|   `-u, --url`   |  要使用的 CloudFormation 端点。 *类型*：字符串  |  否  | 
|  `--http-proxy`  |  HTTP 代理 (非 SSL)。采用以下格式：`http://user:password@host:port` *类型*：字符串  |  否  | 
|  `--https-proxy`  |  HTTPS 代理。采用以下格式：`https://user:password@host:port` *类型*：字符串  |  否  | 
|  `-v, --verbose`  |  详细的输出。这对于调试 `cfn-init` 无法初始化的用例非常有用。  您应该打开 `DisableRollback`，以便调试初始化操作。随后您可以将 SSH 置于控制台中，读取 `/var/log/cfn-init.log` 上的日志。有关更多信息，请参阅《Amazon CloudFormation 用户指南》**中的[选择预置资源时如何处理故障](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/stack-failure-options.html)。   |  否  | 
| `-h, --help` | 显示帮助消息并退出。 |  否 | 

## 示例
<a name="cfn-init-examples"></a>

### Amazon Linux 示例
<a name="w2aac32c27c21b3"></a>

以下示例显示 EC2 实例的 `UserData` 属性，该实例运行与 `WebServerInstance` 资源关联的 `InstallAndRun` 配置集。

要包含最新版本，请将 `yum install -y aws-cfn-bootstrap` 添加到 `UserData`。

#### JSON
<a name="cfn-init-example.json"></a>

`UserData` 属性使用 `Fn::Join` 内置函数。

```
{
    "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
<a name="cfn-init-example.yaml"></a>

`UserData` 属性使用 `Fn::Sub` 内部函数。

```
UserData:
  Fn::Base64: !Sub |
    #!/bin/bash -xe
    yum update -y aws-cfn-bootstrap
    # Install the files and packages from the metadata
    /opt/aws/bin/cfn-init -v --stack ${AWS::StackName} --resource WebServerInstance --configsets InstallAndRun --region ${AWS::Region}
```

## 相关资源
<a name="cfn-init-related-resources"></a>

如需查看带有示例模板的教程，请参阅《Amazon CloudFormation 用户指南》**中的[在 Amazon EC2 上部署应用程序](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/deploying.applications.html)。

**如需查看 Windows 示例，请参阅《Amazon CloudFormation 用户指南》中[引导基于 Windows 的 CloudFormation 堆栈](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/cfn-windows-stacks-bootstrapping.html)。

您也可以访问我们的 GitHub 存储库下载使用 `cfn-init` 的[示例模板](https://docs.amazonaws.cn/AWSCloudFormation/latest/UserGuide/template-guide.html#sample-templates)，包括以下模板。
+  [InstanceWithCfnInit.yaml](https://github.com/aws-cloudformation/aws-cloudformation-templates/blob/main/EC2/InstanceWithCfnInit.yaml) 
+  [AutoScalingRollingUpdates.yaml](https://github.com/aws-cloudformation/aws-cloudformation-templates/blob/main/AutoScaling/AutoScalingRollingUpdates.yaml) 

如需查看使用 `cfn-init` 的 LAMP 堆栈模板示例，请参阅 GitHub 网站上的 [ec2-lamp-server](https://github.com/aws-samples/ec2-lamp-server)。