Utilizzare le credenziali criptate di Cloud KMS

Cloud Key Management Service è un servizio Google Cloud che ti consente di gestire e utilizzare le chiavi di crittografia. Questa pagina spiega come utilizzare le informazioni criptate di Cloud KMS in Cloud Build.

Nota: Secret Manager è la tecnica consigliata per la gestione dei dati sensibili con Cloud Build. Per i progetti esistenti, può continuare a utilizzare Cloud KMS, ma per i nuovi progetti, utilizza Secret Manager. Per istruzioni su come configurare le build per accedere ai secret da Secret Manager, consulta Utilizzare i secret di Secret Manager.

Prima di iniziare

• Enable the Cloud Build and Cloud KMS APIs.

  Enable the APIs

• Per utilizzare gli esempi a riga di comando in questa guida, installa configurare Google Cloud CLI.

  Nota: se hai già installato gcloud CLI in precedenza, assicurati di avere ultima versione disponibile eseguendo gcloud components update.

• Cripta le informazioni sensibili utilizzando Cloud KMS. Cloud KMS salva i contenuti criptati in un file.

• [FACOLTATIVO] Per configurare le build in modo che utilizzino i dati criptati, converti ENCRYPTED_FILE in base64 (questo passaggio non è obbligatorio per le configurazioni di build che utilizzano file criptati):

      base64 ENCRYPTED_FILE
  

Autorizzazioni IAM richieste

Concedi il ruolo IAM Cloud KMS CryptoKey Decrypter (roles/cloudkms.cryptoKeyDecrypter) all'account di servizio di compilazione:

1. Nella console Google Cloud, vai alla pagina Impostazioni di Cloud Build:

   Apri la pagina Impostazioni

2. Individua la riga con il ruolo Autore crittografia CryptoKey Cloud KMS e impostane Stato su ATTIVATO.

Avviso: la concessione del ruolo Decriptatore CryptoKey Cloud KMS all'account di servizio Cloud Build predefinito consente all'account di decriptare le informazioni criptate. Gli trigger di compilazione utilizzano l'account di servizio Cloud Build predefinito per eseguire le build. Pertanto, qualsiasi utente che utilizza gli attivatori di build per eseguire le build avrà le autorizzazioni concesse all'account di servizio al momento della compilazione. Consente agli utenti senza l'autore della decrittografia della CryptoKey per utilizzare trigger di build al fine di eseguire una build che decripta le informazioni criptate. Questa azione viene registrata nella cronologia delle build del progetto.

Configurare le build per utilizzare i dati criptati

1. Nella directory principale del progetto, crea un file di configurazione della build Cloud Build chiamato cloudbuild.yaml o cloudbuild.json.

2. Nel file di configurazione della build:

   • Dopo tutta la compilazione steps, aggiungi un campo availableSecrets per specificare il valore criptato come variabile di ambiente e il kmsKeyName da utilizzare per decriptarlo. Puoi utilizzare le variabili di sostituzione nel valore di kmsKeyName.
   • Nel passaggio di compilazione in cui vuoi specificare il segreto:
     • Aggiungi un campo entrypoint che rimandi a bash per usare lo strumento bash nella il passaggio di build. Questa operazione è necessaria per fare riferimento alla variabile di ambiente per il secret.
     • Aggiungi un campo secretEnv che specifichi la variabile di ambiente per valore criptato.
     • Nel campo args, aggiungi un flag -c come primo argomento. Qualsiasi stringa passata dopo -c viene considerata un comando. Per ulteriori informazioni sulla corsa per i comandi bash con -c, consulta la documentazione di bash.
     • Quando specifichi il valore criptato nel campo args, specificalo utilizzando il metodo variabile di ambiente con prefisso $$.
   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"
        }
      }
      ]
   }
   

Passaggi successivi

• Scopri come configurare le build per accedere ai secret da Secret Manager.
• Scopri come accedere ai repository GitHub privati.