向 Artifact Registry 驗證 Docker

設定 Artifact Registry 的 Docker 驗證後，您就能從本機工作站或外部環境推送及提取容器映像檔。

您不需要為 Cloud Build 或 Google Kubernetes Engine 和 Cloud Run 等執行階段環境設定驗證，但請確認您具備必要的 Google Cloud 權限。

事前準備

  1. 安裝 Google Cloud CLI。 完成後，執行下列指令來初始化 Google Cloud CLI：

    gcloud init

    如果您使用外部識別資訊提供者 (IdP)，請先 使用聯合身分登入 gcloud CLI。

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

    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 憑證輔助程式
直接在 gcloud CLI 中設定 Artifact Registry 憑證，供 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 會將憑證的 base64 編碼版本儲存在檔案的 auths 區段中。
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 控制台的「服務帳戶」頁面，或使用 gcloud iam service-accounts list 指令，查看服務帳戶清單。
      • KEY-FILE：服務帳戶金鑰檔案。如要瞭解如何建立金鑰，請參閱「身分與存取權管理 (IAM) 說明文件」。

  2. 執行下列指令：

    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

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

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

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

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

  4. Docker 規定憑證輔助函式必須位於系統 PATH。確認系統 PATH 中有 gcloud 指令。

獨立憑證輔助程式

獨立的 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。確認系統 PATH 中有 docker-credential-gcr 指令。

  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. 建立服務帳戶來代表應用程式執行作業，或選擇用於自動化的現有服務帳戶。

  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 驗證。