Criar e testar aplicativos Go

Nesta página, explicamos como usar o Cloud Build para criar e testar seus aplicativos Go, fazer upload dos artefatos para o Artifact Registry, gerar informações de procedência e 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.
  • Prepare seu projeto Go.
  • Ter um repositório Go no Artifact Registry. Se você não tiver um, crie um novo repositório.
  • Se você quiser armazenar registros de teste no Cloud Storage ou usar a CLI gcloud para iniciar o build, crie um bucket no Cloud Storage.
  • Confira se você sabe o ID da conta de serviço do ambiente de execução do Cloud Run.

Criar uma conta de serviço personalizada do Cloud Build

Crie uma conta de serviço personalizada do Cloud Build executando o seguinte comando na Google Cloud CLI:

  gcloud iam service-accounts create cloud-build-go \
      --description="Build and test Go applications" \
      --display-name="Cloud Build Go" \
      --project="PROJECT_ID"

Substitua PROJECT_ID pelo ID do projeto Google Cloud . Se a flag for omitida, o projeto atual será usado.

Você vai usar essa conta de serviço para criar e testar seu aplicativo Go.

Configurar as permissões de IAM

Para configurar sua nova conta de serviço com as permissões necessárias para criar e implantar aplicativos Go, faça o seguinte:

  1. No console Google Cloud , acesse a página Permissões do Cloud Build:

    Acessar Permissões

  2. Acesse o menu Conta de serviço e selecione sua conta de serviço cloud-build-go.

  3. Defina o status dos seguintes papéis como Ativado:

    • Administrador do Cloud Run (roles/run.admin): permite que o Cloud Build implante novos serviços no Cloud Run.
    • Administrador do Storage (roles/storage.admin): permite ler e gravar no Cloud Storage.
    • Gravador do Artifact Registry (roles/artifactregistry.writer): permite extrair imagens do Artifact Registry e gravar nele.
    • Gravador de registros (roles/logging.logWriter): permite que entradas de registro sejam gravadas no Cloud Logging.
    • Editor do Cloud Build (roles/cloudbuild.builds.editor): permite que sua conta de serviço execute builds.

Configurar builds do Go

A imagem golang pública do Docker Hub é compatível com a criação usando 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, mostramos como criar um arquivo de configuração de build de exemplo para um app Go do repositório cloud-build-samples do Git. O arquivo de configuração de build tem etapas para criar o app, adicionar testes de unidade e, após a aprovação, implantar o app.

Para criar o aplicativo de exemplo em Go:

  1. Configurar testes de unidade: se você definiu testes de unidade no aplicativo, configure o Cloud Build para executar os testes adicionando os campos a seguir em uma etapa do build:

    • name: defina o valor desse campo como golang para usar a imagem do golang do Docker Hub na sua 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 etapa de build subsequente vai salvar os registros nesse arquivo no Cloud Storage.

        steps:
  # Run tests and save to file
  - name: golang:1.23
    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

  2. Fazer upload para o Artifact Registry: no arquivo de configuração, use o campo goModules para especificar o caminho do aplicativo e o repositório Go no Artifact Registry:

    # Upload Go module to artifact registry
artifacts:
  goModules:
    - repositoryName: 'repositoryName'
      repositoryLocation: 'location'
      repositoryProjectId: 'projectId'
      sourcePath: 'sourcePath'
      modulePath: 'appPath'
      moduleVersion: 'version'

    Substitua os seguintes valores:

    • repositoryName: o nome do seu repositório Go no Artifact Registry.
    • location: o local do repositório no Artifact Registry.
    • projectId: o ID do projeto Google Cloud que contém o repositório do Artifact Registry.
    • sourcePath: o caminho para o arquivo go.mod no espaço de trabalho do build.
    • appPath: o caminho para o aplicativo empacotado.
    • version: o número da versão do seu aplicativo, formatado em números e pontos, como v1.0.1.

  3. Opcional: ativar a geração de origem

    O Cloud Build pode gerar metadados de procedência de build Níveis da cadeia de suprimentos para artefatos de software (SLSA) verificáveis para ajudar a proteger seu pipeline de integração contínua.

    Para ativar a geração de origem, adicione requestedVerifyOption: VERIFIED à seção options no arquivo de configuração.

    Quando o build for concluído, você poderá ver os detalhes do repositório no Artifact Registry.

    Também é possível ver metadados de procedência do build e validar a procedência.

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

    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.23
      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

  # Store golang modules in Google Artifact Registry
  artifacts:
    goModules:
      - repositoryName: 'repositoryName'
        repositoryLocation: 'location'
        repositoryProjectId: 'projectId'
        sourcePath: 'sourcePath'
        modulePath: 'appPath'
        moduleVersion: 'version'

  5. Inicie o build usando a CLI gcloud ou crie um gatilho de build:

    gcloud

    Execute o comando a seguir, usando --substitutions para especificar as variáveis de substituição usadas em cloudbuild.yaml:

    gcloud builds submit --region=us-west2 --config=cloudbuild.yaml \
    --default-buckets-behavior=REGIONAL_USER_OWNED_BUCKET \
    --service-account=projects/PROJECT_ID/serviceAccounts/cloud-build-go@PROJECT_ID.iam.gserviceaccount.com \
    --substitutions=_AR_REPO_NAME="_AR_REPO_NAME",_BUCKET_NAME="_BUCKET_NAME",SHORT_SHA="SHORT_SHA"

    Substitua:

    • _AR_REPO_NAME: o nome do repositório do Artifact Registry.

    • _BUCKET_NAME: o nome do bucket do Cloud Storage para registros de teste.

    • SHORT_SHA: uma string de texto genérica curta, como "manual". Os valores de SHORT_SHA são preenchidos automaticamente para builds invocados por gatilhos, mas não são fornecidos ao enviar um build usando a CLI gcloud.

    Gatilhos de build

    Siga as etapas em Criar um gatilho de build. No campo Variáveis de substituição, também é necessário informar o nome do repositório do Artifact Registry e do bucket do Cloud Storage para registros de teste.

A seguir