Interazione con le immagini Docker Hub

Puoi utilizzare le immagini container di Docker Hub per eseguire le tue attività in Cloud Build. Inoltre, se la build produce immagini, puoi eseguirne il push su Docker Hub. Questa pagina descrive come scrivere file di configurazione della build per eseguire il push e il pull delle immagini di Docker Hub. Per una panoramica di tutti i campi disponibili in un file di configurazione della build, consulta la sezione Panoramica della configurazione della build.

Eseguire il pull delle immagini pubbliche da Docker Hub

Puoi eseguire il pull delle immagini Docker ufficiali, delle immagini con certificazione Docker e delle immagini personalizzate archiviate in Docker Hub nel passaggio di build specificando il nome dell'immagine nel campo name. Cloud Build eseguirà prima il pull dell'immagine specificata da Docker Hub e poi la utilizzerà per eseguire il passaggio di build.

Nota: quando esegui il pull di un'immagine container pubblica da Docker Hub da utilizzare nel file di configurazione della build, Cloud Build controlla automaticamente il proxy di memorizzazione nella cache mirror.gcr.io per una copia memorizzata nella cache dell'immagine container. Se non è disponibile una copia memorizzata nella cache, Cloud Build esegue il pull dell'immagine richiesta da Docker Hub e il proxy di memorizzazione nella cache potrebbe memorizzare l'immagine nella cache per un utilizzo futuro. Per ulteriori informazioni, consulta la sezione Eseguire il pull delle immagini Docker Hub memorizzate nella cache.

Nell'esempio riportato di seguito, Cloud Build esegue il pull dell'immagine Docker per maven per eseguire il comando mvn specificato in args:

YAML

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

JSON

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

Archiviare le credenziali Docker in Secret Manager

Per eseguire il pull delle immagini private e il push delle immagini pubbliche e private su Docker Hub, Cloud Build dovrà eseguire l'autenticazione a Docker con le tue credenziali. Per includere le credenziali Docker nelle build, devi prima archiviarle in Secret Manager e poi concedere l'autorizzazione a Cloud Build ad accedere al secret da Secret Manager.

Per archiviare le credenziali Docker in Secret Manager:

1. Vai alla pagina Secret Manager nella Google Cloud console:

   Vai alla pagina Secret Manager

2. Nella pagina Secret Manager, fai clic su Crea secret.

3. Nella pagina Crea secret, in Nome, inserisci docker-username.

4. Nel campo Valore secret, inserisci il tuo nome utente Docker.

5. Lascia invariata la sezione Regioni.

6. Fai clic sul pulsante Crea secret.

Ripeti i passaggi precedenti per archiviare la password Docker in Secret Manager.

Per concedere il ruolo IAM Secret Manager Secret Accessor al secret al account di servizio che utilizzi per la build:

1. Apri la pagina Secret Manager nella Google Cloud console:

   Vai alla pagina Secret Manager

2. Seleziona la casella di controllo del secret corrispondente al tuo nome utente e alla tua password Docker.

3. Se non è già aperto, fai clic su Mostra riquadro informazioni per aprire il riquadro.

4. Nel riquadro, in Autorizzazioni, fai clic su Aggiungi entità.

5. Nel campo Nuove entità, inserisci l'indirizzo email del tuo account di servizio.

6. Nella casella a discesa Seleziona un ruolo, seleziona il ruolo Secret Manager Secret Accessor.

7. Fai clic su Salva.

Eseguire il pull delle immagini private da Docker Hub

Per eseguire il pull delle immagini private da Docker Hub:

1. Assicurati di aver archiviato le credenziali Docker in Secret Manager e di aver concesso a Cloud Build le autorizzazioni per accedere al secret.

2. Nel file di configurazione della build:

   • Dopo tutti i steps di build, aggiungi un campo availableSecrets che specifichi la versione del secret e la variabile di ambiente per il nome utente e la password Docker.
   • Nel passaggio di build in cui vuoi specificare il nome utente e la password:
     • Aggiungi un campo entrypoint che rimandi a bash per utilizzare lo strumento bash nel 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 il nome utente e la password.
     • Nel campo args, aggiungi un flag -c come primo argomento. Qualsiasi stringa passata dopo -c viene trattata come un comando. Per ulteriori informazioni sull'esecuzione dei comandi bash con -c, consulta la documentazione di bash.
     • Quando specifichi il secret nel campo args, fallo utilizzando la variabile di ambiente con il prefisso $$.

   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'
   
    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"
        }]
     }
   }
   

   Sostituisci i valori dei segnaposto nei comandi precedenti con quanto segue:

   • PROJECT_ID: l'ID del Google Cloud progetto in cui hai archiviato i secret.
   • DOCKER_USERNAME_SECRET_NAME: il nome del secret corrispondente al tuo nome utente Docker.
   • DOCKER_USERNAME_SECRET_VERSION: la versione del secret del tuo nome utente Docker.
   • DOCKER_PASSWORD_SECRET_NAME: il nome del secret corrispondente alla tua password Docker.
   • DOCKER_PASSWORD_SECRET_VERSION: la versione del secret della tua password Docker.
   • REPOSITORY: il nome del repository Docker in cui stai eseguendo il push dell'immagine.
   • TAG: il nome del tag dell'immagine.

3. Utilizza il file di configurazione della build per avviare manualmente una build o per automatizzare le build utilizzando i trigger.

Utilizzare le versioni del client Docker

Il builder Docker supportato per Cloud Build, gcr.io/cloud-builders/docker, utilizza Docker 20.10.14. Con questa versione, se non specifichi un tag quando esegui il push di un'immagine su Docker, Docker esegue il push solo dell'immagine con il tag latest. Se il tag latest non esiste, il push non riesce.

Per eseguire il push di un'immagine con un tag specifico su Docker, specifica il tag nel passaggio di build docker push. L'esempio seguente esegue il push di un'immagine con il tag prod:

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"
      ],
  }
  ...
}

Per eseguire il push di tutti i tag di un'immagine su Docker, aggiungi il flag -a all'elenco degli argomenti nel passaggio di build docker push:

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"
      ],
  }
  ...
}

Puoi utilizzare il client Docker 19.03.9 aggiungendo il tag della versione nel builder Docker:

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"
      ],
  }
  ...
}

Passaggi successivi

• Scopri come scrivere un file di configurazione di compilazione di base.
• Scopri come eseguire le build manualmente o automatizzarle utilizzando i trigger di build.