Use credenciais encriptadas do Cloud KMS

O Cloud Key Management Service é um Google Cloud serviço que lhe permite gerir e usar chaves criptográficas. Esta página explica como usar informações encriptadas do Cloud KMS no Cloud Build.

Nota: o Secret Manager é a técnica recomendada para gerir dados confidenciais com o Cloud Build. Para projetos existentes, pode continuar a usar o Cloud KMS, mas, para novos projetos, use o Secret Manager. Para obter instruções sobre a configuração de compilações para aceder a segredos do Secret Manager, consulte o artigo Usar segredos do Secret Manager.

Antes de começar

• Enable the Cloud Build and Cloud KMS APIs.

  Enable the APIs

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

  Nota: se tiver instalado a CLI gcloud anteriormente, certifique-se de que tem a versão mais recente disponível executando gcloud components update.

• Encriptar as informações confidenciais através do Cloud KMS. O Cloud KMS guarda o seu conteúdo encriptado num ficheiro.

• [OPCIONAL] Para configurar compilações para usar dados encriptados, converta o ENCRYPTED_FILE para base64 (este passo não é necessário para configurações de compilação que usam ficheiros encriptados):

      base64 ENCRYPTED_FILE
  

Autorizações de IAM necessárias

Conceda a função da IAM desencriptador de CryptoKey do Cloud KMS (roles/cloudkms.cryptoKeyDecrypter) à conta de serviço de compilação:

1. Na Google Cloud consola, aceda à página Definições do Cloud Build:

   Abra a página Definições

2. Localize a linha com a função Desencriptador de CryptoKey do Cloud KMS e defina o respetivo Estado como ATIVADO.

Aviso: a concessão da função de desencriptador do CryptoKey do Cloud KMS à conta de serviço do Cloud Build predefinida permite que a conta de serviço descifre as informações encriptadas. Os acionadores de compilação usam a conta de serviço predefinida do Cloud Build para executar compilações. Por conseguinte, qualquer utilizador que use acionadores de compilação para executar compilações tem autorizações concedidas à conta de serviço no momento da compilação. Isto permite que os utilizadores sem a função CryptoKey Decrypter usem acionadores de compilação para realizar uma compilação que desencripta as informações encriptadas. Esta ação é registada no histórico de compilação do projeto.

Configurar compilações para usar dados encriptados

1. No diretório raiz do projeto, crie um ficheiro de configuração de compilação do Cloud Build denominado cloudbuild.yaml ou cloudbuild.json.

2. No ficheiro de configuração de compilação:

   • Depois de criar todos os steps, adicione um campo availableSecrets para especificar o valor encriptado como uma variável de ambiente e o kmsKeyName a usar para o desencriptar. Pode usar variáveis de substituição no valor de kmsKeyName.
   • No passo de compilação onde quer especificar o segredo:
     • Adicione um campo entrypoint que aponte para bash para usar a ferramenta bash no passo de compilação. Isto é necessário para fazer referência à variável de ambiente do segredo.
     • Adicione um campo secretEnv que especifique a variável de ambiente para o valor encriptado.
     • No campo args, adicione uma flag -c como o primeiro argumento. Qualquer string que passe após -c é tratada como um comando. Para mais informações sobre a execução de comandos bash com -c, consulte a documentação do bash.
     • Quando especificar o valor encriptado no campo args, especifique-o através da 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"
        }
      }
      ]
   }
   

O que se segue?

• Saiba como configurar compilações para aceder a segredos do Secret Manager.
• Saiba como aceder a repositórios privados do GitHub.