Mit Docker Hub-Images interagieren

Sie können Container-Images von Docker Hub verwenden, um Ihre Aufgaben in Cloud Build auszuführen. Wenn Ihr Build Images erzeugt, können Sie diese auch an Docker Hub übertragen. Auf dieser Seite wird beschrieben, wie Sie Build-Konfigurationsdateien zum Übertragen und Abrufen von Docker Hub-Images schreiben. Eine Übersicht über alle in einer Build-Konfigurationsdatei verfügbaren Felder finden Sie in der Übersicht über die Build-Konfiguration.

Öffentliche Images aus Docker Hub abrufen

Sie können offizielle Docker-Images, Docker-zertifizierte Images sowie benutzerdefinierte Images abrufen, die in Ihrem Build-Schritt in Docker Hub gespeichert wurden. Geben Sie hierfür im Feld name den Namen des Images an. Cloud Build ruft zuerst das angegebene Image aus Docker Hub ab und verwendet dann das Image, um den Build-Schritt auszuführen.

Hinweis: Wenn Sie ein öffentliches Container-Image aus Docker Hub abrufen, um es in Ihrer Build-Konfigurationsdatei zu verwenden, prüft Cloud Build automatisch den Caching-Proxy mirror.gcr.io auf eine im Cache gespeicherte Kopie des Container-Images. Wenn keine im Cache gespeicherte Kopie verfügbar ist, ruft Cloud Build das angeforderte Image aus Docker Hub ab und der Caching-Proxy könnte das Image zur späteren Verwendung im Cache speichern. Weitere Informationen finden Sie unter Im Cache gespeicherte Bilder abrufen.

Im folgenden Beispiel ruft Cloud Build das Docker-Image für maven ab, um den in args angegebenen mvn-Befehl auszuführen:

YAML

steps:
- name: "maven"
  args: ["mvn", "--version"]

JSON

{
   "steps": [
      {
         "name": "maven",
         "args": [
            "mvn",
            "--version"
         ]
      }
   ]
}

Docker-Anmeldedaten im Secret Manager speichern

Wenn Sie private Images abrufen sowie öffentliche und private Images in Docker Hub hochladen möchten, muss sich Cloud Build mit Ihren Anmeldedaten bei Docker authentifizieren. Wenn Sie Docker-Anmeldedaten in Ihre Builds aufnehmen möchten, müssen Sie zuerst Ihre Anmeldedaten im Secret Manager speichern und dann Cloud Build die Berechtigung für den Zugriff auf das Secret vom Secret Manager erteilen.

So speichern Sie Docker-Anmeldedaten im Secret Manager:

1. Rufen Sie in der Google Cloud Console die Seite "Secret Manager" auf:

   Zur Seite „Secret Manager“

2. Klicken Sie auf der Seite Secret Manager auf Secret erstellen.

3. Geben Sie auf der Seite Secret erstellen unter Name den Wert docker-username ein.

4. Geben Sie im Feld Secret-Wert Ihren Docker-Nutzernamen ein.

5. Lassen Sie den Abschnitt Regionen unverändert.

6. Klicken Sie auf Secret erstellen.

Wiederholen Sie die obigen Schritte, um Ihr Docker-Passwort im Secret Manager zu speichern.

So weisen Sie dem Dienstkonto, das Sie für den Build verwenden, die IAM-Rolle Secret Manager Secret Accessor für das Secret zu:

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 Ihrem Docker-Nutzernamen und dem Passwort entspricht.

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 im Feld Neue Hauptkonten die E-Mail-Adresse des Dienstkontos ein.

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

7. Klicken Sie auf Speichern.

Private Images aus Docker Hub abrufen

So rufen Sie private Images aus Docker Hub ab:

1. Achten Sie darauf, dass Sie Ihre Docker-Anmeldedaten im Secret Manager gespeichert und Cloud Build Zugriff auf das Secret gewährt haben.

2. In der Build-Konfigurationsdatei:

   • Fügen Sie nach allen Build-steps ein Feld availableSecrets hinzu, das die Secret-Version und die Umgebungsvariable für den Docker-Nutzernamen und das Passwort angibt.
   • Geben Sie im Build-Schritt, in dem Sie den Nutzernamen und das Passwort angeben möchten, Folgendes ein:
     • 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 Nutzername und Passwort 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 mithilfe der Umgebungsvariable mit dem Präfix $$.

   The following build config file shows how to login to Docker using the Docker username and password stored in Secret Manager, and run 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 run $$USERNAME/REPOSITORY:TAG']
      secretEnv: ['USERNAME']
    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'
    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 run $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "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"
        }]
     }
   }
   
   

   Replace the placeholder values in the above commands with the following:

   • PROJECT_ID: The ID of the Google Cloud project where you've stored your secrets.
   • DOCKER_USERNAME_SECRET_NAME: The secret name corresponding to your Docker username.
   • DOCKER_USERNAME_SECRET_VERSION: The secret version of your Docker username.
   • DOCKER_PASSWORD_SECRET_NAME: The secret name corresponding to your Docker password.
   • DOCKER_PASSWORD_SECRET_VERSION: The secret version of your Docker password.
   • REPOSITORY: The name of your Docker repository from where you're pulling the image.
   • TAG: The tag name of your image.

3. Use the build config file to manually start a build or to automate builds using triggers.

Pushing images to Docker Hub

To push public and private images to Docker Hub:

1. Make sure you've stored your Docker credentials in Secret Manager and granted permissions for Cloud Build to access the secret.

2. In the build config file:

   • After all the build steps, add an availableSecrets field specifying the secret version and the env variable for the Docker username and password.
   • In the build step where you want to specify the username and password:
     • Add an entrypoint field pointing to bash to use the bash tool in the build step. This is required to refer to the environment variable for the secret.
     • Add a secretEnv field specifying the environment variable for username and password.
     • In the args field, add a -c flag as the first argument. Any string you pass after -c is treated as a command. For more information on running bash commands with -c, see the bash documentation.
     • When specifying the secret in the args field, specify it using the environment variable prefixed with $$.

   The following example build config file shows how to login to Docker, build an image with source code stored locally, and then push the image to Docker repository.

   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 build -t $$USERNAME/REPOSITORY:TAG .']
      secretEnv: ['USERNAME']
    - name: 'gcr.io/cloud-builders/docker'
      entrypoint: 'bash'
      args: ['-c', 'docker push $$USERNAME/REPOSITORY:TAG']
      secretEnv: ['USERNAME']
    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"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker build -t $$USERNAME/REPOSITORY:TAG ."
        ],
        "secretEnv": [
         "USERNAME"
       ]
     },
     {
       "name": "gcr.io/cloud-builders/docker",
       "entrypoint": "bash",
       "args": [
         "-c",
         "docker push $$USERNAME/REPOSITORY:TAG"
        ],
        "secretEnv": [
         "USERNAME"
       ]
     }
     ],
     "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.
   • DOCKER_USERNAME_SECRET_VERSION: Die Secret-Version Ihres Docker-Nutzernamens.
   • DOCKER_PASSWORD_SECRET_NAME: Der Secret-Name, der Ihrem Docker-Passwort entspricht.
   • DOCKER_PASSWORD_SECRET_VERSION: Die Secret-Version Ihres Docker-Passworts.
   • REPOSITORY: Der Name des Docker-Repositories, in das das Image übertragen wird.
   • TAG: Der Tag-Name Ihres Images.

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

Mit Docker-Clientversionen arbeiten

Der unterstützte Docker-Builder für Cloud Build, gcr.io/cloud-builders/docker, verwendet Docker 20.10.14. Wenn Sie bei dieser Version beim Hochladen eines Images an Docker kein Tag angeben, überträgt Docker nur das Image mit dem Tag latest per Push. Wenn das Tag latest nicht vorhanden ist, schlägt der Push fehl.

Wenn Sie ein Image mit einem bestimmten Tag an Docker hochladen möchten, geben Sie das Tag im Build-Schritt docker push an. Im folgenden Beispiel wird ein Image mit dem Tag prod übertragen:

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push", 
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

Wenn Sie alle Tags eines Images in Docker übertragen möchten, fügen Sie das Flag -a der Liste der Argumente im Build-Schritt docker push hinzu:

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker'
  args: ['docker', 'push', '-a', '$$USERNAME/myrepo']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker",
    "args": [
      "docker",
      "push",
      "-a",
      "$$USERNAME/myrepo"
      ],
  }
  ...
}

Sie können den Docker-Client 19.03.9 verwenden, indem Sie die Version im Docker-Builder taggen:

YAML

steps:
...
- name: 'gcr.io/cloud-builders/docker:19.03.9'
  args: ['docker', 'push', '$$USERNAME/myrepo:prod']
...

JSON

{
  ...
  {
    "name": "gcr.io/cloud-builders/docker:19.03.9",
    "args": [
      "docker",
      "push",
      "$$USERNAME/myrepo:prod"
      ],
  }
  ...
}

Nächste Schritte

• Einfache Build-Konfigurationsdatei schreiben
• Builds manuell starten und Builds mit Build-Triggern automatisieren