Esquema do arquivo de configuração do build

Um arquivo desse tipo contém instruções para o Cloud Build executar tarefas de acordo com as especificações que você define. Por exemplo, seu arquivo de configuração de versão pode conter instruções para criar, empacotar e enviar imagens do Docker.

Nesta página, explicamos o esquema do arquivo de configuração do Cloud Build. Para instruções sobre como criar e usar um arquivo de configuração de versão, consulte Como criar um arquivo de configuração de versão básico.

Estrutura de um arquivo de configuração da criação

Os arquivos de configuração da versão são modelados por meio do recurso Build da API Cloud Build.

É possível gravar o arquivo de configuração da criação usando a sintaxe YAML ou JSON. Se você enviar solicitações de criação usando ferramentas http de terceiros, como curl, use a sintaxe JSON.

A estrutura do arquivo de configuração da criação é a seguinte:

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
- 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
 logStreamingOption: enum(LogStreamingOption)
 logging: enum(LoggingMode)
 defaultLogsBucketBehavior: enum(DefaultLogsBucketBehavior)
 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)
  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"
    },
    {
        "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",
        "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)",
      "mavenArtifacts": ["object(MavenArtifact)", ...],
      "pythonPackages": ["object(PythonPackage)", ...],
      "npmPackages": ["object(npmPackage)", ...],
    "images": [
        "string",
        "string",
        "..."
    ]
}

Cada uma das seções do arquivo de configuração da versão define uma parte da tarefa que você quer que o Cloud Build execute:

Etapas de versão

Uma etapa de versão especifica uma ação que o Cloud Build deve executar. Para cada etapa da criação, o Cloud Build executa um contêiner de Docker como uma instância de docker run. As etapas da criação são análogas aos comandos em um script e oferecem a flexibilidade de execução de instruções arbitrárias na versão. Se você puder inserir uma ferramenta de build em um contêiner, o Cloud Build poderá executá-la como parte da versão. Por padrão, o Cloud Build executa todas as etapas de um build em série na mesma máquina. Caso haja etapas que possam ser executadas simultaneamente, use a opção waitFor.

É possível incluir até 300 etapas de build no seu arquivo de configuração.

Use o campo steps, do arquivo de configuração da build para especificar uma etapa de build. Veja um snippet do tipo de configuração que é possível definir no campo 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

Use o campo name de uma etapa da criação para especificar um criador de nuvem, que é uma imagem de contêiner em que estão sendo executadas ferramentas comuns. Use um builder em uma etapa de build para executar suas tarefas.

O snippet a seguir mostra etapas da criação usadas para chamar os criadores bazel, gcloud e 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

O campo argsde uma etapa da criação recebe uma lista de argumentos e os transmite ao criador referido no campo name. Argumentos transmitidos para o criador são passados para a ferramenta que está sendo executada no criador, o que permite invocar qualquer comando compatível com a ferramenta. Se o criador usado na etapa da criação tiver um entrypoint, args será usado como argumentos para esse entrypoint. Se o criador não definir um entrypoint, o primeiro elemento em args será usado como entrypoint e os demais serão usados como argumento.

É possível criar até 100 argumentos por etapa. O comprimento máximo do argumento é de 10.000 caracteres.

O snippet a seguir invoca o comando docker build e instala as dependências do 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

O campo env de uma etapa da criação recebe uma lista de variáveis de ambiente a serem usadas na execução da etapa. As variáveis estão no formato KEY=VALUE.

Na configuração da criação a seguir, o campo env, da etapa da criação define a zona do Compute Engine e o cluster do GKE antes de executar o 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

Use o campo dir em uma etapa de versão para definir um diretório de trabalho a ser usado ao executar o contêiner da etapa. Se você definir o campo dir na etapa de criação, o diretório de trabalho será definido como /workspace/<dir>. Se esse valor for um caminho relativo, ele é relativo ao diretório de trabalho da criação. Se esse valor for absoluto, talvez ele esteja fora do diretório de trabalho da criação. Nesse caso, o conteúdo do caminho pode não ser permanente durante as execuções de etapas de criação, a não ser que seja especificado um volume para esse caminho.

O snippet de código a seguir define o diretório de trabalho para a etapa de build como /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"
    }
    ]
}

timeout

Para definir um limite de tempo para execução da etapa de criação, use o campo timeout em uma etapa. Se esse campo não for definido, a etapa não terá limite de tempo, permanecendo em execução até se concluir ou até que a própria criação expire. O campo timeout em uma etapa de build não pode exceder o valor de timeout especificado para uma build. É preciso que timeout seja especificado em segundos, com até nove dígitos fracionários, encerrados por "s". Exemplo: 3.5s

Na seguinte configuração de build, a etapa ubuntu expira após 500 segundos:

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"
        ]
    }
    ]
}

script

Use o campo script em uma etapa de criação para especificar um script de shell a ser executado na etapa. Se você especificar script em uma etapa de criação, não será possível especificar args ou entrypoint na mesma etapa. Para instruções sobre como usar o campo script, consulte Como executar scripts bash.

id

Use o campo id para definir um identificador exclusivo para uma etapa de build. id é usado com o campo waitFor para configurar a ordem em que as etapas de criação devem ser executadas. Para receber instruções sobre como usar waitFor e id, consulte Como configurar a ordem das etapas de criação.

waitFor

Use o campo waitFor em uma etapa de criação para especificar as etapas que precisam ser executadas antes que a etapa de criação seja executada. Se nenhum valor for informado para waitFor, a etapa de criação aguardará até que todas as etapas de criação anteriores, que façam parte da solicitação da criação, sejam concluídas com êxito, antes de proceder à execução. Para receber instruções sobre como usar waitFor e id, consulte Como configurar a ordem das etapas de criação.

entrypoint

Se você não quiser usar o entrypoint padrão do criador em uma etapa de criação, use entrypoint para especificar um. Se você não definir esse campo, o Cloud Build usará o entrypoint do criador. O snippet a seguir define os entrypoints da etapa de criação 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

Uma lista de variáveis de ambiente criptografadas com uma chave de criptografia do Cloud KMS. Esses valores precisam ser especificados nos segredos da criação. Para informações sobre como usar esse campo, consulte Como usar a variável criptografada em solicitações de criação.

volumes

Um Volume é um volume de contêiner do Docker que é montado nas etapas de criação para permitir a permanência de arquivos nas etapas de criação. Quando o Cloud Build executa uma etapa de criação, ele monta automaticamente um volume workspace em /workspace. Especifique mais volumes a serem montados nos contêineres das etapas de criação usando o campo volumes para suas etapas

Por exemplo, o arquivo de configuração da criação a seguir grava um arquivo em um volume na primeira etapa e faz a respectiva leitura na segunda etapa. Se o caminho /persistent_volume não for especificado por essas etapas como um volume permanente, a primeira etapa gravará o arquivo nesse caminho e depois esse arquivo será descartado antes da execução da segunda etapa Ao especificar o volume com o mesmo nome nas duas etapas, o conteúdo de /persistent_volume na primeira etapa é mantido na segunda etapa.

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"
        ]
     }
    ]
  }

allowFailure

Em uma etapa de build, se você definir o valor do campo allowFailure como true e a etapa falhar, a criação vai ser bem-sucedida, desde que todas as outras etapas dessa build sejam bem-sucedidas.

Se todas as etapas de um build tiverem allowFailure definido como true e todas falharem, o status do build ainda será Successful.

allowExitCodes tem prioridade sobre este campo.

O snippet de código abaixo permite que o build seja bem-sucedido quando a primeira etapa falha:

YAML

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

JSON

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

allowExitCodes

Use o campo allowExitCodes para especificar que uma falha em uma etapa de build possa ser ignorada quando essa etapa retornar um código de saída específico.

Se uma etapa de build falhar com um código de saída correspondente ao valor fornecido em allowExitCodes, o Cloud Build vai permitir que ela falhe sem gerar falha em todo o build.

Se 100% das etapas de build falharem, mas todas terminarem com um código especificado no campo allowExitCodes, o build ainda vai ser bem-sucedido.

No entanto, se a etapa de build falhar e produzir outro código de saída (um código que não corresponde ao valor especificado está em allowExitCodes), o build geral falhará.

Os códigos de saída relevantes para o build dependem do seu software. Por exemplo, "1" é um código de saída comum no Linux. Você também pode definir seus próprios códigos de saída em seus scripts. O campo allowExitCodes aceita números de até 255.

Esse campo tem precedência sobre allowFailure.

O snippet de código abaixo permite que o build seja bem-sucedido quando a primeira etapa falha com um dos códigos de saída fornecidos:

YAML

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

JSON

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

timeout

Use o campo timeout de uma criação para especificar o tempo de duração da permissão para que a criação seja executada, até a segunda granularidade. Se esse tempo terminar, o trabalho na criação será encerrado e o status da criação será TIMEOUT. Se timeout não for definido, um timeout padrão de 60 minutos será aplicado ao build. O valor máximo que pode ser aplicado ao timeout é de 24 horas. É preciso que timeout seja especificado em segundos, com até nove dígitos fracionários, encerrados por "s". Exemplo: 3.5s

No snippet a seguir, timeout está definido como 660 segundos, para evitar que a criação exceda o tempo limite devido ao modo de suspensão:

YAML

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

JSON

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

queueTtl

Use o campo queueTtl para especificar o tempo que uma versão pode ficar na fila. Se uma versão estiver na fila por mais tempo do que o valor definido em queueTtl, ela expirará e o status da versão será definido como EXPIRED. Se nenhum valor for fornecido, o Cloud Build vai usar o valor padrão de 3600s (1 hora). queueTtl começa a ser marcada a partir de createTime. É preciso especificar queueTtl em segundos, com até nove dígitos fracionários, encerrados por "s". Por exemplo, 3.5s.

No snippet a seguir, timeout é definido como 20s e queueTtl é definido como 10s. queueTtl começa a marcar em createTime, que é o momento em que o build é solicitado, e timeout começa em startTime, que é o momento em que o build é iniciado. Portanto, queueTtl expira em createTime + 10s, a menos que o build comece até essa data.

YAML

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

JSON

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

logsBucket

Defina o campo logsBucket de uma criação para especificar um bucket do Cloud Storage em que os registros precisam ser gravados. Se você não definir esse campo, o Cloud Build usará um bucket padrão para armazenar os registros de criação.

O snippet a seguir define um bucket de registros para armazenar os registros de versão:

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

Use o campo options para especificar os seguintes argumentos opcionais do seu build:

env : uma lista de definições de variáveis de ambiente global para todas as etapas de criação nessa criação. Se uma variável for definida tanto globalmente quanto em uma etapa de criação, a variável usará o valor da etapa de criação. Os elementos estão no formato KEY=VALUE para a variável de ambiente KEY receber o valor VALUE.

secretEnv : uma lista de variáveis de ambiente global, criptografada usando uma chave de criptografia do Cloud Key Management Service, que estará disponível para todas as etapas de criação. É preciso que esses valores sejam especificados no Secret da criação.

volumes : uma lista de volumes a serem montados globalmente para TODAS as etapas de criação. Cada volume é criado como um volume vazio, antes do início do processo de criação. Após a conclusão da versão, os volumes e seus conteúdos são descartados. Os caminhos e nomes de volume globais não podem entrar em conflito com os volumes definidos em uma etapa de criação. O uso de um volume global em uma criação com apenas uma etapa não é válido porque isso significa uma solicitação de criação com uma configuração incorreta.

sourceProvenanceHash : defina a opção sourceProvenanceHash para especificar o algoritmo de hash para a origem. O snippet a seguir especifica que o algoritmo hash é 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: o Cloud Build fornece quatro máquina virtual de alta CPU para executar seus builds: dois com 8 CPUs e dois com 32 CPUs. O Cloud Build também fornece dois tipos máquina virtual adicionais com uma CPU e duas CPUs para executar as versões. O tipo de máquina padrão é e2-standard-2 com duas CPUs. Solicitar uma máquina virtual com grande quantidade de CPUs pode aumentar o tempo de inicialização do seu build. Adicione a opção machineType para solicitar uma máquina virtual com mais CPU:

YAML

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

JSON

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

Para receber mais informações sobre como usar a opção machineType, consulte Como acelerar as criações .

diskSizeGb : use a opção diskSizeGb para solicitar um tamanho de disco personalizado para sua criação. O tamanho máximo que pode ser solicitado é de 2.000 GB.

O snippet a seguir solicita um tamanho de disco de 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: use essa opção para especificar que seja feito stream de registros de criação para o Cloud Storage. Por padrão, o Cloud Build coleta registros de criação na conclusão da criação. Essa opção especifica se você quer transmitir registros de criação em tempo real por meio do processo de criação. O snippet a seguir especifica que os registros de versão são transmitidos para o 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: use essa opção para especificar se você quer armazenar registros no Cloud Logging ou no Cloud Storage. Se você não definir essa opção, o Cloud Build armazenará os registros no Cloud Logging e no Cloud Storage. É possível definir a opção logging para GCS_ONLY para armazenar os registros apenas no Cloud Storage. O seguinte snippet especifica que os registros são armazenados no 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"
    }
}

defaultLogsBucketBehavior: a opção defaultLogsBucketBehavior permite configurar o Cloud Build para criar um bucket de registros padrão no seu próprio projeto na mesma região do build. Para saber mais, consulte Armazenar registros de build em um bucket regionalizado e do usuário.

A configuração de build a seguir define o campo defaultLogsBucketBehavior como o valor REGIONAL_USER_OWNED_BUCKET:

YAML

steps:
- name: 'gcr.io/cloud-builders/docker'
  args: [ 'build', '-t', 'us-central1-docker.pkg.dev/myproject/myrepo/myimage', '.' ]
options:
  defaultLogsBucketBehavior: REGIONAL_USER_OWNED_BUCKET

JSON

{
  "steps": [
    {
      "name": "gcr.io/cloud-builders/docker",
      "args": [
        "build",
        "-t",
        "us-central1-docker.pkg.dev/myproject/myrepo/myimage",
        "."
      ]
    }
    ],
    "options": {
      "defaultLogsBucketBehavior": "REGIONAL_USER_OWNED_BUCKET"
    }
}

dynamic_substitutions: use essa opção para ativar ou desativar explicitamente a expansão de parâmetro bash nas substituições. Se o build for invocado por um gatilho, o campo dynamic_substitutions será sempre definido como "true" e não precisará ser especificado no arquivo de configuração da compilação. Caso sua versão seja invocada manualmente, você precisa definir o campo dynamic_substitutions como verdadeiro para que as expansões de parâmetro bash sejam interpretadas ao executar sua versão.

substitutionOption : você definirá essa opção com o campo substitutions abaixo para especificar o comportamento quando houver um erro nas verificações de substituição.

pool: defina o valor desse campo como o nome do recurso do pool particular para executar o build. Para instruções sobre como executar um build em um pool particular, consulte Como executar builds em um pool particular.

requestedVerifyOption: defina o valor de requestedVerifyOption como VERIFIED para verificar a geração de attestations e metadados de comprovação para seu build. Essa opção também ativa atestados e metadados de procedência para builds e builds regionais em pools particulares. Se você não adicionar requestedVerifyOption: VERIFIED, o Cloud Build vai gerar procedência apenas para builds globais.

substitutions

Use substituições em seu arquivo de configuração da criação para substituir variáveis específicas no momento da criação. As substituições são úteis para variáveis que tenham um valor não conhecido até o momento da criação ou para reutilizar uma solicitação de versão existente com diferentes valores variáveis. Por padrão, a criação retornará um erro se faltar uma variável de substituição ou uma substituição. No entanto, é possível usar a opção ALLOW_LOOSE para ignorar essa verificação.

O snippet a seguir usa substituições para gerar "hello world". A opção de substituição ALLOW_LOOSE está definida, o que significa que a versão não retornará um erro se faltar uma variável de substituição ou uma substituição.

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"
    }
}

Para receber mais instruções sobre o uso de substitutions, consulte Como substituir valores de variável.

tags

Use o campo tags para organizar suas criações em grupos e filtrar suas criações. A configuração a seguir define duas tags chamadas mytag1 e mytag2:

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"
    ]
}

availableSecrets

Use este campo para usar um secret do Gerenciador de secrets com o Cloud Build. Para mais informações, consulte Como usar secrets.

secrets

Um secret combina um conjunto de variáveis de ambiente secretas contendo valores criptografados com a chave do Cloud KMS a ser usada para descriptografar o valor.

serviceAccount

Use este campo para especificar a conta de serviço do IAM a ser usada no momento da criação. Para mais informações, consulte Como configurar contas de serviço especificadas pelo usuário.

images

O campo images no arquivo de configuração da versão especifica uma ou mais imagens do Docker do Linux a serem enviadas pelo Cloud Build para o Artifact Registry ou o Container Registry (descontinuado). É possível ter um build que executa tarefas sem produzir imagens do Linux Docker, mas se você criar imagens e não enviá-las para o registro, elas serão descartadas na conclusão da criação. Se uma imagem especificada não for produzida durante a versão, a versão apresentará falha. Para mais informações sobre como armazenar imagens, consulte Armazenar artefatos no Artifact Registry.

A seguinte configuração da criação define o campo images para armazenar a imagem criada:

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

No arquivo de configuração da criação, o campo artifacts especifica um ou mais artefatos que não são contêineres a serem armazenados no Cloud Storage. Para mais informações sobre como armazenar artefatos que não sejam contêineres, consulte Armazenar artefatos de versão no Cloud Storage.

A configuração a seguir define o campo artifacts para armazenar o pacote Go criado para 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"
        ]
      }
    }
}

mavenArtifacts

O campo mavenArtifacts permite fazer upload de artefatos Java que não são contêineres para repositórios Maven no Artifact Registry. Para saber mais, consulte Criar e testar aplicativos Java.

A configuração do build a seguir define o campo mavenArtifacts para fazer upload do arquivo empacotado my-app-1.0-SNAPSHOT.jar para o repositório https://us-central1-maven.pkg.dev/my-project-id/my-java-repo do Artifact Registry:

YAML

artifacts:
  mavenArtifacts:
    - repository: 'https://us-central1-maven.pkg.dev/my-project-id/my-java-repo'
      path: '/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar'
      artifactId: 'my-app-1'
      groupId: 'com.mycompany.app'
      version: '1.0.0'

JSON

{
  "artifacts": {
    "mavenArtifacts": [
      {
        "repository": "https://us-central1-maven.pkg.dev/my-project-id/my-java-repo",
        "path": "/workspace/my-app/target/my-app-1.0-SNAPSHOT.jar",
        "artifactId": "my-app-1",
        "groupId": "com.mycompany.app",
        "version": "1.0.0"
      }
    ]
  }
}

pythonPackages

O campo pythonPackages permite fazer upload de pacotes Python para o Artifact Registry. Para mais informações, consulte Criar e testar aplicativos Python.

A configuração do build a seguir define o campo pythonPackages para fazer upload do pacote Python dist/my-pkg.whl para o repositório https://us-east1-python.pkg.dev/my-project/my-repo do Artifact Registry:

YAML

artifacts:
  pythonPackages:
   - repository: 'https://us-east1-python.pkg.dev/my-project/my-repo'
     paths: ['dist/my-pkg.whl']

JSON

{
  "artifacts": {
    "pythonPackages": [
      {
        "repository": "https://us-east1-python.pkg.dev/my-project/my-repo",
        "paths": ["dist/my-pkg.whl"]
      }
    ]
  }
}

npmPackages

Use o campo npmPackages para configurar o Cloud Build e fazer upload dos pacotes npm criados para repositórios compatíveis no Artifact Registry. É necessário fornecer valores para repository e packagePath.

O campo repository especifica o repositório do Artifact Registry para armazenar pacotes. O campo packagePath especifica o diretório local que contém o pacote npm para upload. Esse diretório precisa conter um arquivo package.json.

Recomendamos usar um caminho absoluto para o valor de packagePath. É possível usar . para se referir ao diretório de trabalho atual, mas o campo não pode ser omitido ou deixado em branco. Para mais instruções sobre o uso do npmPackages, consulte Criar e testar aplicativos Node.js.

A configuração de build a seguir define o campo npmPackages para fazer upload do pacote npm no diretório /workspace/my-pkg para o repositório https://us-east1-npm.pkg.dev/my-project/my-repo do Artifact Registry.

YAML

artifacts:
  npmPackages:
   - repository: 'https://us-east1-npm.pkg.dev/my-project/my-repo'
     packagePath: '/workspace/my-pkg'

JSON

{
  "artifacts": {
    "npmPackages": [
      {
        "repository": "https://us-east1-npm.pkg.dev/my-project/my-repo",
        "packagePath": "/workspace/my-pkg"
      }
    ]
  }
}

Como usar Dockerfiles

Se você estiver executando versões do Docker no Cloud Build usando a CLI gcloud ou gatilhos de build, poderá usar um Dockerfile sem um arquivo de configuração de build separado. Se você quiser fazer mais ajustes nos seus builds do Docker, forneça um arquivo de configuração do build, além do Dockerfile. Para instruções sobre como criar uma imagem do Docker usando um Dockerfile, consulte o Guia de início rápido: criar.

Rede do Cloud Build

Quando o Cloud Build executa cada etapa de build, ele anexa o contêiner da etapa a uma rede local do Docker denominada cloudbuild. A rede cloudbuild hospeda Application Default Credentials (ADC) que os serviços do Google Cloud podem usar para encontrar suas credenciais automaticamente. Se você estiver executando contêineres do Docker aninhados e quiser expor o ADC a um contêiner subjacente ou usar gsutil ou gcloud em uma etapa docker, use a sinalização --network no a etapa build do docker:

YAML

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

JSON

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

A seguir