推送及提取圖片

本頁說明如何使用 Docker 推送及提取容器映像檔。如果您要排解 Google Kubernetes Engine 的問題，本文也會說明如何使用 crictl 工具提取映像檔。

如要瞭解如何部署至 Google Cloud 執行階段環境，請參閱「部署至 Google Cloud」。

如需列出、標記及刪除映像檔的操作說明，請參閱管理映像檔。

事前準備

1. 如果目標存放區不存在，請建立新的存放區。
2. 您必須至少具備存放區的 Artifact Registry Writer 存取權。
3. 如果尚未安裝 Docker，請安裝。

必要的角色

如要取得推送及提取映像檔所需的權限，請要求管理員授予您存放區的下列 IAM 角色：

• 提取映像檔： Artifact Registry 讀取者 (roles/artifactregistry.reader)
• 為映像檔加上標記並推送： Artifact Registry 寫入者 (roles/artifactregistry.writer)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和機構的存取權」。

您或許還可透過自訂角色或其他預先定義的角色取得必要權限。

向存放區進行驗證

使用 Docker 存放區時，無論是透過 Docker 或其他第三方用戶端，都必須驗證存放區。本節提供快速摘要，說明成功完成驗證的必要條件。如需詳細操作說明，請參閱為 Docker 設定驗證機制。

使用憑證輔助程式

如果是 gcloud CLI 憑證輔助程式或獨立式憑證輔助程式，您使用的 Artifact Registry 主機必須位於 Docker 設定檔中。

Artifact Registry 不會自動將所有登錄主機新增至 Docker 設定檔。如果設定的登錄檔數量龐大，Docker 回應時間會大幅變慢。如要盡量減少設定檔中的登錄項目數量，請將所需主機新增至檔案。

如要確認已設定的主機，請執行下列指令來顯示設定檔內容：

• Linux：cat ~/.docker/config.json
• Windows：type %USERPROFILE%\.docker\config.json

「credHelpers」部分會列出已設定的 Artifact Registry Docker 主機。主機名稱結尾為 -docker.pkg.dev。以下範例顯示為 gcloud CLI 憑證輔助程式設定的部分主機。

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

如果清單中沒有要使用的主機，請再次執行憑證輔助程式來新增主機。舉例來說，下列指令會新增 us-west1-docker.pkg.dev。

• gcloud CLI 憑證輔助程式：

  gcloud auth configure-docker us-west1-docker.pkg.dev
  

• 獨立式憑證輔助程式

  docker-credential-gcr configure-docker us-west1-docker.pkg.dev
  

使用存取憑證

如要使用存取權杖進行驗證，請產生權杖，並透過 docker login 指令將權杖當做密碼使用。權杖的效期為 60 分鐘，因此您應在標記、推送或提取映像檔前不久進行驗證。

以下範例會使用服務帳戶模擬產生存取權杖，然後向 Artifact Registry 進行驗證。您必須具備服務帳戶符記建立者角色 (roles/iam.serviceAccountTokenCreator) 的權限，才能以這種方式產生符記。

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

如果您沒有模擬服務帳戶的權限，可以在 gcloud CLI 工作階段中啟用服務帳戶，然後取得權杖。詳情請參閱存取權杖驗證設定操作說明。

使用服務帳戶金鑰

如果是服務帳戶金鑰，請使用金鑰做為密碼，搭配 docker login 指令。

舉例來說，下列指令會使用檔案 key.json 中經過 Base64 編碼的服務帳戶金鑰，向 us-west1-docker.pkg.dev 進行驗證。

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

詳情請參閱服務帳戶金鑰驗證設定說明。

推送映像檔

存放區模式：標準

如要將本機映像檔推送至標準 Docker 存放區，請使用存放區名稱標記映像檔，然後推送映像檔。

如果 Artifact Registry Docker 存放區已啟用標記不可變更性，標記就必須一律參照存放區中的相同映像檔摘要。您無法在推送至存放區的同一個映像檔的其他版本上使用該標記。如要進一步瞭解映像檔摘要、標記和標記不可變更性，請參閱「容器映像檔版本」。

如果圖片較大，則適用下列限制：

上傳時間

如果使用存取權杖向 Artifact Registry 進行驗證，權杖的效期只有 60 分鐘。如果預計上傳時間會超過 60 分鐘，請使用其他驗證方法。

圖片大小

構件大小上限為 5 TB。

Artifact Registry 不支援 Docker 分塊上傳。 部分工具支援以分塊上傳或單一整體上傳的方式上傳大型圖片。您必須使用單體式上傳功能，才能將映像檔推送至 Artifact Registry。

為本機映像檔加上標記

1. 確認您已通過存放區驗證。

2. 找出映像檔名稱。完整圖片名稱的格式如下：

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   替換下列值：

   • LOCATION 是儲存映像檔的存放區位置，可以是地區或多地區。
   • PROJECT-ID 是您的 Google Cloud 控制台專案 ID。 如果專案 ID 包含冒號 (:)，請參閱「網域範圍專案」。
   • REPOSITORY 是儲存映像檔的存放區名稱。
   • IMAGE 是映像檔的名稱，可以和映像檔的本機名稱不同。

   舉例來說，假設圖片具有下列特徵：

   • 存放區位置：us-west1
   • 存放區名稱：my-repo
   • 專案 ID：my-project
   • 本機圖片名稱：my-image
   • 目標映像檔名稱：test-image

   這個範例的圖片名稱為：

   us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   如要瞭解映像檔名稱格式的詳細資料，包括處理網域範圍專案，請參閱「存放區和映像檔名稱」。

3. 使用存放區名稱標記本機映像檔。

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   將 SOURCE-IMAGE 替換為本機映像檔名稱或映像檔 ID，並將 TAG 替換為標記。如未指定標記，Docker 會套用預設的 latest 標記。

   如果啟用不可變更的映像檔標記設定，每個映像檔版本 (包括 latest 標記) 都必須使用不重複的標記。如果存放區中同一個映像檔的其他版本已使用該標記，您就無法將映像檔推送至存放區。如要確認是否已為存放區啟用這項設定，請執行下列指令：

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

   以上一個步驟的範例圖片為例，如果本機圖片 my-image 位於目前目錄中，您可以使用下列指令：

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   如要套用特定標記，請使用下列指令：

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   如要搭配範例圖片使用 staging 標記，請在指令中加入 :staging：

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

將加上標記的映像檔推送至 Artifact Registry

1. 確認您已通過存放區驗證。

   如果您使用 gcloud auth configure-docker 或 docker-credential-gcr configure-docker 設定 Docker 用戶端，請確認目標主機名稱位於 Docker 設定檔中。

2. 執行下列指令，推送加上標記的映像檔：

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   這項指令會推送含有 latest 標記的映像檔。如果您要推送含有不同標記的映像檔，請執行下列指令：

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

推送映像檔時，系統會將其儲存在指定存放區。

推送映像檔後，您可以：

• 前往Google Cloud 控制台查看映像檔。

• 執行 gcloud 指令，查看映像檔的標記和自動產生的摘要：

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  以下輸出範例顯示截斷的映像檔摘要，但指令一律會傳回完整的映像檔摘要。

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

使用 Docker 提取映像檔

1. 確認您已通過存放區驗證。

   如果您使用 gcloud auth configure-docker 或 docker-credential-gcr configure-docker 設定 Docker 用戶端，請確認目標主機名稱位於 Docker 設定檔中。

2. 如要從存放區提取，請使用下列指令：

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   或

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

   替換下列值：

   • LOCATION 是儲存映像檔的存放區位置，可以是地區或多地區。
   • PROJECT 是您的 Google Cloud 控制台專案 ID。 如果專案 ID 包含冒號 (:)，請參閱「網域範圍專案」。
   • PROJECT 是您的 Google Cloud 主控台專案 ID。
   • REPOSITORY 是儲存映像檔的存放區名稱。
   • IMAGE 是存放區中的映像檔名稱。
   • TAG 是要提取的映像檔版本標記。
   • IMAGE-DIGEST 是映像檔內容的 sha256 雜湊值。每個映像檔版本都有專屬的映像檔摘要。在 Google Cloud 主控台中按一下特定映像檔，即可查看該映像檔的中繼資料。摘要會列為「映像檔摘要」。

   舉例來說，假設圖片具有下列特徵：

   • 存放區位置：us-west1
   • 存放區名稱：my-repo
   • 專案 ID：my-project
   • 圖片名稱：test-image
   • 標記：staging

   提取映像檔的指令如下：

   docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Docker 會下載指定的映像檔。

如果您從遠端存放區要求映像檔，遠端存放區會從上游來源下載並快取映像檔 (如果沒有快取副本)。

如果您從虛擬存放區要求映像檔，Artifact Registry 會在上游存放區中搜尋要求的映像檔。如果您要求的版本在多個上游存放區中提供，Artifact Registry 會根據為虛擬存放區設定的優先順序設定，選擇要使用的上游存放區。

舉例來說，假設虛擬存放區的上游存放區有下列優先順序設定：

• main-repo：優先順序設為 100
• secondary-repo1：優先順序設為 80。
• secondary-repo2：優先順序設為 80。
• test-repo：優先順序設為 20。

main-repo 的優先順序值最高，因此虛擬存放區一律會先搜尋這個存放區。

secondary-repo1 和 secondary-repo2 的優先順序都設為 80。如果 Artifact Registry 在 main-repo 中找不到要求的映像檔，就會接著搜尋這些存放區。由於兩者優先順序值相同，如果兩個存放區都有該版本，Artifact Registry 可以選擇從任一存放區提供映像檔。

test-repo 的優先順序值最低，如果其他上游存放區都沒有儲存構件，就會提供該構件。

使用 crictl提取圖片

crictl 是實用的指令列工具，CRI 執行階段開發人員不必設定 Kubernetes 元件，就能偵錯執行階段。如果 Google Kubernetes Engine 節點使用 containerd 執行階段，您可以使用 crictl 從 Artifact Registry 提取映像檔。

由於 crictl 主要為疑難排解工具，因此無法使用部分 Docker 指令，例如推送或標記映像檔。

如要從 Artifact Registry 提取映像檔，請按照下列步驟操作：

1. 前往 Google Cloud 控制台的「VM Instances」(VM 執行個體) 頁面。

   前往「VM instances」(VM 執行個體) 頁面

2. 透過 SSH 連線至要排解問題的節點。

3. 取得存取權杖，以便向存放區進行驗證。

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. 使用 crictl pull --creds 和 access_token 值提取映像檔

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   或

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   輸出內容如下：

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

後續步驟

• 瞭解如何管理標記及刪除圖片。
• 如果要在 Compute Engine 上執行容器，請進一步瞭解 Compute Engine 上的容器。
• 使用 crictl 偵錯 Kubernetes 節點
• 瞭解如何使用 crictl 從私人 Artifact Registry 存放區提取映像檔
• 進一步瞭解如何設定crictl 映像檔登錄