Secrets aus Secret Manager verwenden

Auf dieser Seite wird erläutert, wie Sie vertrauliche Informationen wie Passwörter und API-Schlüssel in Cloud Build einbinden.

Secret Manager ist ein Google Cloud-Dienst, der API-Schlüssel, Passwörter und andere sensible Daten sicher speichert. Wenn Sie vertrauliche Informationen in Ihre Builds aufnehmen möchten, können Sie die Informationen in Secret Manager speichern und dann den Build für den Zugriff auf die Informationen aus Secret Manager konfigurieren.

Hinweise

• Cloud Build and Secret Manager APIs aktivieren.

  Aktivieren Sie die 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 gcloud components update aus.

• Das Secret muss in Secret Manager gespeichert werden. Eine Anleitung finden Sie unter Secret erstellen.

  • Notieren Sie sich den Namen des Secrets und die Secret-Version Ihres Secrets. Sie benötigen diese Informationen, um Cloud Build für den Zugriff auf das Secret zu konfigurieren.

Erforderliche IAM-Berechtigungen

Gewähren Sie dem Cloud Build-Dienstkonto die IAM-Rolle Secret Manager Secret Accessor (roles/secretmanager.secretAccessor) für das Secret:

1. Öffnen Sie in der Google Cloud Console die Seite „Secret Manager“:

   Zur Seite „Secret Manager“

2. Klicken Sie auf das Kästchen des Secrets, das Sie in Ihrem Build verwenden möchten.

3. Falls das Fenster noch nicht geöffnet ist, klicken Sie auf Infofeld ansehen, um es zu öffnen.

4. Klicken Sie im Steuerfeld unter Berechtigungen auf Hauptkonto hinzufügen.

5. Geben Sie in das Textfeld Neue Hauptkonten die E-Mail-Adresse Ihres Cloud Build-Dienstkontos im Format [e-mail] ein. PROJECT_NUMBER ist die Projektnummer des Projekts, in dem Sie Builds ausführen. Sie finden die Projektnummer auf der Seite mit den Projekteinstellungen.

6. Wählen Sie im Drop-down-Menü Rolle auswählen die Option Zugriffsperson für Secret Manager-Secret aus.

7. Klicken Sie auf Speichern.

Warnung: Wenn Sie dem Cloud Build-Dienstkonto die Rolle "Zugriffsperson für Secret Manager-Secret" zuweisen, kann das Dienstkonto auf das Secret zugreifen. Build-Trigger verwenden zum Ausführen von Builds das 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 "Zugriffsperson für Secret" Build-Trigger verwenden, um einen Build auszuführen, der auf das Secret zugreift. Diese Aktion wird im Build-Verlauf des Projekts protokolliert.

Builds für den Zugriff auf UTF-8-Secrets aus Secret Manager konfigurieren

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

2. In der Build-Konfigurationsdatei:

   • Fügen Sie nach allen Build-steps ein Feld availableSecrets hinzu, um die Secret-Version und die Umgebungsvariablen anzugeben, die für Ihr Secret verwendet werden sollen. In den Wert des Felds secretVersion können Sie Substitutionsvariablen einfügen. Sie können in einem Build mehrere Secrets angeben.
   • 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 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 das Secret im Feld args angeben, geben Sie es mit der Umgebungsvariable $$ an.
   Hinweis: Sie können nur im Feld args eines Build-Schritts auf Secrets verweisen.

   Die folgende Build-Konfigurationsdatei zeigt, wie Sie sich mit dem in Secret Manager gespeicherten Docker-Nutzernamen und -Passwort in Docker anmelden.

   YAML

   steps:
   - name: 'gcr.io/cloud-builders/docker'
     entrypoint: 'bash'
     args: ['-c', 'docker login --username=$$USERNAME --password=$$PASSWORD']
     secretEnv: ['USERNAME', 'PASSWORD']
   availableSecrets:
     secretManager:
     - versionName: projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION
       env: 'PASSWORD'
     - versionName: projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION
       env: 'USERNAME'
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=$$USERNAME --password=$$PASSWORD"
       ],
       "secretEnv": [
         "USERNAME",
         "PASSWORD"
       ]
     }
     ],
     "availableSecrets": {
       "secretManager": [{
         "versionName": "projects/PROJECT_ID/secrets/DOCKER_PASSWORD_SECRET_NAME/versions/DOCKER_PASSWORD_SECRET_VERSION",
         "env": "PASSWORD"
     }, {
       "versionName": "projects/PROJECT_ID/secrets/DOCKER_USERNAME_SECRET_NAME/versions/DOCKER_USERNAME_SECRET_VERSION",
       "env": "USERNAME"
        }]
     }
   }
   

   Ersetzen Sie die Platzhalterwerte in den obigen Befehlen durch Folgendes:

   • PROJECT_ID: Die ID des Google Cloud-Projekts, in dem Sie Ihre Secrets gespeichert haben.
   • DOCKER_USERNAME_SECRET_NAME: Der Secret-Name, der Ihrem Docker-Nutzernamen entspricht. Sie finden den Secret-Namen in der Google Cloud Console auf der Seite Secret Manager.
   • DOCKER_USERNAME_SECRET_VERSION: Die Secret-Version Ihres Docker-Nutzernamens. Sie können die Secret-Version abrufen. Klicken Sie dazu in der Google Cloud Console auf der Seite Secret Manager auf den Namen eines Secrets.
   • DOCKER_PASSWORD_SECRET_NAME: Der Secret-Name, der Ihrem Docker-Passwort entspricht. Sie finden den Secret-Namen in der Google Cloud Console auf der Seite Secret Manager.
   • DOCKER_PASSWORD_SECRET_VERSION: Die Secret-Version Ihres Docker-Passworts. Sie können die Secret-Version abrufen. Klicken Sie dazu in der Google Cloud Console auf der Seite Secret Manager auf den Namen eines Secrets.

3. Verwenden Sie die Build-Konfigurationsdatei, um einen Build über die Befehlszeile zu starten oder Builds mit Triggern zu automatisieren.

Beispiel: Über Skripts und Prozesse auf Secrets zugreifen

Das Feld secretEnv fügt der Umgebung den Wert des Secrets hinzu. Sie können über Skripts oder Prozesse über eine Umgebungsvariable auf diesen Wert zugreifen:

YAML

steps:
- name: python:slim
  entrypoint: python
  args: ['main.py']
  secretEnv: ['MYSECRET']
availableSecrets:
  secretManager:
  - versionName: projects/$PROJECT_ID/secrets/mySecret/versions/latest
    env: 'MYSECRET'

JSON

{
  "steps": [
  {
    "name": "python:slim",
    "entrypoint": "python",
    "args": [
        "main.py"
    ],
    "secretEnv": [
        "MYSECRET"
    ]
}
],
"availableSecrets": {
  "secretManager": [
    {
        "versionName": "projects/$PROJECT_ID/secrets/mySecret/versions/latest",
        "env": "MYSECRET"
    }
  ]
}
}

Mit dem folgenden Inhalt von main.py werden die ersten fünf Zeichen des Secrets ausgegeben:

import os
print(os.environ.get("MYSECRET", "Not Found")[:5], "...")

Beispiel: Docker-Authentifizierung

In manchen Fällen muss sich Ihr Build vor der Interaktion mit Docker-Images bei Docker authentifizieren. Beispielsweise ist die Docker-Authentifizierung erforderlich, damit Builds private Images abrufen und private oder öffentliche Images an Docker Hub übertragen können. In diesen Fällen können Sie Ihren Docker-Nutzernamen und das Passwort in Secret Manager speichern und dann Cloud Build so konfigurieren, dass von Secret Manager auf den Nutzernamen und das Passwort zugegriffen wird. Eine Anleitung dazu finden Sie unter Mit Docker Hub-Images interagieren.

Beispiel: GitHub-Pull-Anfrage erstellen

Ein weiteres Beispiel, bei dem Sie Ihren Build so konfigurieren möchten, dass er auf sensible Informationen aus dem Secret Manager zugreift, ist die Erstellung einer GitHub-Pull-Anfrage als Reaktion auf Builds. So gehen Sie dazu vor:

• Erstellen Sie einen GitHub-Token.
• Speichern Sie das GitHub-Token in Secret Manager:
• In Ihrer Build-Konfigurationsdatei:
  • Fügen Sie nach allen Build-steps ein Feld availableSecrets hinzu, um die Secret-Version und die Umgebungsvariable anzugeben, die für das GitHub-Token verwendet werden soll.
  • Fügen Sie einen Build-Schritt hinzu, um den Befehl zum Erstellen einer GitHub-Pull-Anfrage aufzurufen.
• Erstellen Sie einen GitHub-App-Trigger und rufen Sie den Build mit der Build-Konfigurationsdatei auf.

Die folgende Beispielkonfigurationsdatei zeigt, wie eine GitHub-Pull-Anfrage mit dem GitHub-Token erstellt wird:

YAML

steps:
- name: 'launcher.gcr.io/google/ubuntu1604'
  id: Create GitHub pull request
  entrypoint: bash
  args:
  - -c
  - curl -X POST -H "Authorization:Bearer $$GH_TOKEN" -H 'Accept:application/vnd.github.v3+json' https://api.github.com/repos/GITHUB_USERNAME/REPO_NAME/pulls -d '{"head":"HEAD_BRANCH","base":"BASE_BRANCH", "title":"NEW_PR"}'
  secretEnv: ['GH_TOKEN']
availableSecrets:
  secretManager:
  - versionName: projects/PROJECT_ID/secrets/GH_TOKEN_SECRET_NAME/versions/latest
    env: GH_TOKEN

JSON

{
  "steps": [
  {
    "name": "launcher.gcr.io/google/ubuntu1604",
    "id": "Create GitHub pull request",
    "entrypoint": "bash",
    "args": [
      "-c",
       "curl -X POST -H \"Authorization:Bearer $$GH_TOKEN\" -H 'Accept:application/vnd.github.v3+json' https://api.github.com/repos/GITHUB_USERNAME/REPO_NAME -d '{\"head\":\"HEAD_BRANCH\",\"base\":\"BASE_BRANCH\", \"title\":\"NEW_PR\"}'
    ],
    "secretEnv": ['GH_TOKEN']
}
],
"availableSecrets": {
  "secretManager": [
  {
    "versionName": "projects/PROJECT_ID/secrets/GH_TOKEN_SECRET_NAME/versions/latest",
    "env": "GH_TOKEN"
  }
  ]
}
}

Ersetzen Sie die Platzhalterwerte in den obigen Befehlen durch Folgendes:

• PROJECT_ID: Die ID des Google Cloud-Projekts, in dem Sie Ihre Secrets gespeichert haben.
• GITHUB_USERNAME: Der GitHub-Nutzername des Repository-Inhabers.
• REPO_NAME: Der Name des GitHub-Repositorys.
• HEAD_BRANCH: Der Name des Zweigs, in dem die Änderungen implementiert sind. Geben Sie bei repository-übergreifende Pull-Anfragen im gleichen Netzwerk für den Namespace head einen Nutzer wie den folgenden an: username:branch.
• BASE_BRANCH: Der Name des Zweigs, in den die Änderungen übernommen werden sollen. Dies sollte ein vorhandener Zweig im aktuellen Repository sein. Sie können keine Pull-Anfrage an ein Repository senden, das eine Zusammenführung an eine Basis eines anderen Repositorys anfordert.
• GH_TOKEN_SECRET_NAME: Der Secret-Name, der Ihrem GitHub-Token entspricht.
• NEW_PR: Die neue Pull-Anfrage, die Sie erstellen möchten.

Builds für den Zugriff auf Nicht-UTF-8-Secrets aus Secret Manager konfigurieren

1. Fügen Sie in Ihrer Build-Konfigurationsdatei einen Build-Schritt hinzu, um im Secret Manager auf die geheime Version zuzugreifen und sie in einer Datei zu speichern. Mit dem folgenden Build-Schritt wird auf secret-name zugegriffen und in der Datei decrypted-data.txt gespeichert:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     entrypoint: 'bash'
     args: [ '-c', "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt" ]
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "entrypoint": "bash",
       "args": [
         "-c",
         "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt"
       ]
     }
     ]
   }
   

2. Verwenden Sie die Datei mit den entschlüsselten Daten in einem Build-Schritt. Das folgende Code-Snippet verwendet zur Anmeldung bei einer privaten Docker-Registry decrypted-data.txt:

   YAML

   steps:
   - name: gcr.io/cloud-builders/gcloud
     entrypoint: 'bash'
     args: [ '-c', "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > decrypted-data.txt" ]
   - name: gcr.io/cloud-builders/docker
     entrypoint: 'bash'
     args: [ '-c', 'docker login --username=my-user --password-stdin < decrypted-data.txt']
   

   JSON

   {
     "steps": [
     {
       "name": "gcr.io/cloud-builders/gcloud",
       "entrypoint": "bash",
       "args": [
         "-c",
         "gcloud secrets versions access latest --secret=secret-name --format='get(payload.data)' | tr '_-' '/+' | base64 -d > password.txt"
        ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker login --username=my-user --password-stdin < decrypted-data.txt"
        ]
     }
     ]
   }
   

   Hinweis: Um das Secret in einer Umgebungsvariablen zu verwenden, müssen Sie dem Variablennamen einen Unterstrich „_“ voranstellen und den Wert mit „\(“ maskieren. Zum Beispiel: _VARIABLE_NAME=$(cat password.txt) && echo -n \)_VARIABLE_NAME.

3. Verwenden Sie die Build-Konfigurationsdatei, um einen Build über die Befehlszeile zu starten oder Builds mit Triggern zu automatisieren.

Nächste Schritte

• Verschlüsselte Anmeldedaten in Builds verwenden
• Weitere Informationen finden Sie unter Auf private GitHub-Repositories zugreifen.