本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 将上游注册表与 Amazon ECR 私有注册表同步
使用缓存提取规则，您可以将上游注册表的内容与 Amazon ECR 私有注册表同步。
Amazon ECR 目前支持为以下上游注册表创建提取缓存规则。
+ Amazon ECR Public、Kubernetes 容器映像注册表和 Quay（不需要身份验证）
+ Docker Hub、Microsoft Azure 容器注册表、 GitHub 容器注册表、 GitLab 容器注册表和 Chainguard 注册表（需要使用密钥进行身份验证） AWS Secrets Manager
+ Amazon ECR（需要使用 AWS IAM 角色进行身份验证）
对于 GitLab 容器注册表，Amazon ECR 仅支持通过软件即服务 (SaaS) 产品提取缓存。 GitLab有关使用 GitLab的 SaaS 产品的更多信息，请参阅 [GitLab.com](https://docs.gitlab.com/17.5/subscriptions/choosing_subscription/)。
对于需要使用密钥进行身份验证的上游注册表（例如 Docker Hub），您必须将凭据存储在密钥中。 AWS Secrets Manager 您可以使用 Amazon ECR 控制台为每个经过身份验证的上游注册表创建 Secrets Manager 密钥。有关使用 Secrets Manager 控制台创建 Secrets Manager 密钥的更多信息，请参阅[将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中](pull-through-cache-creating-secret.md)。
对于 Amazon ECR，如果上游和下游 Amazon ECR 注册表属于不同的账户，则必须创建一个 IAM 角色。 AWS 有关创建 IAM 角色的更多信息，请参阅[跨账户 ECR 到 ECR 提取缓存所需的 IAM 策略](pull-through-cache-private.md#pull-through-cache-private-permissions)。
为上游注册表创建提取缓存规则后，使用 Amazon ECR 私有注册表 URI 从该上游注册表中提取映像即可。然后，Amazon ECR 会创建一个存储库，在私有注册表中缓存该映像。对于随后的具有给定标签的缓存映像的提取请求，Amazon ECR 会检查上游注册表，看看是否有新版本的具有该特定标签的映像，并且尝试至少每 24 小时更新一次私有注册表中的映像。
## 存储库创建模板
Amazon ECR 已支持存储库创建模板。这样的话，在为 Amazon ECR 使用缓存提取规则代表您创建的新存储库指定初始配置时，您有控制权。每个模板都包含存储库命名空间前缀，用于将新存储库与特定模板匹配。模板可以指定所有存储库设置的配置，包括基于资源的访问策略、标签不变性、加密和生命周期策略。存储库创建模板中的设置仅在存储库创建期间应用，对现有存储库或使用任何其他方法创建的存储库没有任何影响。有关更多信息，请参阅 [用于控制在缓存拉取、推送时创建或复制操作期间创建的存储库的模板](repository-creation-templates.md)。
## 使用缓存提取规则的注意事项
使用 Amazon ECR 缓存提取规则时，请考虑以下内容。
+ 以下区域不支持创建缓存提取规则。
+ 中国（北京） (`cn-north-1`)
+ 中国（宁夏） (`cn-northwest-1`)
+ AWS GovCloud （美国东部）(`us-gov-east-1`)
+ AWS GovCloud （美国西部）(`us-gov-west-1`)
+ AWS Lambda 不支持使用拉取缓存规则从 Amazon ECR 提取容器映像。
+ 如果使用提取缓存提取镜像，首次提取镜像时不支持 Amazon ECR FIPS 服务端点。但是，使用 Amazon ECR FIPS 服务端点可以处理后续提取。
+ 对于需要身份验证的上游存储库，当首次通过 Amazon ECR 私有注册表 URI 提取图像或更新缓存时，映像拉取由与拉取缓存规则中配置的证书关联的用户启动。随后的拉取操作将直接从客户私有注册表的缓存中返回图像。
+ 对于不需要身份验证的上游存储库，当通过 Amazon ECR 私有注册表 URI 提取图像时，映像拉取将由 AWS IP 地址启动。
+ 当客户通过 Amazon ECR 私有注册表 URI 提取缓存的图像时，Amazon ECR 会检查它是否在过去 24 小时内根据上游注册表验证了该映像。如果 24 小时窗口已过期，Amazon ECR 会向上游发送请求以检查是否有更新的版本，并更新缓存（如果存在）。如果窗口尚未过期，Amazon ECR 将提供缓存的图像，而无需联系上游。
+ 向已创建的拉取缓存存储库调用 `ListImageReferrers` API 会将符合 OCI 的反向链接工件返回到私有缓存。
+ Amazon ECR 会检查反向链接构件是否在过去 6 小时内进行了更新。如果 6 小时窗口已过期，Amazon ECR 会向上游发送请求以检查是否有较新的版本，并更新缓存（如果存在）。
+ 如果 Amazon ECR 出于任何原因无法从上游注册表更新映像，并且映像已提取，则系统仍会提取最后缓存的映像。
+ 在创建包含上游注册表凭证的 Secrets Manager 密钥时，密钥名称必须使用 `ecr-pullthroughcache/` 前缀。密钥还必须与缓存提取规则位于相同的账户和区域。
+ 当使用缓存提取规则提取多架构镜像时，清单列表和清单列表中引用的每个镜像都会被提取到 Amazon ECR 存储库中。如果您只想提取特定架构，则可以使用与架构关联的镜像摘要或标签，而不是与清单列表关联的标签来提取镜像。
+ Amazon ECR 使用服务相关的 IAM 角色，为 Amazon ECR 提供所需的权限，以创建存储库、检索用于身份验证的 Secrets Manager 密钥，以及代表您推送缓存映像。服务相关 IAM 角色在创建缓存提取规则时自动创建。有关更多信息，请参阅 [用于缓存提取的 Amazon ECR 服务相关角色](slr-pullthroughcache.md)。
+ 默认情况下，提取缓存映像的 IAM 主体具有通过其 IAM policy 授予的权限。您可以使用 Amazon ECR 私有注册表权限策略进一步限定 IAM 实体的权限范围。有关更多信息，请参阅 [使用注册表权限](pull-through-cache-iam.md#pull-through-cache-registry-permissions)。
+ 使用缓存提取工作流创建的 Amazon ECR 存储库与任何其他 Amazon ECR 存储库受到同等对待。支持所有存储库功能，例如复制和镜像扫描。
+ 当 Amazon ECR 使用提取缓存操作代表您创建新存储库时，除非存在匹配的存储库创建模板，否则以下默认设置将应用于存储库。您可以使用存储库创建模板，定义 Amazon ECR 代表您创建的存储库所应用的设置。有关更多信息，请参阅 [用于控制在缓存拉取、推送时创建或复制操作期间创建的存储库的模板](repository-creation-templates.md)。
+ 标签不可变性 - 标签不可变性指定是否可以覆盖映像标签。默认情况下，映像标签是可变的（可以覆盖）。您可以修改标签行为，方法是在**可变**已选定时在**可变标签排除项**文本框中，或在**不可变**已选定时在**不可变标签排除项**文本框中配置标签排除项筛选条件。
+ 加密 – 使用默认 `AES256` 加密。
+ 存储库权限 – 已忽略，不应用任何存储库权限策略。
+ 生命周期策略 – 已忽略，不应用任何生命周期策略。
+ 资源标签 – 已忽略，不应用任何资源标签。
+ 使用缓存提取规则为存储库启用映像标签不变性，这将阻止 Amazon ECR 使用相同的标签更新映像。
+ 首次使用缓存提取规则提取映像时，可能需要通往互联网的路由。在某些情况下，需要通往互联网的路由，因此最好设置一条这样的路由，以免出现任何故障。因此，如果您已将 Amazon ECR 配置为使用接口 VPC 终端节点， AWS PrivateLink 则需要确保第一次拉取具有通往互联网的路由。一种方法是在同个 VPC 中创建带有互联网网关的公有子网，然后将流至互联网的所有出站流量从私有子网路由到公有子网。使用缓存提取规则进行的后续映像提取不需要此操作。有关更多信息，请参阅《Amazon Virtual Private Cloud 用户指南》中的[示例路由选项](https://docs.aws.amazon.com/vpc/latest/userguide/route-table-options.html)。**
# 将上游注册表与 Amazon ECR 私有注册表同步所需的 IAM 权限
除了对私有注册表进行身份验证以及推送和提取映像时所需的 Amazon ECR API 权限之外，还需要以下其他权限才能有效使用缓存提取规则。
+ `ecr:CreatePullThroughCacheRule` – 授予创建拉取缓存规则的权限。此权限必须通过基于身份的 IAM policy 授予。
+ `ecr:BatchImportUpstreamImage` – 授权检索外部镜像并将其导入到您的私有注册表。可以通过使用私有注册表权限策略、基于身份的 IAM policy 或通过使用基于资源的存储库权限策略授予此权限。有关使用存储库权限的更多信息，请参阅 [Amazon ECR 中的私有存储库策略](repository-policies.md)。
+ `ecr:CreateRepository` – 授予在私有注册表中创建存储库的权限。如果存储缓存图像的存储库不存在，则需要此权限。可以通过基于身份的 IAM policy 或私有注册表权限策略授予此权限。
## 使用注册表权限
Amazon ECR 私有注册表权限可用于限定各个 IAM 实体使用缓存提取的权限范围。如果 IAM policy 授予 IAM 实体的权限多于注册表权限策略授予的权限，则 IAM policy 优先。例如，如果用户已授予 `ecr:*` 权限，则无需额外的注册表级别权限。
### 要创建私有注册表的权限策略 (AWS 管理控制台)
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择您在其中配置私有注册表权限语句的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Registry permissions**（注册表权限）。
1. 在 **Registry permissions**（注册表权限）页面上，选择 **Generate statement**（生成语句）。
1. 对于要创建的每个缓存提取权限策略语句，请执行以下操作。
1. 对于 **Policy type**（策略类型），请选择 **Pull through cache policy**（推送缓存策略）。
1. 对于 **Statement id**（语句 ID），为推送缓存语句策略提供名称。
1. 对于 **IAM entities**（IAM 实体），指定要包含在策略中的用户、组或角色。
1. 对于 **Repository namespace**（存储库命名空间），选择要与策略关联的推送缓存规则。
1. 对于 **Repository names**（存储库名称），指定要应用规则的存储库基本名称。例如，如果您想在 Amazon ECR Public 上指定 Amazon Linux 存储库，存储库名称将为 `amazonlinux`。
### 要创建私有注册表的权限策略 (AWS CLI)
使用以下 AWS CLI 命令通过指定私有注册表权限 AWS CLI。
1. 创建名为 `ptc-registry-policy.json` 的本地文件，其中包含注册表策略的内容。以下示例授予创建存储库并从 Amazon ECR Public 中拉取镜像的 `ecr-pull-through-cache-user` 权限，Amazon ECR Public 是与之前创建的拉取缓存规则相关联的上游源。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "PullThroughCacheFromReadOnlyRole",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::111122223333:user/ecr-pull-through-cache-user"
},
"Action": [
"ecr:CreateRepository",
"ecr:BatchImportUpstreamImage"
],
"Resource": "arn:aws:ecr:us-east-1:111122223333:repository/ecr-public/*"
}
]
}
```
------
**重要**
仅当存储缓存镜像的存储库不存在时才需要 `ecr-CreateRepository` 权限。例如，如果存储库创建操作和镜像拉取操作是由单独的 IAM 主体（例如管理员和开发人员）完成。
1. 使用[put-registry-policy](https://docs.aws.amazon.com/cli/latest/reference/ecr/put-registry-policy.html)命令设置注册表策略。
```
aws ecr put-registry-policy \
--policy-text file://ptc-registry.policy.json
```
## 后续步骤
准备好开始使用缓存提取规则后，请执行以下后续步骤。
+ 创建缓存提取规则。有关更多信息，请参阅 [在 Amazon ECR 中创建缓存提取规则](pull-through-cache-creating-rule.md)。
+ 创建存储库创建模板。有了存储库创建模板，在为 Amazon ECR 在缓存提取操作期间代表您创建的新存储库定义设置时，您能拥有控制权。有关更多信息，请参阅 [用于控制在缓存拉取、推送时创建或复制操作期间创建的存储库的模板](repository-creation-templates.md)。
# 设置跨账户 ECR 到 ECR PTC 的权限
Amazon ECR 到 Amazon ECR（ECR 到 ECR）直通缓存功能支持在区域、 AWS 账户或两者之间自动同步图像。使用 ECR 到 ECR PTC，您可以将映像推送到主要 Amazon ECR 注册表，并配置提取缓存规则，将映像缓存在下游 Amazon ECR 注册表中。
## 跨账户 ECR 到 ECR 提取缓存所需的 IAM 策略
要在不同 AWS 账户的 Amazon ECR 注册表之间缓存映像，请在下游账户中创建 IAM 角色并配置本节中的策略以提供以下权限：
+ Amazon ECR 需要权限才能代表您从上游 Amazon ECR 注册表中提取映像。您可以通过创建 IAM 角色，然后在提取缓存规则中指定该角色，授予这些权限。
+ 上游注册表所有者还必须向缓存注册表所有者授予将映像拉入资源策略所需的权限。
**Topics**
+ [创建 IAM 角色来定义提取缓存权限](#ecr-policies-for-cross-account-ecr-to-ecr-pull-through-cache)
+ [为 IAM 角色创建信任策略](#ecr-creating-a-trust-policy-for-the-iam-role)
+ [在上游 Amazon ECR 注册表中创建资源策略](#ecr-creating-registry-permissions-policy-in-upstream-registry)
### 创建 IAM 角色来定义提取缓存权限
以下示例显示了一个权限策略，该策略授予 IAM 角色权限，代表您从上游 Amazon ECR 注册表中提取映像。当 Amazon ECR 担任该角色时，它将获得在此策略中指定的权限。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"ecr:GetDownloadUrlForLayer",
"ecr:GetAuthorizationToken",
"ecr:BatchImportUpstreamImage",
"ecr:BatchGetImage",
"ecr:GetImageCopyStatus",
"ecr:InitiateLayerUpload",
"ecr:UploadLayerPart",
"ecr:CompleteLayerUpload",
"ecr:PutImage"
],
"Resource": "*"
}
]
}
```
------
### 为 IAM 角色创建信任策略
以下示例显示了一个信任策略，该策略将 Amazon ECR 穿过缓存确定为可以担任该角色的 AWS 服务主体。
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "pullthroughcache.ecr.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
```
------
### 在上游 Amazon ECR 注册表中创建资源策略
上游 Amazon ECR 注册表所有者还必须添加注册表策略或存储库策略，以授予下游注册表所有者执行以下操作所需的权限。
**注意**
只有**跨账户** ECR 到 ECR 拉取缓存配置才需要以下资源策略。对于**同账户、跨区域**的直通缓存，您只需要前几节中显示的 IAM 角色策略和信任策略。当上游和下游注册管理机构在同一个账户中时，不需要主 AWS 账户委托人权限。
```
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::444455556666:root"
},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer",
"ecr:BatchImportUpstreamImage",
"ecr:GetImageCopyStatus"
],
"Resource": "arn:aws:ecr:region:111122223333:repository/*"
}
```
# 在 Amazon ECR 中创建缓存提取规则
对于包含您要在 Amazon ECR 私有注册表中缓存的映像的每个上游注册表，您必须创建缓存提取规则。
对于需要使用密钥进行身份验证的上游注册表，您必须以 Secrets Manager 密钥存储凭证。您可以使用现有的 密钥或创建一个新密钥。您可以在 Amazon ECR 控制台或 Secrets Manager 控制台中创建 Secrets Manager 密钥。要使用 Secrets Manager 控制台而不是 Amazon ECR 控制台创建 Secrets Manager 密钥，请参阅[将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中](pull-through-cache-creating-secret.md)。
## 先决条件
+ 请验证您是否拥有创建缓存提取规则的适当 IAM 权限。有关信息，请参阅[将上游注册表与 Amazon ECR 私有注册表同步所需的 IAM 权限](pull-through-cache-iam.md)。
+ 对于需要使用密钥进行身份验证的上游注册表：如果要使用现有密钥，则请验证 Secrets Manager 密钥是否满足以下要求：
+ 密钥的名称以 `ecr-pullthroughcache/` 开头。 AWS 管理控制台 仅显示带有 `ecr-pullthroughcache/` 前缀的 Secrets Manager 密钥。
+ 密钥所在的账户和区域必须与缓存提取规则所在的账户和区域相匹配。
## 要创建缓存提取规则 (AWS 管理控制台)
以下步骤演示如何使用 Amazon ECR 控制台创建缓存提取规则和 Secrets Manager 密钥。要使用 Secrets Manager 控制台创建密钥，请参阅[将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中](pull-through-cache-creating-secret.md)。
### 对于 Amazon ECR Public、Kubernetes 容器注册表或 Quay
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在**步骤 1：指定来源**页面上，对于**注册表**，请从上游注册表的列表中选择 Amazon ECR Public、Kubernetes 或 Quay，然后选择**下一步**。
1. 在**步骤 2：指定目标**页面上，对于 **Amazon ECR 存储库前缀**，请指定在缓存从源公有注册表中提取的映像时要使用的存储库命名空间前缀，然后选择**下一步**。默认情况下，已填充命名空间，但也可以指定自定义命名空间。
1. 在**步骤 3：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个缓存提取重复上一步骤。单独为每个区域创建了缓存提取规则。
### 对于 Docker Hub
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在**步骤 1：指定来源**页面上，对于**注册表**，选择 **Docker Hub**，然后选择**下一步**。
1. 在**步骤 2：配置身份验证**页面上，对于**上游凭证**，您必须以 AWS Secrets Manager 密钥存储 Docker Hub 的身份验证凭证。您可以指定现有密钥，也可以使用 Amazon ECR 控制台创建新密钥。
1. 要使用现有密钥，请选择**使用现有 AWS 密钥**。对于**密钥名称**，使用下拉列表选择现有的密钥，然后选择**下一步**。
**注意**
AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 密钥。密钥还必须与缓存提取规则位于相同的账户和区域。
1. 要创建新密钥，请选择**创建 AWS 密钥**，执行以下操作，然后选择**下一步**。
1. 在**密钥名称**中，请为密钥指定一个描述性名称。密钥名称必须包含 1-512 个 Unicode 字符。
1. 在 **Docker Hub 电子邮件**中，指定您的 Docker Hub 电子邮件。
1. 在 **Docker Hub 访问令牌**中，请指定 Docker Hub 访问令牌。有关如何创建 Docker Hub 访问令牌的更多信息，请参阅 Docker 文档中的 [Create and manage access tokens](https://docs.docker.com/security/for-developers/access-tokens/)。
1. 在**步骤 3：指定目标**页面上，对于 **Amazon ECR 存储库前缀**，请指定在缓存从源公有注册表中提取的映像时要使用的存储库命名空间，然后选择**下一步**。
默认情况下，已填充命名空间，但也可以指定自定义命名空间。
1. 在**步骤 4：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个缓存提取重复上一步骤。单独为每个区域创建了缓存提取规则。
### 对于 GitHub 容器注册表
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在 “**步骤 1：指定来源**” 页面上，对于 “注册表”，选择 “**GitHub 容器注册****表**”，然后选择 “**下一步**”。
1. 在 “**步骤 2：配置身份验证**” 页面上，对于**上游凭证**，您必须将 GitHub 容器注册表的身份验证凭据存储在 AWS Secrets Manager 密钥中。您可以指定现有密钥，也可以使用 Amazon ECR 控制台创建新密钥。
1. 要使用现有密钥，请选择**使用现有 AWS 密钥**。对于**密钥名称**，使用下拉列表选择现有的密钥，然后选择**下一步**。
**注意**
AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 密钥。密钥还必须与缓存提取规则位于相同的账户和区域。
1. 要创建新密钥，请选择**创建 AWS 密钥**，执行以下操作，然后选择**下一步**。
1. 在**密钥名称**中，请为密钥指定一个描述性名称。密钥名称必须包含 1-512 个 Unicode 字符。
1. 对于**GitHub 容器注册表用户名**，请指定您的 GitHub 容器注册表用户名。
1. 对于**GitHub 容器注册表访问令牌**，请指定您的 GitHub 容器注册表访问令牌。有关创建 GitHub 访问令牌的更多信息，请参阅 GitHub 文档中的[管理您的个人访问令牌](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)。
1. 在**步骤 3：指定目标**页面上，对于 **Amazon ECR 存储库前缀**，请指定在缓存从源公有注册表中提取的映像时要使用的存储库命名空间，然后选择**下一步**。
默认情况下，已填充命名空间，但也可以指定自定义命名空间。
1. 在**步骤 4：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个缓存提取重复上一步骤。单独为每个区域创建了缓存提取规则。
### 对于 Microsoft Azure 容器注册表
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在**步骤 1：指定来源**页面上，执行以下操作。
1. 在**注册表**中，请选择**Microsoft Azure 容器注册表**
1. 在**源注册表 URL** 中，请指定 Microsoft Azure 容器注册表的名称，然后选择**下一步**。
**重要**
您只需要指定前缀，因为系统已代表您填充 `.azurecr.io` 后缀。
1. 在**步骤 2：配置身份验证**页面上，对于**上游凭证**，您必须以 AWS Secrets Manager 密钥存储 Microsoft Azure 容器注册表的身份验证凭证。您可以指定现有密钥，也可以使用 Amazon ECR 控制台创建新密钥。
1. 要使用现有密钥，请选择**使用现有 AWS 密钥**。对于**密钥名称**，使用下拉列表选择现有的密钥，然后选择**下一步**。
**注意**
AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 密钥。密钥还必须与缓存提取规则位于相同的账户和区域。
1. 要创建新密钥，请选择**创建 AWS 密钥**，执行以下操作，然后选择**下一步**。
1. 在**密钥名称**中，请为密钥指定一个描述性名称。密钥名称必须包含 1-512 个 Unicode 字符。
1. 在 **Microsoft Azure 容器注册表用户名**中，请指定 Microsoft Azure 容器注册表用户名。
1. 在 **Microsoft Azure 容器注册表访问令牌**中，请指定 Microsoft Azure 容器注册表访问令牌。有关如何创建 Microsoft Azure 容器注册表访问令牌的更多信息，请参阅 Microsoft Azure 文档中的[创建令牌 - 门户](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions#create-token---portal)。
1. 在**步骤 3：指定目标**页面上，对于 **Amazon ECR 存储库前缀**，请指定在缓存从源公有注册表中提取的映像时要使用的存储库命名空间，然后选择**下一步**。
默认情况下，已填充命名空间，但也可以指定自定义命名空间。
1. 在**步骤 4：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个缓存提取重复上一步骤。单独为每个区域创建了缓存提取规则。
### 对于 GitLab 容器注册表
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在 “**步骤 1：指定来源**” 页面上，对于 “注册表”，选择 “ GitLab 容器注册表”，然后选择 “下一步”。
1. 在 “**步骤 2：配置身份验证**” 页面上，对于**上游凭证**，您必须将 GitLab 容器注册表的身份验证凭据存储在 AWS Secrets Manager 密钥中。您可以指定现有密钥，也可以使用 Amazon ECR 控制台创建新密钥。
1. 要使用现有密钥，请选择**使用现有 AWS 密钥**。对于**密钥名称**，使用下拉列表选择现有的密钥，然后选择**下一步**。有关使用 Secrets Manager 控制台创建 Secrets Manager 密钥的更多信息，请参阅[将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中](pull-through-cache-creating-secret.md)。
**注意**
AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 密钥。密钥还必须与缓存提取规则位于相同的账户和区域。
1. 要创建新密钥，请选择**创建 AWS 密钥**，执行以下操作，然后选择**下一步**。
1. 在**密钥名称**中，请为密钥指定一个描述性名称。密钥名称必须包含 1-512 个 Unicode 字符。
1. 对于**GitLab 容器注册表用户名**，请指定您的 GitLab 容器注册表用户名。
1. 对于**GitLab 容器注册表访问令牌**，请指定您的 GitLab 容器注册表访问令牌。有关创建 GitLab 容器注册表访问令牌的更多信息，请参阅 GitLab 文档中的[个人访问令](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)[牌、群组](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html)[访问令牌或项目访问令牌](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html)。
1. 在**步骤 3：指定目标**页面上，对于 **Amazon ECR 存储库前缀**，请指定在缓存从源公有注册表中提取的映像时要使用的存储库命名空间，然后选择**下一步**。
默认情况下，已填充命名空间，但也可以指定自定义命名空间。
1. 在**步骤 4：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个缓存提取重复上一步骤。单独为每个区域创建了缓存提取规则。
### 对于您的 AWS 账户中的 Amazon ECR 私有注册表
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在**步骤 1：指定上游**页面上，在**注册表**中选择 **Amazon ECR 私有**和**此账户**。对于**区域**，选择上游 Amazon ECR 注册表的区域，然后选择**下一步**。
1. 在**步骤 2：指定命名空间**页面上，对于**缓存命名空间**，选择是创建带**特定前缀**还是**不带前缀**的提取缓存存储库。如果选择**特定前缀**，则必须指定一个前缀名称，该名称将用作命名空间的一部分，用于缓存来自上游注册表的映像。
1. 对于**上游命名空间**，选择是否从上游注册表中存在的**特定前缀**中提取。如果选择**不带前缀**，则可以从上游注册表中的任何存储库中提取数据。如果出现提示，请指定上游存储库前缀，然后选择**下一步**。
**注意**
要了解有关自定义缓存和上游命名空间的更多信息，请参阅 [自定义 ECR 到 ECR 提取缓存的存储库前缀](pull-through-cache-private-wildcards.md)。
1. 在**步骤 3：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个提取缓存，重复这些步骤。单独为每个区域创建了缓存提取规则。
### 对于来自其他 AWS 账户的 Amazon ECR 私有注册表
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在**步骤 1：指定上游**页面上，在**注册表**中选择 **Amazon ECR 私有**和**跨账户**。对于**区域**，选择上游 Amazon ECR 注册表的区域。在 “**账户**” 中，指定上游 Amazon ECR 注册表的 AWS 账户 ID，然后选择 “**下一步**”。
1. 在**步骤 2：指定权限**页面上，对于 **IAM 角色**，选择用于跨账户提取缓存访问的角色，然后选择**创建**。
**注意**
请务必选择使用在 [跨账户 ECR 到 ECR 提取缓存所需的 IAM 策略](pull-through-cache-private.md#pull-through-cache-private-permissions) 中创建的权限的 IAM 角色。
1. 在**步骤 3：指定命名空间**页面上，对于**缓存命名空间**，选择是创建带**特定前缀**还是**不带前缀**的提取缓存存储库。如果选择**特定前缀**，则必须指定一个前缀名称，该名称将用作命名空间的一部分，用于缓存来自上游注册表的映像。
1. 对于**上游命名空间**，选择是否从上游注册表中存在的**特定前缀**中提取。如果选择**不带前缀**，则可以从上游注册表中的任何存储库中提取数据。如果出现提示，请指定上游存储库前缀，然后选择**下一步**。
**注意**
要了解有关自定义缓存和上游命名空间的更多信息，请参阅 [自定义 ECR 到 ECR 提取缓存的存储库前缀](pull-through-cache-private-wildcards.md)。
1. 在**步骤 4：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个提取缓存，重复这些步骤。单独为每个区域创建了缓存提取规则。
### 对于链条注册表
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 从导航栏中，选择要配置私有注册表设置的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在 **Pull through cache configuration**（缓存提取配置）页面上，选择 **Add rule**（添加规则）。
1. 在 “**步骤 1：指定源**页面” 中，对于 “注册表”，选择 Chainguard Registry，下一步。
1. 在 “**步骤 2：配置身份验证**” 页面上，对于**上游凭据**，您必须将 Chainguard Registr AWS Secrets Manager y 的身份验证凭据存储在密钥中。您可以指定现有密钥，也可以使用 Amazon ECR 控制台创建新密钥。
1. 要使用现有密钥，请选择**使用现有 AWS 密钥**。对于**密钥名称**，使用下拉列表选择现有的密钥，然后选择**下一步**。有关使用 Secrets Manager 控制台创建 Secrets Manager 密钥的更多信息，请参阅[将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中](pull-through-cache-creating-secret.md)。
**注意**
AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 密钥。密钥还必须与缓存提取规则位于相同的账户和区域。
1. 要创建新密钥，请选择**创建 AWS 密钥**，执行以下操作，然后选择**下一步**。
1. 在**密钥名称**中，请为密钥指定一个描述性名称。密钥名称必须包含 1-512 个 Unicode 字符。
1. 对于 **Chainguard 注册表用户名**，请指定您的 Chainguard 注册表用户名。
1. 对于 **Chainguard Registry 拉取令牌**，请指定您的 Chainguard Regist 有关创建 Chainguard Registry 拉取令牌的更多信息，请参阅 Chainguard 文档中的[使用拉取令牌进行身份验证](https://edu.chainguard.dev/chainguard/chainguard-images/chainguard-registry/authenticating/#authenticating-with-a-pull-token)。
1. 在 “**步骤 3：指定目标**页面” 中，在 **Amazon ECR 存储库前缀中**，指定缓存从源注册表中提取的图像时要使用的存储库命名空间，然后选择**下一步**。
默认情况下，已填充命名空间，但也可以指定自定义命名空间。
1. 在**步骤 4：审核并创建**页面上，审核缓存提取规则配置，然后选择**创建**。
1. 对要创建的每个缓存提取重复上一步骤。单独为每个区域创建了缓存提取规则。
## 要创建缓存提取规则 (AWS CLI)
使用 [create-pull-through-cache- AWS CLI rule](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-pull-through-cache-rule.html) 命令为 Amazon ECR 私有注册表创建直通缓存规则。对于需要使用密钥进行身份验证的上游注册表，您必须以 Secrets Manager 密钥存储凭证。要使用 Secrets Manager 控制台创建密钥，请参阅[将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中](pull-through-cache-creating-secret.md)。
针对每个支持的上游注册表提供以下示例。
### 对于 Amazon ECR Public
以下示例为 Amazon ECR 公有注册表创建一个缓存提取规则。它指定了存储库前缀 `ecr-public`，这导致使用缓存提取规则创建的每个存储库都具有 `ecr-public/upstream-repository-name` 命名方案。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix ecr-public \
--upstream-registry-url public.ecr.aws \
--region us-east-2
```
### 对于 Kubernetes 容器注册表
以下示例为 Kubernetes 公有注册表创建了一个缓存提取规则。它指定了存储库前缀 `kubernetes`，这导致使用缓存提取规则创建的每个存储库都具有 `kubernetes/upstream-repository-name` 命名方案。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix kubernetes \
--upstream-registry-url registry.k8s.io \
--region us-east-2
```
### 对于 Quay
以下示例为 Quay 公有注册表创建了一个缓存提取规则。它指定了存储库前缀 `quay`，这导致使用推送缓存规则创建的每个存储库都具有命名方案 `quay/upstream-repository-name`。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix quay \
--upstream-registry-url quay.io \
--region us-east-2
```
### 对于 Docker Hub
以下示例为 Docker Hub 注册表创建了一个缓存提取规则。它指定了存储库前缀 `docker-hub`，这导致使用缓存提取规则创建的每个存储库都具有 `docker-hub/upstream-repository-name` 命名方案。您必须指定包含 Docker Hub 凭证的密钥的完整 Amazon 资源名称（ARN）。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix docker-hub \
--upstream-registry-url registry-1.docker.io \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### 对于 GitHub 容器注册表
以下示例为 GitHub 容器注册表创建了通过缓存规则。它指定了存储库前缀 `github`，这导致使用缓存提取规则创建的每个存储库都具有 `github/upstream-repository-name` 命名方案。您必须指定包含您的 GitHub 容器注册凭证的密钥的完整 Amazon 资源名称 (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix github \
--upstream-registry-url ghcr.io \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### 对于 Microsoft Azure 容器注册表
以下示例为 Microsoft Azure 容器注册表创建了一个缓存提取规则。它指定了存储库前缀 `azure`，这导致使用缓存提取规则创建的每个存储库都具有 `azure/upstream-repository-name` 命名方案。您必须指定包含 Microsoft Azure 容器注册表凭证的密钥的完整 Amazon 资源名称（ARN）。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix azure \
--upstream-registry-url myregistry.azurecr.io \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### 对于 GitLab 容器注册表
以下示例为 GitLab 容器注册表创建了通过缓存规则。它指定了存储库前缀 `gitlab`，这导致使用缓存提取规则创建的每个存储库都具有 `gitlab/upstream-repository-name` 命名方案。您必须指定包含您的 GitLab 容器注册凭证的密钥的完整 Amazon 资源名称 (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix gitlab \
--upstream-registry-url registry.gitlab.com \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
### 对于您的 AWS 账户中的 Amazon ECR 私有注册表
以下示例在同一 AWS 账户中为跨区域的 Amazon ECR 私有注册表创建直通缓存规则。它指定了存储库前缀 `ecr`，这导致使用缓存提取规则创建的每个存储库都具有 `ecr/upstream-repository-name` 命名方案。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix ecr \
--upstream-registry-url aws_account_id.dkr.ecr.region.amazonaws.com \
--region us-east-2
```
### 对于来自其他 AWS 账户的 Amazon ECR 私有注册表
以下示例在同一 AWS 账户中为跨区域的 Amazon ECR 私有注册表创建直通缓存规则。它指定了存储库前缀 `ecr`，这导致使用缓存提取规则创建的每个存储库都具有 `ecr/upstream-repository-name` 命名方案。您必须指定具有在 [在 Amazon ECR 中创建缓存提取规则](#pull-through-cache-creating-rule) 中创建的权限的 IAM 角色的完整 Amazon 资源名称 (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix ecr \
--upstream-registry-url aws_account_id.dkr.ecr.region.amazonaws.com \
--custom-role-arn arn:aws:iam::aws_account_id:role/example-role \
--region us-east-2
```
### 对于链条注册表
以下示例为 Chainguard Registry 创建了通过缓存规则。它指定了存储库前缀 `chainguard`，这导致使用缓存提取规则创建的每个存储库都具有 `chainguard/upstream-repository-name` 命名方案。您必须指定包含您的 Chainguard Registry 凭证的密钥的完整亚马逊资源名称 (ARN)。
```
aws ecr create-pull-through-cache-rule \
--ecr-repository-prefix chainguard \
--upstream-registry-url cgr.dev \
--credential-arn arn:aws:secretsmanager:us-east-2:111122223333:secret:ecr-pullthroughcache/example1234 \
--region us-east-2
```
## 后续步骤
创建缓存提取规则后，请执行以下后续步骤：
+ 创建存储库创建模板。有了存储库创建模板，在为 Amazon ECR 在缓存提取操作期间代表您创建的新存储库定义设置时，您能拥有控制权。有关更多信息，请参阅 [用于控制在缓存拉取、推送时创建或复制操作期间创建的存储库的模板](repository-creation-templates.md)。
+ 验证缓存提取规则。在验证缓存提取规则时，Amazon ECR 会与上游注册表建立网络连接，验证它是否可以访问包含上游注册表凭证的 Secrets Manager 密钥，以及身份验证是否成功。有关更多信息，请参阅 [验证 Amazon ECR 中的缓存提取规则](pull-through-cache-working-validating.md)。
+ 开始使用缓存提取规则。有关更多信息，请参阅 [在 Amazon ECR 中使用缓存提取规则来提取映像](pull-through-cache-working-pulling.md)。
# 验证 Amazon ECR 中的缓存提取规则
创建缓存提取规则后，对于需要身份验证的上游注册表，您可以验证该规则是否正常工作。在验证缓存提取规则时，Amazon ECR 会与上游注册表建立网络连接，验证它是否可以访问包含上游注册表凭证的 Secrets Manager 密钥，并确认身份验证是否成功。
在开始使用缓存提取规则之前，请确认您拥有适当的 IAM 权限。有关更多信息，请参阅 [将上游注册表与 Amazon ECR 私有注册表同步所需的 IAM 权限](pull-through-cache-iam.md)。
## 删除缓存提取规则（AWS 管理控制台）
以下步骤演示如何使用 Amazon ECR 控制台验证缓存提取规则。
1. 打开 Amazon ECR 控制台，网址为[https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/)。
1. 在导航栏中，选择包含要验证的缓存提取规则的区域。
1. 在导航窗格中，选择 **Private registry**（私有注册表）、**Pull through cache**（缓存提取）。
1. 在**缓存提取配置**页面上，选择要验证的缓存提取规则。然后，使用**操作**下拉菜单并选择**查看详细信息**。
1. 在缓存提取规则详细信息页面上，使用**操作**下拉菜单并选择**验证身份验证**。Amazon ECR 将显示带结果的横幅。
1. 对要验证的每个缓存提取规则重复上述步骤。
## 删除缓存提取规则（AWS CLI）
[validate-pull-through-cache- AWS CLI rule](https://docs.aws.amazon.com/cli/latest/reference/ecr/validate-pull-through-cache-rule.html) 命令用于验证 Amazon ECR 私有注册表的直通缓存规则。以下示例使用 `ecr-public` 命名空间前缀。将该值替换为要验证的缓存提取规则的前缀值。
```
aws ecr validate-pull-through-cache-rule \
--ecr-repository-prefix ecr-public \
--region us-east-2
```
在响应中，`isValid` 参数指示验证是否成功。如果为 `true`，则表示 Amazon ECR 能够访问上游注册表，并且身份验证成功。如果为 `false`，则表示存在问题且验证失败。`failure` 参数指示原因。
# 在 Amazon ECR 中使用缓存提取规则来提取映像
以下示例演示在使用缓存提取规则来提取映像时要使用的命令语法。如果您在使用拉取缓存规则拉取上游镜像时收到错误，请参阅 [排查 Amazon ECR 中的缓存提取问题](error-pullthroughcache.md)，以查看最常见的错误以及如何解决这些错误。
在开始使用缓存提取规则之前，请确认您拥有适当的 IAM 权限。有关更多信息，请参阅 [将上游注册表与 Amazon ECR 私有注册表同步所需的 IAM 权限](pull-through-cache-iam.md)。
**注意**
以下示例使用使用的默认 Amazon ECR 存储库命名空间值。 AWS 管理控制台 确保您使用已配置的 Amazon ECR 私有存储库 URI。
## 对于 Amazon ECR Public
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/ecr-public/repository_name/image_name:tag
```
## Kubernetes 容器注册表
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/kubernetes/repository_name/image_name:tag
```
## Quay
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/quay/repository_name/image_name:tag
```
## Docker Hub
对于 Docker Hub 官方映像：
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/library/image_name:tag
```
**注意**
对于 Docker Hub 官方映像，必须包含 `/library` 前缀。对于所有其他 Docker Hub 存储库，应省略 `/library` 前缀。
对于所有其他 Docker Hub 映像：
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/repository_name/image_name:tag
```
## GitHub 容器注册表
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/github/repository_name/image_name:tag
```
## Microsoft Azure 容器注册表
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/azure/repository_name/image_name:tag
```
## GitLab 容器注册表
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/gitlab/repository_name/image_name:tag
```
## Chainguard 注册表
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/chainguard/repository_name/image_name:tag
```
# 将您的上游存储库凭证存储在 AWS Secrets Manager 密钥中
为需要身份验证的上游存储库创建缓存提取规则时，您必须以 Secrets Manager 密钥存储凭证。使用 Secrets Manager 密钥可能会产生费用。有关更多信息，请参阅[AWS Secrets Manager 定价](https://aws.amazon.com/secrets-manager/pricing/)。
以下过程引导您了解如何为每个支持的上游存储库创建 Secrets Manager 密钥。您可以选择在 Amazon ECR 控制台中使用“创建缓存提取规则”工作流程来创建密钥，而不是使用 Secrets Manager 控制台来创建密钥。有关更多信息，请参阅 [在 Amazon ECR 中创建缓存提取规则](pull-through-cache-creating-rule.md)。
------
#### [ Docker Hub ]
**为 Docker Hub 凭证创建 Secrets Manager 密钥（AWS 管理控制台）**创建 Secrets Manager 密钥（AWS 管理控制台）
1. 打开 Secrets Manager 控制台，网址为[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 选择**存储新密钥**。
1. 在**选择密钥类型**页面上，执行以下操作：
1. 对于**密钥类型**，请选择**其他密钥类型**。
1. 在**键/值对**中，为 Docker Hub 凭证创建两行键/值对。您可以在密钥中存储最多 65536 个字节。
1. 对于第一 key/value 对，指定`username`为密钥，将您的 Docker Hub 用户名指定为值。
1. 对于第二 key/value 对，指定`accessToken`为密钥，将您的 Docker Hub 访问令牌指定为值。有关如何创建 Docker Hub 访问令牌的更多信息，请参阅 Docker 文档中的 [Create and manage access tokens](https://docs.docker.com/security/for-developers/access-tokens/)。
1. 对于**加密密钥**，保留默认的 **aws/secretsmanager** AWS KMS key 值，然后选择**下一步**。使用此密钥不产生任何费用。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的 [Secrets Manager 中的密钥加密和解密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html)。
**重要**
您必须使用默认 `aws/secretsmanager` 加密密钥来加密密钥。Amazon ECR 不支持为此密钥使用客户自主管理型密钥（CMK）。
1. 在**配置密钥**页面上，执行以下操作：
1. 输入一个描述性的 **Secret name**（密钥名称）和 **Description**（说明）。密钥名称必须包含 1-512 个 Unicode 字符，并且以 `ecr-pullthroughcache/` 为前缀。
**重要**
Amazon ECR AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 机密。
1. （可选）在**标签**部分中，在您的密钥中添加一个或多个标签。有关标记策略，请参阅《AWS Secrets Manager 用户指南》**中的[标记 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。请不要将敏感信息存储在标签中，因为它们未加密。
1. （可选）在**资源权限**，要将资源策略添加到您的密钥中，请选择**编辑权限**。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将权限策略附加到 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html)。
1. （可选）在**复制密钥**中，要将您的密钥复制到另一个密钥 AWS 区域，请选择**复制密钥**。您可以现在复制密钥，也可以回头再复制。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将密钥复制到其他区域](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html)。
1. 选择**下一步**。
1. （可选）在 **Configure rotation**（配置轮换）页面上，您可以启用自动轮换。您也可以现在保持关闭轮换，然后稍后将其打开。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[轮换 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。选择**下一步**。
1. 在 **Review (审核)** 页上，审核您的密钥详细信息，然后选择 **Store (存储)**。
Secrets Manager 将返回到密钥列表。如果您的新密钥未显示，请选择 Refresh（刷新）按钮。
------
#### [ GitHub Container Registry ]
**为你的 GitHub 容器注册表凭证创建 Secrets Manager 密钥 (AWS 管理控制台)**创建 Secrets Manager 密钥（AWS 管理控制台）
1. 打开 Secrets Manager 控制台，网址为[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 选择**存储新密钥**。
1. 在**选择密钥类型**页面上，执行以下操作：
1. 对于**密钥类型**，请选择**其他密钥类型**。
1. 在**键/值对**中，为您的 GitHub 凭据创建两行。您可以在密钥中存储最多 65536 个字节。
1. 对于第一 key/value 对，指定`username`为密钥，将您的 GitHub用户名指定为值。
1. 对于第二 key/value 对，指定`accessToken`为密钥，将 GitHub 访问令牌指定为值。有关创建 GitHub 访问令牌的更多信息，请参阅 GitHub 文档中的[管理您的个人访问令牌](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)。
1. 对于**加密密钥**，保留默认的 **aws/secretsmanager** AWS KMS key 值，然后选择**下一步**。使用此密钥不产生任何费用。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的 [Secrets Manager 中的密钥加密和解密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html)。
**重要**
您必须使用默认 `aws/secretsmanager` 加密密钥来加密密钥。Amazon ECR 不支持为此密钥使用客户自主管理型密钥（CMK）。
1. 在 **Configure secret**（配置密钥）页面上，执行以下操作：
1. 输入一个描述性的 **Secret name**（密钥名称）和 **Description**（说明）。密钥名称必须包含 1-512 个 Unicode 字符，并且以 `ecr-pullthroughcache/` 为前缀。
**重要**
Amazon ECR AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 机密。
1. （可选）在**标签**部分中，在您的密钥中添加一个或多个标签。有关标记策略，请参阅《AWS Secrets Manager 用户指南》**中的[标记 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。请不要将敏感信息存储在标签中，因为它们未加密。
1. （可选）在**资源权限**，要将资源策略添加到您的密钥中，请选择**编辑权限**。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将权限策略附加到 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html)。
1. （可选）在**复制密钥**中，要将您的密钥复制到另一个密钥 AWS 区域，请选择**复制密钥**。您可以现在复制密钥，也可以回头再复制。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将密钥复制到其他区域](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html)。
1. 选择**下一步**。
1. （可选）在 **Configure rotation**（配置轮换）页面上，您可以启用自动轮换。您也可以现在保持关闭轮换，然后稍后将其打开。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[轮换 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。选择**下一步**。
1. 在 **Review (审核)** 页上，审核您的密钥详细信息，然后选择 **Store (存储)**。
Secrets Manager 将返回到密钥列表。如果您的新密钥未显示，请选择 Refresh（刷新）按钮。
------
#### [ Microsoft Azure Container Registry ]
**为 Microsoft Azure 容器注册表凭证创建 Secrets Manager 密钥（AWS 管理控制台）**创建 Secrets Manager 密钥（AWS 管理控制台）
1. 打开 Secrets Manager 控制台，网址为[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 选择**存储新密钥**。
1. 在**选择密钥类型**页面上，执行以下操作：
1. 对于**密钥类型**，请选择**其他密钥类型**。
1. 在**键/值对**中，为 Microsoft Azure 凭证创建两行键/值对。您可以在密钥中存储最多 65536 个字节。
1. 对于第一 key/value 对，指定`username`为密钥，将你的 Microsoft Azure 容器注册表用户名指定为值。
1. 对于第二 key/value 对，指定`accessToken`为密钥，将你的 Microsoft Azure 容器注册表访问令牌指定为值。有关如何创建 Microsoft Azure 访问令牌的更多信息，请参阅 Microsoft Azure 文档中的[创建令牌 - 门户](https://learn.microsoft.com/en-us/azure/container-registry/container-registry-repository-scoped-permissions#create-token---portal)。
1. 对于**加密密钥**，保留默认的 **aws/secretsmanager** AWS KMS key 值，然后选择**下一步**。使用此密钥不产生任何费用。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的 [Secrets Manager 中的密钥加密和解密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html)。
**重要**
您必须使用默认 `aws/secretsmanager` 加密密钥来加密密钥。Amazon ECR 不支持为此密钥使用客户自主管理型密钥（CMK）。
1. 在 **Configure secret**（配置密钥）页面上，执行以下操作：
1. 输入一个描述性的 **Secret name**（密钥名称）和 **Description**（说明）。密钥名称必须包含 1-512 个 Unicode 字符，并且以 `ecr-pullthroughcache/` 为前缀。
**重要**
Amazon ECR AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 机密。
1. （可选）在**标签**部分中，在您的密钥中添加一个或多个标签。有关标记策略，请参阅《AWS Secrets Manager 用户指南》**中的[标记 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。请不要将敏感信息存储在标签中，因为它们未加密。
1. （可选）在**资源权限**，要将资源策略添加到您的密钥中，请选择**编辑权限**。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将权限策略附加到 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html)。
1. （可选）在**复制密钥**中，要将您的密钥复制到另一个密钥 AWS 区域，请选择**复制密钥**。您可以现在复制密钥，也可以回头再复制。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将密钥复制到其他区域](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html)。
1. 选择**下一步**。
1. （可选）在 **Configure rotation**（配置轮换）页面上，您可以启用自动轮换。您也可以现在保持关闭轮换，然后稍后将其打开。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[轮换 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。选择**下一步**。
1. 在 **Review (审核)** 页上，审核您的密钥详细信息，然后选择 **Store (存储)**。
Secrets Manager 将返回到密钥列表。如果您的新密钥未显示，请选择 Refresh（刷新）按钮。
------
#### [ GitLab Container Registry ]
**为你的 GitLab 容器注册表凭证创建 Secrets Manager 密钥 (AWS 管理控制台)**创建 Secrets Manager 密钥（AWS 管理控制台）
1. 打开 Secrets Manager 控制台，网址为[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 选择**存储新密钥**。
1. 在**选择密钥类型**页面上，执行以下操作：
1. 对于**密钥类型**，请选择**其他密钥类型**。
1. 在**键/值对**中，为您的 GitLab 凭据创建两行。您可以在密钥中存储最多 65536 个字节。
1. 对于第一 key/value 对，指定`username`作为密钥，将您的 GitLab 容器注册表用户名指定为值。
1. 对于第二 key/value 对，指定`accessToken`为密钥，将您的 GitLab 容器注册表访问令牌指定为值。有关创建 GitLab 容器注册表访问令牌的更多信息，请参阅 GitLab 文档中的[个人访问令](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html)[牌、群组](https://docs.gitlab.com/ee/user/group/settings/group_access_tokens.html)[访问令牌或项目访问令牌](https://docs.gitlab.com/ee/user/project/settings/project_access_tokens.html)。
1. 对于**加密密钥**，保留默认的 **aws/secretsmanager** AWS KMS key 值，然后选择**下一步**。使用此密钥不产生任何费用。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的 [Secrets Manager 中的密钥加密和解密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html)。
**重要**
您必须使用默认 `aws/secretsmanager` 加密密钥来加密密钥。Amazon ECR 不支持为此密钥使用客户自主管理型密钥（CMK）。
1. 在 **Configure secret**（配置密钥）页面上，执行以下操作：
1. 输入一个描述性的 **Secret name**（密钥名称）和 **Description**（说明）。密钥名称必须包含 1-512 个 Unicode 字符，并且以 `ecr-pullthroughcache/` 为前缀。
**重要**
Amazon ECR AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 机密。
1. （可选）在**标签**部分中，在您的密钥中添加一个或多个标签。有关标记策略，请参阅《AWS Secrets Manager 用户指南》**中的[标记 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。请不要将敏感信息存储在标签中，因为它们未加密。
1. （可选）在**资源权限**，要将资源策略添加到您的密钥中，请选择**编辑权限**。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将权限策略附加到 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html)。
1. （可选）在**复制密钥**中，要将您的密钥复制到另一个密钥 AWS 区域，请选择**复制密钥**。您可以现在复制密钥，也可以回头再复制。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将密钥复制到其他区域](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html)。
1. 选择**下一步**。
1. （可选）在 **Configure rotation**（配置轮换）页面上，您可以启用自动轮换。您也可以现在保持关闭轮换，然后稍后将其打开。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[轮换 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。选择**下一步**。
1. 在 **Review (审核)** 页上，审核您的密钥详细信息，然后选择 **Store (存储)**。
Secrets Manager 将返回到密钥列表。如果您的新密钥未显示，请选择 Refresh（刷新）按钮。
------
#### [ Chainguard Registry ]
**为你的 Chainguard 凭证创建 Secrets Manager 密钥 ()AWS 管理控制台**创建 Secrets Manager 密钥（AWS 管理控制台）
1. 打开 Secrets Manager 控制台，网址为[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 选择**存储新密钥**。
1. 在**选择密钥类型**页面上，执行以下操作：
1. 对于**密钥类型**，请选择**其他密钥类型**。
1. 在**键/值对**中，为您的 Chainguard 凭据创建两行。您可以在密钥中存储最多 65536 个字节。
1. 对于第一 key/value 对，指定`username`为密钥，将您的 Chainguard Registry 用户名指定为值。
1. 对于第二 key/value 对，指定`accessToken`为密钥，将您的 Chainguard Registry 访问令牌指定为值。有关创建 Chainguard Registry 拉取令牌的更多信息，请参阅 Chainguard 文档中的[使用拉取令牌进行身份验证](https://edu.chainguard.dev/chainguard/chainguard-images/chainguard-registry/authenticating/#authenticating-with-a-pull-token)。
1. 对于**加密密钥**，保留默认的 **aws/secretsmanager** AWS KMS key 值，然后选择**下一步**。使用此密钥不产生任何费用。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的 [Secrets Manager 中的密钥加密和解密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/security-encryption.html)。
**重要**
您必须使用默认 `aws/secretsmanager` 加密密钥来加密密钥。Amazon ECR 不支持为此密钥使用客户自主管理型密钥（CMK）。
1. 在 **Configure secret**（配置密钥）页面上，执行以下操作：
1. 输入一个描述性的 **Secret name**（密钥名称）和 **Description**（说明）。密钥名称必须包含 1-512 个 Unicode 字符，并且以 `ecr-pullthroughcache/` 为前缀。
**重要**
Amazon ECR AWS 管理控制台 仅显示名称使用`ecr-pullthroughcache/`前缀的 Secrets Manager 机密。
1. （可选）在**标签**部分中，在您的密钥中添加一个或多个标签。有关标记策略，请参阅《AWS Secrets Manager 用户指南》**中的[标记 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。请不要将敏感信息存储在标签中，因为它们未加密。
1. （可选）在**资源权限**，要将资源策略添加到您的密钥中，请选择**编辑权限**。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将权限策略附加到 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_resource-policies.html)。
1. （可选）在**复制密钥**中，要将您的密钥复制到另一个密钥 AWS 区域，请选择**复制密钥**。您可以现在复制密钥，也可以回头再复制。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[将密钥复制到其他区域](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create-manage-multi-region-secrets.html)。
1. 选择**下一步**。
1. （可选）在 **Configure rotation**（配置轮换）页面上，您可以启用自动轮换。您也可以现在保持关闭轮换，然后稍后将其打开。有关更多信息，请参阅《AWS Secrets Manager 用户指南》**中的[轮换 Secrets Manager 密钥](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotating-secrets.html)。选择**下一步**。
1. 在 **Review (审核)** 页上，审核您的密钥详细信息，然后选择 **Store (存储)**。
Secrets Manager 将返回到密钥列表。如果您的新密钥未显示，请选择 Refresh（刷新）按钮。
------
# 自定义 ECR 到 ECR 提取缓存的存储库前缀
提取缓存规则同时支持 **ecr 存储库前缀**和**上游存储库前缀**。**ecr 存储库前缀**是 Amazon ECR 缓存注册表中与规则关联的存储库命名空间前缀。所有使用此前缀的存储库都将成为规则中定义的上游注册表的支持提取缓存的存储库。例如，前缀 `prod` 将应用于以 `prod/` 开头的所有存储库。要将某模板应用于注册表中没有关联提取缓存规则的所有存储库，请使用 `ROOT` 作为前缀。
**重要**
前缀末尾始终应用假定的 `/`。如果您指定 `ecr-public` 为前缀，Amazon ECR 会将其视为 `ecr-public/`。
**上游存储库前缀**与上游存储库名称匹配。默认情况下，它设置为 `ROOT`，允许与任何上游存储库进行匹配。只有当 Amazon ECR 存储库前缀的值不是 `ROOT` 时，您才能设置**上游存储库前缀**。
下表根据提取缓存规则中的前缀配置，显示了缓存存储库名称和上游存储库名称之间的映射。
| 缓存命名空间 | 上游命名空间 | 映射关系（缓存存储库 → 上游存储库） |
| --- | --- | --- |
| ecr-public | ROOT（默认） | `ecr-public/my-app/image1` → `my-app/image1` `ecr-public/my-app/image2` → `my-app/image2` |
| ROOT | ROOT | `my-app/image1` → `my-app/image1` |
| team-a | team-a | `team-a/myapp/image1` → `team-a/myapp/image1` |
| my-app | upstream-app | `my-app/image1` → `upstream-app/image1` |
# 排查 Amazon ECR 中的缓存提取问题
使用拉取缓存规则拉取上游镜像时，您可能会收到以下常见错误。
**存储库不存在**
指示存储库不存在的错误通常是由该存储库不存在于 Amazon ECR 私有注册表中或者未向拉取上游镜像的 IAM 主体授予 `ecr:CreateRepository` 权限所致。要解决此错误，您应该验证拉取命令中的存储库 URI 正确，已向拉取上游镜像的 IAM 主体授予所需的 IAM 权限，或者在执行上游镜像拉取之前，已在您的 Amazon ECR 私有注册表中创建要向其推送上游镜像的存储库。有关所需 IAM 权限的更多信息，请参阅 [将上游注册表与 Amazon ECR 私有注册表同步所需的 IAM 权限](pull-through-cache-iam.md)。
以下是此错误的示例。
```
Error response from daemon: repository 111122223333.dkr.ecr.us-east-1.amazonaws.com/ecr-public/amazonlinux/amazonlinux not found: name unknown: The repository with name 'ecr-public/amazonlinux/amazonlinux' does not exist in the registry with id '111122223333'
```
**找不到请求的映像**
指示找不到镜像的错误通常是由该镜像不存在于上游注册表中或者未向拉取上游镜像的 IAM 主体授予 `ecr:BatchImportUpstreamImage` 权限但已在 Amazon ECR 私有注册表中创建存储库所致。要解决此错误，您应验证上游镜像和镜像标签名称正确且存在，并且已向拉取上游镜像的 IAM 主体授予所需的 IAM 权限。有关所需 IAM 权限的更多信息，请参阅 [将上游注册表与 Amazon ECR 私有注册表同步所需的 IAM 权限](pull-through-cache-iam.md)。
以下是此错误的示例。
```
Error response from daemon: manifest for 111122223333.dkr.ecr.us-east-1.amazonaws.com/ecr-public/amazonlinux/amazonlinux:latest not found: manifest unknown: Requested image not found
```
**从 Docker Hub 存储库中提取时发生 403 Forbidden 错误**
从标记为 **Docker 官方映像**的 Docker Hub 存储库中提取时，您必须在使用的 URI 中包含 `/library/`。例如 `aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/library/image_name:tag`。如果您省略 Docker Hub 官方映像的 `/library/`，则当您尝试使用提取缓存规则来提取映像时，系统将返回 `403 Forbidden` 错误。有关更多信息，请参阅 [在 Amazon ECR 中使用缓存提取规则来提取映像](pull-through-cache-working-pulling.md)。
以下是此错误的示例。
```
Error response from daemon: failed to resolve reference "111122223333.dkr.ecr.us-west-2.amazonaws.com/docker-hub/amazonlinux:2023": pulling from host 111122223333.dkr.ecr.us-west-2.amazonaws.com failed with status code [manifests 2023]: 403 Forbidden
```