本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。
# 將上游登錄檔與 Amazon ECR 私有登錄檔同步
使用提取快取規則，您可以將上游登錄檔的內容與 Amazon ECR 私有登錄檔同步。
Amazon ECR 目前支援為下列上游登錄檔建立提取快取規則：
+ Amazon ECR Public、Kubernetes 容器映像登錄檔和 Quay （不需要身分驗證）
+ Docker Hub、Microsoft Azure Container Registry、GitHub Container Registry、GitLab Container Registry 和 Chainguard Registry （需要使用 AWS Secrets Manager 秘密進行身分驗證）
+ Amazon ECR （需要使用 IAM AWS 角色進行身分驗證）
對於 GitLab Container Registry，Amazon ECR 僅支援使用 GitLab 的軟體即服務 (SaaS) 產品提取快取。如需使用 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 登錄檔屬於不同的 AWS 帳戶，您必須建立 IAM 角色。如需建立 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 政策授予他們的許可。您可以使用 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)。
+ 標籤不可變性 – 標籤不可變性指定是否可以覆寫影像標籤。根據預設，影像標籤是可變的 （可以覆寫）。您可以在****選取 **Mutable 時，透過在 Mutable 標籤排除**文字方塊中設定標籤排除篩選條件來修改標籤行為，或在選取 **Immutable 時設定 Immutable 標籤排除**文字方塊。 ****
+ 加密 – 使用預設`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 政策授予此許可。
+ `ecr:BatchImportUpstreamImage` – 授予檢索外部映像並將其匯入到您的私有登錄檔的許可。可以藉由使用身分型 IAM 政策的私有登錄檔許可政策或藉由使用資源型儲存庫許可政策來授予此許可。如需使用儲存庫許可的詳細資訊，請參閱 [Amazon ECR 中的私有儲存庫政策](repository-policies.md)。
+ `ecr:CreateRepository` – 授予在私有登錄檔中建立儲存庫的許可。如果存放快取映像的儲存庫尚不存在，則需要此許可。可以由身分型 IAM 政策或私有登錄檔許可政策授予此許可。
## 使用登錄檔許可
Amazon ECR 私有登錄檔許可可用來設定個別 IAM 實體使用提取快取的許可範圍。如果 IAM 實體擁有的由 IAM 政策授予的許可多過登錄檔許可政策授予的許可，則 IAM 政策優先。例如，如果使用者已具有 `ecr:*` 許可，則在登錄檔層級不需要額外的許可。
### 建立私有登錄檔的許可政策 (AWS 管理主控台)
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon 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` 的本機檔案。下列範例會授予 `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 公共，Kubernetes 容器登錄檔或 Quay
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇要在其中進行私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定來源**頁面上，針對**登錄檔**，從上游登錄檔清單中選擇 Amazon ECR 公共、Kubernetes 或 Quay，接著選擇**下一步**。
1. 在**步驟 2：指定目的地**頁面上，針對 **Amazon ECR 儲存庫字首**，指定快取從來源公有登錄檔提取的映像時要使用的儲存庫命名空間字首，接著選擇**下一步**。預設會填入命名空間，但也可以指定自訂命名空間。
1. 在**步驟 3：檢閱並建立**頁面上，檢閱提取快取規則組態，接著選擇**建立**。
1. 為要建立的每個提取快取重複前面的步驟。系統會針對每個區域分別建立提取快取規則。
### 對於 Docker Hub
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇要在其中進行私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定來源**頁面上，針對**登錄檔**選擇 **Docker Hub**、**下一步**。
1. 在**步驟 2：設定身分驗證**頁面上，針對**上游憑證**，您必須將 Docker Hub 的身分驗證憑證儲存在 AWS Secrets Manager 秘密中。您可以指定現有秘密，或使用 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 文件中的[建立和管理存取字符](https://docs.docker.com/security/for-developers/access-tokens/)。
1. 在**步驟 3：指定目的地**頁面上，針對 **Amazon ECR 儲存庫字首**，指定快取從來源公有登錄檔提取的映像時要使用的儲存庫命名空間，接著選擇**下一步**。
預設會填入命名空間，但也可以指定自訂命名空間。
1. 在**步驟 4：檢閱並建立**頁面上，檢閱提取快取規則組態，接著選擇**建立**。
1. 為要建立的每個提取快取重複前面的步驟。系統會針對每個區域分別建立提取快取規則。
### 對於 GitHub Container Registry
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇要在其中進行私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定來源**頁面上，針對**登錄檔**選擇 **GitHub Container Registry**、**下一步**。
1. 在**步驟 2：設定身分驗證**頁面上，針對**上游憑證**，您必須將 GitHub Container Registry 的身分驗證憑證儲存在 AWS Secrets Manager 秘密中。您可以指定現有秘密，或使用 Amazon ECR 主控台建立新秘密。
1. 若要使用現有的秘密，請選擇**使用現有的 AWS 秘密**。針對**秘密名稱**，使用下拉式選單選取您現有的秘密，接著選擇**下一步**。
**注意**
AWS 管理主控台 只會顯示使用 `ecr-pullthroughcache/`字首名稱的 Secrets Manager 秘密。秘密也必須位於在其中建立提取快取規則的相同帳戶和區域中。
1. 若要建立新秘密，請選擇**建立 AWS 秘密**，執行下列動作，接著選擇**下一步**。
1. 針對**秘密名稱**，指定秘密的描述性名稱。秘密名稱必須含有 1 至 512 個 Unicode 字元。
1. 針對 **GitHub Container Registry 使用者名稱**，請指定您的 GitHub Container Registry 使用者名稱。
1. 對於 **GitHub Container Registry 存取字符**，請指定您的 GitHub Container Registry 存取字符。如需建立 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 Container Registry
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇要在其中進行私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定來源**頁面上，執行下列動作。
1. 針對**登錄檔**，選擇 **Microsoft Azure Container Registry**
1. 針對**來源登錄檔 URL**，指定 Microsoft Azure Container Registry 的名稱，接著選擇**下一步**。
**重要**
您只需要指定字首，因為會代表您填入 `.azurecr.io` 字尾。
1. 在**步驟 2：設定身分驗證**頁面上，針對**上游憑證**，您必須將 Microsoft Azure Container Registry 的身分驗證憑證儲存在 AWS Secrets Manager 秘密中。您可以指定現有秘密，或使用 Amazon ECR 主控台建立新秘密。
1. 若要使用現有的秘密，請選擇**使用現有的 AWS 秘密**。針對**秘密名稱**，使用下拉式選單選取您現有的秘密，接著選擇**下一步**。
**注意**
AWS 管理主控台 只會顯示使用 `ecr-pullthroughcache/`字首名稱的 Secrets Manager 秘密。秘密也必須位於在其中建立提取快取規則的相同帳戶和區域中。
1. 若要建立新秘密，請選擇**建立 AWS 秘密**，執行下列動作，接著選擇**下一步**。
1. 針對**秘密名稱**，指定秘密的描述性名稱。秘密名稱必須含有 1 至 512 個 Unicode 字元。
1. 對於 **Microsoft Azure Container Registry 使用者名稱**，請指定您的 MMicrosoft Azure Container Registry 使用者名稱。
1. 對於 **Microsoft Azure Container Registry 存取字符**，請指定您的 Microsoft Azure Container Registry 存取字符。如需建立 Microsoft Azure Container Registry 存取字符的詳細資訊，請參閱 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. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇要在其中進行私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定來源**頁面上，針對登錄檔，選擇 GitLab Container Registry，下一步。
1. 在**步驟 2：設定身分驗證**頁面上，對於**上游憑證**，您必須將 GitLab Container Registry 的身分驗證憑證存放在秘密 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 Container Registry 使用者名稱**，指定您的 GitLab Container Registry 使用者名稱。
1. 對於 **GitLab Container Registry 存取權杖**，指定您的 GitLab Container Registry 存取權杖。如需建立 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. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列中，選擇您要在其中設定私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定上游**頁面上，針對**登錄**檔，選擇 **Amazon ECR Private** 和**此帳戶**。針對**區域**，選取上游 Amazon ECR 登錄檔的區域，然後選擇**下一步**。
1. 在**步驟 2：指定命名空間**頁面上，針對**快取命名空間**，選擇是否建立具有**特定字首**或**無字首**的提取快取儲存庫。如果您選取**特定字首**，則必須指定字首名稱，做為從上游登錄檔快取映像的命名空間的一部分。
1. 針對**上游命名空間**，選擇是否從上游登錄檔中存在**的特定字首**提取。如果**未選取字首**，您可以從上游登錄檔中的任何儲存庫提取 。如果出現提示，請指定上游儲存庫字首，然後選擇**下一步**。
**注意**
若要進一步了解自訂快取和上游命名空間，請參閱 [自訂 ECR 到 ECR 提取快取的儲存庫字首](pull-through-cache-private-wildcards.md)。
1. 在**步驟 3：檢閱並建立**頁面上，檢閱提取快取規則組態，接著選擇**建立**。
1. 針對您要建立的每個提取快取重複這些步驟。系統會針對每個區域分別建立提取快取規則。
### 對於來自另一個 AWS 帳戶的 Amazon ECR 私有登錄
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon 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 角色**，選取要用於跨帳戶提取快取存取的角色，然後選擇**建立**。
**注意**
請務必選取使用在 中建立之許可的 IAM 角色[跨帳戶 ECR 到 ECR 提取快取所需的 IAM 政策](pull-through-cache-private.md#pull-through-cache-private-permissions)。
1. 在**步驟 3：指定命名空間**頁面上，針對**快取命名空間**，選擇是否建立具有**特定字首**或**無字首**的提取快取儲存庫。如果您選取**特定字首**，則必須指定字首名稱，做為從上游登錄檔快取映像的命名空間的一部分。
1. 針對**上游命名空間**，選擇是否從上游登錄檔中存在**的特定字首**提取。如果**未選取字首**，您可以從上游登錄檔中的任何儲存庫提取 。如果出現提示，請指定上游儲存庫字首，然後選擇**下一步**。
**注意**
若要進一步了解自訂快取和上游命名空間，請參閱 [自訂 ECR 到 ECR 提取快取的儲存庫字首](pull-through-cache-private-wildcards.md)。
1. 在**步驟 4：檢閱並建立**頁面上，檢閱提取快取規則組態，接著選擇**建立**。
1. 針對您要建立的每個提取快取重複這些步驟。系統會針對每個區域分別建立提取快取規則。
### 對於 Chainguard 登錄檔
1. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇要在其中進行私有登錄檔設定的區域。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在 **Pull through cache configuration** (提取快取組態) 頁面上，選擇 **Add rule** (新增規則)。
1. 在**步驟 1：指定來源**頁面上，針對登錄檔，選擇 Chainguard 登錄檔，下一步。
1. 在**步驟 2：設定身分驗證**頁面上，對於**上游憑證**，您必須將 Chainguard Registry 的身分驗證憑證存放在秘密 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. 針對 **Chainguard 登錄檔使用者名稱**，指定您的 Chainguard 登錄檔使用者名稱。
1. 針對 **Chainguard Registry 提取字符**，指定您的 Chainguard Registry 提取字符。如需建立 Chainguard 登錄檔提取字符的詳細資訊，請參閱 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-rule](https://docs.aws.amazon.com/cli/latest/reference/ecr/create-pull-through-cache-rule.html) AWS CLI 命令來建立 Amazon ECR 私有登錄檔的提取快取規則。對於需要使用秘密進行身分驗證的上游登錄檔，您必須將登入資料存放在 Secrets Manager 秘密中。若要使用 Secrets Manager 主控台建立秘密，請參閱 [將上游儲存庫登入資料存放在 AWS Secrets Manager 秘密中](pull-through-cache-creating-secret.md)。
提供給每個受支援的登錄檔的下列範例。
### 對於 Amazon ECR Public
下列範例會為 Amazon ECR Public 登錄檔建立提取快取規則。其會指定 `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 Container Registry
下列範例會為 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 Resource Name (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 Container Registry
下列範例會建立 GitHub Container Registry 的提取快取規則。其會指定 `github` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `github/upstream-repository-name` 的命名規則。您必須指定秘密包含 GitHub Container Registry 憑證的完整 Amazon Resource Name (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 Container Registry
下列範例會建立 Microsoft Azure Container Registry 的提取快取規則。其會指定 `azure` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `azure/upstream-repository-name` 的命名規則。您必須指定秘密包含 Microsoft Azure Container Registry 憑證的完整 Amazon Resource Name (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 Container Registry 的提取快取規則。其會指定 `gitlab` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `gitlab/upstream-repository-name` 的命名規則。您必須指定包含 GitLab Container Registry 登入資料之秘密的完整 Amazon Resource Name (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` 的命名規則。您必須使用在 中建立的許可來指定 IAM 角色的完整 Amazon Resource Name (ARN)[在 Amazon ECR 中建立提取快取規則](#pull-through-cache-creating-rule)。
```
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 登錄檔
下列範例會建立 Chainguard Registry 的提取快取規則。其會指定 `chainguard` 的儲存庫字首，這會導致使用提取快取規則建立的每個儲存庫具有 `chainguard/upstream-repository-name` 的命名規則。您必須指定包含 Chainguard 登錄檔登入資料之秘密的完整 Amazon Resource Name (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. 在 [https://console.aws.amazon.com/ecr/](https://console.aws.amazon.com/ecr/) 開啟 Amazon ECR 主控台。
1. 從導覽列選擇包含提取快取規則的區域以進行驗證。
1. 在導覽窗格中，選擇 **Private registry** (私有登錄檔)、**Pull through cache** (提取快取)。
1. 在**提取快取組態**頁面上，選取要驗證的提取快取規則。接著，使用**動作**下拉式選單並選擇**檢視詳細資料**。
1. 在提取快取規則詳細資料頁面上，使用**動作**下拉式選單，然後選擇**驗證身分驗證**。Amazon ECR 將顯示寫著結果的橫幅。
1. 針對您要驗證的每個提取快取規則重複這些步驟。
## 若要驗證提取快取規則 (AWS CLI)
[validate-pull-through-cache-rule](https://docs.aws.amazon.com/cli/latest/reference/ecr/validate-pull-through-cache-rule.html) AWS CLI 命令用於驗證 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)。
**注意**
下列範例使用 AWS 管理主控台 使用的預設 Amazon ECR 儲存庫命名空間值。確保使用已設定的 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 Container Registry
```
docker pull aws_account_id.dkr.ecr.region.amazonaws.com/github/repository_name/image_name:tag
```
## Microsoft Azure Container Registry
```
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/)。
下列程序將逐步指引您為每個支援的上游儲存庫建立 Secret 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. 前往以下位置開啟機密管理員控制台：[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 選擇 **Store a new secret** (存放新機密)。
1. 在**選擇秘密類型**頁面上，執行下列動作。
1. 針對**機密類型**，選擇**其他類型的機密**。
1. 在**鍵值對**中，為您的 Docker Hub 憑證建立兩個資料列。秘密當中最多可以存放 65536 個位元組。
1. 針對第一個鍵值對，請指定 `username` 為鍵，並指定您的 Docker Hub 使用者名稱為值。
1. 針對第二個鍵值對，請指定 `accessToken` 為鍵，並指定您的 Docker Hub 存取字符為值。如需建立 Docker Hub 存取字符的詳細資訊，請參閱 Docker 文件中的[建立和管理存取字符](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. (選用) 在 **Tags** (標籤) 區段，將標籤新增到秘密。關於標記策略，請參閱 *《AWS Secrets Manager 使用者指南》*中的[標記 Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。請勿在標籤中存放敏感資訊，因為標籤並未加密。
1. (選用) 若要將資源政策新增至秘密，請在 **Resource permissions** (資源使用權限) 中選擇 **Edit permissions** (編輯許可)。如需詳細資訊，請參閱 *《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 會傳回秘密清單。如果您的新秘密沒有顯示，請選擇重新整理按鈕。
------
#### [ GitHub Container Registry ]
**若要為 GitHub Container Registry 憑證建立 Secrets Manager 秘密 (AWS 管理主控台)**若要建立 Secrets Manager 秘密 (AWS 管理主控台)
1. 前往以下位置開啟機密管理員控制台：[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 選擇 **Store a new secret** (存放新機密)。
1. 在**選擇秘密類型**頁面上，執行下列動作。
1. 針對**機密類型**，選擇**其他類型的機密**。
1. 在**鍵/值對**中，為您的 GitHub 憑證建立兩個資料列。秘密當中最多可以存放 65536 個位元組。
1. 針對第一個鍵值對，請指定 `username` 為鍵，並指定您的 GitHub 使用者名稱為值。
1. 針對第二個鍵值對，請指定 `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. (選用) 在 **Tags** (標籤) 區段，將標籤新增到秘密。關於標記策略，請參閱 *《AWS Secrets Manager 使用者指南》*中的[標記 Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。請勿在標籤中存放敏感資訊，因為標籤並未加密。
1. (選用) 若要將資源政策新增至秘密，請在 **Resource permissions** (資源使用權限) 中選擇 **Edit permissions** (編輯許可)。如需詳細資訊，請參閱 *《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 會傳回秘密清單。如果您的新秘密沒有顯示，請選擇重新整理按鈕。
------
#### [ Microsoft Azure Container Registry ]
**若要為您的 Microsoft Azure Container Registry 憑證建立 Secrets Manager 秘密 (AWS 管理主控台)**若要建立 Secrets Manager 秘密 (AWS 管理主控台)
1. 前往以下位置開啟機密管理員控制台：[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 選擇 **Store a new secret** (存放新機密)。
1. 在**選擇秘密類型**頁面上，執行下列動作。
1. 針對**機密類型**，選擇**其他類型的機密**。
1. 在**鍵/值對**中，為您的 Microsoft Azure 憑證建立兩個資料列。秘密當中最多可以存放 65536 個位元組。
1. 針對第一個鍵值對，請指定 `username` 為鍵，並指定您的 Microsoft Azure Container Registry 使用者名稱為值。
1. 針對第二個鍵值對，請指定 `accessToken` 為鍵，並指定您的 Microsoft Azure Container Registry 存取字符為值。如需建立 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. (選用) 在 **Tags** (標籤) 區段，將標籤新增到秘密。關於標記策略，請參閱 *《AWS Secrets Manager 使用者指南》*中的[標記 Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。請勿在標籤中存放敏感資訊，因為標籤並未加密。
1. (選用) 若要將資源政策新增至秘密，請在 **Resource permissions** (資源使用權限) 中選擇 **Edit permissions** (編輯許可)。如需詳細資訊，請參閱 *《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 會傳回秘密清單。如果您的新秘密沒有顯示，請選擇重新整理按鈕。
------
#### [ GitLab Container Registry ]
**為您的 GitLab Container Registry 登入資料建立 Secrets Manager 秘密 (AWS 管理主控台)**若要建立 Secrets Manager 秘密 (AWS 管理主控台)
1. 前往以下位置開啟機密管理員控制台：[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 選擇 **Store a new secret** (存放新機密)。
1. 在**選擇秘密類型**頁面上，執行下列動作。
1. 針對**機密類型**，選擇**其他類型的機密**。
1. 在**金鑰/值對**中，為您的 GitLab 登入資料建立兩列。秘密當中最多可以存放 65536 個位元組。
1. 對於第一個金鑰/值對，將 指定`username`為金鑰，將 GitLab Container Registry 使用者名稱指定為值。
1. 對於第二個金鑰/值對，請將 指定`accessToken`為金鑰，並將 GitLab Container Registry 存取權杖指定為值。如需建立 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. (選用) 在 **Tags** (標籤) 區段，將標籤新增到秘密。關於標記策略，請參閱 *《AWS Secrets Manager 使用者指南》*中的[標記 Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。請勿在標籤中存放敏感資訊，因為標籤並未加密。
1. (選用) 若要將資源政策新增至秘密，請在 **Resource permissions** (資源使用權限) 中選擇 **Edit permissions** (編輯許可)。如需詳細資訊，請參閱 *《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 會傳回秘密清單。如果您的新秘密沒有顯示，請選擇重新整理按鈕。
------
#### [ Chainguard Registry ]
**為您的 Chainguard 登入資料建立 Secrets Manager 秘密 (AWS 管理主控台)**若要建立 Secrets Manager 秘密 (AWS 管理主控台)
1. 前往以下位置開啟機密管理員控制台：[https://console.aws.amazon.com/secretsmanager/](https://console.aws.amazon.com/secretsmanager/)。
1. 選擇 **Store a new secret** (存放新機密)。
1. 在**選擇秘密類型**頁面上，執行下列動作。
1. 針對**機密類型**，選擇**其他類型的機密**。
1. 在**金鑰/值對**中，為您的 Chainguard 登入資料建立兩列。秘密當中最多可以存放 65536 個位元組。
1. 對於第一個金鑰/值對，將 指定`username`為金鑰，將 Chainguard Registry 使用者名稱指定為值。
1. 對於第二個金鑰/值對，將 指定`accessToken`為金鑰，將 Chainguard Registry 存取權杖指定為值。如需建立 Chainguard 登錄檔提取字符的詳細資訊，請參閱 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. (選用) 在 **Tags** (標籤) 區段，將標籤新增到秘密。關於標記策略，請參閱 *《AWS Secrets Manager 使用者指南》*中的[標記 Secrets Manager 秘密](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets_tagging.html)。請勿在標籤中存放敏感資訊，因為標籤並未加密。
1. (選用) 若要將資源政策新增至秘密，請在 **Resource permissions** (資源使用權限) 中選擇 **Edit permissions** (編輯許可)。如需詳細資訊，請參閱 *《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 會傳回秘密清單。如果您的新秘密沒有顯示，請選擇重新整理按鈕。
------
# 自訂 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 | 上游應用程式 | `my-app/image1` → `upstream-app/image1` |
# 對 Amazon ECR 中的提取快取問題進行故障診斷
在使用提取快取規則提取上游映像時，以下是您可能會收到的最常見錯誤。
**儲存庫不存在**
指示儲存庫不存在的錯誤大多是因為儲存庫不存在於您的 Amazon ECR 私有登錄檔中，或是因為未授予 `ecr:CreateRepository` 許可給提取上游映像的 IAM 主體。若要解決此錯誤，您應該確認您提取命令中的儲存庫 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'
```
**找不到請求的映像**
指示找不到映像的錯誤大多是因為映像不存在於上游登錄檔中，或是因為未授予 `ecr:BatchImportUpstreamImage` 許可給提取上游映像的 IAM 主體，但已在您的 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
```
**403 從 Docker Hub 儲存庫提取時禁止**
從標記為 **Docker 官方映像**的 Docker Hub 儲存庫中提取時，您必須在您使用的 URI 中包含 `/library/`。例如 `aws_account_id.dkr.ecr.region.amazonaws.com/docker-hub/library/image_name:tag`。如果您省略 `/library/` Docker Hub 官方映像的 ，當您嘗試使用提取快取規則提取映像時，將會傳回`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
```