构建配置概览

构建配置文件包含 Cloud Build 根据您的规范执行任务的说明。例如,您的构建配置文件可以包含构建、打包和推送 Docker 映像的说明。

本页面介绍了 Cloud Build 构建配置文件的结构。

构建配置文件的结构

构建配置文件使用 Cloud Build API 的 Build 资源进行建模。

您可以使用 YAML 或 JSON 语法编写构建配置文件。如果您使用第三方 http 工具(如 curl)提交构建请求,请使用 JSON 语法。

构建配置文件的结构如下:

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  dir: string
  id: string
  waitFor: [string, string, ...]
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
- name: string
  ...
- name: string
  ...
timeout: string (Duration format)
queueTtl: string (Duration format)
logsBucket: string
options:
 env: [string, string, ...]
 secretEnv: string
 volumes: object(Volume)
 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",
            "string",
            "..."
        ],
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)"
    },
    {
        "name": "string"
        ...
    },
    {
        "name": "string"
        ...
    }
    ],
    "timeout": "string (Duration format)",
    "queueTtl": "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)"
        "env": [
            "string",
            "string",
            "..."
        ],
        "secretEnv": "string",
        "volumes": "object(Volume)",
    },
    "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 可将构建工具作为构建的一部分执行。默认情况下,Cloud Build 会在同一机器上顺序执行所有构建步骤。如果您有可以并发运行的步骤,请使用 waitFor 选项。

您可以在配置文件中包含一个或多个构建步骤。

使用构建配置文件中的 steps 字段可以指定一个构建步骤。以下代码段展示了您可以在 steps 字段中设置的配置类型:

YAML

steps:
- name: 'gcr.io/cloud-builders/kubectl'
  args: ['set', 'image', 'deployment/mydepl', 'my-image=gcr.io/my-project/myimage']
  env:
  - 'CLOUDSDK_COMPUTE_ZONE=us-east4-b'
  - 'CLOUDSDK_CONTAINER_CLUSTER=my-cluster'
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t', 'gcr.io/my-project-id/myimage', '.']

JSON

{
    "steps": [
    {
        "name": "gcr.io/cloud-builders/kubectl",
        "args": [
            "set",
            "image"
            "deployment/mydepl"
            "my-image=gcr.io/my-project/myimage"
        ],
        "env": [
            "CLOUDSDK_COMPUTE_ZONE=us-east4-b",
            "CLOUDSDK_CONTAINER_CLUSTER=my-cluster"
        ]
    },
    {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
            "build",
            "-t",
            "gcr.io/my-project-id/myimage",
            "."
        ]
    }
    ]
}

name

使用构建步骤的 name 字段来指定 Cloud Builder,这是一种运行常见工具的容器映像。您可以在构建步骤中使用构建器来执行任务。

以下代码段展示了调用 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 字段会在执行 kubectl 之前设置 Compute Engine 地区和 GKE 集群:

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 字段值不得超过为构建指定的 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 来指定入口点。如果您未设置此字段,则 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,则系统会为构建使用默认 timeout 值,即 10 分钟。可为 timeout 应用的最大值为 24 小时。timeout 必须以秒为单位指定,最多包含九个小数位,并以“s”结尾。示例:"3.5s"

在以下代码段中,timeout 设置为 660 秒,以避免构建因休眠而超时:

YAML

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

JSON

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

queueTtl

使用 queueTtl 字段指定构建可以加入队列的时长。如果构建在队列中的时长超过 queueTtl 中设置的值,则构建会过期,并且构建状态设置为 EXPIREDqueueTtlcreateTime 开始计时。queueTtl 必须以秒为单位指定,最多包含九个小数位,并以“s”结尾,例如“3.5s”。

在以下代码段中,timeout 设置为“20s”,而 queueTtl 设置为“10s”。queueTtlcreateTime(即构建的请求时间)开始计时,timeoutstartTime(即构建的启动时间)开始计时。因此,queueTtl 将于 createTime + 10s 过期,除非在这个时间点启动构建。

YAML

steps:
- name: 'ubuntu'
  args: ['sleep', '5']
timeout: 20s
queueTtl: 10s

JSON

{
    "steps": [
    {
        "name": "ubuntu",
        "args": [
            "sleep",
            "5"
        ]
    }
    ],
    "timeout": "20s",
    "queueTtl": "10s"
}

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可选参数

env:将存在于此构建的所有构建步骤中的全局环境变量定义列表。如果同时在全局范围内和构建步骤中定义了变量,则该变量将使用构建步骤值。元素的格式为 KEY=VALUE,表示环境变量 KEY 的值为 VALUE

secretEnv:使用 Cloud Key Management Service 加密密钥加密的全局环境变量列表,这些变量可用于此构建中的所有构建步骤。您必须在构建的 Secret 中指定这些值。

volumes:要在全局范围内为所有构建步骤装载的卷列表。在开始构建过程之前,每个卷都是作为空卷创建的。构建完成后,系统会舍弃卷及其内容。全局卷名称和路径不能与构建步骤定义的卷冲突。在只有一个步骤的构建中使用全局卷是无效的,因为它意味着构建请求的配置不正确。

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:使用此选项指定是要在 Cloud 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 字段,以指定当替代变量检查出现错误时采取的行为。

substitutions

在构建配置文件中使用 substitutions 以在构建时替换特定变量。对于那些直到构建时才知道值的变量,或者使用不同的变量值重用现有构建请求,替代变量很有用。默认情况下,如果缺少替代变量或缺少替换,则构建将返回错误。但您可以使用 ALLOW_LOOSE 选项跳过此检查。

以下代码段使用替代变量来打印“hello world”。ALLOW_LOOSE 替换选项已设置,这意味着如果缺少替代变量或缺少替换,则构建不会返回错误。

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 字段将构建分成组,并过滤构建。以下配置设置了名为 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

密钥将包含加密值的一组秘密环境变量与用于解密该值的 Cloud KMS 密钥进行配对。使用 secrets 字段定义要使用 Cloud KMS 解密的 secret。如需查看有关如何使用此字段的示例,请参阅使用加密的 secret 和凭据

图片

构建配置文件中的 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"
        ]
      }
    }
}

使用 Dockerfile

如果您使用的 gcloud 工具或构建触发器在 Cloud Build 中执行 Docker 构建,可以只使用 Dockerfile 来构建映像。您不需要单独的构建配置文件。如果您想要对 Docker 构建进行更多调整,则除了 Dockerfile 之外,您还可以提供构建配置文件。如需查看关于如何使用 Dockerfile 创建 Docker 映像的说明,请参阅 Docker 快速入门

Cloud Build 网络

在 Cloud Build 运行每个构建步骤时,它会将相应步骤的容器连接到一个名为 cloudbuild 的本地 Docker 网络。cloudbuild 网络托管着应用默认凭据 (ADC),Google Cloud 服务可使用 ADC 来自动查找您的凭据。如果您运行的是嵌套的 Docker 容器,并希望将 ADC 公开给底层容器,请在 Docker 的 build 步骤中使用 --network 标志:

YAML

steps:
- name: gcr.io/cloud-builders/docker
  args: ["build","--network=cloudbuild", "."]

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "--network=cloudbuild",
        "."
      ]
   }
  ]
}

后续步骤