Transférer et extraire des images

Le transfert (importation) et l'extraction (téléchargement) d'images sont deux des tâches les plus courantes de Container Registry. Ce document explique comment transférer et extraire des images avec Docker.

Si vous utilisez Cloud Build, consultez la documentation Cloud Build pour en savoir plus sur la création et le transfert de conteneurs vers Container Registry.

Pour découvrir comment répertorier des images, leur ajouter des tags et les supprimer, consultez la page Gérer les images.

Avant de commencer

Vous devez disposer des éléments suivants :

  1. Vous avez activé Container Registry dans votre projet.

  2. Vous avez installé et configuré Docker.

Ajouter un registre

Vous pouvez ajouter les registres Container Registry suivants à un projet:

Nom d'hôte Emplacement de stockage
gcr.io Stocke les images dans des centres de données aux États-Unis
asia.gcr.io Stocke les images dans des centres de données en Asie
eu.gcr.io Stocke les images dans des centres de données dans les États membres de l'Union européenne
us.gcr.io Stocke les images dans des centres de données aux États-Unis

Le transfert de la première image vers un nom d'hôte déclenche la création du registre dans un projet et du bucket de stockage Cloud Storage correspondant. Ce transfert initial nécessite des autorisations à l'échelle du projet pour créer des buckets de stockage.

Une fois qu'un hôte de registre existe dans votre projet, vous pouvez configurer des autorisations sur le bucket de stockage pour contrôler l'accès aux images dans le registre.

Pour ajouter un registre et configurer les autorisations:

  1. Vérifiez que vous disposez des autorisations requises. Vous devez disposer du rôle Administrateur de l'espace de stockage (roles/storage.admin), d'un rôle personnalisé ou d'un rôle prédéfini avec les mêmes autorisations.

    Pour savoir comment attribuer le rôle d'administrateur de l'espace de stockage au niveau du projet, consultez la documentation IAM.

  2. Transférez une image initiale vers l'hôte. Par exemple, les commandes suivantes:

    • Extraire l'image busybox de Docker Hub
    • Ajoutez à l'image un tag correspondant à son chemin d'accès cible dans Container Registry, y compris l'hôte de registre gcr.io et l'ID du projet my-project.
    • Transfère l'image vers le registre.
    docker pull busybox
    docker tag busybox gcr.io/my-project/busybox
    docker push gcr.io/my-project/busybox
    

Container Registry ajoute le registre à votre projet, crée un bucket de stockage pour le registre et stocke l'image.

Vous pouvez maintenant configurer le contrôle des accès sur le bucket de stockage du registre pour accorder l'accès au registre à d'autres utilisateurs.

Transférer une image vers un registre

Pour transférer une image locale vers Container Registry à l'aide de Docker ou d'un autre outil tiers, vous devez d'abord lui ajouter un tag correspondant au nom du registre, puis transférer l'image.

Les facteurs suivants peuvent avoir une incidence sur les importations d'images volumineuses:

Délai d'importation
Toute requête envoyée à Container Registry est soumise à un délai avant expiration de deux heures. Si vous vous authentifiez auprès de Container Registry à l'aide d'un jeton d'accès, le jeton expire au bout de 60 minutes. Si vous prévoyez que le temps d'importation dépassera 60 minutes, utilisez une autre méthode d'authentification.
Taille d'image
Container Registry utilise Cloud Storage pour le stockage sous-jacent de chaque registre. Les quotas et limites de Cloud Storage s'appliquent à chaque registre, y compris la taille maximale de 5 To pour un objet dans l'espace de stockage.
Container Registry n'est pas compatible avec les importations fragmentées de Docker. Certains outils permettent d'importer des images volumineuses par le biais d'importations fragmentées ou d'une seule importation monolithique. Vous devez utiliser des importations monolithiques pour transférer des images vers Container Registry.

Autorisations requises

Le transfert d'une image nécessite l'un des rôles Cloud Storage suivants ou un rôle disposant des mêmes autorisations:

Transférer la première image vers un registre de votre projet

Rôle: administrateur de l'espace de stockage (roles/storage.admin) au niveau du projet Google Cloud. Le rôle prédéfini "Propriétaire" inclut ces autorisations.

La première fois que vous transférez une image vers un hôte de registre de votre projet (par exemple, gcr.io), Container Registry crée un bucket de stockage pour le registre. Le rôle "Administrateur de l'espace de stockage" dispose des autorisations nécessaires pour créer le bucket de stockage.

Transférer des images vers un registre existant dans votre projet

Rôle: Rédacteur des anciens buckets Storage (roles/storage.legacyBucketWriter) sur le bucket de stockage du registre.

Ce rôle dispose des autorisations nécessaires pour transférer et extraire des images pour les hôtes de registre existants de votre projet. Par exemple, si votre projet ne contient que le registre gcr.io, un utilisateur doté du rôle "Rédacteur des anciens buckets de l'espace de stockage" peut transférer des images vers gcr.io, mais pas vers asia.gcr.io.

Pour en savoir plus sur l'attribution d'autorisations à un registre, consultez la section Configurer le contrôle des accès.

Ajouter un tag de nom de registre à l'image locale

Pour ajouter un tag à une image:

  1. Vérifiez que vous avez configuré l'authentification dans Container Registry.
  2. Déterminez le nom de l'image dans Container Registry:

    1. Choisissez un nom d'hôte, qui spécifie l'emplacement où les images sont stockées.

      • gcr.io héberge les images dans des centres de données aux États-Unis, mais cet emplacement peut être amené à changer par la suite.
      • us.gcr.io héberge les images dans des centres de données aux États-Unis, dans un bucket de stockage distinct de celui des images hébergées par gcr.io.
      • eu.gcr.io héberge les images dans l'Union européenne.
      • asia.gcr.io héberge les images dans des centres de données en Asie.

      Ces emplacements multirégionaux hébergent les buckets de stockage Cloud Storage. Lorsque vous transférez une image vers un registre avec un nouveau nom d'hôte, Container Registry crée un bucket de stockage dans l'emplacement multirégional spécifié. Ce bucket forme le stockage sous-jacent du registre. Dans un projet, tous les registres portant le même nom d'hôte partagent un bucket de stockage.

      Dans la console, le nom d'hôte des images apparaîtra sous Emplacement.

    2. Choisissez un nom d'image cible, qui peut être différent du nom de l'image sur votre ordinateur local. Par exemple, l'image locale peut s'appeler web-image, mais vous pouvez la stocker dans Container Registry en tant que web-site

    3. Combinez le nom d'hôte, l'ID de votre projet dans la console Google Cloud et le nom de l'image cible:

      HOSTNAME/PROJECT-ID/TARGET-IMAGE
      

      Prenons l'exemple suivant :

      • Nom d'hôte : gcr.io
      • Projet Google Cloud: my-project
      • Nom de l'image cible : web-site

      En combinant le nom d'hôte, le projet et le nom de l'image cible, vous obtenez le chemin d'accès complet de l'image à utiliser pour l'ajout de tags:

      gcr.io/my-project/web-site

      Si l'ID du projet contient le signe deux-points (:), consultez la section Projets à l'échelle du domaine.

  3. Ajoutez à l'image locale un tag correspondant au nom récupéré à l'étape précédente. Si vous souhaitez ajouter un tag à cette version de l'image, indiquez le nom de la balise.

    docker tag SOURCE_IMAGE HOSTNAME/PROJECT-ID/TARGET-IMAGE:TAG
    

    Remplacez les éléments suivants :

    • SOURCE_IMAGE est le nom ou l'ID de l'image locale.
    • HOSTNAME est l'hôte de registre que vous avez choisi à l'étape 2.
    • PROJECT est l'ID du projet Google Cloud.
    • TARGET-IMAGE est le nom de l'image lorsqu'elle est stockée dans Container Registry.
    • TAG est le tag que vous souhaitez associer à cette version de l'image.

    Par exemple, cette commande ajoute le tag v1.5 à l'image locale web-image comme gcr.io/my-project/web-site dans Container Registry

    docker tag web-image gcr.io/my-project/web-site:v1.5
    

    Si vous ne spécifiez pas de tag, Docker ajoute le tag latest par défaut. Étant donné que latest est un tag par défaut, il représente la version d'image la plus récemment taguée avec la balise latest, et pas nécessairement la version la plus récente d'une image.

Docker ajoute à votre image un tag correspondant au nom et au tag d'image que vous avez spécifiés dans la commande.

Transférer l'image avec son tag vers Container Registry

  1. Vérifiez que vous avez configuré l'authentification dans Container Registry.

  2. Transférez l'image taguée dans Container Registry:

    Exécutez la commande suivante pour transférer une image avec un tag spécifique:

    docker push HOSTNAME/PROJECT-ID/IMAGE:TAG
    

    Si vous omettez :TAG, Docker transfère la version de l'image avec le tag latest.

    Par exemple, cette commande transfère l'image gcr.io/my-project/web-site avec le tag v1.5:

    docker push gcr.io/my-project/web-site:v1.5
    

Lorsque vous transférez une image vers un hôte de registre qui n'existe pas encore dans votre projet, Container Registry crée un bucket de stockage pour l'hôte du registre.

Pour afficher l'image que vous avez envoyée:

  • Accédez à la console Google Cloud pour consulter le registre et l'image.

  • Exécutez gcloud container images list-tags pour afficher le tag d'image et le condensé généré automatiquement:

    gcloud container images list-tags HOSTNAME/PROJECT-ID/IMAGE
    

    Le résultat de la commande ressemble à ce qui suit :

    DIGEST        TAGS        TIMESTAMP
    44bde...      test        2017-..-..
    

Extraire des images d'un registre

Pour extraire une image, vous devez disposer du lecteur des objets Storage pour le bucket de stockage du registre ou d'un rôle disposant des mêmes autorisations.

Pour extraire une image de Container Registry, exécutez la commande :

docker pull HOSTNAME/PROJECT-ID/IMAGE:TAG

ou

docker pull HOSTNAME/PROJECT-ID/IMAGE@IMAGE_DIGEST

où :

  • HOSTNAME est répertorié sous Emplacement dans la console. Il s'agit de l'une des quatre options suivantes : gcr.io, us.gcr.io, eu.gcr.io ou asia.gcr.io.
  • PROJECT-ID est l'ID du projet dans la console Google Cloud. Si l'ID du projet contient le signe deux-points (:), consultez la section Projets à l'échelle du domaine.
  • IMAGE est le nom de l'image dans Container Registry.
  • TAG est le tag appliqué à l'image. Dans un registre, les tags sont uniques à une image.
  • IMAGE_DIGEST est la valeur de hachage sha256 du contenu de l'image. Dans la console Google Cloud, cliquez sur une image spécifique pour afficher ses métadonnées. Le condensé y apparaît sous l'intitulé Condensé de l'image.

Pour obtenir la commande d'extraction correspondant à une image spécifique, procédez comme suit :

  1. Cliquez sur le nom d'une image pour accéder au registre spécifique.

  2. Dans le registre, cochez la case à côté de la version de l'image que vous souhaitez extraire.

  3. Cliquez sur AFFICHER LA COMMANDE D'EXTRACTION en haut de la page.

  4. Copiez la commande d'extraction, qui identifie l'image à l'aide du tag ou du condensé.

Étapes suivantes