驗證方法

本頁說明如何設定第三方用戶端，以便透過 Container Registry 進行驗證。

Google Cloud 與 Container Registry 整合的服務預先設定了存取同一個專案中存放區的權限。您不需要為這些服務設定驗證，但應確認權限是否適當設定。

事前準備

  1. 請確認您已啟用 Container Registry API 並安裝 gcloud CLI。請參閱啟用及停用服務一文的操作說明。

  2. 請確認用於驗證的帳戶是否具有存取 Container Registry 的權限。建議您使用服務帳戶，而非使用者帳戶。

  3. 如果尚未安裝 Docker，請安裝 Docker。Cloud Shell 已內建 Docker。

  4. 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 是您的使用者名稱。

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

驗證方法

您必須設定任何需要存取 Container Registry 的第三方用戶端。

可用的驗證方法如下：

gcloud 憑證輔助程式 (建議)
設定要搭配 Docker 使用的 Container Registry 憑證，直接在 gcloud 中使用。請盡可能使用這項方法，以便安全地存取專案資源。這個選項僅支援 Docker 18.03 以上版本。
獨立憑證輔助程式
這個選項主要是用於在沒有 Google Cloud CLI 的情況下，設定可與 Docker 搭配使用的憑證。這個選項僅支援 Docker 18.03 以上版本。
存取權杖
應用程式預設憑證會提供短期存取權存證，供服務帳戶用來存取您的 Google Cloud 資源。這是使用 gcloud 做為憑證輔助工具的替代方案中最安全的做法。
JSON 金鑰檔案

使用者管理金鑰組，可做為服務帳戶的憑證。由於憑證的有效期限很長，因此在所有可用的驗證方法中，這是最不安全的選項。

盡可能使用存取權權杖或其他可用的驗證方法，降低未經授權存取構件檔案的風險。如果服務帳戶金鑰管理不當，就會帶來安全風險。因此請盡可能 選擇比服務帳戶金鑰更安全的替代方案。如果您必須使用服務帳戶金鑰進行驗證，則您必須負責維護私密金鑰的安全，並負責 管理服務帳戶金鑰的最佳做法所述的其他作業。如果您無法建立服務帳戶金鑰，表示貴機構可能已停用服務帳戶金鑰建立功能。詳情請參閱「 管理預設安全的機構資源」。

如果您是從外部來源取得服務帳戶金鑰，則必須先驗證金鑰再使用。詳情請參閱「 外部來源憑證的安全性規定」。

部分工具或工作流程無法妥善支援使用 gcloud 做為憑證輔助工具。如果您使用其中一種替代選項，請務必瞭解安全性影響。

Docker 設定檔中的驗證設定

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

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

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

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

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

gcloud 憑證輔助程式

我們強烈建議您儘可能使用此方法，這項方法可以提供安全的專案資源短期存取權。

請使用 gcloud CLI 在 Cloud Shell 或任何已安裝 Google Cloud CLI 的環境中設定驗證機制。Cloud Shell 包含最新版本的 Docker。

如要設定驗證機制，請按照下列步驟操作：

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

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

      gcloud auth login

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

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

      地點

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

  2. 使用下列指令設定 Docker：

    gcloud auth configure-docker

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

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

獨立憑證輔助程式

獨立 Docker 憑證輔助程式會將 Docker 設為在 gcloud CLI 無法使用的系統上，向 Container Registry 驗證。

憑證輔助程式會先自動擷取 Container Registry 憑證，或是從 --token-source 標記指定的位置擷取憑證，接著再將憑證寫入 Docker 的設定檔。這樣一來，您就可以使用 Docker 的指令列工具 docker，直接與 Container Registry 互動。

如要設定驗證機制，請按照下列步驟操作：

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

  2. 從 GitHub 版本下載 docker-credential-gcr：

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

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

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：

    docker-credential-gcr configure-docker

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

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

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

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

存取權杖

您可以產生短期 OAuth 存取權杖，以便驗證 Container Registry。權杖的有效時間為 60 分鐘，因此請在使用權杖連線至 Container Registry 前，提早一小時左右要求權杖。

  1. 建立新的服務帳戶，以便與 Container Registry 互動。

    主控台

    1. 前往 Google Cloud 控制台的「Create service account」(建立服務帳戶) 頁面。

      前往「Create Service Account」(建立服務帳戶) 頁面

    2. 選取要使用的專案。

    3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。

    4. 選用：在「服務帳戶說明」欄位中輸入說明。

    5. 按一下 [建立]。

    6. 按一下「請選擇角色」欄位。在「所有角色」下方，根據您要授予服務帳戶的權限，選取適當的 Cloud Storage 角色。

    7. 按一下 [完成]。

    gcloud

    您可以在本機電腦或 Cloud Shell 中，使用 Google Cloud CLI 執行下列指令。

    1. 建立服務帳戶。將 NAME 替換為服務帳戶的名稱。

      gcloud iam service-accounts create NAME

    2. 將角色授予服務帳戶。將 PROJECT_ID 替換為專案 ID，並將 ROLE 替換為服務帳戶的適當 Cloud Storage 角色。這個角色會套用至專案中的所有存放區。您可以稍後變更角色，也可以為特定存放區的服務帳戶授予不同角色。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

  2. 取得服務帳戶的金鑰，以便與 Container Registry 互動。

    主控台

    1. 前往 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面。

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

    2. 按一下要使用的服務帳戶電子郵件地址。

    3. 點選「金鑰」。

    4. 依序點選「新增金鑰」和「建立新的金鑰」。

    5. 按一下「建立」，系統就會將含有金鑰的 JSON 檔案下載至您的電腦。

      本頁的操作說明會使用此金鑰檔案的檔案名稱 keyfile.json。

    6. 按一下 [關閉]。

    gcloud

    您可以在本機電腦或 Cloud Shell 中，使用 Google Cloud CLI 執行下列指令。

    本頁操作說明會使用檔案名稱 keyfile.json 做為金鑰檔案。

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

  3. 執行下列指令，以服務帳戶身分登入 Google Cloud CLI。

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

    地點

    • ACCOUNT 是服務帳戶名稱，格式為 [USERNAME]@[PROJECT-ID].iam.gserviceaccount.com。
    • KEY-FILE 是服務帳戶金鑰檔案。如要瞭解如何建立金鑰，請參閱 身分與存取權管理說明文件。

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

  5. 取得服務帳戶的存取權杖。由於權杖的有效期限很短，請在使用權杖連線至 Container Registry 前，提前一個小時要求權杖。

    執行下列指令：

    Linux

    gcloud auth print-access-token | docker login -u oauth2accesstoken \
    --password-stdin https://HOSTNAME

    Windows

    gcloud auth print-access-token |
    docker login -u oauth2accesstoken --password-stdin https://HOSTNAME

    其中 HOSTNAME 是 gcr.io、us.gcr.io、eu.gcr.io 或 asia.gcr.io。

    提取圖片。

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

JSON 金鑰檔案

服務帳戶金鑰是長效型金鑰組，可做為服務帳戶的憑證使用。與 OAuth 存取權憑證不同，服務帳戶金鑰不會過期。

任何人只要有權存取服務帳戶的有效私密金鑰，就可以透過該服務帳戶存取資源。舉例來說， Google Cloud會自動建立一些服務帳戶 (例如 Container Registry 服務帳戶)，並將父項專案的讀取/寫入 Editor 角色授予服務帳戶。Compute Engine 預設服務帳戶設定為具備相同專案中儲存空間的唯讀存取權。

此外，金鑰的服務帳戶存取權 (以及服務帳戶有權存取的資料) 生命週期與下載金鑰之使用者的生命週期無關。

請遵循下列規範，限制容器映像檔的存取權：

  • 建立專用服務帳戶，僅用於與 Container Registry 互動。
  • 授予服務帳戶所需的最低存取權限角色。
  • 請遵循憑證管理的最佳做法。

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

  1. 建立新的服務帳戶，以便與 Container Registry 互動。

    主控台

    1. 前往 Google Cloud 控制台的「Create service account」(建立服務帳戶) 頁面。

      前往「Create Service Account」(建立服務帳戶) 頁面

    2. 選取要使用的專案。

    3. 在 [Service account name] (服務帳戶名稱) 欄位中輸入一個名稱。

    4. 選用：在「服務帳戶說明」欄位中輸入說明。

    5. 按一下 [建立]。

    6. 按一下「請選擇角色」欄位。在「All roles」下方，為服務帳戶選取適當的 Cloud Storage 角色。

    7. 按一下 [完成]。

    gcloud

    您可以在本機電腦或 Cloud Shell 中，使用 Google Cloud CLI 執行下列指令。

    1. 建立服務帳戶。將 NAME 替換為服務帳戶的名稱。

      gcloud iam service-accounts create NAME

    2. 將角色授予服務帳戶。將 PROJECT_ID 替換為專案 ID，並將 ROLE 替換為服務帳戶的適當 Cloud Storage 角色。

      gcloud projects add-iam-policy-binding PROJECT_ID --member "serviceAccount:NAME@PROJECT_ID.iam.gserviceaccount.com" --role "roles/ROLE"

  2. 取得服務帳戶的金鑰，以便與 Container Registry 互動。

    主控台

    1. 前往 Google Cloud 控制台的「Service Accounts」(服務帳戶) 頁面。

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

    2. 按一下要使用的服務帳戶電子郵件地址。

    3. 點選「金鑰」。

    4. 依序點選「新增金鑰」和「建立新的金鑰」。

    5. 按一下「建立」，系統就會將含有金鑰的 JSON 檔案下載至您的電腦。

      本頁的操作說明會使用此金鑰檔案的檔案名稱 keyfile.json。

    6. 按一下 [關閉]。

    gcloud

    您可以在本機電腦或 Cloud Shell 中，使用 Google Cloud CLI 執行下列指令。

    本頁操作說明會使用檔案名稱 keyfile.json 做為金鑰檔案。

    gcloud iam service-accounts keys create keyfile.json --iam-account [NAME]@[PROJECT_ID].iam.gserviceaccount.com

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

  4. 使用服務帳戶金鑰做為密碼，向 Docker 進行驗證。

    Linux / macOS

    cat KEY-FILE | docker login -u _json_key --password-stdin \
https://HOSTNAME

    Windows

    Get-Content KEY-FILE |
docker login -u _json_key --password-stdin https://HOSTNAME

    更改下列內容：

    • KEY-FILE 是服務帳戶金鑰檔案的名稱，格式為 JSON。
    • HOSTNAME 為 gcr.io、us.gcr.io、eu.gcr.io 或 asia.gcr.io。
    提取圖片。

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