Interagir avec les images de Docker Hub

Vous pouvez exécuter vos tâches dans Cloud Build à l'aide d'images de conteneur provenant de Docker Hub. En outre, si votre compilation génère des images, vous pouvez les transférer vers Docker Hub. Cette page explique comment créer des fichiers de configuration de compilation pour transférer et extraire des images Docker Hub. Pour obtenir une présentation de tous les champs disponibles dans un fichier de configuration de compilation, consultez la section Présentation de la configuration des compilations.

Extraire des images publiques de Docker Hub

Vous pouvez extraire des images Docker officielles, des images Docker certifiées et des images personnalisées stockées dans Docker Hub lors de l'étape de compilation en spécifiant le nom de l'image dans le champ name. Cloud Build extrait d'abord l'image spécifiée à partir de Docker Hub, puis s'en sert pour exécuter l'étape de compilation.

Remarque :Lorsque vous extrayez une image de conteneur publique de Docker Hub pour l'utiliser dans votre de compilation, Cloud Build vérifie automatiquement le proxy de mise en cache mirror.gcr.io pour obtenir une copie mise en cache de l'image de conteneur. Si une copie mise en cache n'est pas disponible, Cloud Build extrait l'image demandée de Docker Hub, qui pourra être mise en cache par le proxy pour une utilisation ultérieure. Pour plus d'informations, consultez la section Extraire des images mises en cache.

Dans l'exemple ci-dessous, Cloud Build extrait l'image Docker pour maven pour exécuter la commande mvn spécifiée dans args:

YAML

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

JSON

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

Stocker des identifiants Docker dans Secret Manager

Pour extraire des images privées et transférer des images publiques et privées vers Docker Hub, Cloud Build doit s'authentifier auprès de Docker avec vos identifiants. Pour inclure des identifiants Docker dans vos compilations, vous devez d'abord stocker vos identifiants dans Secret Manager, puis autoriser Cloud Build à accéder au secret à partir de Secret Manager.

Pour stocker les identifiants Docker dans Secret Manager :

1. Accédez à la page Secret Manager dans la console Google Cloud :

   Accéder à la page Secret Manager

2. Sur la page Secret Manager, cliquez sur Créer un secret.

3. Sur la page Créer un secret, sous Nom, saisissez docker-username.

4. Dans le champ Valeur du secret, saisissez votre nom d'utilisateur Docker.

5. Ne modifiez pas la section Régions.

6. Cliquez sur le bouton Créer un secret.

Répétez les étapes ci-dessus pour stocker votre mot de passe Docker dans Secret Manager.

Pour accorder le rôle IAM Accesseur de secrets Secret Manager pour le secret au compte de service que vous utilisez pour la compilation :

1. Ouvrez la page Secret Manager dans la console Google Cloud :

   Accéder à la page Secret Manager

2. Cochez la case du secret correspondant à votre nom d'utilisateur et à votre mot de passe Docker.

3. S'il n'est pas déjà ouvert, cliquez sur Afficher le panneau d'informations pour ouvrir celui-ci.

4. Dans le panneau, sous Autorisations, cliquez sur Ajouter un compte principal.

5. Dans le champ Nouveaux comptes principaux, saisissez l'adresse e-mail de votre compte de service.

6. Dans la boîte déroulante Sélectionner un rôle, sélectionnez le rôle Accesseur de secrets Secret Manager.

7. Cliquez sur Enregistrer.

Extraire des images privées de Docker Hub

Pour extraire des images privées de Docker Hub, procédez comme suit :

1. Assurez-vous d'avoir stocké vos identifiants Docker dans Secret Manager et accordé les autorisations permettant à Cloud Build d'accéder au secret.

2. Dans le fichier de configuration de compilation :

   • Après toutes les étapes steps de la compilation, ajoutez un champ availableSecrets spécifiant la version du secret et la variable d'environnement correspondant au nom d'utilisateur et au mot de passe Docker.
   • À l'étape de compilation où vous souhaitez spécifier le nom d'utilisateur et le mot de passe :
     • Ajoutez un champ entrypoint pointant vers bash pour utiliser l'outil bash dans l'étape de compilation. Cette valeur est obligatoire pour faire référence à la variable d'environnement du secret.
     • Ajoutez un champ secretEnv spécifiant la variable d'environnement correspondant au nom d'utilisateur et au mot de passe.
     • Dans le champ args, ajoutez une option -c en tant que premier argument. Toutes les chaînes que vous transmettez après -c sont traitées comme des commandes. Pour en savoir plus sur l'exécution des commandes bash avec -c, consultez la documentation bash.
     • Lorsque vous spécifiez le secret dans le champ args, indiquez-le à l'aide de la méthode variable d'environnement précédée de $$.

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

   Remplacez les valeurs d'espace réservé dans les commandes ci-dessus par les éléments suivants :

   • PROJECT_ID: ID du projet Google Cloud où vous avez stocké vos secrets.
   • DOCKER_USERNAME_SECRET_NAME : nom du secret correspondant à votre nom d'utilisateur Docker.
   • DOCKER_USERNAME_SECRET_VERSION : version du secret de votre nom d'utilisateur Docker.
   • DOCKER_PASSWORD_SECRET_NAME : nom du secret correspondant à votre mot de passe Docker.
   • DOCKER_PASSWORD_SECRET_VERSION : version du secret de votre mot de passe Docker.
   • REPOSITORY : nom du dépôt Docker dans lequel vous transférez l'image.
   • TAG : nom du tag de votre image.

3. Vous pouvez utiliser le fichier de configuration de compilation pour démarrer manuellement une compilation ou pour automatiser les compilations à l'aide de déclencheurs.

Utiliser les versions du client Docker

Le compilateur Docker compatible avec Cloud Build, gcr.io/cloud-builders/docker, utilise Docker 20.10.14. Avec cette version, si vous ne spécifiez pas de tag lorsque envoyant une image à Docker, Docker ne transfère que l'image portant le tag latest. Si la balise latest n'existe pas, l'envoi échoue.

Pour transférer une image avec un tag spécifique vers Docker, spécifiez le tag dans le fichier docker push étape de compilation. L'exemple suivant transfère une image avec le 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"
      ],
  }
  ...
}

Pour transférer tous les tags d'une image vers Docker, ajoutez l'option -a à la liste des arguments de la section Étape de compilation 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"
      ],
  }
  ...
}

Vous pouvez utiliser le client Docker 19.03.9 en ajoutant un tag de version dans le compilateur 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"
      ],
  }
  ...
}

Étape suivante

• Découvrez comment rédiger un fichier de configuration de compilation de base.
• Découvrez comment exécuter des compilations manuellement ou de manière automatisée à l'aide de déclencheurs de compilation.