AWS CodeDeploy
User Guide (API Version 2014-10-06)
AWS 服务或AWS文档中描述的功能,可能因地区/位置而异。点 击 Getting Started with Amazon AWS to see specific differences applicable to the China (Beijing) Region.

使用 register-on-premises-instance 命令 (IAM 会话 ARN) 注册本地实例

为最大程度控制您的本地实例的身份验证和注册,可使用 register-on-premises-instance 命令和 AWS Security Token Service (AWS STS) 所生成的定期刷新的临时凭证。实例的一个静态 IAM 角色将担任这些刷新 AWS STS 凭证的角色来执行 AWS CodeDeploy 部署操作。

当您需要注册大量实例时,此方法非常有用。您可以使用此方法来借助 AWS CodeDeploy 自动执行注册过程。您可以使用自己的身份和身份验证系统对本地实例进行身份验证,并将 IAM 会话凭证从服务分发给实例以便用于 AWS CodeDeploy。

注意

或者,您也可以使用分发给所有本地实例的一个共享 IAM 用户调用 AWS STS AssumeRole API,以检索本地实例的会话凭证。此方法安全性较低,建议不要用于生产或关键任务型环境。

参考以下主题中的信息,使用 AWS STS 生成的临时安全凭证来配置本地实例。

IAM 会话 ARN 注册前提条件

除了在 配置本地实例的先决条件 中列出的前提条件之外,还必须满足以下要求:

IAM 权限

您用来注册本地实例的 IAM 身份必须有权执行 AWS CodeDeploy 操作。确保 AWSCodeDeployFullAccess 托管策略已挂载到该 IAM 身份。有关信息,请参阅 IAM 用户指南 中的 AWS 托管策略

用于刷新临时凭证的系统

如果您使用 IAM 会话 ARN 注册本地实例,则您必须有一个系统来定期刷新该临时凭证。如果在生成凭证时指定的期限较短,临时凭证会在一小时 (或更短时间) 后过期。有两种刷新凭证的方法:

  • 方法 1:使用您的企业网络中的身份和身份验证系统以及一个 CRON 脚本,该脚本定期轮询该身份和身份验证系统,并将最新的会话凭证复制到该实例。采用此方法,您可以将您的身份验证和身份结构与 AWS 集成,而无需更改 AWS CodeDeploy 代理或服务来为您在组织中使用的身份验证类型提供支持。

  • 方法 2:定期在实例上运行 CRON 作业来调用 AWS STS AssumeRole 操作,并将会话凭证写入 AWS CodeDeploy 代理可访问的文件。此方法仍需要使用 IAM 用户并将凭证复制到本地实例,但您可以对您的各个本地实例重复使用相同的 IAM 用户和凭证。

有关创建和使用 AWS STS 凭证的信息,请参阅 AWS Security Token Service API Reference使用临时安全凭证以请求对 AWS 资源的访问权限

步骤 1:创建本地实例将担任的 IAM 角色

您可以使用 AWS CLI 或 IAM 控制台创建一个 IAM 角色,供您的本地实例在进行身份验证和与 AWS CodeDeploy 进行交互时使用。

您只需要创建一个 IAM 角色。您的每个本地实例都可以担任此角色,以获取为此角色提供权限的临时安全凭证。

您创建的角色需要以下权限来访问安装 AWS CodeDeploy 代理所需的文件:

Copy
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "s3:Get*", "s3:List*" ], "Effect": "Allow", "Resource": "*" } ] }

我们建议您将此策略限制为您的本地实例需要访问的那些 Amazon S3 存储桶。如果您限制此策略,请确保授予对包含 AWS CodeDeploy 代理的 Amazon S3 存储桶的访问权限。否则,只要在本地实例上安装或更新 AWS CodeDeploy 代理,就可能出现错误。有关如何控制对 Amazon S3 存储桶的访问权限的信息,请参阅管理您的 Amazon S3 资源的访问权限

创建 IAM 角色

  1. 调用 create-role 命令,同时使用 --role-name 选项指定 IAM 角色的名称 (例如 CodeDeployInstanceRole),并使用 --assume-role-policy-document 选项提供权限。

    为此实例创建 IAM 角色时,您可以为其指定角色名称 CodeDeployInstanceRole,并在名为 CodeDeployRolePolicy.json 的文件中提供所需的权限:

    Copy
    aws iam create-role --role-name CodeDeployInstanceRole --assume-role-policy-document file://CodeDeployRolePolicy.json
  2. 在调用 create-role 命令的输出中,记录 ARN 字段的值。例如:

    Copy
    arn:aws:iam::123456789012:role/CodeDeployInstanceRole

    当您使用 AWS STS AssumeRole API 生成每个实例的短期凭证时,将需要该角色 ARN。

    有关创建 IAM 角色的更多信息,请参阅 IAM 用户指南 中的创建向 AWS 服务委托权限的角色

    有关向现有角色分配权限的信息,请参阅 AWS Command Line Interface Reference中的 put-role-policy

步骤 2:使用 AWS STS 为单独的实例生成临时凭证

在生成将用于注册本地实例的临时凭证之前,必须创建或选择您将为其生成临时凭证的 IAM 身份 (用户或角色)。在此 IAM 身份的策略设置中,必须包含 sts:AssumeRole 权限。

有关对 IAM 身份授予 sts:AssumeRole 权限的信息,请参阅创建向 AWS 服务委托权限的角色AssumeRole

有两种生成临时凭证的方法:

  • assume-role 命令用于 AWS CLI。例如:

    Copy
    aws sts assume-role --role-arn arn:aws:iam::12345ACCOUNT:role/role-arn --role-session-name session-name

    其中:

    注意

    如果您使用 CRON 脚本定期轮询身份和身份认证系统,并将最新会话凭证复制到实例 (用于刷新 IAM 会话 ARN 注册前提条件 中所述的临时凭证的方法 1),则您可以改为使用任何受支持的 AWS SDK 来调用 AssumeRole

  • 使用 AWS 提供的工具。

    aws-codedeploy-session-helper 工具生成 AWS STS 凭证并将它们写入您放在实例上的文件。此工具最适用于 IAM 会话 ARN 注册前提条件 中所述的用于刷新临时凭证的方法 2。在此方法中,aws-codedeploy-session-helper 工具置于每个实例之上,并使用 IAM 用户的权限执行命令。每个实例都将相同的 IAM 用户凭证与此工具结合使用。

    有关更多信息,请参阅 aws-codedeploy-session-helper GitHub 存储库。

在您创建 IAM 会话凭证之后,请将它们置于本地实例上的任何位置。在下一个步骤中,您将配置 AWS CodeDeploy 代理以访问此位置的凭证。

在继续操作之前,请确保您将用来定期刷新临时凭证的系统已经准备就绪。如果未刷新临时凭证,则部署到本地实例的操作将失败。有关更多信息,请参阅 IAM 会话 ARN 注册前提条件 中的“用于刷新临时凭证的系统”。

步骤 3:将配置文件添加到本地实例

使用 root 或管理员权限将配置文件添加到本地实例。此配置文件用于声明将对 AWS CodeDeploy 使用的 IAM 凭证和目标 AWS 区域。必须将该文件添加到本地实例上的特定位置。该文件必须包含 IAM 临时会话 ARN、其私有密钥 ID 和秘密访问密钥,以及目标 AWS 区域。

添加配置文件

  1. 在本地实例上的以下位置,创建名为 codedeploy.onpremises.yml(用于 Ubuntu Server 或 RHEL 本地实例)或 conf.onpremises.yml 的文件(用于 Windows Server 本地实例):

    • 对于 Ubuntu Server:/etc/codedeploy-agent/conf

    • 对于 Windows Server:C:\ProgramData\Amazon\CodeDeploy

  2. 使用文本编辑器,向新创建的 codedeploy.onpremises.ymlconf.onpremises.yml 文件添加以下信息:

    Copy
    --- iam_session_arn: iam-session-arn aws_credentials_file: credentials-file region: supported-region

    其中:

步骤 4:为 AWS CodeDeploy 部署准备本地实例

安装和配置 AWS CLI

在本地实例上安装和配置 AWS CLI。(AWS CLI 将用于在本地实例上下载和安装 AWS CodeDeploy 代理。)

  1. 要在本地实例上安装 AWS CLI,请按照 AWS 命令行界面用户指南使用 AWS命令行界面进行设置中的说明执行操作。

    注意

    1.7.19 版 AWS CLI 中提供了用于处理本地实例的 AWS CodeDeploy 命令。如果您已经安装了 AWS CLI 版本,则可以调用 aws --version 来检查其版本。

  2. 要在本地实例上配置 AWS CLI,请按照 AWS 命令行界面用户指南配置 AWS 命令行界面中的说明执行操作。

    重要

    在配置 AWS CLI (例如通过调用 aws configure 命令) 时,请确保指定私有密钥 ID 和 IAM 用户的秘密访问密钥,该用户应至少具有IAM 会话 ARN 注册前提条件中所述的权限。

设置 AWS_REGION 环境变量 (仅针对 Ubuntu Server 和 RHEL)

如果您未在本地实例上运行 Ubuntu Server 或 RHEL,请跳过此步骤,直接转到“安装 AWS CodeDeploy 代理”。

在 Ubuntu Server 或 RHEL 本地实例上安装 AWS CodeDeploy 代理,并让实例能够在发布新版本时及时更新 AWS CodeDeploy 代理。为此,您可以将实例上的 AWS_REGION 环境变量设置为 AWS CodeDeploy 支持的某个区域的标识符。我们建议您将区域的值设置为您的 AWS CodeDeploy 应用程序、部署组和应用程序修订所在的区域(例如,us-west-2)。有关区域列表,请参阅 AWS General Reference 中的区域和终端节点

要设置环境变量,请从终端调用以下命令:

Copy
export AWS_REGION=supported-region

其中 supported-region 是区域标识符(例如,us-west-2)。

安装 AWS CodeDeploy 代理

步骤 5:将本地实例注册到 AWS CodeDeploy

这一步中的说明假设您从本地实例本身上注册该本地实例。您还可以从安装和配置了 AWS CLI 的其他设备或实例上注册本地实例。

使用 AWS CLI 将本地实例注册到 AWS CodeDeploy,以便可以在部署中使用该实例。

您需要有您在步骤 3:将配置文件添加到本地实例中创建的临时会话凭证的 ARN,才能使用 AWS CLI。例如,对于您指定为 AssetTag12010298EX 的实例:

Copy
arn:sts:iam::123456789012:assumed-role/CodeDeployInstanceRole/AssetTag12010298EX

调用 register-on-premises-instance 命令,在命令中指定:

  • 唯一标识本地实例的名称 (使用 --instance-name 选项)。

    重要

    为了帮助标识本地实例,特别是用于调试用途,我们强烈建议您指定能够反映本地实例的某种唯一特性的名称 (例如,在适用时可以指定 STS 凭证的会话名称以及序列号或内部资产标识符)。如果您指定 MAC 地址作为名称,请注意 MAC 地址包含 AWS CodeDeploy 不允许使用的字符,例如冒号 (:)。有关允许字符的列表,请参阅限制

  • 您在步骤 1:创建本地实例将担任的 IAM 角色中设置以对多个本地实例进行身份验证的 IAM 会话 ARN。

例如:

Copy
aws deploy register-on-premises-instance --instance-name name-of-instance --iam-session-arn arn:aws:sts::account-id:assumed-role/role-to-assume/session-name

其中:

  • name-of-instance 是您用来标识本地实例的名称,如 AssetTag12010298EX.

  • account-id 是您的组织的 12 位数账户 ID,如 111222333444.

  • role-to-assume 是您为实例创建的 IAM 角色的名称,如 CodeDeployInstanceRole.

  • session-name 是您在 步骤 2:使用 AWS STS 为单独的实例生成临时凭证 中指定的会话角色的名称。

步骤 6:标记本地实例

您可以使用 AWS CLI 或 AWS CodeDeploy 控制台标记本地实例。(在部署期间,AWS CodeDeploy 使用本地实例标签来标识部署目标。)

标记本地实例 (CLI)

  • 调用 add-tags-to-on-premises-instances 命令,在命令中指定:

    • 唯一标识本地实例的名称 (使用 --instance-names 选项)。

    • 您要使用的本地实例标签密钥的名称和标签值 (使用 --tags 选项)。您必须同时指定名称和值。AWS CodeDeploy 不允许本地实例标签只具有值。

      例如:

      Copy
      aws deploy add-tags-to-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem

标记本地实例(控制台)

  1. 登录 AWS 管理控制台并通过以下网址打开 AWS CodeDeploy 控制台:https://console.www.amazonaws.cn/codedeploy

    注意

    使用您在入门中使用的相同账户或 IAM 用户信息进行登录。

  2. 从 AWS CodeDeploy 菜单中,选择 On-premises instances

  3. 在本地实例列表中,选择您要标记的本地实例旁边的箭头。

  4. 在标签列表中,选择或键入所需的标签密钥和标签值。当您键入标签密钥和标签值之后,将显示另一行。您可以重复此步骤,最多添加 10 个标签。要删除标签,请选择删除图标 ( )。

  5. 在您添加标签之后,选择 Update Tags

步骤 7:将应用程序修订部署到本地实例

现在,您已准备好将应用程序修订部署到已注册和标记的本地实例。

将应用程序修订部署到本地实例的方法类似于将应用程序修订部署到 Amazon EC2 实例。有关说明,请参阅 创建部署。这些说明包含指向先决条件的链接,其中包括创建应用程序、创建部署组和准备应用程序修订。如果您希望部署简单的示例应用程序修订,可以创建教程:将应用程序部署到本地实例步骤 2:创建示例应用程序修订中所述的修订。

重要

在创建以本地实例为目标的部署组的过程中,如果您重用 AWS CodeDeploy 服务角色,则必须将 Tag:get* 包含到服务角色策略语句的 Action 部分中。有关更多信息,请参阅 步骤 3:创建服务角色

步骤 8:跟踪对本地实例的部署

将应用程序修订部署到已注册和标记的本地实例之后,您可以跟踪部署进度。

跟踪对本地实例的部署的方法与跟踪对 Amazon EC2 实例的部署的方法类似。有关说明,请参阅查看部署详细信息