Usar credenciais criptografadas do Cloud KMS

O Cloud Key Management Service é um serviço do Google Cloud em que é possível gerenciar e usar chaves criptográficas. Nesta página, explicamos como usar informações criptografadas do Cloud KMS no Cloud Build.

Observação: o Gerenciador de secrets é a técnica recomendada para gerenciar dados confidenciais com o Cloud Build. Para projetos existentes, você pode continuar usando o Cloud KMS, mas para novos projetos, use o Gerenciador de secrets. Para instruções sobre como configurar builds para acessar secrets do Secret Manager, consulte Como usar secrets do Secret Manager.

Antes de começar

• Ative as APIs Cloud Build and Cloud KMS.

  Ative as APIs

• Para usar os exemplos de linha de comando neste guia, instale e configure a Google Cloud CLI.

  Observação :se você instalou a CLI gcloud anteriormente, verifique se tem a versão mais recente disponível executando gcloud components update.

• Criptografe informações confidenciais usando o Cloud KMS. O Cloud KMS salva o conteúdo criptografado em um arquivo.

• [OPCIONAL] Para configurar versões para usar dados criptografados, converta a ENCRYPTED_FILE em base64. Essa etapa não é necessária para configurações de versão que usam arquivos criptografados:

      base64 ENCRYPTED_FILE
  

Permissões do IAM obrigatórias

Conceda o papel do IAM descriptografador do Cloud KMS CryptoKey (roles/cloudkms.cryptoKeyDecrypter) à conta de serviço do Cloud Build:

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

   Abrir a página Configurações

2. Localize a linha com o papel Descriptografador de CryptoKey do Cloud KMS e defina o Status como ENABLED.

Aviso: a concessão do papel de descriptografia do CryptoKey do Cloud KMS à conta de serviço do Cloud Build permite que a conta de serviço descriptografe as informações criptografadas. Os gatilhos de compilação usam a conta de serviço do Cloud Build para executar builds. Portanto, qualquer usuário que use acionadores de versão para executar versões terá permissões concedidas à conta de serviço no momento da criação. Isso permite que usuários sem o papel de descriptografia do CryptoKey usem acionadores de versão para realizar uma versão que descriptografa as informações criptografadas. Essa ação é registrada no histórico da versão do projeto.

Como configurar builds para usar dados criptografados

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. No arquivo de configuração de build, faça o seguinte:

   • Após a criação de steps, adicione um campo availableSecrets para especificar o valor criptografado como uma variável de ambiente e o kmsKeyName a ser usado para descriptografá-lo. É possível usar variáveis de substituição no valor de kmsKeyName.
   • Na etapa de versão em que você quer especificar o secret:
     • Adicione um campo entrypoint que aponte para bash para usar a ferramenta bash na etapa de versão. Isso é necessário para fazer referência à variável de ambiente do secret.
     • Adicione um campo de secretEnv especificando a variável de ambiente para o valor criptografado.
     • No campo args, adicione uma sinalização -c como primeiro argumento. Qualquer string que você passar depois de -c será tratada como um comando. Para mais informações sobre como executar comandos bash com -c, consulte a documentação do bash.
     • Ao especificar o valor criptografado no campo args, especifique-o usando a variável de ambiente com o prefixo $$.
   Observação: só é possível se referir a valores criptografados usando variáveis de ambiente no campo args de uma etapa do build.

   O exemplo de arquivo de configuração da compilação a seguir mostra como fazer login no Docker e extrair uma imagem particular:

   YAML

    steps:
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
      secretEnv: ['USERNAME', 'PASSWORD']
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker pull $$USERNAME/IMAGE:TAG']
      secretEnv: ['USERNAME']
    availableSecrets:
      inline:
      - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME
        envMap:
          USERNAME: 'ENCRYPTED_USERNAME'
      - kmsKeyName: projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME
        envMap:
          PASSWORD: 'ENCRYPTED_PASSWORD'
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=$$USERNAME --password=$$PASSWORD"
       ],
       "secretEnv": [
         "USERNAME",
         "PASSWORD"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker pull $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "availableSecrets": {
       "inline": [{
         "kmsKeyName":  "projects/PROJECT_ID/locations/global/keyRings/USERNAME_KEYRING_NAME/cryptoKeys/USERNAME_KEY_NAME",
         "envMap": {
           "USERNAME": "ENCRYPTED_USERNAME"
          }
      },
      {
       "kmsKeyName": "projects/PROJECT_ID/locations/global/keyRings/PASSWORD_KEYRING_NAME/cryptoKeys/PASSWORD_KEY_NAME",
       "envMap": {
           "PASSWORD": "ENCRYPTED_PASSWORD"
          }
      }]
    }
   }
   

   Substitua os valores dos marcadores nos comandos acima pelo seguinte:

   • PROJECT_ID: o ID do projeto do Google Cloud que contém o serviço do Cloud KMS.
   • USERNAME_KEYRING_NAME: o nome do keyring do nome de usuário do Docker;
   • USERNAME_KEY_NAME: o nome da chave do seu nome de usuário do Docker;
   • ENCRYPTED_USERNAME: seu nome de usuário do Docker criptografado no formato base64.
   • PASSWORD_KEYRING_NAME: o nome do keyring da senha do Docker.
   • PASSWORD_KEY_NAME: o nome da chave da senha do Docker.
   • ENCRYPTED_PASSWORD: sua senha criptografada do Docker no formato Base64.
   • REPOSITORY: o nome do repositório do Docker de onde você está extraindo a imagem.

   • TAG: o nome da tag da imagem.

     Observação :o campo secretEnv não é compatível com variáveis de substituição. Se o projeto do Google Cloud que hospeda a chave mudar, o conteúdo criptografado nesse projeto também mudará.

3. Use o arquivo de configuração de build para iniciar manualmente um build ou para automatizar builds usando acionadores.

Como configurar builds para usar arquivos criptografados

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. No arquivo de configuração de versão, antes de qualquer etapa de versão que interaja com o arquivo descriptografado, adicione uma etapa de versão gcloud para descriptografar o arquivo criptografado usando a chave de criptografia. O seguinte exemplo de arquivo de configuração de versão mostra como fazer login no Docker usando o arquivo criptografado com senha do Docker:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     args:
     - kms
     - decrypt
     - "--ciphertext-file=ENCRYPTED_PASSWORD_FILE"
     - "--plaintext-file=PLAINTEXT_PASSWORD_FILE"
     - "--location=global"
     - "--keyring=KEYRING_NAME"
     - "--key=KEY_NAME"
   - name: gcr.io/cloud-builders/docker
     entrypoint: bash
     args:
     - "-c"
     - docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "args": [
         "kms",
         "decrypt",
         "--ciphertext-file=ENCRYPTED_PASSWORD_FILE",
         "--plaintext-file=PLAINTEXT_PASSWORD_FILE",
         "--location=global",
         "--keyring=KEYRING_NAME",
         "--key=KEY_NAME"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=DOCKER_USERNAME --password-stdin < PLAINTEXT_PASSWORD_FILE"
       ]
      }
     ]
   }
   

   Substitua os valores dos marcadores nos comandos acima pelo seguinte:

   • KEYRING_NAME: o nome do keyring da senha do Docker.
   • KEY_NAME: o nome da chave da senha do Docker.
   • ENCRYPTED_PASSWORD_FILE: arquivo criptografado com a senha do Docker.
   • PLAINTEXT_PASSWORD_FILE: arquivo de texto simples com sua senha do Docker.

3. Use o arquivo de configuração de build para iniciar manualmente um build ou para automatizar builds usando acionadores.

Como configurar builds para usar dados criptografados (legados)

Aviso: este é o método legado de uso do Cloud KMS com o Cloud Build. Esse método continuará funcionando, mas recomendamos que você use a maneira mais recente de configurar builds para usar dados criptografados.

Para criptografar dados confidenciais usando o Cloud KMS e usar esses dados em um arquivo de configuração de versão:

1. No arquivo de configuração da versão, adicione um campo secrets para especificar o valor criptografado e o CryptoKey a ser usado para descriptografá-lo. Em seguida, na etapa de versão em que você quer usar a variável criptografada, adicione um campo secretEnv para especificar a variável como uma variável de ambiente. Inclua o nome da variável no campo secretEnv. Se você especificar o valor da variável ou uma variável de ambiente não secreta com o mesmo nome, o Cloud Build emitirá um erro.

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     entrypoint: 'bash'
     args: ['-c', 'docker login --username=user-name --password=$$PASSWORD']
     secretEnv: ['PASSWORD']
   - name: 'gcr.io/cloud-builders/docker'
     args: ['push', 'user-name/myubuntu']
   secrets:
   - kmsKeyName: projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name
     secretEnv:
       PASSWORD: 'encrypted-password'
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=user-name --password=$$PASSWORD"
       ],
       "secretEnv": [
         "PASSWORD"
        ]
      },
      {
        "name": "gcr.io/cloud-builders/docker",
        "args": [
          "push",
          "user-name/myubuntu"
         ]
      }
      ],
      "secrets": [
      {
        "kmsKeyName": "projects/project-id/locations/global/keyRings/keyring-name/cryptoKeys/key-name",
        "secretEnv": {
          "PASSWORD": "encrypted-password"
        }
      }
      ]
   }
   

A seguir

• Saiba como configurar builds para acessar secrets do Secret Manager.
• Saiba como acessar repositórios GitHub particulares.