Usar credenciales cifradas de Cloud KMS

Cloud Key Management Service es un Google Cloud servicio que te permite gestionar y usar claves criptográficas. En esta página se explica cómo usar información encriptada de Cloud KMS en Cloud Build.

Nota: Secret Manager es la técnica recomendada para gestionar datos sensibles con Cloud Build. En los proyectos que ya tengas, puedes seguir usando Cloud KMS, pero en los nuevos, usa Secret Manager. Para obtener instrucciones sobre cómo configurar las compilaciones para acceder a los secretos de Secret Manager, consulta el artículo Usar secretos de Secret Manager.

Antes de empezar

• Enable the Cloud Build and Cloud KMS APIs.

  Enable the APIs

• Para usar los ejemplos de línea de comandos de esta guía, instala y configura la CLI de Google Cloud.

  Nota: Si ya has instalado la CLI de gcloud, asegúrate de tener la última versión disponible ejecutando gcloud components update.

• Encripta la información sensible con Cloud KMS. Cloud KMS guarda el contenido cifrado en un archivo.

• [OPCIONAL] Para configurar las compilaciones de forma que usen datos cifrados, convierte el ENCRYPTED_FILE a base64 (este paso no es obligatorio para las configuraciones de compilación que usan archivos cifrados):

      base64 ENCRYPTED_FILE
  

Permisos de gestión de identidades y accesos necesarios

Asigna el rol de gestión de identidades y accesos Encargado de desencriptar claves de CryptoKey de Cloud KMS (roles/cloudkms.cryptoKeyDecrypter) a la cuenta de servicio de compilación:

1. En la Google Cloud consola, ve a la página Configuración de Cloud Build:

   Abre la página Configuración

2. Busca la fila con el rol Encargado de desencriptar claves de CryptoKey de Cloud KMS y asigna el valor ENABLED al campo Estado.

Advertencia: Si asignas el rol de encargado de descifrar claves de CryptoKey de Cloud KMS a la cuenta de servicio predeterminada de Cloud Build, la cuenta de servicio podrá descifrar la información cifrada. Los activadores de compilación usan la cuenta de servicio predeterminada de Cloud Build para ejecutar compilaciones. Por lo tanto, cualquier usuario que utilice activadores de compilación para ejecutar compilaciones tendrá los permisos concedidos a la cuenta de servicio en el momento de la compilación. De esta forma, los usuarios que no tengan el rol Descifrador de CryptoKey pueden usar los activadores de compilación para realizar una compilación que descifre la información cifrada. Esta acción se registra en el historial de compilaciones del proyecto.

Configurar compilaciones para usar datos cifrados

1. En el directorio raíz de tu proyecto, crea un archivo de configuración de compilación de Cloud Build llamado cloudbuild.yaml o cloudbuild.json.

2. En el archivo de configuración de compilación:

   • Después de todas las compilaciones steps, añade un campo availableSecrets para especificar el valor cifrado como variable de entorno y el kmsKeyName que se usará para descifrarlo. Puedes usar variables de sustitución en el valor de kmsKeyName.
   • En el paso de compilación en el que quieras especificar el secreto:
     • Añade un campo entrypoint que apunte a bash para usar la herramienta bash en el paso de compilación. Es necesario para hacer referencia a la variable de entorno del secreto.
     • Añade un campo secretEnv que especifique la variable de entorno del valor cifrado.
     • En el campo args, añade una marca -c como primer argumento. Cualquier cadena que envíes después de -c se tratará como un comando. Para obtener más información sobre cómo ejecutar comandos de bash con -c, consulta la documentación de bash.
     • Cuando especifique el valor cifrado en el campo args, hágalo con la variable de entorno con el prefijo $$.
   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"
        }
      }
      ]
   }
   

Siguientes pasos

• Consulta cómo configurar compilaciones para acceder a secretos de Secret Manager.
• Consulta cómo acceder a repositorios privados de GitHub.