Configurar contas de serviço especificadas pelo usuário

Para seguir o princípio do menor privilégio (em inglês) no Cloud Build, configure o Cloud Build para usar uma conta de serviço com privilégios suficientes para executar um build. Nesta página, documentamos como configurar uma conta de serviço.

Se você não especificar uma conta de serviço, o Cloud Build poderá selecionar automaticamente uma conta de serviço para executar builds em seu nome. Essa conta de serviço pode ter permissões desnecessariamente amplas para seu caso de uso, como acesso ao Cloud Source Repositories e qualquer bucket do Cloud Storage no projeto.

Para melhorar a postura de segurança dos seus projetos e reduzir o possível impacto de configurações incorretas ou usuários mal-intencionados, recomendamos seguir o princípio de privilégio mínimo. Adotando esse princípio, é possível atribuir a cada conta de serviço as permissões e os papéis com escopo para a tarefa que ela executa. Por exemplo, é possível usar uma conta de serviço para criar e enviar imagens para o Artifact Registry, conforme mostrado no blog do Google Cloud.

Antes de começar

Ative as APIs Cloud Build and IAM.
Ative 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 IAM Service Account Credentials.

Ative a API
Crie uma conta de serviço, caso ainda não tenha feito isso.

Conceder permissões do IAM

Para permitir que sua versão acesse os serviços a que precisa se conectar, é necessário conceder alguns papéis e permissões:

Abra a página "Configurações" do Cloud Build:

Abrir a página "Configurações do Cloud Build"

Você verá a guia Permissões da conta de serviço:
Na lista suspensa, selecione a conta de serviço que tem os papéis que você quer alterar.
Defina o status do papel que você quer adicionar como Ativar.
Se o papel necessário para o pipeline de compilação não estiver listado aqui, é possível conceder outros papéis na página de configurações do IAM.

Encontre mais informações sobre os papéis normalmente necessários para uma versão em Como configurar o acesso aos recursos do Cloud Build e na lista completa de papéis e permissões do IAM do Cloud Build.

Configurar registros do build

Ao especificar sua própria conta de serviço para builds, você precisa armazenar seus registros de build no Cloud Logging ou em um bucket do Cloud Storage criado pelo usuário. Não é possível armazenar seus registros no bucket de registros padrão.

Para armazenar registros em um bucket do Cloud Storage, siga as instruções em Armazenar registros de versão no bucket criado pelo usuário. Verifique se você não definiu uma política de retenção no bucket de registros, porque isso pode impedir que o Cloud Build grave registros de versão no bucket.
Para armazenar registros de build no Cloud Logging, conceda o papel de gravador de registros (roles/logging.logWriter) à conta de serviço.
Para saber mais sobre onde armazenar registros de build, consulte Escolher onde armazenar registros de build.

Executar um build usando um arquivo de configuração

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

No diretório raiz do projeto, crie um arquivo de configuração de versão do Cloud Build chamado cloudbuild.yaml ou cloudbuild.json.
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 do 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.
No exemplo a seguir, o Cloud Build é configurado para executar versões usando uma conta de serviço especificada pelo usuário e os registros de compilação são 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 os valores de marcador 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 Google Cloud 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, o endereço de e-mail de uma conta de serviço tem esta aparência: service-account-name@project-id.iam.gserviceaccount.com.
Inicie o build usando o arquivo de configuração do build:
```
gcloud builds submit --config CONFIG_FILE_PATH SOURCE_DIRECTORY
```
Substitua os valores dos marcadores nos comandos acima pelo seguinte:
- CONFIG_FILE_PATH é o caminho para o arquivo de configuração do build;
- 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 preferida e selecione a conta de serviço preferida ao criar o gatilho.

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 do 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.
No exemplo a seguir, os registros do build são configurados 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 do build. Por exemplo, gs://mylogsbucket.
Especifique uma conta de serviço para usar com o gatilho de compilação:
Console
Para executar builds usando a página "Gatilho" no console do Google Cloud, a conta de serviço especificada pelo usuário precisa estar no mesmo projeto que o acionador de build. Para usar gatilhos com contas de serviço entre projetos, crie o gatilho de compilação usando a ferramenta gcloud.
1. Crie ou edite o gatilho de compilação.
2. No campo Conta de serviço especifique sua conta de serviço. Se você não especificar uma conta de serviço, o Cloud Build usará a conta de serviço padrão.
3. Clique em Criar para salvar o gatilho de build.
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 código de um repositório do 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 os valores de marcador no arquivo de configuração do build pelo seguinte:
- 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 é o e-mail associado à conta de serviço.
- BUILD_PROJECT é o projeto em que você está iniciando os builds.

Configuração entre projetos

Se a conta de serviço especificada pelo usuário estiver em um projeto diferente do em que você está iniciando builds, conceda o acesso necessário:

No projeto que tem a conta de serviço especificada pelo usuário, verifique se a restrição iam.disableCrossProjectServiceAccountUsage da política da organização não foi aplicada. Essa restrição é aplicada por padrão. Para desativar essa restrição de política da organização, execute o seguinte comando, em que SERVICE_ACCOUNT_PROJECT_ID é o projeto que contém a conta de serviço especificada pelo usuário:
```
gcloud resource-manager org-policies disable-enforce \
   iam.disableCrossProjectServiceAccountUsage \
   --project=SERVICE_ACCOUNT_PROJECT_ID
```
No projeto que tem a conta de serviço especificada pelo usuário, conceda o papel roles/iam.serviceAccountTokenCreator ao agente de serviço do Cloud Build do projeto em que você está executando as versões:
```
gcloud projects add-iam-policy-binding SERVICE_ACCOUNT_PROJECT_ID \
    --member="serviceAccount:BUILD_SERVICE_AGENT" \
    --role="roles/iam.serviceAccountTokenCreator"
```
Substitua os valores de marcador no comando pelo seguinte:
- SERVICE_ACCOUNT_PROJECT_ID: o ID do projeto que contém a conta de serviço especificada 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.iam.gserviceaccount.com, em que BUILD_PROJECT_NUMBER é o número do projeto em que você está executando builds. Você pode conseguir o número do projeto na página de configurações do projeto.

Limitações:

Seu projeto do Google Cloud precisa estar em uma organização do Google Cloud.
É necessário iniciar os builds na linha de comando usando gcloud builds submit ou gcloud builds triggers create. Para usar a página "Gatilhos" no console do Google Cloud, a conta de serviço especificada pelo usuário e o gatilho de compilação precisam estar no mesmo projeto.

A seguir

Saiba mais sobre os papéis e permissões do IAM no Cloud Build.
Saiba como as mudanças na conta de serviço afetam a forma como você executa seus builds.