Verschlüsselte Anmeldedaten von Cloud KMS verwenden

Der Cloud Key Management Service ist ein Google Cloud -Dienst, mit dem Sie kryptografische Schlüssel verwalten und verwenden können. Auf dieser Seite wird erläutert, wie Sie verschlüsselte Informationen aus Cloud KMS in Cloud Build verwenden.

Hinweis: Secret Manager wird für die Verwaltung vertraulicher Daten mit Cloud Build empfohlen. Für bestehende Projekte können Sie weiterhin Cloud KMS verwenden, für neue Projekte jedoch Secret Manager. Eine Anleitung zum Konfigurieren von Builds für den Zugriff auf Secrets von Secret Manager finden Sie unter Secrets aus Secret Manager verwenden.

Hinweise

• Enable the Cloud Build and Cloud KMS APIs.

  Roles required to enable APIs

  To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

  Enable the APIs

• Wenn Sie die Befehlszeilenbeispiele in dieser Anleitung verwenden möchten, installieren und konfigurieren Sie die Google Cloud CLI.

  Hinweis: Wenn Sie die gcloud CLI bereits installiert haben, prüfen Sie, ob Sie die neueste verfügbare Version haben. Führen Sie dazu den Befehl gcloud components update aus.

• Verschlüsseln Sie die vertraulichen Informationen mit Cloud KMS. Cloud KMS speichert Ihre verschlüsselten Inhalte in einer Datei.

• [OPTIONAL] Um Builds für die Verwendung verschlüsselter Daten zu konfigurieren, konvertieren Sie das ENCRYPTED_FILE in base64: (Dieser Schritt ist für Build-Konfigurationen, die verschlüsselte Dateien verwenden, nicht erforderlich.)

      base64 ENCRYPTED_FILE
  

Erforderliche IAM-Berechtigungen

Weisen Sie dem Build-Dienstkonto die IAM-Rolle Cloud KMS CryptoKey-Entschlüsseler (roles/cloudkms.cryptoKeyDecrypter) zu:

1. Rufen Sie in der Google Cloud Console die Cloud Build-Seite Einstellungen auf:

   Zur Seite "Einstellungen"

2. Suchen Sie die Zeile mit der Rolle Cloud KMS CryptoKey-Entschlüsseler und setzen Sie ihren Status auf AKTIVIERT.

Warnung: Wenn Sie dem Standard-Cloud Build-Dienstkonto die Rolle „Cloud KMS CryptoKey-Entschlüsseler“ zuweisen, kann das Dienstkonto die verschlüsselten Informationen entschlüsseln. Build-Trigger verwenden zum Ausführen von Builds das Standard-Cloud Build-Dienstkonto. Daher werden jedem Nutzer, der Build-Trigger zum Ausführen von Builds verwendet, zum Zeitpunkt der Build-Erstellung Berechtigungen für das Dienstkonto erteilt. Dadurch können Nutzer ohne die Rolle „CryptoKey-Entschlüsseler“ Build-Trigger verwenden, um einen Build auszuführen, der die verschlüsselten Informationen entschlüsselt. Diese Aktion wird im Build-Verlauf des Projekts protokolliert.

Builds für die Verwendung verschlüsselter Daten konfigurieren

1. Erstellen Sie im Stammverzeichnis des Projekts eine Cloud Build-Konfigurationsdatei mit dem Namen cloudbuild.yaml oder cloudbuild.json.

2. In Ihrer Build-Konfigurationsdatei:

   • Fügen Sie nach Abschluss des Builds steps ein availableSecrets-Feld hinzu, um den verschlüsselten Wert als Umgebungsvariable und den zur Entschlüsselung zu verwendenden kmsKeyName anzugeben. Sie können Substitutionsvariablen im Wert von kmsKeyName verwenden.
   • Geben Sie im Build-Schritt, in dem Sie das Secret angeben möchten, Folgendes an:
     • Fügen Sie das Feld entrypoint hinzu, das auf bash verweist, um das Bash-Tool im Build-Schritt zu verwenden. Dies ist erforderlich, um auf die Umgebungsvariable für das Secret zu verweisen.
     • Fügen Sie das Feld secretEnv hinzu, das die Umgebungsvariable für den verschlüsselten Wert angibt.
     • Fügen Sie im Feld args das Flag -c als erstes Argument hinzu. Jeder String, den Sie nach -c übergeben, wird als Befehl behandelt. Weitere Informationen zum Ausführen von Bash-Befehlen mit -c finden Sie in der Bash-Dokumentation.
     • Wenn Sie den verschlüsselten Wert im Feld args angeben, geben Sie ihn mit der Umgebungsvariable $$.
   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'
    an.
    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"
        }
      }
      ]
   }
   

Nächste Schritte

• Builds für den Zugriff auf Secrets von Secret Manager konfigurieren
• Weitere Informationen finden Sie unter Auf private GitHub-Repositories zugreifen.