# 在 Amazon ECS 中使用非 AWS 容器映像
<a name="private-auth"></a>

使用私有注册表在 AWS Secrets Manager 中存储您的凭证，然后在任务定义中引用它们。这提供了一种方法来引用存在于 AWS 以外的私有注册表中的容器映像，这需要在任务定义中进行身份验证。在 Fargate 上托管的任务、Amazon EC2 实例以及使用 Amazon ECS Anywhere 的外部实例都支持此功能。

**重要**  
如果您的任务定义引用了存储在 Amazon ECR 中的映像，则此主题不适用。有关更多信息，请参阅 *Amazon Elastic Container Registry 用户指南*中的[使用 Amazon ECR 和 Amazon ECS](https://docs.aws.amazon.com/AmazonECR/latest/userguide/ECR_on_ECS.html)。

对于 Amazon EC2 实例上托管的任务，此功能要求您具有版本 `1.19.0` 或更高版本的容器代理。但是，我们建议使用最新的容器代理版本。有关如何检查您的代理版本并更新到最新版本的信息，请参阅[更新 Amazon ECS 容器代理](ecs-agent-update.md)。

对于 Fargate 上托管的任务，此功能需要平台版本 `1.2.0` 或更高版本。有关信息，请参阅[适用于 Amazon ECS 的 Fargate 平台版本](platform-fargate.md)。

在容器定义中，使用您创建的密钥的详细信息指定 `repositoryCredentials` 对象。引用的密钥可以来自与使用此密钥的任务不同的 AWS 区域 或不同的账户。

**注意**  
使用 Amazon ECS API、AWS CLI 或 AWS SDK 时，如果密钥存在于要启动的任务所在的AWS 区域，可以使用密钥的完整 ARN 或名称。如果密钥存在于另一个账户中，则必须指定密钥的完整 ARN。使用 AWS 管理控制台 时，必须始终指定密钥的完整 ARN。

下面是显示必需参数的任务定义代码段：

替换以下参数：
+ 将 *private-repo* 替换为私有存储库主机名称 
+ 将 *private-image* 替换为映像名称
+ 将 *arn:aws:secretsmanager:region:aws\$1account\$1id:secret:secret\$1name* 替换为密钥 Amazon 资源名称（ARN）

```
"containerDefinitions": [
    {
        "image": "private-repo/private-image",
        "repositoryCredentials": {
            "credentialsParameter": "arn:aws:secretsmanager:region:aws_account_id:secret:secret_name"
        }
    }
]
```

**注意**  
启用私有注册表身份验证的另一种方法使用 Amazon ECS 容器代理环境变量向私有注册表进行身份验证。此方法仅支持 Amazon EC2 实例上托管的任务。有关更多信息，请参阅 [为私有 Docker 映像配置 Amazon ECS 容器实例](private-auth-container-instances.md)。

**要使用私有注册表**

1. 任务定义必须具有任务执行角色。这允许容器代理拉取容器映像。有关更多信息，请参阅 [Amazon ECS 任务执行 IAM 角色](task_execution_IAM_role.md)。

   借助私有注册表身份验证，您的 Amazon ECS 任务将可以从位于 AWS 之外且需要身份验证凭证的私有注册表（例如 Docker Hub、Quay.io 或您自己的私有注册表）拉取容器映像。此功能使用 Secrets Manager 来安全地存储注册表凭证，然后使用 `repositoryCredentials` 参数在任务定义中引用这些凭证。

   有关配置私有注册表身份验证的更多信息，请参阅[在 Amazon ECS 中使用非 AWS 容器映像](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/private-auth.html)。

   要允许访问包含您的私有注册表凭证的密钥，请将以下权限作为内联策略添加到任务执行角色中。有关更多信息，请参阅[添加和删除 IAM 策略。](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)
   + `secretsmanager:GetSecretValue`：从 Secrets Manager 检索私有注册表凭证时为必需。
   + `kms:Decrypt`：仅当您的密钥使用自定义 KMS 密钥而不是默认密钥时才需要。您的自定义密钥的 Amazon 资源名称（ARN）必须添加为资源。

   下面是添加所需权限的示例内联策略。

------
#### [ JSON ]

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "kms:Decrypt",
                   "secretsmanager:GetSecretValue"
               ],
               "Resource": [
                   "arn:aws:secretsmanager:us-east-1:111122223333:secret:secret_name",
                   "arn:aws:kms:us-east-1:111122223333:key/key_id"
               ]
           }
       ]
   }
   ```

------

1. 使用 AWS Secrets Manager 为您的私有注册表凭证创建密钥。有关如何创建密钥的信息，请参阅《AWS Secrets Manager 用户指南》**中的[创建 AWS Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_secret.html)。

   使用以下格式输入您的私有注册表凭证：

   ```
   {
     "username" : "privateRegistryUsername",
     "password" : "privateRegistryPassword"
   }
   ```

1. 注册任务定义。有关更多信息，请参阅 [使用控制台创建 Amazon ECS 任务定义](create-task-definition.md)。