构建配置文件架构

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

本页面介绍了 Cloud Build 构建配置文件的架构。 如需了解如何创建和使用构建配置文件，请参阅创建基本的构建配置文件。

构建配置文件的结构

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

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

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

YAML

steps:
- name: string
  args: [string, string, ...]
  env: [string, string, ...]
  allowFailure: boolean
  allowExitCodes: [string (int64 format), string (int64 format), ...]
  dir: string
  id: string
  waitFor: [string, string, ...]
  entrypoint: string
  secretEnv: string
  volumes: object(Volume)
  timeout: string (Duration format)
  script: string
  automapSubstitutions: boolean
  results: object(Results)
- 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)
 dynamicSubstitutions: boolean
 automapSubstitutions: boolean
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
 defaultLogsBucketBehavior: enum(DefaultLogsBucketBehavior)
 pool: object(PoolOption)
 pubsubTopic: string
 requestedVerifyOption: enum(RequestedVerifyOption)
substitutions: map (key: string, value: string)
tags: [string, string, ...]
serviceAccount: string
secrets: object(Secret)
availableSecrets: object(Secrets)
artifacts: object(Artifacts)
  goModules: [object(GoModules), ...]
  mavenArtifacts: [object(MavenArtifact), ...]
  pythonPackages: [object(PythonPackage), ...]
  npmPackages: [object(npmPackage), ...]
images:
- [string, string, ...]

JSON

{
    "steps": [
    {
        "name": "string",
        "args": [
            "string",
            "string",
            "..."
        ],
        "env": [
            "string",
            "string",
            "..."
        ],
        "allowFailure": "boolean",
        "allowExitCodes: [
            "string (int64 format)",
            "string (int64 format)",
            "..."
        ],
        "dir": "string",
        "id": "string",
        "waitFor": [
            "string",
            "string",
            "..."
        ],
        "entrypoint": "string",
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "timeout": "string (Duration format)",
        "script" : "string",
        "automapSubstitutions" : "boolean",
        "results": "object(Results)"
    },
    {
        "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)",
        "dynamicSubstitutions": "boolean",
        "automapSubstitutions": "boolean",
        "logStreamingOption": "enum(LogStreamingOption)",
        "logging": "enum(LoggingMode)"
        "defaultLogsBucketBehavior": "enum(DefaultLogsBucketBehavior)"
        "env": [
            "string",
            "string",
            "..."
        ],
        "secretEnv": "string",
        "volumes": "object(Volume)",
        "pool": "object(PoolOption)"
        "requestedVerifyOption": "enum(RequestedVerifyOption)"
    },
    "substitutions": "map (key: string, value: string)",
    "tags": [
        "string",
        "string",
        "..."
    ],
    "serviceAccount": "string",
    "secrets": "object(Secret)",
    "availableSecrets": "object(Secrets)",
    "artifacts": "object(Artifacts)",
      "goModules": [object(GoModules), ...],
      "mavenArtifacts": ["object(MavenArtifact)", ...],
      "pythonPackages": ["object(PythonPackage)", ...],
      "npmPackages": ["object(npmPackage)", ...],
    "images": [
        "string",
        "string",
        "..."
    ]
}

构建配置文件的每个部分都定义了您想要 Cloud Build 执行的任务的一部分：

构建步骤

构建步骤指定您想要 Cloud Build 执行的操作。对于每个构建步骤，Cloud Build 都会将 docker 容器作为 docker run 的实例执行。构建步骤类似于脚本中的命令，便于您在构建中灵活执行任意指令。如果您可以将构建工具打包到容器中，则 Cloud Build 可将构建工具作为构建的一部分执行。默认情况下，Cloud Build 会在同一机器上顺序执行所有构建步骤。如果您有可以并发运行的步骤，请使用 waitFor 选项。

配置文件中最多可以包含 300 个构建步骤。

使用构建配置文件中的 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，这是一种运行常见工具的容器映像。您可以在构建步骤中使用构建器来执行任务。

以下代码段展示了调用 bazel、gcloud 和 docker 构建器的构建步骤：

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 中的第一个元素将用作入口点，其余元素将用作参数。

每个步骤最多可以创建 100 个参数。实参长度上限为 10,000 个字符。

以下代码段调用 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"
        ]
    }
    ]
}

allowFailure

在构建步骤中，如果您将 allowFailure 字段的值设置为 true，并且该构建步骤失败，那么只要相应构建中的所有其他构建步骤都成功，该构建就会成功。

如果 build 中的所有 build 步骤都将 allowFailure 设置为 true，并且所有 build 步骤都失败，则 build 的状态仍为 Successful。

allowExitCodes 的优先级高于此字段。

以下代码段允许在第一个步骤失败时构建成功：

YAML 

steps:
- name: 'ubuntu'
  args: [ '-c', 'exit 1']
  allowFailure: true
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON 

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit -1"
        ],
        "allowFailure": true,
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

allowExitCodes

使用 allowExitCodes 字段指定当构建步骤返回特定退出代码时，可以忽略该步骤的失败。

如果构建步骤失败，且退出代码与您在 allowExitCodes 中提供的值一致，则 Cloud Build 将允许此构建步骤失败，而不会导致整个构建失败。

如果 100% 的 build 步骤都失败了，但每个步骤都以您在 allowExitCodes 字段中指定的代码退出，那么 build 仍然成功。

不过，如果 build 步骤失败，并生成了另一个退出代码（与您在 allowExitCodes 中指定的值不匹配），则整个 build 将失败。

与您的 build 相关的退出代码取决于您的软件。例如，“1”是 Linux 中的常见退出代码。您还可以在脚本中定义自己的退出代码。allowExitCodes 字段接受的数字上限为 255。

此字段的优先级高于 allowFailure。

以下代码段允许在第一个步骤因提供的某个退出代码而失败时，构建成功完成：

YAML 

steps:
- name: 'ubuntu'
  args: ['-c', 'exit 1']
  allowExitCodes: [1]
- name: 'ubuntu'
  args: ['echo', 'Hello World']

JSON 

{
  "steps": [
    {
        "name": "ubuntu",
        "args": [
            "-c",
            "exit 1"
        ],
        "allowExitCodes": [1],
    },
    {
        "name": "ubuntu",
        "args": [
            "echo",
            "Hello World"
        ]
    }
  ]
}

dir

在构建步骤中使用 dir 字段设置运行该步骤的容器时使用的工作目录。如果您在构建步骤中设置了 dir 字段，则工作目录会设置为 /workspace/<dir>。如果此值是相对路径，则它相对于构建的工作目录。如果此值是绝对值，则它可能位于构建的工作目录之外，在这种情况下，在构建步骤执行期间，该路径的内容可能不会持久保留（除非指定了该路径的卷）。

以下代码段会将构建步骤的工作目录设置为 /workspace/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"
    }
    ]
}

ID

使用 id 字段为构建步骤设置唯一标识符。请将 id 与 waitFor 字段一起使用，以配置运行构建步骤的顺序。如需了解如何使用 waitFor 和 id，请参阅配置构建步骤顺序。

waitFor

在构建步骤中使用 waitFor 字段指定在运行该构建步骤之前必须运行的步骤。如果没有为 waitFor 提供任何值，则构建步骤将在构建请求中的所有先前构建步骤成功完成后才开始运行。如需了解如何使用 waitFor 和 id，请参阅配置构建步骤顺序。

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'