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

• Enable the Cloud Build and Cloud KMS APIs.

  Enable the APIs

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

  Observação :se você já instalou CLI gcloud, 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 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 padrão do Cloud Build permite que a conta de serviço descriptografe as informações criptografadas. Gatilhos de build usar a conta de serviço padrã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 $$.
   Note: You can refer to encrypted values using environment variables only in the args field of a build step.

   The following example build config file shows how to login to Docker and pull a private image:

   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"
          }
      }]
    }
   }
   
   

   Replace the placeholder values in the above commands with the following:

   • PROJECT_ID: The ID of the Google Cloud project which contains your Cloud KMS service.
   • USERNAME_KEYRING_NAME: The key ring name of your Docker username.
   • USERNAME_KEY_NAME: The key name of your Docker username.
   • ENCRYPTED_USERNAME: Your encrypted Docker username in base64 format.
   • PASSWORD_KEYRING_NAME: The key ring name of your Docker password.
   • PASSWORD_KEY_NAME: The key name of your Docker password.
   • ENCRYPTED_PASSWORD: Your encrypted Docker password in base64 format.
   • REPOSITORY: The name of your Docker repository from where you're pulling the image.

   • TAG: The tag name of your image.

     Note: The secretEnv field does not support substitution variables. If the Google Cloud project hosting the key changes, the encrypted contents within that project also change.

3. Use the build config file to manually start a build or to automate builds using triggers.

Configuring builds to use encrypted files

1. In your project root directory, create a Cloud Build build config file named cloudbuild.yaml or cloudbuild.json.

2. In your build config file, before any build steps that interact with the decrypted file, add a gcloud build step to decrypt the encrypted file using the encryption key. The following example build config file shows how to login to Docker using the encrypted file with Docker password:

   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"
       ]
      }
     ]
   }
   

   Replace the placeholder values in the above commands with the following:

   • KEYRING_NAME: The key ring name of your Docker password.
   • KEY_NAME: The key name of your Docker password.
   • ENCRYPTED_PASSWORD_FILE: Encrypted file with your Docker password.
   • PLAINTEXT_PASSWORD_FILE: Plaintext file with your Docker password.

3. Use the build config file to manually start a build or to automate builds using triggers.

Configuring builds to use encrypted data (legacy)

Warning: This is the legacy method of using Cloud KMS with Cloud Build. This method will continue to work, but we recommend that you use the newer way of configuring builds to use encrypted data.

To encrypt sensitive data using Cloud KMS and use that data in a build config file:

1. In your build config file, add a secrets field to specify the encrypted value and the CryptoKey to use to decrypt it. Then, in the build step where you want to use the encrypted variable, add a secretEnv field to specify the variable as an environment variable. Include the variable's name in the secretEnv field. If you specify the variable value, or a non-secret environment variable with the same name, Cloud Build throws an error.

   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.