本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 使用 register-on-premises-instance命令（IAM 会话 ARN）注册本地实例
为了最大限度地控制本地实例的身份验证和注册，您可以使用[register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html)命令并定期刷新通过 AWS Security Token Service (AWS STS) 生成的临时证书。实例的静态 IAM 角色扮演这些刷新的 AWS STS 证书的角色来执行 CodeDeploy 部署操作。
当您需要注册大量实例时，此方法非常有用。它允许您使用自动完成注册过程 CodeDeploy。您可以使用自己的身份和身份验证系统对本地实例进行身份验证，并将服务中的 IAM 会话证书分发给实例以供使用 CodeDeploy。
**注意**
或者，您可以使用分布到所有本地实例的共享 IAM 用户调用 AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)API 来检索本地实例的会话证书。此方法安全性较低，建议不要用于生产或关键任务型环境。
使用以下主题中的信息，使用生成的临时安全证书配置本地实例 AWS STS。
**Topics**
+ [IAM 会话 ARN 注册前提条件](#register-on-premises-instance-iam-session-arn-prerequisites)
+ [步骤 1：创建本地实例将担任的 IAM 角色](#register-on-premises-instance-iam-session-arn-1)
+ [步骤 2：使用为单个实例生成临时证书 AWS STS](#register-on-premises-instance-iam-session-arn-2)
+ [步骤 3：将配置文件添加到本地实例](#register-on-premises-instance-iam-session-arn-3)
+ [步骤 4：为部署准备本地实例 CodeDeploy](#register-on-premises-instance-iam-session-arn-4)
+ [步骤 5：向注册本地实例 CodeDeploy](#register-on-premises-instance-iam-session-arn-5)
+ [步骤 6：标记本地实例](#register-on-premises-instance-iam-session-arn-6)
+ [步骤 7：将应用程序修订部署到本地实例](#register-on-premises-instance-iam-session-arn-7)
+ [步骤 8：跟踪对本地实例的部署](#register-on-premises-instance-iam-session-arn-8)
## IAM 会话 ARN 注册前提条件
除了在 [配置本地实例的先决条件](instances-on-premises-prerequisites.md) 中列出的前提条件之外，还必须满足以下要求：
**IAM 权限**
必须向用于注册本地实例的 IAM 身份授予执行 CodeDeploy 操作的权限。确保 **AWSCodeDeployFullAccess** 托管策略已附加到该 IAM 身份。有关更多信息，请参阅《IAM 用户指南》**中的 [AWS 托管策略](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_managed-vs-inline.html#aws-managed-policies)。
**用于刷新临时凭证的系统**
如果您使用 IAM 会话 ARN 注册本地实例，则您必须有一个系统来定期刷新该临时凭证。如果在生成凭证时指定的期限较短，临时凭证会在一小时（或更短时间）后过期。有两种刷新凭证的方法：
+ **方法 1**：使用您的企业网络中的身份和身份验证系统以及一个 CRON 脚本，该脚本定期轮询该身份和身份验证系统，并将最新的会话凭证复制到该实例。这使您能够将身份验证和身份结构与集成，而 AWS 无需更改 CodeDeploy 代理或服务以支持您在组织中使用的身份验证类型。
+ **方法 2**：定期在实例上运行 CRON 作业以调用 AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)操作并将会话凭证写入 CodeDeploy 代理可以访问的文件。此方法仍需要使用 IAM 用户并将凭证复制到本地实例，但您可以对您的各个本地实例重复使用相同的 IAM 用户和凭证。
**注意**
无论您使用的是方法 1 还是方法 2，都必须设置一个进程，以便在临时会话证书更新后重新启动 CodeDeploy 代理，这样新的凭证才能生效。
有关创建和使用 AWS STS 证书的信息，请参阅 [AWS Security Token Service API 参考](https://docs.aws.amazon.com/STS/latest/APIReference/)和[使用临时安全证书请求访问 AWS 资源](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html)。
## 步骤 1：创建本地实例将担任的 IAM 角色
您可以使用 AWS CLI 或 IAM 控制台创建 IAM 角色，您的本地实例将使用该角色进行身份验证和交互 CodeDeploy。
您只需要创建一个 IAM 角色。您的每个本地实例都可以担任此角色，以获取为此角色提供权限的临时安全凭证。
您创建的角色需要以下权限才能访问安装 CodeDeploy 代理所需的文件：
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"s3:Get*",
"s3:List*"
],
"Effect": "Allow",
"Resource": "*"
}
]
}
```
------
我们建议您将此策略限制为您的本地实例需要访问的那些 Amazon S3 存储桶。如果您限制此策略，请确保允许访问包含 CodeDeploy 代理的 Amazon S3 存储桶。否则，每当在本地实例上安装或更新 CodeDeploy 代理时，都可能出现错误。有关如何控制对 Amazon S3 存储桶的访问权限的更多信息，请参阅[管理您的 Amazon S3 资源的访问权限](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html)。
**创建 IAM 角色**
1. 调用 [create-role](https://docs.aws.amazon.com/cli/latest/reference/iam/create-role.html) 命令，同时使用 `--role-name` 选项指定 IAM 角色的名称（例如 `CodeDeployInstanceRole`），并使用 `--assume-role-policy-document` 选项提供权限。
为此实例创建 IAM 角色时，您可以为其指定角色名称 `CodeDeployInstanceRole`，并在名为 `CodeDeployRolePolicy.json` 的文件中提供所需的权限：
```
aws iam create-role --role-name CodeDeployInstanceRole --assume-role-policy-document file://CodeDeployRolePolicy.json
```
1. 在调用 **create-role** 命令的输出中，记录 ARN 字段的值。例如：
```
arn:aws:iam::123456789012:role/CodeDeployInstanceRole
```
当您使用 AWS STS [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)API 为每个实例生成短期证书时，您将需要角色 ARN。
有关创建 IAM 角色的更多信息，请参阅 I [A *M 用户指南*中的创建角色以向 AWS 服务委派权限](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)。
有关为现有角色分配权限的信息，请参阅[AWS CLI 命令参考[put-role-policy](https://docs.aws.amazon.com/cli/latest/reference/iam/put-role-policy.html)](https://docs.aws.amazon.com/cli/latest/reference/)中的。
## 步骤 2：使用为单个实例生成临时证书 AWS STS
在生成将用于注册本地实例的临时凭证之前，必须创建或选择您将为其生成临时凭证的 IAM 身份（用户或角色）。在此 IAM 身份的策略设置中，必须包含 `sts:AssumeRole` 权限。
有关向 IAM 身份授予`sts:AssumeRole`权限的信息，请参阅[创建向 AWS 服务委派权限的角色](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html)和[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)。
有两种生成临时凭证的方法：
+ 将 [assume-role](https://docs.aws.amazon.com/cli/latest/reference/sts/assume-role.html) 命令与 AWS CLI结合使用。例如：
```
aws sts assume-role --role-arn arn:aws:iam::12345ACCOUNT:role/role-arn --role-session-name session-name
```
其中：
+ *12345ACCOUNT*是贵组织的 12 位账号。
+ *role-arn*是你在中生成的要担任的角色的 ARN。[步骤 1：创建本地实例将担任的 IAM 角色](#register-on-premises-instance-iam-session-arn-1)
+ *session-name*是您要为现在正在创建的角色会话起的名称。
**注意**
如果您使用定期轮询身份和身份验证系统并将最新的会话凭证复制到实例的 CRON 脚本（用于刷新临时证书的方法 1，如所述[IAM 会话 ARN 注册前提条件](#register-on-premises-instance-iam-session-arn-prerequisites)），则可以改用任何支持的 AWS 软件开发工具包进行调[AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html)用。
+ 使用提供的工具 AWS。
该 aws-codedeploy-session-helper工具会生成 AWS STS 凭证并将其写入您放置在实例上的文件中。此工具最适用于 [IAM 会话 ARN 注册前提条件](#register-on-premises-instance-iam-session-arn-prerequisites) 中所述的用于刷新临时凭证的方法 2。在此方法中，该 aws-codedeploy-session-helper工具放在每个实例上，并使用 IAM 用户的权限执行命令。每个实例都将相同的 IAM 用户凭证与此工具结合使用。
有关更多信息，请参阅[aws-codedeploy-session-helper](https://github.com/awslabs/aws-codedeploy-samples/tree/master/utilities/aws-codedeploy-session-helper) GitHub 存储库。
**注意**
在您创建 IAM 会话凭证之后，请将它们置于本地实例上的任何位置。在下一步中，您将配置 CodeDeploy 代理以访问此位置的凭证。
在继续操作之前，请确保您将用来定期刷新临时凭证的系统已经准备就绪。如果未刷新临时凭证，则部署到本地实例的操作将失败。有关更多信息，请参阅 [IAM 会话 ARN 注册前提条件](#register-on-premises-instance-iam-session-arn-prerequisites) 中的“用于刷新临时凭证的系统”。
## 步骤 3：将配置文件添加到本地实例
使用 root 或管理员权限将配置文件添加到本地实例。此配置文件用于声明 IAM 证书和要使用的目标 AWS 区域 CodeDeploy。必须将该文件添加到本地实例上的特定位置。该文件必须包含 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`
1. 使用文本编辑器将以下信息添加到新创建的 `codedeploy.onpremises.yml` 文件（Linux）或 `conf.onpremises.yml` 文件（Windows）：
```
---
iam_session_arn: iam-session-arn
aws_credentials_file: credentials-file
region: supported-region
```
其中：
+ *iam-session-arn*是您在中记下的 IAM 会话 ARN。[步骤 2：使用为单个实例生成临时证书 AWS STS](#register-on-premises-instance-iam-session-arn-2)
+ *credentials-file*是临时会话 ARN 的证书文件的位置，如中所述。[步骤 2：使用为单个实例生成临时证书 AWS STS](#register-on-premises-instance-iam-session-arn-2)
+ *supported-region*是 CodeDeploy支持的区域之一，如中的[区域和终端节点](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region)中所列*AWS 一般参考*。
## 步骤 4：为部署准备本地实例 CodeDeploy
**安装和配置 AWS CLI **
在本地实例 AWS CLI 上安装和配置。（ AWS CLI 将用于在本地实例上下载和安装 CodeDeploy 代理。）
1. 要在本地实例 AWS CLI 上安装，请按照*AWS Command Line Interface 用户指南*中的[开始设置 AWS CLI中的说明进行](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-set-up.html)操作。
**注意**
CodeDeploy 用于处理本地实例的命令已在 1.7.19 版本中提供。 AWS CLI如果您 AWS CLI 已经安装了的版本，则可以通过调用来检查其版本**aws --version**。
1. 要在本地实例 AWS CLI 上配置，请按照*AWS Command Line Interface 用户指南*中的[配置 AWS CLI中的](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)说明进行操作。
**重要**
在配置时 AWS CLI （例如，通过调用**aws configure**命令），请务必指定至少具有中所述权限的 IAM 用户的私有密钥 ID 和私有访问密钥[IAM 会话 ARN 注册前提条件](#register-on-premises-instance-iam-session-arn-prerequisites)。
**设置 AWS\$1REGION环境变量（仅限 Ubuntu 服务器和 RHEL）**
如果您没有在本地实例上运行 Ubuntu Server 或 RHEL，请跳过此步骤，直接转到 “安装代理”。 CodeDeploy
在 Ubuntu 服务器或 RHEL 本地实例上安装代 CodeDeploy 理，并允许实例在新版本 CodeDeploy 可用时更新代理。为此，您可以将实例上的 `AWS_REGION` 环境变量设置为 CodeDeploy 支持的某个区域的标识符。我们建议您将该值设置为 CodeDeploy 应用程序、部署组和应用程序修订所在的区域（例如`us-west-2`）。有关区域的列表，请参阅《AWS 一般参考》**中的[区域和终端节点](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region)。
要设置环境变量，请从终端调用以下命令：
```
export AWS_REGION=supported-region
```
哪里*supported-region*是区域标识符（例如，`us-west-2`）。
**安装代 CodeDeploy 理**
+ 对于 Ubuntu Server 本地实例，请按照[为 Ubuntu 服务器安装 CodeDeploy 代理](codedeploy-agent-operations-install-ubuntu.md)中的说明操作，然后返回本页。
+ 对于 RHEL 本地实例，请按照[安装适用于亚马逊 Linux 或 RHEL 的 CodeDeploy 代理](codedeploy-agent-operations-install-linux.md)中的说明操作，然后返回本页。
+ 对于 Windows Server 本地实例，请按照[安装适用于 Windows 服务器的 CodeDeploy 代理](codedeploy-agent-operations-install-windows.md)中的说明操作，然后返回本页。
## 步骤 5：向注册本地实例 CodeDeploy
这一步中的说明假设您从本地实例本身上注册该本地实例。您可以从单独的设备或已 AWS CLI 安装和配置的实例注册本地实例。
使用 AWS CLI 向注册本地实例， CodeDeploy 以便可以在部署中使用该实例。
在使用之前 AWS CLI，您需要在中创建的临时会话证书的 ARN。[步骤 3：将配置文件添加到本地实例](#register-on-premises-instance-iam-session-arn-3)例如，对于您指定为 `AssetTag12010298EX` 的实例：
```
arn:sts:iam::123456789012:assumed-role/CodeDeployInstanceRole/AssetTag12010298EX
```
调用 [register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html) 命令，在命令中指定：
+ 唯一标识本地实例的名称（使用 `--instance-name` 选项）。
**重要**
为了帮助标识本地实例，特别是用于调试用途，我们强烈建议您指定能够反映本地实例的某种唯一特性的名称（例如，在适用时可以指定 STS 凭证的会话名称以及序列号或内部资产标识符）。如果您指定 MAC 地址作为名称，请注意 MAC 地址包含 CodeDeploy 不允许使用的字符，例如冒号 (:)。有关允许字符的列表，请参阅[CodeDeploy 配额](limits.md)。
+ 您在[步骤 1：创建本地实例将担任的 IAM 角色](#register-on-premises-instance-iam-session-arn-1)中设置以对多个本地实例进行身份验证的 IAM 会话 ARN。
例如：
```
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](#register-on-premises-instance-iam-session-arn-2)。
## 步骤 6：标记本地实例
您可以使用 AWS CLI 或 CodeDeploy 控制台来标记本地实例。 （在部署期间CodeDeploy使用本地实例标签来识别部署目标。）
**标记本地实例（CLI）**
+ 调用-premis [add-tags-to-ones-instances 命令，](https://docs.aws.amazon.com/cli/latest/reference/deploy/add-tags-to-on-premises-instances.html)指定：
+ 唯一标识本地实例的名称（使用 `--instance-names` 选项）。
+ 您要使用的本地实例标签密钥的名称和标签值（使用 `--tags` 选项）。必须同时指定名称和值。 CodeDeploy 不允许仅包含值的本地实例标签。
例如：
```
aws deploy add-tags-to-on-premises-instances --instance-names AssetTag12010298EX --tags Key=Name,Value=CodeDeployDemo-OnPrem
```
**标记本地实例（控制台）**
1. 登录 AWS 管理控制台 并在 [https://console.aws.amazon.com/codede](https://console.aws.amazon.com/codedeploy) ploy 上打开 CodeDeploy 控制台。
**注意**
使用您在[入门 CodeDeploy](getting-started-codedeploy.md)中设置的同一用户登录。
1. 在导航窗格中，展开**部署**，然后选择**本地实例**。
1. 在本地实例列表中，选择要标记的本地实例名称。
1. 在标签列表中，选择或输入所需的标签键和标签值。当您输入标签键和标签值之后，将显示另一行。您可以重复此步骤，最多添加 10 个标签。要删除标签，请选择**移除**。
1. 在您添加标签之后，选择 **Update Tags**。
## 步骤 7：将应用程序修订部署到本地实例
现在，您已准备好将应用程序修订部署到已注册和标记的本地实例。
将应用程序修订部署到本地实例的方法类似于将应用程序修订部署到 Amazon EC2 实例。有关说明，请参阅[使用创建部署 CodeDeploy](deployments-create.md)。这些说明包含指向先决条件的链接，其中包括创建应用程序、创建部署组和准备应用程序修订。如果您希望部署简单的示例应用程序修订，可以创建[教程：使用 CodeDeploy （Windows 服务器、Ubuntu 服务器或红帽企业 Linux）将应用程序部署到本地实例](tutorials-on-premises-instance.md)的[步骤 2：创建示例应用程序修订](tutorials-on-premises-instance-2-create-sample-revision.md)中所述的修订。
**重要**
如果您在创建以本地实例为目标的部署组时重复使用 CodeDeploy 服务角色，则必须在该服务角色的策略声明`Action`部分中包含`Tag:get*`该服务角色。有关更多信息，请参阅 [步骤 2：为创建服务角色 CodeDeploy](getting-started-create-service-role.md)。
## 步骤 8：跟踪对本地实例的部署
将应用程序修订部署到已注册和标记的本地实例之后，您可以跟踪部署进度。
跟踪对本地实例的部署的方法与跟踪对 Amazon EC2 实例的部署的方法类似。有关说明，请参阅[查看 CodeDeploy 部署详情](deployments-view-details.md)。