Envie uma compilação através da CLI e da API

Esta página descreve como iniciar uma compilação no Cloud Build manualmente através da CLI Google Cloud e da API Cloud Build.

Antes de começar

Autorizações de IAM necessárias

Para receber as autorizações de que precisa para enviar compilações, peça ao seu administrador para lhe conceder as seguintes funções do IAM na sua conta de serviço:

Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Executar compilações

Pode especificar a origem da compilação através do campo Origem da compilação. O campo Origem da criação é um dos seguintes: storage_source, repo_source, git_source e connected_repository.

Envie compilações com storage_source

gcloud

Usando um Dockerfile:

O seu Dockerfile contém todas as informações necessárias para criar uma imagem do Docker com o Cloud Build.

Para criar usando um Dockerfile, execute o seguinte comando a partir do diretório que contém o código-fonte e o Dockerfile:

gcloud builds submit --tag LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME

Onde:

  • LOCATION: a localização regional ou multirregional do seu repositório Docker no Artifact Registry.
  • PROJECT_ID: o ID do seu Google Cloud projeto.
  • REPOSITORY: o nome do seu repositório do Artifact Registry.
  • IMAGE_NAME: o nome da imagem do contentor a ser criada.

O nome completo da imagem a ser criada é LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. As imagens enviadas para o Artifact Registry usam a convenção de nomenclatura do Artifact Registry.

O comando gcloud builds submit:

  • Comprime o código da aplicação Dockerfile e todos os outros recursos no diretório atual, conforme indicado por .;
  • Inicia uma compilação na localização LOCATION usando os ficheiros carregados como entrada;
  • etiqueta a imagem com o nome fornecido;
  • Envia a imagem criada para o Artifact Registry.

À medida que a compilação avança, o respetivo resultado é apresentado na janela da shell ou do terminal. Quando a compilação estiver concluída, deverá ver um resultado semelhante ao seguinte:

    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 compilação.

Usando o ficheiro de configuração de compilação do Cloud Build:

Para enviar uma compilação através da configuração de compilação, execute o seguinte comando:

    gcloud builds submit --config BUILD_CONFIG SOURCE

Onde:

  • BUILD_CONFIG é o caminho para o ficheiro de configuração de compilação.
  • SOURCE é o caminho ou o código-fonte do URL.

Quando executa gcloud builds submit pela primeira vez num Google Cloud projeto, o Cloud Build cria um contentor do Cloud Storage denominado [YOUR_PROJECT_NAME]_cloudbuild nesse projeto. O Cloud Build usa este contentor para armazenar qualquer código fonte que possa usar para as suas compilações. O Cloud Build não elimina automaticamente o conteúdo neste contentor. Para eliminar objetos que já não está a usar para compilações, pode configurar a configuração do ciclo de vida no contentor ou eliminar manualmente os objetos.

O comando seguinte demonstra como enviar um cloudbuild.yamlpedido de compilação usando código fonte armazenado num contentor do Cloud Storage.

    gcloud builds submit --config cloudbuild.yaml \         gs://BUCKET/SOURCE.tar.gz

Onde:

  • BUCKET é o nome do seu contentor no Cloud Storage que contém o código-fonte a compilar.
  • SOURCE é o nome do ficheiro de código-fonte comprimido.

Pode usar . para especificar que o código-fonte está no diretório de trabalho atual:

    gcloud builds submit --config=cloudbuild.yaml .

API

Para enviar o pedido de criação através do curl:

  1. Crie um ficheiro denominado 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",             "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",             "."         ]     }],     "images": [         "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"     ] }

    Onde:

    • BUCKET é o nome do seu contentor do Cloud Storage que contém o código-fonte a compilar.
    • SOURCE é o nome do ficheiro de código-fonte comprimido.
    • IMAGE_NAME é o nome da imagem a ser criada.
    • LOCATION: a localização regional ou multirregional do seu repositório Docker no Artifact Registry.
    • PROJECT_ID: o ID do seu Google Cloud projeto.
    • REPOSITORY: o nome do seu repositório Docker no Artifact Registry.

    Neste pedido de compilação, o Cloud Build chama o dockerpasso de compilação com os argumentos build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY ..

    O nome completo da imagem a ser criada é LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY.

    As imagens enviadas para o Artifact Registry usam a convenção de nomenclatura do Artifact Registry.

  2. Execute o seguinte comando, em que PROJECT_ID é o ID do seu projeto eGoogle Cloud é uma das regiões suportadas:REGION

    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 envia request.json numa chamada POST para o ponto final builds para o método da API projects.builds.create.

    O comando apresenta detalhes sobre a sua compilação na janela da shell ou do terminal. O resultado é uma resposta JSON e tem um aspeto semelhante ao seguinte:

        {         "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",                         "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",                         "."                     ]                 }                 ],                 "timeout": "600s",                 "images": [                     "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/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"             }         }     }

    A resposta JSON é modelada através do recurso Operation na API Cloud Build. O campo metadata é modelado com o recurso Build. O estado QUEUED indica que a compilação está a aguardar execução.

Envie compilações com connected_repository

gcloud

Para executar um pedido de compilação com a origem de compilação de um recurso de repositório de 2.ª geração, execute o seguinte comando:

gcloud builds submit REPOSITORY --revision=REVISION --config=BUILD_CONFIG LOCATION

Onde:

  • LOCATION é a localização regional ou multirregional do seu repositório Docker no Artifact Registry.
  • REPOSITORY é o nome do repositório de 2.ª geração do Cloud Build, formatado como projects/*/locations/*/connections/*repositories/*.
  • REVISION é a revisão a obter do repositório Git, como um ramo, uma etiqueta, um SHA de commit ou qualquer ref Git.
  • BUILD_CONFIG é o caminho para o ficheiro de configuração de compilação.

À medida que a compilação avança, o respetivo resultado é apresentado na janela da shell ou do terminal. Quando a compilação estiver concluída, deverá ver um resultado semelhante ao seguinte:

    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 compilação.

gcloudignore: quando inclui o código-fonte para a compilação, o comando anterior carrega todos os ficheiros no diretório especificado para Google Cloud para compilar. Se quiser excluir determinados ficheiros no diretório, pode incluir um ficheiro denominado .gcloudignore no diretório de carregamento de nível superior. Os ficheiros especificados no ficheiro .gcloudignore serão ignorados. Se .gcloudignore não estiver presente no diretório de carregamento de nível superior, mas existir um ficheiro .gitignore, a CLI gcloud gera um ficheiro .gcloudignore compatível com o Git que respeita os ficheiros .gitignore editados. Para mais informações, consulte a gcloudignore documentação.

Se não tiver código-fonte para transmitir à sua compilação, use a flag --no-source onde BUILD_CONFIG é o caminho para o ficheiro de configuração da compilação:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY

API

Para enviar o pedido de criação através do curl:

  1. Crie um ficheiro denominado request.json com o seguinte conteúdo:

    {     "source": {         "connectedRepository": {             "repository": "REPOSITORY",             "revision": "REVISION"         }     },     "steps": [{         "name": "gcr.io/cloud-builders/docker",         "args": [             "build",             "-t",             "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",             "."         ]     }],     "images": [         "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME"     ] }

    Onde:

    • REPOSITORY é o nome do repositório de 2.ª geração do Cloud Build, formatado como projects/*/locations/*/connections/*repositories/*.
    • REVISION é a revisão a obter do repositório Git, como um ramo, uma etiqueta, um SHA de commit ou qualquer ref Git.
    • IMAGE_NAME é o nome da imagem a ser criada.
    • LOCATION: a localização regional ou multirregional do seu repositório Docker no Artifact Registry.
    • PROJECT_ID: o ID do seu Google Cloud projeto.

    Neste pedido de compilação, o Cloud Build chama o dockerpasso de compilação com os argumentos build -t LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME ..

    O nome completo da imagem a ser criada é LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME. As imagens enviadas para o Artifact Registry usam a convenção de nomenclatura do Artifact Registry.

  2. Execute o seguinte comando em que PROJECT_ID é o ID do seu projeto e REGION é uma das regiões suportadas:Google Cloud 

    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 envia request.json numa chamada POST para o ponto final builds para o método da API projects.builds.create.

    O comando apresenta detalhes sobre a sua compilação na janela da shell ou do terminal. O resultado é uma resposta JSON e tem um aspeto semelhante ao seguinte:

        {         "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",                         "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE_NAME",                         "."                     ]                 }                 ],                 "timeout": "600s",                 "images": [                     "LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/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"             }         }     }

    A resposta JSON é modelada através do recurso Operation na API Cloud Build. O campo metadata é modelado com o recurso Build. O estado QUEUED indica que a compilação está a aguardar execução.

O que se segue?