Criar, testar e conteinerizar aplicativos Go

Nesta página, explicamos como usar o Cloud Build para criar, testar, contêinerizar e implantar aplicativos Go, além de como salvar os registros de teste no Cloud Storage.

Antes de começar

As instruções nesta página pressupõem que você conhece o Go. Além disso:

  • Ative as APIs Cloud Build, Cloud Run e Artifact Registry, se alguma delas ainda não estiver ativada.

    Funções necessárias para ativar APIs

    Para ativar APIs, você precisa da permissão serviceusage.services.enable. Se você criou o projeto, provavelmente já tem essa permissão com o papel de Proprietário (roles/owner). Caso contrário, é possível receber essa permissão com o papel de Administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  • Para executar os comandos gcloud nesta página, instale a Google Cloud CLI.
  • Tenha seu projeto em Go à mão.
  • Para contentorizar o aplicativo Go usando o Cloud Build, você precisará de um Dockerfile com o código-fonte.
  • Se você quiser armazenar o contêiner criado no Artifact Registry, crie um repositório do Docker no Artifact Registry.
  • Para armazenar registros de teste no Cloud Storage, crie um bucket no Cloud Storage.

Permissões do IAM obrigatórias

Para instruções sobre como conceder esses papéis, consulte Como conceder um papel usando a página do IAM.

Como configurar builds do Go

A imagem golang pública do Docker Hub é compatível com a criação de módulos do Go. Usar essa imagem como uma etapa de build no arquivo de configuração do Cloud Build permite invocar comandos go na imagem. Os argumentos transmitidos nessa etapa de build são transmitidos diretamente para a ferramenta golang, o que permite executar qualquer comando go nessa imagem.

Nesta seção, você vai conferir um exemplo de arquivo de configuração de build para um app Go. Ele tem etapas de build para criar o app, adicionar testes de unidade e, após a aprovação, criar um contêiner e implantar o app.

Para criar seu aplicativo Go:

  1. No diretório raiz do projeto, crie um arquivo de configuração do Cloud Build chamado cloudbuild.yaml.

  2. Compilar e testar: se você tiver definido testes de unidade no aplicativo, poderá configurar o Cloud Build para executar os testes adicionando os seguintes campos em uma etapa de versão:

    • name: defina o valor desse campo como golang para usar a imagem golang do Docker Hub na tarefa.
    • entrypoint: defina o valor desse campo como /bin/bash. Isso permite que você execute comandos bash de várias linhas diretamente da etapa de build.

    • args: o campo args de uma etapa de criação recebe uma lista de argumentos e os passa para a imagem referenciada pelo campo name. No exemplo a seguir, o campo args usa os argumentos para:

      • Executar o formatador de registros de teste para fazer o download da saída do registro de teste.
      • Imprimir a saída do registro.
      • Salvando os resultados do teste em sponge.log.
      • Resultados em sponge.log para um arquivo XML JUNIT. O nome do arquivo XML JUNIT é construído usando a versão curta do ID de confirmação associado ao seu build. Uma próxima etapa de versão salvará os registros nesse arquivo no Cloud Storage.
      steps:
  # Run tests and save to file
  - name: golang:1.26-trixie
    entrypoint: /bin/bash
    args:
      - -c
      - |
        go install github.com/jstemmer/go-junit-report/v2@latest
        2>&1 go test -timeout 1m -v ./... | /go/bin/go-junit-report -set-exit-code -iocopy -out ${SHORT_SHA}_test_log.xml

  3. Crie o contêiner no app: depois de adicionar a etapa de versão para garantir que os testes passaram, você pode criar o aplicativo. O Cloud Build oferece uma imagem Docker pré-criada que pode ser usada para conteinerizar seu aplicativo Go. Para contentorizar o aplicativo, adicione os seguintes campos em uma etapa do build

    • name: defina o valor desse campo como gcr.io/cloud-builders/docker para usar a imagem do Docker pré-criada para sua tarefa.
    • args: adicione os argumentos do comando docker build como valores para este campo.

    A etapa de criação a seguir cria a imagem myimage e a marca com a versão curta do seu ID de confirmação. A etapa de build usa substituições para ID do projeto, nome do repositório e valores SHA abreviados. Portanto, esses valores são substituídos automaticamente no momento do build. Você precisará criar ou ter um repositório do Docker no Artifact Registry para armazenar a imagem.

    # Docker Build
- name: 'gcr.io/cloud-builders/docker'
  args: ['build', '-t',
         'us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA', '.']

  4. Envie o contêiner por push para o Artifact Registry: é possível armazenar o contêiner criado no Artifact Registry, um serviço Google Cloud que pode ser usado para armazenar, gerenciar e proteger artefatos de build. Para isso, é necessário ter um repositório existente do Docker no Artifact Registry. Para configurar o Cloud Build para armazenar a imagem em um repositório do Artifact Registry no Docker, adicione uma etapa de versão com os seguintes campos:

    • name: defina o valor desse campo como gcr.io/cloud-builders/docker para usar a imagem oficial do builder docker na sua tarefa.
    • args: adicione os argumentos do comando docker push como valores deste campo. Para o URL de destino, insira o repositório Docker do Artifact Registry em que você quer armazenar a imagem.

    A etapa de criação a seguir envia a imagem que você criou na etapa anterior para o Artifact Registry:

    # Docker push to Google Artifact Registry
- name: 'gcr.io/cloud-builders/docker'
  args: ['push', 'us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA']

  5. Implantar o contêiner no Cloud Run: para implantar a imagem no Cloud Run, adicione uma etapa de versão com os seguintes campos:

    • name: defina o valor desse campo como google/cloud-sdk para usar a imagem da CLI gcloud e invocar o comando gcloud para implantar a imagem no Cloud Run.
    • args: adicione os argumentos do comando gcloud run deploy como os valores deste campo.

    A etapa de criação a seguir implanta a imagem criada anteriormente no Cloud Run:

    # Deploy to Cloud Run
- name: 'gcr.io/cloud-builders/gcloud'
  args: ['run', 'deploy', 'helloworld-${SHORT_SHA}',
         '--image=us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA',
         '--region', 'us-central1', '--platform', 'managed']

  6. Salvar registros de teste no Cloud Storage: é possível configurar o Cloud Build para armazenar todos os registros de teste no Cloud Storage especificando um local e um caminho do bucket existente para os registros de teste.

    A etapa de criação a seguir armazena os registros de teste que você salvou no arquivo XML JUNIT em um bucket do Cloud Storage:

    # Save test logs to Google Cloud Storage
artifacts:
  objects:
    location: gs://$_BUCKET_NAME/
    paths:
      - ${SHORT_SHA}_test_log.xml

    O snippet a seguir mostra o arquivo de configuração de build completo para as etapas anteriores:

    steps:
  # Run tests and save to file
  - name: golang:1.26-trixie
    entrypoint: /bin/bash
    args:
      - -c
      - |
        go install github.com/jstemmer/go-junit-report/v2@latest
        2>&1 go test -timeout 1m -v ./... | /go/bin/go-junit-report -set-exit-code -iocopy -out ${SHORT_SHA}_test_log.xml

  # Docker Build
  - name: 'gcr.io/cloud-builders/docker'
    args: ['build', '-t',
           'us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA', '.']

  # Docker push to Google Artifact Registry
  - name: 'gcr.io/cloud-builders/docker'
    args: ['push', 'us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA']

  # Deploy to Cloud Run
  - name: 'gcr.io/cloud-builders/gcloud'
    args: ['run', 'deploy', 'helloworld-${SHORT_SHA}',
           '--image=us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA',
           '--region', 'us-central1', '--platform', 'managed']

# Save test logs to Google Cloud Storage
artifacts:
  objects:
    location: gs://$_BUCKET_NAME/
    paths:
      - ${SHORT_SHA}_test_log.xml
# Store images in Google Artifact Registry
images:
  - us-central1-docker.pkg.dev/$PROJECT_ID/$_AR_REPO_NAME/myimage:$SHORT_SHA

  7. Inicie o build usando a CLI gcloud ou gatilhos de build. Você precisa especificar o nome do repositório do Artifact Registry ao iniciar o build.

    Para especificar o repositório do Artifact Registry ao iniciar o build usando a CLI gcloud:

    gcloud builds submit --region=us-west2 --config=cloudbuild.yaml \
    --substitutions=_AR_REPO_NAME="AR_REPO_NAME"

    Substitua AR_REPO_NAME pelo nome do repositório do Artifact Registry.

    Para especificar o repositório do Artifact Registry ao criar com gatilhos de build, especifique o nome do repositório do Artifact Registry no campo Variáveis de substituição ao criar o gatilho de build.

A seguir