Esta página descreve como iniciar um build no Cloud Build manualmente usando a CLI do Google Cloud e a API Cloud Build.
Antes de começar
- Para usar os exemplos de linha de comando deste guia, instale a Google Cloud CLI.
- Para criar usando a configuração da versão do Cloud Build, crie um arquivo de configuração da versão.
- Para criar usando um
Dockerfile
, prepare seuDockerfile
. - Se a compilação exigir código-fonte, tenha o código-fonte em mãos.
Permissões do IAM obrigatórias
- Se você estiver armazenando registros de versão no bucket de registros padrão, será necessário ter o papel Visualizador do projeto e o papel de Editor do Cloud Build para executar uma versão.
- Se você armazena registros de criação no bucket de registros criados pelo usuário, é necessário ter o papel de editor do Cloud Build para executar uma compilação.
- Se você usa pools particulares, é necessário ter o papel Usuário do WorkerPool do Cloud Build para executar dos builds.
Para instruções sobre como conceder papéis do IAM, consulte Configurar o acesso aos recursos do Cloud Build.
Como executar versões
É possível especificar a origem do build usando o campo Origem do build. O campo "Build source" é um dos seguintes: storage_source
, repo_source
, git_source
e connected_repository
.
Enviar builds com storage_source
gcloud
Usando um Dockerfile:
O Dockerfile
contém todas as informações necessárias para criar uma imagem do Docker usando o Cloud Build.
Para executar uma solicitação de build usando o Dockerfile
, execute o seguinte comando no diretório que contém o código do aplicativo Dockerfile
e outros recursos:
gcloud builds submit --region=us-west2 --tag gcr.io/PROJECT_ID/IMAGE_NAME .
Em que:
- PROJECT_ID é o nome do projeto do Google Cloud.
- IMAGE_NAME é a imagem a ser criada;
.
especifica que o código-fonte está no diretório de trabalho atual.
O nome completo da imagem a ser criada é gcr.ioPROJECT_ID/IMAGE_NAME
. As imagens enviadas ao Container Registry usam o
formato do nome do registro.
O comando gcloud builds submit
:
- compacta o código do aplicativo
Dockerfile
e todos os outros recursos no diretório atual, conforme indicado por.
; - carrega os arquivos em um bucket do Cloud Storage;
- inicia um build no local
us-west2
usando os arquivos enviados como entrada; - marca a imagem usando o nome fornecido
- envia a imagem criada ao Container Registry.
À medida que a versão avança, a saída é exibida no shell ou na janela do terminal: Quando a versão for concluída, você verá um resultado semelhante a este:
DONE
---------------------------------------------------------------------------------
ID CREATE_TIME DURATION STATUS
$BUILD_ID 2023-10-28T15:21:18+00:00 12S SUCCESS
em que $BUILD_ID
é o identificador exclusivo da sua build.
Usando o arquivo de configuração de build do Cloud Build:
Para enviar uma versão usando a configuração de versão, execute este comando:
gcloud builds submit --region=us-west2 --config BUILD_CONFIG SOURCE
Em que:
- BUILD_CONFIG é o caminho para o arquivo de configuração da compilação;
- SOURCE é o caminho ou o código-fonte do URL.
Quando você executa gcloud builds submit
pela primeira vez em um projeto do Google Cloud,
O Cloud Build cria um bucket do Cloud Storage chamado [YOUR_PROJECT_NAME]_cloudbuild
nesse projeto. O Cloud Build usa esse bucket para armazenar qualquer
código-fonte que possa ser usado para suas versões. O Cloud Build não exclui automaticamente
o conteúdo neste bucket. Para excluir objetos que você não está mais usando para
versões, é possível definir a configuração do ciclo de vida no bucket
ou excluir os objetos manualmente.
O comando a seguir demonstra como enviar uma solicitação de build cloudbuild.yaml
usando o código-fonte armazenado em um bucket do Cloud Storage.
gcloud builds submit --region=us-west2 --config cloudbuild.yaml \
gs://BUCKET/SOURCE.tar.gz
Em que:
- BUCKET é o nome do bucket no Cloud Storage que contém o código-fonte a ser criado.
- SOURCE é o nome do arquivo de código-fonte compactado.
Use .
para especificar que o código-fonte está no diretório de trabalho atual:
gcloud builds submit --region=us-west2 --config=cloudbuild.yaml .
API
Para enviar a solicitação de versão usando curl
:
Crie um arquivo chamado
request.json
com o seguinte conteúdo:{ "source": { "storageSource": { "bucket": "BUCKET", "object": "SOURCE.tar.gz" } }, "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "gcr.io/PROJECT_ID/IMAGE_NAME", "." ] }], "images": [ "gcr.io/PROJECT_ID/IMAGE_NAME" ] }
Em que:
- BUCKET é o nome do bucket do Cloud Storage que contém o código-fonte a ser criado.
- SOURCE é o nome do arquivo de código-fonte compactado.
- IMAGE_NAME é o nome da imagem a ser criada.
Nesta solicitação de build, o Cloud Build chama a etapa de build
docker
usando os argumentosbuild -t gcr.io/$PROJECT_ID/IMAGE-NAME .
.O nome completo da imagem a ser criada é
gcr.io/$PROJECT_ID/IMAGE_NAME
.As imagens enviadas para o Container Registry usam o formato do nome do registro.
Execute este comando, em que
PROJECT_ID
é seu O ID do projeto do Google Cloud eREGION
é um dos regiões com suporte:curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \ --format='value(credential.access_token)')" \ https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds
Neste comando,
curl
enviarequest.json
em uma chamada POST para o endpointbuilds
no método da API projects.builds.create.O comando exibe detalhes sobre sua versão no shell ou na janela do terminal. O resultado é uma resposta JSON semelhante a esta:
{ "name": "operations/build/$PROJECT-ID/NmZhZW...", "metadata": { "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata", "build": { "id": $BUILD-ID, "status": "QUEUED", "source": { "storageSource": { "bucket": "BUCKET", "object": "SOURCE.tar.gz" } }, "createTime": "2017-05-12T18:58:07.341526Z", "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "gcr.io/PROJECT_ID/IMAGE_NAME", "." ] } ], "timeout": "600s", "images": [ "gcr.io/$PROJECT_ID/IMAGE_NAME" ], "projectId": $PROJECT-ID, "logsBucket": "gs://...", "sourceProvenance": { "resolvedStorageSource": { "bucket": "BUCKET", "object": "SOURCE.tar.gz" "generation": "..." } }, "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=$PROJECT_ID" } } }
O modelo da resposta JSON é baseado no recurso
Operation
na API Cloud Build. O modelo do campometadata
é baseado no recursoBuild
. O statusQUEUED
indica que o build está aguardando execução.
Enviar builds com connected_repository
gcloud
Para executar uma solicitação de build com o código-fonte de um recurso de repositório de 2a geração, execute o seguinte comando:
gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG --region=us-west2
Em que:
- REPOSITORY é o nome do repositório do Google Cloud Build de 2ª geração, formatado como
projects/*/locations/*/connections/*repositories/*
. - REVISION é a revisão a ser buscada do repositório do Git, como uma ramificação, uma tag, um SHA de confirmação ou qualquer referência do Git.
- BUILD_CONFIG é o caminho para o arquivo de configuração da compilação;
À medida que a versão avança, a saída é exibida no shell ou na janela do terminal: Quando a versão for concluída, você verá um resultado semelhante a este:
DONE
---------------------------------------------------------------------------------
ID CREATE_TIME DURATION STATUS
$BUILD_ID 2023-10-28T15:21:18+00:00 12S SUCCESS
em que $BUILD_ID
é o identificador exclusivo da sua build.
gcloudignore: ao incluir o código-fonte da versão, o comando acima carrega todos os arquivos no diretório especificado para criação no Google Cloud Platform. Se você quiser excluir determinados arquivos do diretório, inclua um arquivo chamado .gcloudignore
no diretório de upload de nível superior. Os arquivos especificados por ele serão ignorados. Se nenhum arquivo .gcloudignore
estiver
presente no diretório de upload de nível superior, mas houver um arquivo .gitignore
, a
CLI gcloud vai gerar um arquivo .gcloudignore
compatível com o Git que
respeita os arquivos com .gitignore
. Para mais informações, consulte a
Documentação do gcloudignore
.
Se você não tiver o código-fonte para informar sua versão, use a sinalização --no-source
, em que BUILD_CONFIG é o caminho para o arquivo de configuração da criação:
gcloud builds submit --region=us-west2 --config=BUILD_CONFIG --no-source
API
Para enviar a solicitação de versão usando curl
:
Crie um arquivo chamado
request.json
com o seguinte conteúdo:{ "source": { "connectedRepository": { "repository": "REPOSITORY", "revision": "REVISION" } }, "steps": [{ "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "gcr.io/PROJECT_ID/IMAGE_NAME", "." ] }], "images": [ "gcr.io/PROJECT_ID/IMAGE_NAME" ] }
Em que:
- REPOSITORY é o nome do repositório do Google Cloud Build de 2ª geração, formatado como
projects/*/locations/*/connections/*repositories/*
. - REVISION é a revisão a ser buscada no repositório Git, como uma ramificação, uma tag, um SHA de confirmação ou qualquer referência do Git.
- IMAGE_NAME é o nome da imagem a ser criada.
Nesta solicitação de build, o Cloud Build chama a etapa de build
docker
usando os argumentosbuild -t gcr.io/PROJECT_ID/IMAGE_NAME .
.O nome completo da imagem a ser criada é
gcr.io/PROJECT_ID/IMAGE_NAME
. As imagens enviadas ao Container Registry usam o formato do nome do registro.- REPOSITORY é o nome do repositório do Google Cloud Build de 2ª geração, formatado como
Execute o seguinte comando, em que
PROJECT_ID
é o ID do projeto do Google Cloud e REGION é uma das regiões com suporte:curl -X POST -T request.json -H "Authorization: Bearer $(gcloud config config-helper \ --format='value(credential.access_token)')" \ https://cloudbuild.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/builds
Neste comando,
curl
enviarequest.json
em uma chamada POST para o endpointbuilds
no método da API projects.builds.create.O comando exibe detalhes sobre sua versão no shell ou na janela do terminal. O resultado é uma resposta JSON semelhante a esta:
{ "name": "operations/build/$PROJECT-ID/NmZhZW...", "metadata": { "@type": "type.googleapis.com/google.devtools.cloudbuild.v1.BuildOperationMetadata", "build": { "id": $BUILD-ID, "status": "QUEUED", "source": { "connectedRepository": { "repository": "REPOSITORY", "revision": "REVISION" } }, "createTime": "2017-05-12T18:58:07.341526Z", "steps": [ { "name": "gcr.io/cloud-builders/docker", "args": [ "build", "-t", "gcr.io/PROJECT_ID/IMAGE_NAME", "." ] } ], "timeout": "600s", "images": [ "gcr.io/PROJECT_ID/IMAGE_NAME" ], "projectId": PROJECT_ID, "logsBucket": "gs://...", "sourceProvenance": { "resolvedConnectedRepository": { "repository": "REPOSITORY", "revision": "REVISION.tar.gz" "generation": "..." } }, "logUrl": "https://console.cloud.google.com/cloud-build/builds/...?project=PROJECT_ID" } } }
O modelo da resposta JSON é baseado no recurso
Operation
na API Cloud Build. O modelo do campometadata
é baseado no recursoBuild
. O statusQUEUED
indica que o build está aguardando execução.
A seguir
- Saiba como criar gatilhos manuais.
- Saiba como ver os resultados da build.
- Saiba como resolver erros de build.