建立自訂建構步驟

撰寫建構設定時,您可以使用系統支援的開放原始碼建構步驟 (由 Cloud Build 提供),或定義自己的自訂建構步驟

自訂建構步驟是一個容器映像檔,Cloud Build 工作站 VM 可在來源磁碟區掛接至 /workspace 的情況下提取及執行此建構步驟。您的自訂建構步驟可以執行容器內的任何指令碼或二進位檔,因此可以執行容器能夠執行的所有操作。

自訂建構步驟適用於下列操作:

  • 從外部位置下載原始碼或套件
  • 使用外部工具鏈
  • 快取任何所需程式庫
  • 預先建構原始碼 (Cloud Build 僅對可能會將建構封裝至容器映像檔的情況負責)

自訂建構步驟會在來源掛接到 /workspace 之下時執行,並且會在 /workspace 之下的某個工作目錄中執行。指定建構步驟留在 /workspace 的任何檔案都可供其他建構步驟使用,無論這些步驟是並行執行還是依序執行都是如此。

自訂建構步驟可推送到您的建構工具服務帳戶可以存取的 Google Container Registry 存放區 (在 gcr.io/$PROJECT-NAME/ 託管),或從該處提取。docker 指令列工具憑證不足以提供 Docker Hub 的經驗證存取權。

本指南將使用範例說明如何建立自訂建構步驟,引導您逐步瞭解如何建立執行殼層指令碼的建構步驟。您可以建立「殼層指令碼執行者」做為自訂建構步驟,以從建構原始碼的某處執行殼層指令碼。

建立自訂建構步驟

若要建立自訂建構步驟,您可以建立建構設定檔,以建構「建構步驟映像檔」,並將映像檔推送到建構工具服務帳戶可以存取的映像檔註冊資料庫 (例如 Container Registry)。您也可以使用其他工具建構自訂建構步驟映像檔,然後將其儲存在映像檔註冊資料庫中。完成這個步驟之後,未來進行建構時即可叫用您的自訂建構步驟。

關於 entrypoint 欄位

映像檔的 Dockerfile 可能擁有 ENTRYPOINT 及/或 CMD 欄位。如果容器要做為執行檔執行,ENTRYPOINT 會指定用於自訂建構步驟的進入點。CMD 會提供執行的預設值,如果省略 ENTRYPOINT,也應該包含執行檔。

在建構設定中,選用 entrypoint 欄位會定義建構步驟在叫用時的執行方式。例如,您可以指定執行建構步驟時應呼叫的主要指令:docker 建構步驟的進入點為 "/usr/bin/docker"。未來使用建構步驟進行建構時,您可以在該建構中指定 entrypoint 來覆寫 Dockerfile 的 ENTRYPOINT

如果您沒有在建構步驟的建構要求檔案中指定 entrypoint 欄位,「且」建構步驟的映像檔未在其 Dockerfile 中指定 ENTRYPOINTargs 的第一個項目將做為進入點,args 中其餘的項目則做為引數。

範例:從原始碼執行殼層指令碼

對於從原始碼執行殼層指令碼的自訂建構步驟而言,步驟的容器映像檔必須包含能夠執行指令碼的工具。標準基本映像檔 (例如 ubuntudebianalpinebusybox 容器映像檔) 都可以執行指令碼;但是,alpinebusybox 映像檔未預先安裝 bash (因此無法執行 bash 指令碼),而 ubuntudebian 則已預先安裝。

如果映像檔中包含執行指令碼所需的所有工具 (包括殼層),您可以直接使用這個映像檔做為建構步驟。

這個範例使用了 ubuntu 映像檔執行指令碼,因為它預先封裝了 bash,並且支援許多開發人員工具。建構自身會根據 alpine 建立映像檔;這類映像檔小很多,僅包含執行階段環境所需的內容。

以下是自訂建構步驟的 ./cloudbuild.yaml 設定檔範例:

steps:
- name: 'ubuntu'
  args: ['bash', './myscript.bash']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/custom-script-test', '.']
images: ['gcr.io/$PROJECT_ID/custom-script-test']

步驟會執行下列名為 ./myscript.bash 的指令碼:

echo "Hello, world!" > file.txt

以下是 Dockerfile 範例:

FROM alpine
COPY file.txt /file.txt
ENTRYPOINT ["cat", "/file.txt"]

如要提交使用這個自訂建構步驟的建構,請在殼層或終端機視窗中執行下列指令:

$ gcloud builds submit --config cloudbuild.yaml .
...
$ gcloud docker -- pull gcr.io/<your-project-id>/custom-script-test
...
$ docker run gcr.io/<your-project-id>/custom-script-test
Hello, world!

與這個範例中使用的 alpine 基本映像檔所提供的資源相比,自訂建構步驟執行的指令碼可能需要更多資源。如果是這樣的話,您可以在 Dockerfile 中使用 COPY 指令,將資源從工作區導入容器映像檔,來預先建構具有必要資源的映像檔。

例如,假設您要執行一個指令碼,該指令碼會使用 curl 從建構的映像檔取得某個檔案。由於 ubuntu 映像檔未預先封裝 curl 指令列工具,因此我們將建立新映像檔,並將 ubuntu 基本映像檔與 curl 置於最上層。

以下是使用自訂 ubuntu-curl 建構步驟的建構作業 ./cloudbuild.yaml 設定檔範例:

steps:
- name: 'gcr.io/$PROJECT_ID/ubuntu-curl'
  args: ['bash', './curl.bash']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/custom-script-test2', '.']
images: ['gcr.io/$PROJECT_ID/custom-script-test2']

安裝 curl 工具的 Dockerfile.ubuntu-curl

FROM ubuntu
RUN apt-get -q update && apt-get install -qqy curl

./curl.bash 指令碼可能與下面的指令碼類似:

#!/bin/bash
curl http://example.com > example.html

Dockerfile 範例:

FROM alpine
COPY example.html /example.html
ENTRYPOINT ["cat", "/example.html"]

如要針對 ubuntu-curl 執行自訂建構步驟,然後建構映像檔,請在殼層或終端機視窗中執行下列指令:

# First, build and push the `ubuntu-curl` custom build step.
$ docker build -f Dockerfile.ubuntu-curl -t gcr.io/your-project/ubuntu-curl .
...
$ gcloud docker -- push gcr.io/your-project/ubuntu-curl
...

在您將使用 Dockerfile.ubuntu-curl 建立的映像檔推送至 Docker Registry 之後,便可直接使用映像檔做為建構步驟。

# Then, use the custom `ubuntu-curl` build step in a new build.
$ gcloud builds submit --config cloudbuild.yaml .
...
$ gcloud docker -- pull gcr.io/your-project/custom-script-test2
...
$ docker run gcr.io/your-project/custom-script-test2
`<`contents of example.com source`>`

您可以新增初始步驟建構指令碼執行者映像檔,在一次建構中完成相同的操作。建構這個映像檔之後,您可以將其做為建構的下一步使用。這樣做的好處是可以保持 curl.bash 整潔,並且可以在 Cloud Build 服務中執行大量工作。

以下是新增了初始步驟的 ./cloudbuild.yaml 設定檔範例:

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-f', 'Dockerfile.ubuntu-curl', '-t', 'script-runner', '.']
- name: 'script-runner'
  args: ['bash', './curl.bash']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/$PROJECT_ID/custom-script-test2', '.']
images: ['gcr.io/$PROJECT_ID/custom-script-test2']

只要您從 cloudbuild.yamlimages 欄位中排除 script-runner,Cloud Build 服務就不會嘗試進行推送 (在這個範例中將失敗)。但是,在建構中,script-runner 映像檔將存在於映像檔快取中,且可做為建構步驟使用。

後續步驟

本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
Cloud Build 說明文件