在 Google Cloud 中建構及部署內容的相關異動

本文件將說明使用 Cloud Build 建構容器映像檔,並將其部署至 Cloud Run 或 Google Kubernetes Engine 等執行階段環境時,Container Registry 和 Artifact Registry 之間的差異。 Google Cloud

本指南的比較重點是 標準 Artifact Registry 存放區,也就是不隸屬於 Container Registry 的一般 Artifact Registry 存放區,且支援所有 Artifact Registry 功能。如果系統管理員設定支援 gcr.io 網域的存放區,對 gcr.io 主機名稱的請求會自動重新導向至對應的 Artifact Registry 存放區,而具有 Container Registry 存取權的預設服務帳戶,也會在 Artifact Registry 中擁有相同的預設權限。

如要瞭解使用 Docker 用戶端的 Container Registry 和 Artifact Registry 之間的差異,請參閱「使用 Docker 推送及提取的變更」。

您可以利用這項資訊,調整現有的 Cloud Build 與 Container Registry 相關指令、設定或說明文件。

事前準備

本文假設您已具備下列條件:

  1. 在專案中啟用 Artifact Registry
  2. 啟用 Cloud Build API 和您在 Artifact Registry 中使用的任何其他 Google Cloud 服務的 API。

工作流程異動

在同一專案中使用 Cloud Build 搭配 Container Registry 時,工作流程如下所示:

  1. 使用 Dockerfile建構設定檔,透過 Cloud Build 建構、標記並推送映像檔至存放區。

    以下範例會建構映像檔 my-image,並加上 tag1 標記,然後將其推送至專案 my-project 的主機 gcr.io

    gcloud builds submit --tag gcr.io/my-project/my-image:tag1
    
  2. Google Cloud 執行階段環境,例如 Cloud Run 和 Google Kubernetes Engine 會從登錄檔提取映像檔。

    舉例來說,這個指令會將先前步驟中的映像檔部署至 Cloud Run,並設為 my-service

    gcloud run deploy my-service --image gcr.io/my-project/my-image:tag1
    

Container Registry 工作流程將管理員職責與建構和部署作業結合。

  • 啟用 部分 Google Cloud API 時,Container Registry API 會自動啟用。也就是說,這些服務的使用者可在同一個專案中隱含存取 Container Registry。舉例來說,可在 Cloud Build 中執行建構作業的使用者,可以將映像檔推送至登錄,並根據預設新增登錄主機。
  • Cloud Build 服務帳戶具備建立 Cloud Storage 儲存體值區的權限。也就是說,帳戶首次將映像檔推送至主機時,可以自動將 Container Registry 主機新增至專案。這也表示帳戶可以在整個專案中建立、讀取及寫入儲存值區,包括 Container Registry 未使用的值區。

在 Artifact Registry 中,系統會明確區分管理員和建構角色,以便變更建構和部署工作流程中的步驟。如要為 Artifact Registry 調整 Container Registry 工作流程,請進行下列變更。每個步驟都會連結至有關修改工作流程的其他資訊。

  1. 新功能啟用 Artifact Registry API。

    您必須啟用 Artifact Registry API。Cloud Build 和 Cloud Run 和 GKE 等執行階段環境不會自動為您啟用 API。

  2. 新建:如果目標 Docker 存放區尚未存在,請建立。您必須先建立存放區,才能向存放區推送任何映像檔。推送映像檔不會建立存放區,且 Cloud Build 服務帳戶並沒有建立存放區的權限。

  3. 變更:使用 Dockerfile 或建構設定檔,透過 Cloud Build 建構、標記及推送映像檔至存放區。

    下列範例指令與 Container Registry 範例相同,但會使用映像檔的 Artifact Registry 存放區路徑。

    gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
    
  4. 已變更:將映像檔部署至 Google Cloud 執行階段環境,例如 Cloud Run 或 GKE。

    以下範例指令與 Container Registry 範例相同,但會使用映像檔的 Artifact Registry 存放區路徑。

    gcloud run deploy my-service --image us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
    

此外,Artifact Registry 使用的角色與 Container Registry 不同,用於控管映像檔的存取權。您需要在下列情況下設定權限

  • Cloud Build 或 Google Cloud 執行階段環境位於 Artifact Registry 以外的專案中。
  • 您應為 Google Cloud Cloud Build 或 GKE 等服務使用自訂服務帳戶,而非預設服務帳戶。
  • 您已將權限授予其他使用者或服務帳戶。

啟用 API

重點:

下表比較說明如何為各項服務啟用 API:

Container Registry

啟用下列 Google Cloud API 時,系統也會自動啟用 Container Registry API:

  • App Engine 彈性環境
  • Cloud Build
  • Cloud Run 函式
  • Cloud Run
  • 在 Artifact Analysis 中執行容器掃描或隨選掃描
  • Google Kubernetes Engine

在預設權限下,如果使用者可以在 Cloud Build 中執行建構作業、使用 Artifact Analysis 掃描容器,或是將容器部署至Google Cloud 執行階段,則在註冊資料庫位於同一專案時,使用者就能隱含地存取 Container Registry 中的映像檔。

Artifact Registry

您必須啟用 Artifact Registry API。Cloud Build、Cloud Run 和 GKE 等服務不會自動啟用 Artifact Registry API。

您可以使用 gcloud 在同一個專案中啟用多個 API。舉例來說,如要啟用 Cloud Build API 和 Artifact Registry API,請執行下列指令:

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

新增註冊表和存放區

重點:

  • 您必須先建立 Artifact Registry Docker 存放區,才能將映像檔推送至該存放區。
  • Container Registry 會將所有映像檔儲存在同一個儲存空間值區的單一多區域中。在 Artifact Registry 中,您可以在相同地區或多地區中建立多個存放區,並設定不同的存取政策。

以下比較說明各項服務中的存放區設定:

Container Registry

在 Container Registry 中,您最多可以為專案新增四個登錄主機。您可以透過推送第一個映像檔來新增登錄主機。

  1. 如要在專案中新增 gcr.io 等登錄,請由具有專案層級儲存空間管理員角色的帳戶推送初始映像檔。

    舉例來說,如果 gcr.io 主機不在專案 my-project 中,則推送映像檔 gcr.io/my-project/my-image:1.0 會觸發下列步驟:

    1. gcr.io 主機新增至專案
    2. 在專案中為 gcr.io 建立儲存空間值區。
    3. 將圖片儲存為 gcr.io/my-project/my-image:1.0
  2. 完成初始推送後,您就可以為其他使用者授予儲存體儲存空間權限

根據預設,Cloud Build 具備建立儲存空間值區所需的權限,因此初始圖片推送作業和後續推送作業無法區分。

在專案中,註冊資料庫主機會將所有映像檔儲存在相同的儲存空間值區中。在下列範例中,專案 my-project 在註冊表 gcr.io 中具有兩個名為 web-app 的映像檔。一個位於專案 ID my-project 正下方。另一個圖片則位於存放區 team1 中。

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Cloud Build 沒有在 Artifact Registry pkg.dev 網域中建立標準存放區的權限。

具有 Artifact Registry 存放區管理員角色的帳戶必須先建立存放區,才能將映像檔推送至該存放區。接著,您可以授予權限,讓其他使用者存取存放區。

在 Artifact Registry 中,每個存放區都是獨立的資源。因此,所有圖片路徑都必須包含存放區。

有效的圖片路徑:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

無效的圖片路徑 (不含存放區):

us-central1-docker.pkg.dev/my-project/web-app:1.0

以下範例說明將映像檔推送至缺少的存放區時,可能會發生的情況。

  • 如果 us-central1-docker.pkg.dev/my-project/team1 不存在,則將圖片推送至 us-central1-docker.pkg.dev/my-project/team1
  • us-central1-docker.pkg.dev/my-project/team1 存在但 us-central1-docker.pkg.dev/my-project/team2 不存在的情況下,將映像檔推送至 us-central1-docker.pkg.dev/my-project/team2

授予權限

重點:

  • Google Cloud 服務對 Container Registry 和 Artifact Registry 皆具備相同的讀取或寫入權限。不過,預設的 Cloud Build 服務帳戶無法在 pkg.dev 網域上建立標準存放區。
  • 將適當的 Artifact Registry 角色授予其他存取 Artifact Registry 的帳戶。
  • Container Registry 支援儲存空間值區層級的存取權控管。Artifact Registry 支援存放區層級的存取權控管。

下表比較各項服務的權限:

Container Registry

Container Registry 會使用 Cloud Storage 角色控管存取權。Cloud Build 具備 Storage 管理員角色的必要權限,可將 Container Registry 主機新增至專案。

儲存值區層級的 Storage 物件檢視器
從專案中現有的註冊主機提取 (讀取) 映像檔。
儲存空間值區層級的 Storage 舊版值區寫入者
為專案中的現有註冊主機推送 (寫入) 及提取 (讀取) 映像檔。
專案層級的儲存空間管理員
將初始映像檔推送至主機,以便在專案中新增儲存庫主機。

將初始映像檔推送至登錄後,您可以將 Cloud Storage 角色授予其他需要存取儲存值區的帳戶。請注意,任何擁有 Storage Admin 角色所有權限的帳戶,都能在整個專案中讀取、寫入及刪除儲存體值區和儲存體物件。

儲存值區的權限會套用至登錄中的所有存放區。舉例來說,任何使用者只要在 gcr.io/my-project 的值區中具備 Storage Object Viewer 權限,就能讀取所有這些存放區中的圖片:

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry 有專屬的角色可控管存取權。這些角色可明確區分管理員和存放區使用者角色。

Cloud Build 在 Artifact Registry Writer 角色中具有權限,因為它只需要在 pkg.dev 網域中使用標準存放區推送及擷取映像檔。

只有管理存放區的帳戶,才應具備 Artifact Registry 存放區管理員或 Artifact Registry 管理員角色。

Artifact Registry 讀取者
列出構件和存放區。下載構件。
Artifact Registry 寫入者
列出構件和存放區。下載構件、上傳新的構件版本,以及新增或更新標記。
Artifact Registry 存放區管理員
Artifact Registry Writer 權限,以及刪除構件和標記的權限。
Artifact Registry 管理員
Artifact Registry 存放區管理員權限,以及建立、更新、刪除及授予存放區權限的權限。

您可以在存放區層級套用這些權限。例如:

  • us-central1-docker.pkg.dev/my-project/team1 的存取權授予 Team 1
  • us-central1-docker.pkg.dev/my-project/team2 的存取權授予 Team 2。

如要進一步瞭解如何授予 Artifact Registry 權限,請參閱存取權控管說明文件。

建構及推送映像檔

重點:

  • 您必須先建立 Artifact Registry Docker 存放區,才能將映像檔推送至該存放區。
  • Artifact Registry 主機名稱與 Container Registry 主機名稱不同。

Cloud Build 可在單一步驟中建構、標記及推送映像檔。

有了 Container Registry,Cloud Build 就能成功將映像檔推送至尚未在 Google Cloud 專案中存在的登錄主機。對於這項初始的映像檔推送作業,Cloud Build 具有自動將註冊主機新增至專案的權限。

如要調整 Container Registry 工作流程,請按照下列步驟操作:

  1. 請先設定存放區,再將圖片推送至該存放區。
  2. 請更新設定檔或建構設定檔或 gcloud builds submit 指令中的圖片路徑。

使用建構設定檔建構

將建構的映像檔 Container Registry 路徑,替換為現有 Artifact Registry 存放區的路徑。

以下範例 cloudbuild.yaml 檔案會建構 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1 映像檔:

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1', '.' ]
images:
- 'us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1'

接著,您可以使用下列指令建構映像檔:

gcloud builds submit --config cloudbuild.yaml

使用 Dockerfile 建構

將建構的映像檔 Container Registry 路徑,替換為現有 Artifact Registry 存放區的路徑。

以下範例指令會使用目前目錄中的 Dockerfile 建構映像檔 us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

gcloud builds submit --tag us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1

部署映像檔

重點:

  • Artifact Registry 主機名稱與 Container Registry 主機名稱不同。

如要調整 Container Registry 工作流程,請更新部署設定和部署指令中的映像檔路徑。下列各節會列舉 Cloud Build、Cloud Run 和 GKE 的範例,但相同的方法也適用於部署映像檔的任何其他 Google Cloud 服務。

Cloud Build

將要部署的映像檔 Container Registry 路徑,替換為現有 Artifact Registry 存放區的路徑。

以下範例 cloudbuild.yaml 檔案會部署範例圖片 us-docker.pkg.dev/cloudrun/container/hello

steps:
- name: 'gcr.io/cloud-builders/gcloud'
  args:
  - 'run'
  - 'deploy'
  - 'cloudrunservice'
  - '--image'
  - 'us-docker.pkg.dev/cloudrun/container/hello'
  - '--region'
  - 'us-central1'
  - '--platform'
  - 'managed'
  - '--allow-unauthenticated'

Cloud Run

將要部署的映像檔 Container Registry 路徑,替換為現有 Artifact Registry 存放區的路徑。

舉例來說,這個指令會部署範例圖片 us-docker.pkg.dev/cloudrun/container/hello

gcloud run deploy my-service --image us-docker.pkg.dev/cloudrun/container/hello

GKE

將建構的映像檔 Container Registry 路徑,替換為現有 Artifact Registry 存放區的路徑。

以下 Artifact Registry 範例使用範例圖片 us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

透過指令列建立叢集:

kubectl create deployment hello-server --image=us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0

在部署資訊清單中指定映像檔:

In a deployment manifest:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app
spec:
  replicas: 3
  selector:
    matchLabels:
      run: my-app
  template:
    metadata:
      labels:
        run: my-app
    spec:
      containers:
      - name: hello-app
        image: us-docker.pkg.dev/google-samples/containers/gke/hello-app:1.0