Executar builds com uma conta serviço gerenciado pelo usuário

Neste documento, descrevemos como configurar seus builds para usar uma conta serviço gerenciado pelo usuário.

Se você não especificar uma conta de serviço gerenciado pelo usuário para seus builds, o Cloud Build vai usar automaticamente a conta de serviço padrão do Cloud Build. Essa conta de serviço padrão pode ter permissões desnecessariamente amplas, como acesso aos Cloud Source Repositories e a qualquer bucket do Cloud Storage no projeto.

Recomendamos seguir o princípio de privilégio mínimo ao atribuir permissões e papéis a contas de serviço com escopo para a tarefa que elas realizam. Por exemplo, é possível usar uma conta de serviço para criar e enviar imagens para o Artifact Registry, conforme mostrado no blog doCloud de Confiance by S3NS .

Antes de começar

  • Ative as APIs Cloud Build e IAM, se ainda não estiverem ativadas.

    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 pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar as APIs

  • Se você planeja usar essa conta para criar e gerenciar credenciais, por exemplo, para criar credenciais de curta duração, ative a API Service Account Credentials do IAM.

    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 pelo papel de proprietário (roles/owner). Caso contrário, é possível conseguir essa permissão pelo papel de administrador do Service Usage (roles/serviceusage.serviceUsageAdmin). Saiba como conceder papéis.

    Ativar a API

  • Crie uma conta de serviço, se ainda não tiver feito isso.

Configurar a conta de serviço

Conceda papéis do IAM à sua conta de serviço gerenciado pelo usuário para que ela tenha as permissões necessárias para executar os builds. Também é possível configurar o Cloud Build para escolher automaticamente essa conta de serviço para novos gatilhos.

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

    Acesse Permissões.

  2. Acesse o menu Conta de serviço e selecione sua conta de serviço. Para escolher uma conta de serviço em um projeto diferente, clique em Alternar projeto.

  3. Para usar a conta de serviço selecionada como a conta de serviço para novos gatilhos, ative Definir como pré-selecionada para novos gatilhos.

  4. Na lista de serviços do Cloud de Confiance , ative os papéis do IAM que você quer conceder à sua conta de serviço.

  5. Se o papel necessário para o pipeline de build não estiver listado aqui, conceda outros papéis na página de configurações do IAM.

  6. Se você selecionou uma conta de serviço em um projeto diferente, conclua as etapas em Configuração entre projetos.

Para saber mais sobre os papéis do IAM normalmente necessários para uma build, consulte as seguintes informações:

Configurar registros de build

Ao especificar sua própria conta de serviço para builds, é necessário armazenar os registros de build em um dos seguintes tipos de bucket:

Se você criar um bucket de registros, verifique se ele não tem uma política de retenção, porque ela pode impedir que o Cloud Build grave registros de build no bucket.

Não é possível armazenar os registros em um bucket de registros de propriedade do Cloud de Confiance.

Para mais informações sobre onde armazenar registros de build, consulte Opções de armazenamento de registros de build.

Executar um build usando um arquivo de configuração

Para executar manualmente um build usando um arquivo de configuração:

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

  2. Adicione o campo serviceAccount e a configuração de geração de registros preferida.

    • Se você estiver armazenando os registros de build no Cloud Logging, adicione um campo logging e defina o valor dele como CLOUD_LOGGING_ONLY.

    • Se você estiver armazenando os registros de build em um bucket do Cloud Storage criado pelo usuário:

      • Adicione um campo logging e defina o valor dele como GCS_ONLY.
      • Adicione um campo de logsBucket e defina o valor dele como o local do bucket do Cloud Storage.

    O exemplo a seguir configura o Cloud Build para executar builds usando uma conta de serviço gerenciado pelo usuário e configura os registros de build para serem armazenados em um bucket do Cloud Storage criado pelo usuário:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    serviceAccount: 'projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "serviceAccount": "projects/PROJECT_ID/serviceAccounts/SERVICE_ACCOUNT",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    
    

    Substitua as variáveis no arquivo de configuração do build pelo seguinte:

    • LOGS_BUCKET_LOCATION é o bucket do Cloud Storage para armazenar registros do build. Por exemplo, gs://mylogsbucket.
    • PROJECT_ID é o ID do projeto do Cloud de Confiance em que você está executando o build.
    • SERVICE_ACCOUNT é o endereço de e-mail ou o ID exclusivo da conta de serviço que você quer especificar para builds. Por exemplo, um endereço de e-mail de conta de serviço é semelhante a: service-account-name@project-id.s3ns.iam.gserviceaccount.com.
  3. Inicie o build usando o arquivo de configuração do build:

    gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
    

    Substitua as variáveis nos comandos pelos seguintes valores:

    • CONFIG_FILE_PATH é o caminho para o arquivo de configuração da compilação;
    • SOURCE_DIRECTORY é o caminho ou o URL do código-fonte.

    Se você não especificar CONFIG_FILE_PATH e SOURCE_DIRECTORY no comando gcloud builds submit, o Cloud Build presumirá que o arquivo de configuração do build e o código-fonte estão no diretório de trabalho atual.

Executar builds usando gatilhos

Para executar um build com gatilhos do Cloud Build usando sua própria conta de serviço, configure a opção de geração de registros de sua preferência e selecione a conta de serviço que preferir ao criar o gatilho.

Se você quiser usar a mesma conta de serviço para todos os novos gatilhos, configure o Cloud Build para selecionar automaticamente a conta de serviço.

  1. No arquivo de configuração de build:

    • Se você estiver armazenando os registros de build no Cloud Logging, adicione um campo logging e defina o valor dele como CLOUD_LOGGING_ONLY.

    • Se você estiver armazenando os registros de build em um bucket do Cloud Storage criado pelo usuário:

      • Adicione um campo logging e defina o valor dele como GCS_ONLY.
      • Adicione um campo de logsBucket e defina o valor dele como o local do bucket do Cloud Storage.

    O exemplo a seguir configura os registros de build para serem armazenados em um bucket do Cloud Storage criado pelo usuário:

    YAML

    steps:
    - name: 'bash'
      args: ['echo', 'Hello world!']
    logsBucket: 'LOGS_BUCKET_LOCATION'
    options:
      logging: GCS_ONLY
    

    JSON

    {
      "steps": [
      {
        "name": "bash",
        "args": [
          "echo",
          "Hello world!"
        ]
      }
      ],
      "logsBucket": "LOGS_BUCKET_LOCATION",
      "options": {
        "logging": "GCS_ONLY"
      }
    }
    

    Substitua LOGS_BUCKET_LOCATION pelo bucket do Cloud Storage para armazenar registros de build. Por exemplo, gs://mylogsbucket.

  2. Especifique uma conta de serviço para usar com o gatilho de compilação:

    Console

    1. Crie ou edite o gatilho de compilação.

    2. No campo Conta de serviço especifique sua conta de serviço. Para escolher uma conta de serviço em um projeto diferente, clique em Alternar projeto.

      Se você não especificar uma conta de serviço, o Cloud Build vai usar a conta de serviço padrão.

    3. Clique em Criar para salvar o gatilho de compilação.

    gcloud

    Ao criar um gatilho de compilação, especifique sua conta de serviço usando a sinalização --service-account. No exemplo a seguir, o comando gcloud cria um gatilho de compilação que extrai o código de um repositório Git:

    gcloud builds triggers create github \
       --name=TRIGGER_NAME \
       --repo-name=REPO_NAME \
       --repo-owner=REPO_OWNER \
       --branch-pattern=BRANCH_PATTERN
       --build-config=BUILD_CONFIG_FILE
       --service-account=SERVICE_ACCOUNT
       --project=BUILD_PROJECT
    

    Substitua as variáveis no arquivo de configuração do build pelos seguintes valores:

    • TRIGGER_NAME é o nome do gatilho de compilação.
    • REPO_NAME é o nome do repositório;
    • REPO_OWNER é o nome de usuário do proprietário do repositório.
    • BRANCH_PATTERN é o nome da ramificação no seu repositório para invocar o build.
    • TAG_PATTERN é o nome da tag no repositório para invocar o build.
    • BUILD_CONFIG_FILE é o caminho para seu arquivo de configuração da compilação.
    • SERVICE_ACCOUNT é sua conta de serviço no formato /projects/PROJECT_ID/serviceAccounts/ACCOUNT_ID_OR_EMAIL.
    • BUILD_PROJECT é o projeto em que você está iniciando as versões.

Configuração entre projetos

É possível usar uma conta de serviço gerenciado pelo usuário para executar builds em um projeto diferente daquele em que você criou a conta de serviço somente se a restrição da política da organização iam.disableCrossProjectServiceAccountUsage não for aplicada. Essa restrição é aplicada por padrão. Saiba mais.

  • O comando a seguir desativa a aplicação dessa restrição e concede o acesso necessário. Sua organização precisa estar ciente das compensações de segurança envolvidas antes de definir a restrição na política da organização:

    gcloud resource-manager org-policies disable-enforce \
       iam.disableCrossProjectServiceAccountUsage \
       --project=SERVICE_ACCOUNT_PROJECT_ID
    

    Nesse comando, SERVICE_ACCOUNT_PROJECT_ID é o projeto que contém sua conta de serviço gerenciado pelo usuário.

  • No projeto que tem sua conta de serviço gerenciado pelo usuário, conceda o papel roles/iam.serviceAccountTokenCreator ao agente de serviço do Cloud Build do projeto em que você está executando builds:

    gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
        --member="serviceAccount:BUILD_SERVICE_AGENT" \
        --role="roles/iam.serviceAccountTokenCreator"
    

    Substitua as variáveis no comando pelo seguinte:

    • SERVICE_ACCOUNT_PROJECT_ID: o ID do projeto que contém sua conta de serviço gerenciado pelo usuário.
    • BUILD_SERVICE_AGENT: o ID de e-mail do agente de serviço no formato service-BUILD_PROJECT_NUMBER@gcp-sa-cloudbuild.s3ns-system.iam.gserviceaccount.com, em que BUILD_PROJECT_NUMBER é o número do projeto em que você está executando builds. O número do projeto está disponível na página de configurações do projeto.

Limitações:

  • O projeto do Cloud de Confiance precisa estar em uma organização do Cloud de Confiance by S3NS .

  • Inicie as versões na linha de comando usando gcloud builds submit ou gcloud builds triggers create.

  • Se você receber um erro service account not found ao conceder o papel do IAM, talvez seja necessário criar o agente de serviço manualmente.

A seguir