建構設定總覽

本頁面說明 Cloud Build 建構設定檔的結構。

Dockerfile 與建構設定檔

如果您要使用 gcloud 指令列工具建構觸發條件在 Cloud Build 中執行非 Docker 版本,則必須提供建構設定檔。建構設定檔中包含讓 Cloud Build 根據規格執行工作的操作說明。例如,您的建構設定檔可以包含建構、封裝和推送 Docker 映像檔的操作說明。

如果您使用 gcloud 工具或建構觸發條件執行 Docker 版本,則可使用 Dockerfile 或建構設定檔建構映像檔。如需如何使用 Dockerfile 建構 Docker 映像檔的操作說明,請參閱使用 Docker 的快速入門導覽課程

建構設定檔的結構

建構設定檔使用 Cloud Build API 的 Build 資源進行建構。

您可以使用 YAML 或 JSON 語法編寫建構設定檔。如果您使用 curl 等第三方 http 工具提交建構要求,請使用 JSON 語法。您必須在專案的根目錄中建立建構設定檔,且 Cloud Build 將在每次啟動建構時讀取該設定檔。

建構設定檔的結構如下:

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  dir: string
  id: string
  waitFor: string
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
- name: string
  ...
- name: string
  ...
timeout: string (Duration format)
logsBucket: string
options:
 sourceProvenanceHash: enum(HashType)
 machineType: enum(MachineType)
 diskSizeGb: string (int64 format)
 substitutionOption: enum(SubstitutionOption)
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
secrets: object(Secret)
images:
- [string, string, ...]
artifacts: object (Artifacts)

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "env": [
        [
            "string",
            "string",
            "..."
        ]
        ],
        "dir": "string",
        "id": "string",
        "waitFor": "string",
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "logsBucket": "string",
    "options": {
        "sourceProvenanceHash": "enum(HashType)",
        "machineType": "enum(MachineType)",
        "diskSizeGb": "string (int64 format)",
        "substitutionOption": "enum(SubstitutionOption)",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)"
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
    [
        "string",
        "string",
        "..."
    ]
    ],
    "secrets": "object(Secret)",
    "images": [
    [
        "string",
        "string",
        "..."
    ]
    ],
    "artifacts": "object(Artifacts)"
}

建構設定檔的每個區段都定義您想讓 Cloud Build 執行的一部分工作:

建構步驟

建構步驟指定您想讓 Cloud Build 執行的動作。對於每個建構步驟,Cloud Build 都會執行 docker 容器做為 docker run 的執行個體。建構步驟與指令碼中的指令類似,可讓您在建構中靈活執行任意操作說明。如果您可以將建構工具封裝至容器,即表示 Cloud Build 可將其做為建構的一部分來執行。

您可以在設定檔中包含一或多個建構步驟。

在建構設定檔中使用 steps 欄位可指定建構步驟。以下提供的設定種類程式碼片段可以在 steps 欄位中設定:

YAML

steps:
- name: 'gcr.io/cloud-builders/git'
  args: ['clone', 'https://github.com/GoogleCloudPlatform/cloud-builders']
  env: ['PROJECT_ROOT=hello']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/git",
        "args": [
            "clone",
            "https://github.com/GoogleCloudPlatform/cloud-builders"
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

name

請使用建構步驟的 name 欄位指定雲端建構工具,該工具是執行常用工具的容器映像檔。您可以在建構步驟中使用建構工具來執行您的工作。

下列程式碼片段示範呼叫 bazelgclouddocker 建構工具的建構步驟:

YAML

steps:
- name: 'gcr.io/cloud-builders/bazel'
...

- name: 'gcr.io/cloud-builders/gcloud'
...

- name: 'gcr.io/cloud-builders/docker'
...

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/bazel"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/gcloud"
        ...
    },
    {
        "name": "gcr.io/cloud-builders/docker"
        ...
    }
    ]
}

args

建構步驟的 args 欄位會取得引數清單並將其傳送至 name 欄位參照的建構工具。系統會將已傳送至建構工具的引數傳送至在建構工具中執行的工具,進而讓您叫用工具支援的任何指令。如果建構步驟中使用的建構工具擁有進入點,系統會將 args 做為該進入點的引數使用。如果建構工具並未定義進入點,系統會將 args 中的第一個元素做為進入點使用,並將其餘元素做為引數使用。

以下程式碼片段會叫用 docker build 指令並安裝 Maven 依附元件:

YAML

steps:
- name: 'gcr.io/cloud-builders/mvn'
  args: ['install']
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/mvn",
        "args": [
            "install"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

env

建構步驟的 env 欄位會取得要在執行步驟時使用的環境變數清單。變數的格式為 KEY=VALUE

在下列建構設定中,建構步驟的 env 欄位會先設定 Compute Engine 區域與 GKE 叢集,然後再執行 kubectl

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/myimage', 'frontend=gcr.io/myproject/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east1-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image",
            "deployment/myimage",
            "frontend=gcr.io/myproject/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east1-b",
            "CLOUDSDK_CONTAINER_CLUSTER=node-example-cluster"
        ]
    }
    ]
}

dir

在建構步驟中使用 dir 欄位可設定要在執行步驟時使用的工作目錄。根據預設,Cloud Build 會使用名為 /workspace 的目錄做為工作目錄。如果您的設定檔擁有多個建構步驟,透過保留 /workspace 目錄,系統可以將一個步驟產生的資產傳送至下一個步驟,進而讓您設定共用資產的建構步驟管道。如果您在建構步驟中設定 dir 欄位,系統會將工作目錄設定為 /workspace/<dir>。如果這個值是相對路徑,即表示該值與建構的工作目錄相對。如果這個值是絕對路徑,其可能位於建構的工作目錄之外,在此情況下,路徑的內容可能不會在建構步驟執行中保留 (除非指定該路徑的磁碟區)。

以下程式碼片段會將工作目錄設定為 examples/hello_world

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
  env: ['PROJECT_ROOT=hello']
  dir: 'examples/hello_world'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ],
        "env": [
            "PROJECT_ROOT=hello"
        ],
        "dir": "examples/hello_world"
    }
    ]
}

timeout

在建構步驟中使用 timeout 欄位可設定執行步驟的時間限制。如果您並未設定這個欄位,步驟會沒有時間限制,可執行到其完成或建構自身逾時為止。timeout 必須以秒為單位指定,且不得超過九個小數位數,結尾必須是「s」,例如「3.5s」。

在下面的建構設定中,ubuntu 步驟會在 500 秒之後逾時:

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
  timeout: 500s
- name: 'ubuntu'
  args: ['echo', 'hello world, after 600s']

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ],
        "timeout": "500s"
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello world, after 600s"
        ]
    }
    ]
}

id

使用 id 欄位可設定建構步驟的唯一識別碼。idwaitFor 欄位搭配使用,可設定應執行建構步驟的順序。如需使用 waitForid 的操作說明,請參閱設定建構步驟順序

waitFor

在建構步驟中使用 waitFor 欄位可指定在執行建構步驟之前必須執行的步驟。如果並未提供 waitFor 的值,建構步驟會等待建構要求中之前的所有建構步驟都成功完成才會執行。如需使用 waitForid 的操作說明,請參閱設定建構步驟順序

entrypoint

如果您不想使用建構工具的預設進入點,在建構步驟中使用 entrypoint 可指定進入點。如果您並未設定這個欄位,Cloud Build 會使用建構工具的進入點。以下程式碼片段會設定 npm 建構步驟的進入點:

YAML

steps:
- name: 'gcr.io/cloud-builders/npm'
  entrypoint: 'node'
  args: ['--version']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/npm",
        "entrypoint": "node",
        "args": [
            "--version"
        ]
    }
    ]
}

secretEnv

這是使用 Cloud KMS 加密編譯金鑰加密的環境變數清單。這些值必須在建構的密碼中指定。如要瞭解如何使用這個欄位,請參閱在建構要求中使用加密的變數一文。

volumes

磁碟區是一種 Docker 容器,可以掛接到建構步驟,以便跨建構步驟保存檔案。Cloud Build 執行建構步驟時,會將 workspace 磁碟區自動掛接到 /workspace。您可以針對步驟使用 volumes 欄位,指定要掛接到建構步驟容器的其他磁碟區。

例如,下面的建構設定檔會在第一個步驟中將檔案寫入磁碟區,並在第二個步驟中讀取該檔案。如果這兩個步驟並未指定 /persistent_volume 路徑做為永久磁碟區,第一個步驟會在該路徑寫入檔案,然後系統會在第二個步驟執行之前捨棄該檔案。透過在兩個步驟中指定相同名稱的磁碟區,系統會將第一個步驟中 /persistent_volume 的內容保留到第二個步驟。

YAML

steps:
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
        echo "Hello, world!" > /persistent_volume/file
- name: 'ubuntu'
  volumes:
  - name: 'vol1'
    path: '/persistent_volume'
  args: ['cat', '/persistent_volume/file']

JSON

  {
    "steps": [
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "entrypoint": "bash",
        "args": [
          "-c",
          "echo \"Hello, world!\" > /persistent_volume/file\n"
        ]
      },
      {
        "name": "ubuntu",
        "volumes": [
          {
            "name": "vol1",
            "path": "/persistent_volume"
          }
        ],
        "args": [
          "cat",
          "/persistent_volume/file"
        ]
     }
    ]
  }

timeout

針對建構使用 timeout 欄位可指定必須允許建構執行的時間長度 (精確到秒)。如果過了這個時間,建構工作將停止,且建構狀態將會是 TIMEOUT。如果未設定 timeout,則會將 10 分鐘的預設逾時套用到建構。timeout 必須以秒為單位指定,且不得超過九個小數位數,結尾必須是「s」。例如「3.5s」。

在下面的程式碼片段中,timeout 設定為 660 秒,以免建構因休眠而逾時:

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '600']
timeout: 660s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "600"
        ]
    }
    ],
    "timeout": "660s"
}

logsBucket

為建構設定 logsBucket 欄位可指定必須寫入記錄的 Cloud Storage 值區。如果您並未設定這個欄位,Cloud Build 將使用預設值區儲存建構記錄。

以下程式碼片段會設定儲存建構記錄的記錄值區:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
logsBucket: 'gs://mybucket'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "logsBucket": "gs://mybucket"
}

options

請使用 options 欄位為建構指定下列選用引數

sourceProvenanceHash:請設定 sourceProvenanceHash 選項,為原始碼來源指定雜湊演算法。以下程式碼片段指定雜湊演算法為 SHA256

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
    sourceProvenanceHash: ['SHA256']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "sourceProvenanceHash": ["SHA256"]
    }
}

machineType:Cloud Build 提供兩種高效率 CPU 虛擬機器類型來執行建構:8 個 CPU 與 32 個 CPU。預設機器類型為 1 個 CPU。如果要求高效率 CPU 虛擬機器,可能會增加建構的啟動時間。新增 machineType 選項可要求 CPU 效率較高的虛擬機器:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 machineType: 'N1_HIGHCPU_8'

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    },
    ],
    "options": {
        "machineType": "N1_HIGHCPU_8"
    }
}

如要進一步瞭解如何使用 machineType 選項,請參閱加速建構

diskSizeGb:請使用 diskSizeGb 選項針對建構要求自訂磁碟大小。您可以要求的大小上限為 1000 GB。

以下程式碼片段要求 200 GB 的磁碟大小:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 diskSizeGb: 200

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "diskSizeGb": 200
    }
}

logStreamingOption:請使用這個選項指定是否希望將建構記錄串流至 Cloud Storage。根據預設,Cloud Build 會在建構完成時收集建構記錄;這個選項可指定您是否要透過建構程序即時串流建構記錄。以下程式碼片段指定系統會將建構記錄串流至 Cloud Storage:

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['install', '.']
options:
 logStreamingOption: STREAM_ON

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "install",
            "."
        ]
    }
    ],
    "options": {
        "logStreamingOption": "STREAM_ON"
    }
}

logging:請使用這個選項指定是否希望在 Stackdriver Logging 或 Cloud Storage 中儲存記錄。如果您並未設定這個選項,Cloud Build 會將記錄儲存在 Stackdriver Logging 與 Cloud Storage 中。您可以將 logging 選項設定為 GCS_ONLY,以僅在 Cloud Storage 中儲存記錄。以下程式碼片段指定系統會將記錄儲存在 Cloud Storage 中:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
options:
 logging: GCS_ONLY

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "options": {
        "logging": "GCS_ONLY"
    }
}

substitutionOption:此選項將與以下的 substitutions 欄位一起設定,以指定當 substitution 檢查發生錯誤時的行為。

substitutions

在建構設定檔中使用 substitutions 可在建構時間替換特定變數。對於值在建構之前仍未知的變數,或者以不同變數值重複使用現有建構要求而言,substitutions 很實用。根據預設,如果有遺失的 substitution 變數或遺失的 substitution,建構會傳回錯誤,但是您可以使用 ALLOW_LOOSE 選項略過這項檢查。

以下程式碼片段使用 substitutions 輸出「hello world」。ALLOW_LOOSE substitution 選項已設定,表示如果有遺失的 substitution 變數或遺失的 substitution,建構不會傳回錯誤。

YAML

steps:
- name: 'ubuntu'
  args: ['echo', 'hello ${_SUB_VALUE}']
substitutions:
    _SUB_VALUE: world
options:
    substitution_option: 'ALLOW_LOOSE'

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "hello ${_SUB_VALUE}"
        ]
    }
    ],
    "substitutions": {
        "_SUB_VALUE": "world"
},
    "options": {
        "substitution_option": "ALLOW_LOOSE"
    }
}

如需使用 substitutions 的其他操作說明,請參閱取代變數值

tags

請使用 tags 欄位將建構分組,並篩選建構。以下設定會設定名為 mytag1mytag2 的兩個標記:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  ...
- name: 'ubuntu'
  ...
tags: ['mytag1', 'mytag2']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker"
    },
    {
        "name": "ubuntu"
    }
    ],
    "tags": [
        "mytag1",
        "mytag2"
    ]
}

secrets

Secret 會將包含加密值的一組私密環境變數,與用來解密值的 Cloud KMS 金鑰配對。請使用 secrets 欄位定義要使用 Cloud KMS 進行解密的密鑰。如需如何使用這個欄位的範例,請參閱使用已加密的密鑰和憑證

images

建構設定檔中的 images 欄位指定要由 Cloud Build 推送至 Container Registry 的一或多個 Docker 映像檔。您的建構可能會執行工作而不產生任何 Docker 映像檔,但如果您建構映像檔而不將映像檔推送至 Container Registry,系統會在建構完成時捨棄映像檔。如果在建構期間並未產生指定的映像檔,建構作業將會失敗。如要進一步瞭解如何儲存映像檔,請參閱儲存映像檔與成果一文。

以下建構設定會設定 images 欄位來儲存建構的映像檔:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/myproject/myimage', '.']
images: ['gcr.io/myproject/myimage']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/myproject/myimage",
            "."
        ]
    }
    ],
    "images": [
        "gcr.io/myproject/myimage"
    ]
}

artifacts

建構設定檔中的 artifacts 欄位指定儲存在 Cloud Storage 中的一或多個非容器成果。如要進一步瞭解如何儲存非容器成果,請參閱儲存映像檔與成果一文。

以下建構設定會設定 artifacts 欄位來將建構的 Go 套件儲存至 gs://mybucket/

YAML

steps:
- name: 'gcr.io/cloud-builders/go'
  args: ['build', 'my-package']
artifacts:
  objects:
    location: 'gs://mybucket/'
    paths: ['my-package']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/go",
        "args": [
            "build",
            "my-package"
        ]
    }
    ],
    "artifacts": {
      "objects": {
        "location": "gs://mybucket/",
        "paths": [
            "my-package"
        ]
      }
    }
}

後續步驟