設定 Docker 適用的 Artifact Registry 驗證機制

本頁面說明如何設定 Docker，讓 Docker 向 Artifact Registry Docker 存放區進行驗證。

您不需要為 Cloud Build 或 Google Cloud執行階段環境 (例如 Google Kubernetes Engine 和 Cloud Run) 設定驗證，但應確認已設定必要的權限。

事前準備

  1. After installing the Google Cloud CLI, initialize it by running the following command: 

    gcloud init

    If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  2. (選用) 設定 gcloud CLI 指令的預設值。
  3. 請確認您用於驗證的帳戶是否具備存取 Artifact Registry 的權限。建議您使用服務帳戶，而非使用者帳戶。
  4. 如果尚未安裝 Docker，請安裝 Docker。Cloud Shell 已包含 Docker。
  5. Docker 需要特殊權限才能與登錄檔互動。在 Linux 或 Windows 上，將用來執行 Docker 指令的使用者新增至 Docker 安全性群組。在 macOS 上不需要執行這個步驟，因為 Docker Desktop 會以 root 使用者身分在虛擬機器上執行。

    Linux

    Docker 安全群組稱為 docker。如要新增使用者名稱，請執行下列指令：

          sudo usermod -a -G docker ${USER}

    Windows

    Docker 安全群組稱為 docker-users。如要透過管理員命令提示字元新增使用者，請執行下列指令：

            net localgroup docker-users DOMAIN\USERNAME /add

    其中：

    • DOMAIN 是您的 Windows 網域。
    • USERNAME 是您的使用者名稱。

    如要讓群組成員異動生效，請登出後再重新登入。 如果您使用的是虛擬機器，可能需要重新啟動虛擬機器，成員異動才會生效。

選擇驗證方式

可用的驗證方法如下：

gcloud CLI 憑證輔助程式
設定 Artifact Registry 憑證，即可直接在 gcloud CLI 中使用 Docker。這是最簡單的驗證方法，但可能比獨立憑證輔助程式慢。
獨立式 Docker 憑證輔助程式
這個選項主要是用於在沒有 Google Cloud CLI 的情況下，設定可與 Docker 搭配使用的憑證。這項工具比 gcloud CLI 憑證輔助程式快上許多，而且會使用應用程式預設憑證 (ADC) 自動在環境中尋找憑證。
存取權杖
您可以為服務帳戶產生短期存取權杖，然後使用該權杖進行密碼驗證。由於權杖的有效期限只有 60 分鐘，因此比服務帳戶金鑰更安全。
服務帳戶金鑰
使用者管理的金鑰組，可做為服務帳戶的憑證。由於憑證的有效期限很長，因此在所有可用的驗證方法中，這是最不安全的選項。

盡可能使用存取權權杖或憑證輔助程式，降低容器映像檔遭到未經授權存取的風險。如果您必須使用服務帳戶金鑰，請務必遵循管理憑證的最佳做法。

Docker 設定檔中的驗證設定

Docker 會將驗證設定儲存在設定檔 config.json 中。

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

檔案中會針對不同的驗證方法提供個別的部分：

credHelpers
如果您使用 Docker 憑證輔助程式進行驗證，Artifact Registry 會將憑證輔助程式設定儲存在檔案的 credHelpers 區段中。
auths
如果您使用 Docker 登入，並以權杖或服務帳戶金鑰做為密碼，Docker 會在檔案的 auths 區段中儲存以 base64 編碼的憑證。
credStore
如果您已設定憑證儲存庫來管理憑證，憑證儲存庫的設定會位於檔案的 credStore 部分。

Docker 連線至登錄項時，會先檢查與主機相關聯的憑證輔助程式。因此，如果 config.json 在 credHelpers 和 auths 區段中都包含 Artifact Registry 設定，系統會忽略 auths 區段中的設定。

gcloud CLI 憑證輔助程式

gcloud CLI 憑證輔助程式可提供安全的專案資源短期存取權。這個檔案會設定 Docker，在安裝 Google Cloud CLI 的任何環境中，向 Artifact Registry 主機進行驗證。Cloud Shell 包含 Google Cloud CLI 和目前版本的 Docker。

gcloud CLI 憑證輔助程式是最簡單的驗證方法。這個指令會使用 gcloud CLI 工作階段中有效使用者或服務帳戶的憑證設定 Docker。由於此憑證輔助程式取決於 gcloud CLI，因此速度可能比獨立憑證輔助程式慢許多。如果是使用第三方工具或 Docker 用戶端的自動建構作業，且有大量已設定的登錄主機，請改用獨立憑證輔助程式。

如要向 Artifact Registry 進行驗證，請按照下列步驟操作：

  1. 以要執行 Docker 指令的使用者身分登入 gcloud CLI。

    • 如要使用使用者憑證設定驗證，請執行下列指令：

      gcloud auth login

    • 如要使用服務帳戶憑證設定驗證機制，請執行下列指令：

      gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE

      地點

      • ACCOUNT 是您要與 Artifact Registry 搭配使用的服務帳戶，格式為 USERNAME@PROJECT-ID.iam.gserviceaccount.com。如果您想使用現有帳戶，可以在 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面上查看服務帳戶清單，也可以使用 gcloud iam service-accounts list 指令
      • KEY-FILE 是服務帳戶金鑰檔案。如要瞭解如何建立金鑰，請參閱 身分與存取權管理 (IAM) 說明文件。

  1. 執行下列指令：

    gcloud auth configure-docker HOSTNAME-LIST

    其中 HOSTNAME-LIST 是以半形逗號分隔的清單，列出要新增至憑證輔助程式設定的存放區主機名稱。

    舉例來說，如要新增區域 us-west1 和 asia-northeast1，請執行下列指令：

    gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    系統會將指定的主機名稱新增至憑證輔助程式設定。您稍後可以再次執行指令，將其他主機名稱新增至設定。

    如要查看支援的存放區位置清單，請執行下列指令：

    gcloud artifacts locations list

  2. 這個指令會顯示目前 Docker 設定的 credHelpers 部分，以及新增指定主機名稱後的更新設定。

    如要接受設定變更，請輸入 y。

    憑證會儲存在使用者主目錄中。

    • Linux：$HOME/.docker/config.json
    • Windows：%USERPROFILE%/.docker/config.json

  3. Docker 要求憑證輔助程式必須位於系統 PATH 中。確認 gcloud 指令位於系統 PATH 中。

獨立憑證輔助程式

獨立式 Docker 憑證輔助程式會將 Docker 設定為在 gcloud CLI 無法使用的系統中，向 Artifact Registry 進行驗證。這項工具比 gcloud CLI 憑證輔助工具 快上許多，而且會使用應用程式預設憑證 (ADC) 自動在您的環境中尋找憑證。除了推送和拉取圖片之外的作業，例如標記或列出圖片。建議您在使用第三方工具或 Docker 用戶端進行自動建構時，使用這項驗證方法，因為這類工具或用戶端會設定大量的登錄主機。

獨立式 Docker 憑證輔助程式會擷取 Artifact Registry 憑證，並將憑證寫入 Docker 設定檔。這樣一來，您就可以使用 Docker 指令列工具 docker，直接與 Artifact Registry 互動。

如要使用 Docker 憑證輔助程式：

  1. 以要執行 Docker 指令的使用者身分登入機器。

  2. 從 GitHub 下載獨立式 Docker 憑證輔助程式。

    您可以選擇使用 curl 指令列公用程式。例如：

    VERSION=2.1.29
OS=linux  # or "darwin" for OSX, "windows" for Windows.
ARCH=amd64  # or "386" for 32-bit OSs

curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
| tar xz docker-credential-gcr \
&& chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/

  3. 將 Docker 設定成與 Artifact Registry 互動時會使用您的 Artifact Registry 憑證 (您只需執行這項操作一次)：

    docker-credential-gcr configure-docker --registries=HOSTNAME-LIST

    其中 HOSTNAME-LIST 是以半形逗號分隔的清單，列出要新增至憑證輔助程式設定的存放區主機名稱。

    舉例來說，如要新增區域 us-west1 和 asia-northeast1，請執行下列指令：

    docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev

    系統會將指定的主機名稱新增至憑證輔助程式設定。您稍後可以再次執行指令，將其他主機名稱新增至設定。

    如要查看支援的存放區位置清單，請執行下列指令：

    gcloud artifacts locations list

    詳情請參閱 GitHub 上的獨立 Docker 憑證輔助程式說明文件。

    憑證會儲存在使用者主目錄中。

    • Linux：$HOME/.docker/config.json
    • Windows：%USERPROFILE%/.docker/config.json

  4. Docker 要求憑證輔助程式必須位於系統 PATH 中。確認 docker-credential-gcr 指令位於系統 PATH 中。

  5. 如要確認憑證輔助程式能否順利擷取憑證，請執行下列指令：

    echo "https://HOSTNAME" | docker-credential-gcr get

    將 HOSTNAME 替換為您新增至設定中的主機名稱。例如：

    echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get

    如果指令執行成功，則傳回的 JSON 輸出內容會在 Secret 欄位中包含權杖。例如：

    {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}

Docker 現已設定為透過 Artifact Registry 進行驗證。如要推送及提取圖片，請確認權限已正確設定。

存取權杖

您可以產生短期 OAuth 存取權杖，以便透過 Artifact Registry 進行驗證。權杖的有效時間為 60 分鐘，因此請在使用權杖連線至 Artifact Registry 前，提前 1 小時提出要求。

如要使用服務帳戶憑證的存取權杖：

  1. 建立服務帳戶，以便代表應用程式執行動作，或選擇用於自動化功能的現有服務帳戶。

  2. 授予服務帳戶特定的 Artifact Registry 角色，以便提供存放區存取權。

  3. 為服務帳戶產生存取權杖並進行驗證：

    您必須具備服務帳戶憑證建立者角色 (roles/iam.serviceAccountTokenCreator) 的權限，才能冒用服務帳戶，取得該帳戶的權杖，然後以服務帳戶身分進行驗證。

    執行下列指令，並將 ACCOUNT 替換為服務帳戶電子郵件地址，將 LOCATION 替換為儲存庫的區域或多區域位置。

    Linux

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

    Windows

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

Docker 現已透過 Artifact Registry 進行驗證。

服務帳戶金鑰

任何人只要有權存取服務帳戶的有效私密金鑰，就可以透過該服務帳戶存取資源。請注意，金鑰的服務帳戶存取權 (以及服務帳戶有權存取的資料) 生命週期與下載金鑰之使用者的生命週期無關。

請遵循下列規範，限制存放區的存取權：

  • 建立專屬的服務帳戶，僅用於與存放區互動。
  • 授予服務帳戶所需存取權的特定 Artifact Registry 角色。舉例來說，如果服務帳戶只下載構件，就只需要「Artifact Registry Reader」角色。
  • 請在各個存放區，而非專案層級，設定專屬服務帳戶的權限。接著，您可以根據存放區內容指定存取權。舉例來說，開發構建作業的服務帳戶可能會具有用於正式版存放區的 Artifact Registry Reader 角色，以及用於階段性存放區的 Artifact Registry Writer 角色。
  • 請遵循憑證管理的最佳做法。

如要建立新的服務帳戶和服務帳戶金鑰，僅供使用 Artifact Registry 存放區：

  1. 建立服務帳戶，以便代表應用程式執行動作，或選擇用於自動化的現有服務帳戶。

    您需要服務帳戶金鑰檔案的位置，才能設定 Artifact Registry 的驗證機制。如要查看現有帳戶的金鑰，或建立新的金鑰，請前往「服務帳戶」頁面。

    前往「Service Accounts」(服務帳戶) 頁面

  2. 您可以選擇對金鑰檔案的所有內容進行 Base64 編碼。

    Linux

    base64 FILE-NAME > NEW-FILE-NAME

    macOS

    base64 -i FILE-NAME -o NEW-FILE-NAME

    Windows

    Base64.exe -e FILE-NAME > NEW-FILE-NAME

    其中 FILE-NAME 是原始金鑰檔案名稱，而 NEW-FILE-NAME 是 base64 編碼金鑰檔案。

  3. 請確認服務帳戶的權限設定正確無誤。如果您使用的是 Compute Engine 服務帳戶，則必須正確設定權限和存取範圍。

  4. 使用服務帳戶金鑰設定與 Docker 的整合：

    執行下列指令：

    Linux / macOS

    cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
https://LOCATION-docker.pkg.dev

    Windows

    Get-Content KEY-FILE |
docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev

    更改下列內容：

    • KEY-TYPE 可以是下列任一值：
      • _json_key，如果您使用的是 JSON 格式的服務帳戶金鑰，也就是您建立檔案時提供的金鑰。
      • _json_key_base64，如果您已為檔案的所有內容進行 Base64 編碼。
    • KEY-FILE 是服務帳戶金鑰檔案的名稱，格式為 JSON。
    • LOCATION 是映像檔儲存位置的地區或多地區位置。

Docker 現已透過 Artifact Registry 進行驗證。