Visão geral da configuração da versão

Nesta página, explicamos a estrutura do arquivo de configuração da versão do Cloud Build.

Dockerfile e arquivo de configuração da versão

Se você estiver executando versões que não são do Docker no Cloud Build usando a ferramenta de linha de comando gcloud ou um acionador de versão, será necessário fornecer um arquivo de configuração da versão. 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 da versão pode conter instruções para criar, empacotar e enviar imagens do Docker.

Se você estiver executando versões do Docker usando a ferramenta gcloud ou acionadores de versão, use um Dockerfile ou um arquivo de configuração da versão para criar a imagem. Para ver instruções sobre como criar uma imagem do Docker usando um Dockerfile, consulte os Guias de início rápido usando o Docker.

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

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

Escreva o arquivo de configuração da versão usando a sintaxe YAML ou JSON. Se você enviar solicitações de versão usando ferramentas http de terceiros, como curl, use a sintaxe JSON. É necessário criar o arquivo de configuração da versão no diretório raiz do seu projeto. O Cloud Build fará a leitura dele sempre que iniciar uma versão.

Um arquivo de configuração da versão tem a seguinte estrutura:

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

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 de versão, o Cloud Build executa um contêiner de Docker como uma instância de docker run. As etapas de versão são análogas aos comandos em um script e oferecem a flexibilidade de executar instruções arbitrárias na versão. Se você puder inserir uma ferramenta de versão em um contêiner, o Cloud Build poderá executá-la como parte da versão.

Você pode incluir uma ou mais etapas de versão em seu arquivo de configuração.

Use o campo steps no arquivo de configuração da versão para especificar uma etapa de versão. Veja um trecho do tipo de configuração que você pode definir no campo 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

Use o campo name de uma etapa de versão para especificar um criador de nuvem, que é uma imagem de contêiner que executa ferramentas comuns. Use um construtor em uma etapa de versão para executar suas tarefas.

O snippet a seguir mostra etapas de versão que chamam os criadores de 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 args de uma etapa de versão transmite uma lista de argumentos ao construtor referenciado pelo campo name. Argumentos transmitidos para o construtor são passados para a ferramenta que está sendo executada no construtor, o que permite invocar qualquer comando aceito pela ferramenta. Se o construtor usado na etapa de versão tiver um ponto de entrada, args será usado como os argumentos para esse ponto de entrada. Se o construtor não definir um ponto de entrada, o primeiro elemento em args será usado como ponto de entrada e o restante será usado como argumento.

O fragmento 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 de versão transmite uma lista de variáveis de ambiente a serem usadas ao executar a etapa. As variáveis estão no formato KEY=VALUE.

Na configuração da versão a seguir, o campo env da etapa de versão define a zona do Compute Engine e o cluster do GKE antes da execução de 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 a etapa. Por padrão, o Cloud Build usa um diretório chamado /workspace como diretório de trabalho. Se o arquivo de configuração tiver mais de uma etapa de versão, os recursos produzidos por uma etapa poderão ser transmitidos para a próxima por meio da persistência do diretório /workspace, que permite configurar um pipeline de etapas de versão que compartilhem ativos. Se você definir o campo dir na etapa de versão, o diretório de trabalho será configurado para /workspace/<dir>. Se esse valor for um caminho relativo, ele é relativo ao diretório de trabalho da versão. Se esse valor for absoluto, pode estar fora do diretório de trabalho da versão, caso em que o conteúdo do caminho pode não ser persistido durante as execuções de etapas de versão (a menos que um volume para esse caminho seja especificado).

O snippet a seguir define o diretório de trabalho como 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

Use o campo timeout em uma etapa de versão para definir um limite de tempo para executar a etapa. Se você não definir esse campo, a etapa não tem limite de tempo e poderá ficar em execução até ser concluída ou a versão expirar. timeout precisa ser especificado em segundos com até nove dígitos fracionários, terminados por "s". Exemplo: "3.5s"

Na configuração da versão a seguir, 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"
        ]
    }
    ]
}

id

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

waitFor

Use o campo waitFor em uma etapa de versão para especificar quais etapas precisam ser executadas antes dela. Se nenhum valor for fornecido para waitFor, a etapa de versão aguarda a conclusão de todas as etapas de versão anteriores na solicitação de versão antes de serem executadas. Para ver instruções sobre como usar waitFor e id, consulte Como configurar a ordem das etapas de versão.

entrypoint

Use entrypoint em uma etapa de versão para especificar um ponto de entrada se você não quiser usar o padrão do construtor. Se você não definir esse campo, o Cloud Build usará o ponto de entrada do construtor. O snippet a seguir define os pontos de entrada para a etapa de versã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 versão. Para informações sobre como usar esse campo, consulte Como usar a variável criptografada em solicitações de versão.

volumes

Um Volume é um contêiner do Docker ativado em etapas de versão para manter arquivos nessas etapas. Quando o Cloud Build executa uma etapa de versão, ele ativa automaticamente um volume workspace em /workspace. Você pode especificar volumes adicionais a serem ativados nos contêineres de etapas de versão usando o campo volumes em suas etapas.

Por exemplo, o arquivo de configuração da versão a seguir grava um arquivo em um volume na primeira etapa e faz a leitura dele na segunda etapa. Se essas etapas não especificarem o caminho /persistent_volume como um volume persistente, a primeira etapa escreverá o arquivo no caminho. Em seguida, esse arquivo será descartado antes da execução da segunda etapa. Ao especificar o volume com o mesmo nome em ambas as etapas, o conteúdo de /persistent_volume na primeira etapa será mantido na segunda.

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

Use o campo timeout de uma versão para especificar a quantidade de tempo permitida para execução da versão, para a granularidade de segundos. Se esse tempo se esgotar, o trabalho na versão cessará, e o status da versão será TIMEOUT. Se timeout não estiver definido, um tempo limite padrão de 10 minutos será aplicado à versão. timeout precisa ser especificado em segundos com até nove dígitos fracionários, terminados por "s". Exemplo: "3.5s"

No snippet a seguir, timeout é definido para 660 segundos para evitar o esgotamento do tempo limite da versão em função da suspensão:

YAML

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

JSON

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

logsBucket

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

O snippet a seguir define um intervalo 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 para sua versão:

sourceProvenanceHash: defina a opção sourceProvenanceHash para especificar o algoritmo hash da proveniência de 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 dois tipos de máquinas virtuais de alta CPU para executar suas versões: a de 8 CPUs e a de 32 CPUs. O tipo de máquina padrão é de uma CPU. Solicitar uma máquina virtual de alta CPU pode aumentar o tempo de inicialização da sua versão. Adicione a opção machineType para solicitar uma máquina virtual com uma CPU mais alta:

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

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

diskSizeGb: use a opção diskSizeGb para solicitar um tamanho de disco personalizado para sua versão. O tamanho máximo que você pode solicitar é de 1.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 se quer transmitir registros de versão para o Cloud Storage. Por padrão, o Cloud Build coleta registros de versão na conclusão da versão. Essa opção especifica se você quer transmitir registros de versão em tempo real por meio do processo de versã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 quer armazenar registros no Stackdriver Logging ou no Cloud Storage. Se você não definir essa opção, o Cloud Build armazenará os registros no Stackdriver Logging e no Cloud Storage. É possível definir a opção logging como 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"
    }
}

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.

Substituições

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

O snippet a seguir usa substituições para imprimir "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 houver uma variável de substituição ausente ou uma substituição ausente.

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 ver mais instruções sobre o uso de substitutions, consulte Como substituir valores de variáveis.

tags

Use o campo tags para agrupar e filtrar suas versões. A seguinte configuração 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"
    ]
}

secrets

Um segredo 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. Use o campo secrets a fim de definir chaves secretas para descriptografar usando o Cloud KMS. Para ver um exemplo de como usar esse campo, consulte Como usar chaves secretas e credenciais criptografadas.

images

O campo images no arquivo de configuração da versão especifica uma ou mais imagens do Docker a serem enviadas pelo Cloud Build ao Container Registry. Você pode ter uma versão que executa tarefas sem produzir nenhuma imagem do Docker, mas se você criar imagens e não as enviar para o Container Registry, elas serão descartadas na conclusão da versã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 Como armazenar imagens e artefatos.

A configuração da versão a seguir 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

O campo artifacts no arquivo de configuração da versão especifica um ou mais artefatos que não sejam contêineres para serem armazenados no Cloud Storage. Para mais informações sobre como armazenar artefatos que não sejam contêineres, consulte Como armazenar imagens e artefatos.

A seguinte configuração da versão define o campo artifacts para armazenar o pacote do Go criado em 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"
        ]
      }
    }
}

A seguir

Enviar comentários sobre…