本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 使用 register 命令（IAM 用户 ARN）注册本地实例
<a name="instances-on-premises-register-instance"></a>

**重要**  
不建议使用 IAM 用户注册实例，因为它使用静态（永久）凭证进行身份验证。为了提高安全性，我们建议使用临时凭证注册实例以进行身份验证。有关更多信息，请参阅 [使用 register-on-premises-instance命令（IAM 会话 ARN）注册本地实例](register-on-premises-instance-iam-session-arn.md)。

**重要**  
确保您制定了轮换 IAM 用户的访问密钥（永久凭证）的计划。有关更多信息，请参阅[轮换访问密钥](https://docs.aws.amazon.com//IAM/latest/UserGuide/id_credentials_access-keys.html#Using_RotateAccessKey)。

本部分介绍如何以最少的工作量使用 CodeDeploy 配置本地实例并注册和标记该实例。当您处理一个或少量的本地实例时，**register** 命令非常有用。仅当您使用 IAM 用户 ARN 对实例进行身份验证时，才能使用 **register** 命令。使用 IAM 会话 ARN 进行身份验证时，不能使用 **register** 命令。

当你使用该**register**命令时，你可以让它 CodeDeploy 执行以下操作：
+ 如果您未使用命令指定 IAM 用户，请在中 AWS Identity and Access Management 为本地实例创建 IAM 用户。
+ 将该 IAM 用户的凭证保存到本地实例配置文件中。
+ 向注册本地实例 CodeDeploy。
+ 如果您在命令中指定了标签，则向本地实例添加标签。

**注意**  
该[register-on-premises-instance](https://docs.aws.amazon.com/cli/latest/reference/deploy/register-on-premises-instance.html)命令是[寄存器](https://docs.aws.amazon.com/cli/latest/reference/deploy/register.html)命令的替代命令。如果您希望主要靠自己使用 CodeDeploy 配置本地实例并注册和标记该实例，请使用 **register-on-premises-instance** 命令。您也可以通过 **register-on-premises-instance** 命令来使用 IAM 会话 ARN 注册实例，而不是使用 IAM 用户 ARN 进行注册。如果您有大量本地实例，则此方法有很大的优势。具体来说，您可以使用一个 IAM 会话 ARN 对多个实例进行身份验证，而不必为每个本地实例都单独创建一个 IAM 用户。有关更多信息，请参阅[使用 register-on-premises-instance命令（IAM 用户 ARN）注册本地实例](register-on-premises-instance-iam-user-arn.md)和[使用 register-on-premises-instance命令（IAM 会话 ARN）注册本地实例](register-on-premises-instance-iam-session-arn.md)。

**Topics**
+ [步骤 1：在本地实例 AWS CLI 上安装和配置](#instances-on-premises-register-instance-1-install-cli)
+ [步骤 2：调用 register 命令](#instances-on-premises-register-instance-2-register-command)
+ [步骤 3：调用 install 命令](#instances-on-premises-register-instance-3-install-command)
+ [步骤 4：将应用程序修订部署到本地实例](#instances-on-premises-register-instance-4-deploy-revision)
+ [步骤 5：跟踪对本地实例的部署](#instances-on-premises-register-instance-5-track-deployment)

## 步骤 1：在本地实例 AWS CLI 上安装和配置
<a name="instances-on-premises-register-instance-1-install-cli"></a>

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 和私有 AWS 访问密钥[配置本地实例的先决条件](instances-on-premises-prerequisites.md)。这使得在本地实例上下载和安装 CodeDeploy 代理成为可能。访问权限应与以下示例类似：  

****  

   ```
   {
     "Version":"2012-10-17",		 	 	 
     "Statement" : [
       {
         "Effect" : "Allow",
         "Action" : [
           "codedeploy:*",
           "iam:CreateAccessKey",
           "iam:CreateUser",
           "iam:DeleteAccessKey",
           "iam:DeleteUser",
           "iam:DeleteUserPolicy",
           "iam:ListAccessKeys",
           "iam:ListUserPolicies",
           "iam:PutUserPolicy",
           "iam:GetUser",
           "tag:getTagKeys",
           "tag:getTagValues",
           "tag:GetResources"
         ],
         "Resource" : "*"
       },
       {
         "Effect" : "Allow",
         "Action" : [
           "s3:Get*",
           "s3:List*"
         ],
         "Resource" : [
           "arn:aws:s3:::amzn-s3-demo-bucket/*",
           "arn:aws:s3:::amzn-s3-demo-bucket1/*"
         ]
       }     
     ]
   }
   ```
如果您在尝试访问前面显示的 Amazon S3 存储桶时看到访问被拒绝错误，请尝试省略该存储桶的资源 ARN 的 `/*` 部分，例如，`arn:aws:s3:::aws-codedeploy-sa-east-1`。

****  

   ```
   {
     "Version":"2012-10-17",		 	 	 
     "Statement" : [
       {
         "Effect" : "Allow",
         "Action" : [
           "codedeploy:*",
           "iam:CreateAccessKey",
           "iam:CreateUser",
           "iam:DeleteAccessKey",
           "iam:DeleteUser",
           "iam:DeleteUserPolicy",
           "iam:ListAccessKeys",
           "iam:ListUserPolicies",
           "iam:PutUserPolicy",
           "iam:GetUser",
           "tag:GetResources"
         ],
         "Resource" : "*"
       },
       {
         "Effect" : "Allow",
         "Action" : [
           "s3:Get*",
           "s3:List*"
         ],
         "Resource" : [
           "arn:aws:s3:::amzn-s3-demo-bucket/*",
           "arn:aws:s3:::amzn-s3-demo-bucket2/*"
         ]
       }     
     ]
   }
   ```

## 步骤 2：调用 register 命令
<a name="instances-on-premises-register-instance-2-register-command"></a>

在这一步中，我们假设您从本地实例本身注册该本地实例。您也可以从单独的设备或实例注册本地实例，该设备或实例已按上一步所述 AWS CLI 安装和配置了本地实例。

使用调用 AWS CLI regist [er](https://docs.aws.amazon.com/cli/latest/reference/deploy/register.html) 命令，指定：
+ 用于唯一标识本地实例的名称 CodeDeploy （带`--instance-name`选项）。
**重要**  
为了帮助在以后标识本地实例，特别是用于调试用途，我们强烈建议您使用的名称能够映射到本地实例的某种唯一特性（例如，在适用时可以使用序列号或唯一内部资产标识符）。如果您为名称指定 MAC 地址，请注意 MAC 地址包含 CodeDeploy 不允许使用的字符，例如冒号 (`:`)。有关允许字符的列表，请参阅[CodeDeploy 配额](limits.md)。
+ （可选）您希望与此本地实例关联的现有 IAM 用户的 ARN（使用 `--iam-user-arn` 选项）。要获取 IAM 用户的 ARN，请调用 [get-user](https://docs.aws.amazon.com/cli/latest/reference/iam/get-user.html) 命令，或者在 IAM 控制台的**用户**部分中选择 IAM 用户名，然后在**摘要**部分找到**用户 ARN** 值。如果未指定此选项，则 CodeDeploy 将在您的 AWS 账户中代表您创建一个 IAM 用户，并将其与本地实例关联。
**重要**  
如果您指定了 `--iam-user-arn` 选项，则还必须手动创建本地实例配置文件，如[步骤 4：将配置文件添加到本地实例](register-on-premises-instance-iam-user-arn.md#register-on-premises-instance-iam-user-arn-4)中所述。  
 您只能将一个 IAM 用户与一个本地实例关联。尝试将一个 IAM 用户与多个本地实例关联会导致出错，对这些本地实例的部署将失败，或者对这些本地实例的部署会停滞在永久等待的状态。
+ （可选）一组本地实例标签（带`--tags`选项）， CodeDeploy 用于标识要部署到的 Amazon EC2 实例集。使用 `Key=tag-key,Value=tag-value` 指定各个标签（例如，`Key=Name,Value=Beta Key=Name,Value=WestRegion`）。如果未指定此选项，将不注册标签。要稍后注册标签，请调用-premises [add-tags-to-on-instances 命令](https://docs.aws.amazon.com/cli/latest/reference/deploy/add-tags-to-on-premises-instances.html)。
+ （可选）将在其中注册本地实例的 AWS 区域 CodeDeploy （带`--region`选项）。这必须是 *AWS 一般参考*的[区域和终端节点](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region)中列出的受支持区域之一（例如 `us-west-2`）。如果未指定此选项，则将使用与调用 IAM 用户关联的默认 AWS 区域。

例如：

```
aws deploy register --instance-name AssetTag12010298EX --iam-user-arn arn:aws:iam::444455556666:user/CodeDeployUser-OnPrem --tags Key=Name,Value=CodeDeployDemo-OnPrem --region us-west-2
```

**register** 命令执行以下操作：

1. 如果未指定现有 IAM 用户，则创建一个 IAM 用户，向该用户附加必需的权限，然后生成对应的私有密钥和私有访问密钥。本地实例将使用此 IAM 用户及其权限和凭证进行身份验证和交互 CodeDeploy。

1. 向注册本地实例 CodeDeploy。

1. 如果指定，则 CodeDeploy 将使用`--tags`选项指定的标签与注册的本地实例名称相关联。

1. 如果创建了 IAM 用户，则还会在调用 **register** 命令的同一个目录中创建必需的配置文件。

如果此命令遇到错误，则将显示错误消息，说明您可以如何手动完成剩余步骤。否则，将显示成功消息，说明如何调用 **install** 命令，如接下来的步骤中所列。

## 步骤 3：调用 install 命令
<a name="instances-on-premises-register-instance-3-install-command"></a>

在本地实例中，使用调 AWS CLI 用[安装](https://docs.aws.amazon.com/cli/latest/reference/deploy/install.html)命令，指定：
+ 配置文件的路径（使用 `--config-file` 选项）。
+ （可选）是否替换本地实例上已存在的配置文件（使用 `--override-config` 选项）。如果未指定，则不替换现有配置文件。
+ （可选）将在其中注册本地实例的 AWS 区域 CodeDeploy （带`--region`选项）。这必须是 *AWS 一般参考*的[区域和终端节点](https://docs.aws.amazon.com/general/latest/gr/rande.html#codedeploy_region)中列出的受支持区域之一（例如 `us-west-2`）。如果未指定此选项，则将使用与调用 IAM 用户关联的默认 AWS 区域。
+ （可选）安装 CodeDeploy 代理的自定义位置（带`--agent-installer`选项）。此选项对于安装 CodeDeploy 不正式支持的 CodeDeploy 代理的自定义版本（例如基于中[CodeDeploy代理](https://github.com/aws/aws-codedeploy-agent)存储库的自定义版本 GitHub）非常有用。该值必须是指向包含以下二者之一的 Amazon S3 存储桶的路径：
  +  CodeDeploy 代理安装脚本（适用于基于 Linux 或 UNIX 的操作系统，类似于中[CodeDeploy代理](https://github.com/aws/aws-codedeploy-agent/blob/master/bin/install)存储库中的 GitHub安装文件）。
  +  CodeDeploy 代理安装程序包 (.msi) 文件（适用于基于 Windows 的操作系统）。

   如果未指定此选项，则 CodeDeploy 将尽最大努力从自己的位置安装与本地实例上的操作系统兼容的官方支持的 CodeDeploy 代理版本。

例如：

```
aws deploy install --override-config --config-file /tmp/codedeploy.onpremises.yml --region us-west-2 --agent-installer s3://aws-codedeploy-us-west-2/latest/codedeploy-agent.msi
```

**install** 命令执行以下操作：

1. 检查本地实例是否为 Amazon EC2 实例。如果是，则将显示错误消息。

1. 将本地实例配置文件从实例上的指定位置复制到 CodeDeploy 代理期望找到的位置，前提是该文件尚未位于该位置。

   对于 Ubuntu Server 和 Red Hat Enterprise Linux（RHEL），这是 `/etc/codedeploy-agent/conf`/`codedeploy.onpremises.yml`。

   对于 Windows Server，这是 `C:\ProgramData\Amazon\CodeDeploy`\$1`conf.onpremises.yml`。

   如果指定了 `--override-config` 选项，则创建或覆盖文件。

1. 在本地实例上安装 CodeDeploy 代理，然后启动它。

## 步骤 4：将应用程序修订部署到本地实例
<a name="instances-on-premises-register-instance-4-deploy-revision"></a>

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

将应用程序修订部署到本地实例的方法类似于将应用程序修订部署到 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)。

## 步骤 5：跟踪对本地实例的部署
<a name="instances-on-premises-register-instance-5-track-deployment"></a>

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

跟踪对本地实例的部署的方法与跟踪对 Amazon EC2 实例的部署的方法类似。有关说明，请参阅[查看 CodeDeploy 部署详情](deployments-view-details.md)。

有关更多选项，请参阅[在中管理本地实例的操作 CodeDeploy](on-premises-instances-operations.md)。