Transférer et extraire des images

Cette page explique comment stocker et extraire des images de conteneur avec Docker. Il fournit également des informations sur l'extraction d'images avec l'outil crictl si vous rencontrez des problèmes dans Google Kubernetes Engine.

Pour en savoir plus sur le déploiement dans les environnements d'exécution Google Cloud , consultez Déploiement dans Google Cloud.

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

1. Si le dépôt cible n'existe pas, créez un dépôt.
2. Vous devez au moins disposer d'un accès Rédacteur à Artifact Registry au dépôt.
3. Installez Docker si ce n'est pas encore fait.

Rôles requis

Pour obtenir les autorisations nécessaires pour pousser et extraire des images, demandez à votre administrateur de vous accorder les rôles IAM suivants sur le dépôt:

• Extraire des images : Lecteur Artifact Registry (roles/artifactregistry.reader)
• Taguer et transférer des images : Rédacteur Artifact Registry (roles/artifactregistry.writer)

Pour en savoir plus sur l'attribution de rôles, consultez la page Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

S'authentifier dans un dépôt

Vous devez vous authentifier auprès des dépôts chaque fois que vous utilisez Docker ou un autre client tiers avec un dépôt Docker. Cette section fournit un résumé rapide de ce dont vous avez besoin pour vous authentifier. Pour obtenir des instructions détaillées, consultez Configurer l'authentification pour Docker.

Utiliser un assistant d'identification

Pour l'assistant d'identification de la gcloud CLI ou l'assistant d'identification autonome, les hôtes Artifact Registry que vous utilisez doivent figurer dans votre fichier de configuration Docker.

Artifact Registry n'ajoute pas automatiquement tous les hôtes de registre au fichier de configuration Docker. Le temps de réponse de Docker est considérablement plus lent lorsqu'un grand nombre de registres sont configurés. Pour réduire le nombre de registres dans le fichier de configuration, ajoutez les hôtes dont vous avez besoin au fichier.

Pour vérifier les hôtes configurés, exécutez la commande suivante pour afficher le contenu du fichier de configuration:

• Linux : cat ~/.docker/config.json
• Windows : cat %USERPROFILE%\.docker\config.json

La section credHelpers liste les hôtes Docker Artifact Registry configurés. Les noms d'hôte se terminent par -docker.pkg.dev. L'exemple suivant montre certains hôtes configurés pour l'assistant d'identifiants de gcloud CLI.

"credHelpers": {
  "asia.gcr.io": "gcloud",
  "eu.gcr.io": "gcloud",
  "gcr.io": "gcloud",
  "marketplace.gcr.io": "gcloud",
  "northamerica-northeast1-docker.pkg.dev": "gcloud",
  "us-central1-docker.pkg.dev": "gcloud",
  "us-east1-docker.pkg.dev": "gcloud",
  "us.gcr.io": "gcloud"
}

Si un hôte que vous souhaitez utiliser ne figure pas dans la liste, exécutez à nouveau l'assistant d'identification pour l'ajouter. Par exemple, la commande suivante ajoute us-west1-docker.pkg.dev.

• Assistant d'identification gcloud CLI:

  gcloud auth configure-docker us-west1-docker.pkg.dev
  

• Assistant d'identification autonome

  docker-credential-gcr configure-docker us-west1-docker.pkg.dev
  

Un jeton d'accès

Pour l'authentification par jeton d'accès, vous générez un jeton et l'utilisez comme mot de passe avec la commande docker login. Les jetons sont valides pendant 60 minutes. Vous devez donc vous authentifier peu de temps avant d'ajouter un tag, de transférer ou d'extraire des images.

L'exemple suivant génère un jeton d'accès à l'aide de l'emprunt d'identité d'un compte de service, puis s'authentifie auprès d'Artifact Registry. Vous devez disposer des autorisations du rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) pour générer un jeton de cette manière.

Linux

gcloud auth print-access-token \
  --impersonate-service-account  ACCOUNT | docker login \
  -u oauth2accesstoken \
  --password-stdin https://LOCATION-docker.pkg.dev

Windows

gcloud auth print-access-token \
--impersonate-service-account  ACCOUNT

ya29.8QEQIfY_...

docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
https://LOCATION-docker.pkg.dev

Si vous n'êtes pas autorisé à usurper l'identité d'un compte de service, vous pouvez activer le compte de service dans votre session gcloud CLI, puis obtenir un jeton. Pour en savoir plus, consultez les instructions de configuration de l'authentification par jeton d'accès.

Utiliser une clé de compte de service

Pour une clé de compte de service, vous utilisez la clé comme mot de passe avec la commande docker login.

Par exemple, la commande suivante utilise la clé de compte de service encodée en base64 dans le fichier key.json pour s'authentifier auprès de us-west1-docker.pkg.dev.

Linux

cat key.json | docker login -u _json_key_base64 --password-stdin \
https://us-west1-docker.pkg.dev

Windows

docker login -u _json_key_base64 --password-stdin https://us-west1-docker.pkg.dev < key.json

Pour en savoir plus, consultez les instructions de configuration de l'authentification par clé de compte de service.

Transférer une image

Modes de dépôt: standard

Pour transférer une image locale dans un dépôt Docker standard, ajoutez-lui un tag correspondant au nom du dépôt avant de la transférer.

Si l'immuabilité des tags est activée dans votre dépôt Docker Artifact Registry, un tag doit toujours faire référence au même condensé d'image dans le dépôt. Vous ne pouvez pas utiliser le tag sur une autre version de la même image que vous transférez vers le dépôt. Pour en savoir plus sur les condensés d'image, les tags et l'immuabilité des tags, consultez la section Versions d'images de conteneur.

Pour les images volumineuses, les limites suivantes s'appliquent:

Heure d'importation

Si vous vous authentifiez sur Artifact Registry avec un jeton d'accès, celui-ci n'est valable que 60 minutes. Si vous estimez que le délai d'importation peut dépasser 60 minutes, utilisez une autre méthode d'authentification.

Taille d'image

La taille maximale de l'artefact est de 5 To.

Artifact 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 Artifact Registry.

Ajouter des tags à l'image locale

1. Assurez-vous d'être authentifié auprès du dépôt.

2. Déterminez le nom de l'image. Le format d'un nom d'image complet est le suivant:

   LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   Remplacez les valeurs suivantes :

   • LOCATION est l'emplacement régional ou multirégional du dépôt dans lequel l'image est stockée.
   • PROJECT-ID est l'ID de projet dans la console Google Cloud . Si l'ID de votre projet contient un signe deux-points (:), consultez la section Projets à l'échelle du domaine.
   • REPOSITORY est le nom du dépôt où l'image est stockée.
   • IMAGE correspond au nom de l'image. Ce nom peut être différent du nom local de l'image.

   Prenons l'exemple d'une image présentant les caractéristiques suivantes :

   • Emplacement du dépôt : us-west1
   • Nom du dépôt : my-repo
   • ID du projet : my-project
   • Nom de l'image locale : my-image
   • Nom de l'image cible : test-image

   Le nom de l'image pour cet exemple est :

   us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   Remarque :Le nom de l'image que vous allez stocker dans le dépôt peut être différent de celui de l'image sur votre ordinateur local.

   Pour en savoir plus sur le format de nom d'image, y compris la gestion des projets de portée de domaine, consultez la section Noms de dépôt et d'image.

3. Ajoutez un tag à l'image locale avec le nom du dépôt.

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   Remplacez SOURCE-IMAGE par le nom ou l'ID de l'image locale et TAG par le tag. Si vous ne spécifiez pas de tag, Docker applique le tag par défaut latest.

   Si le paramètre des tags d'image immuables est activé, les tags doivent être uniques pour chaque version d'image, y compris le tag latest. Vous ne pouvez pas transférer une image vers le dépôt si le tag est déjà utilisé par une autre version de la même image dans le dépôt. Pour vérifier si le paramètre est activé pour le dépôt, exécutez la commande suivante:

   gcloud artifacts repositories describe REPOSITORY \
       --project=PROJECT-ID \
       --location=LOCATION
   

   Pour l'image d'exemple de l'étape précédente, vous devez utiliser la commande suivante si l'image locale my-image se trouve dans le répertoire actuel :

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image
   

   Si vous souhaitez appliquer un tag spécifique, utilisez la commande suivante :

   docker tag SOURCE-IMAGE LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   Pour utiliser le tag staging avec l'image de l'exemple, vous devez ajouter :staging à la commande :

   docker tag my-image us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Transférer l'image taguée vers Artifact Registry

Remarque : Artifact Registry n'est pas compatible avec les importations fragmentées de Docker. Certains outils de gestion d'images de conteneurs permettent d'importer des images de conteneurs volumineuses par le biais d'importations fragmentées ou d'une seule importation monolithique. Vous devez utiliser des importations monolithiques lorsque vous transférez des images de conteneurs vers Artifact Registry.

1. Assurez-vous d'être authentifié auprès du dépôt.

   Si vous avez utilisé gcloud auth configure-docker ou docker-credential-gcr configure-docker pour configurer votre client Docker, vérifiez que le nom d'hôte cible figure dans votre fichier de configuration Docker.

2. Transférez l'image taguée à l'aide de la commande suivante :

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE
   

   Cette commande transfère l'image qui possède le tag latest. Si vous souhaitez transférer une image avec un autre tag, exécutez la commande suivante :

   docker push LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

Lorsque vous transférez une image, elle est stockée dans le dépôt spécifié.

Après avoir transféré votre image, vous pouvez effectuer les opérations suivantes :

• Accédez à la consoleGoogle Cloud

• Exécutez la commande gcloud pour afficher les tags de l'image et le condensé généré automatiquement :

  gcloud artifacts docker images list \
  LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE [--include-tags]
  

  L'exemple de sortie suivant affiche des récapitulatifs d'image tronqués, mais la commande renvoie toujours le récapitulatif d'image complet.

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-west1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:46  2019-04-10T15:08:46
  

Extraire des images avec Docker

Modes de dépôt: standard, distant, virtuel

1. Assurez-vous d'être authentifié auprès du dépôt.

   Si vous avez utilisé gcloud auth configure-docker ou docker-credential-gcr configure-docker pour configurer votre client Docker, vérifiez que le nom d'hôte cible figure dans votre fichier de configuration Docker.

2. Pour extraire des images d'un dépôt, exécutez la commande suivante :

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG
   

   ou

   docker pull LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST
   

   Remplacez les valeurs suivantes :

   • LOCATION est l'emplacement régional ou multirégional du dépôt dans lequel l'image est stockée.
   • PROJECT est l'ID de projet dans la console Google Cloud . Si l'ID de votre projet contient un signe deux-points (:), consultez la section Projets à l'échelle du domaine.
   • PROJECT est l'ID de projet dans la console Google Cloud .
   • REPOSITORY est le nom du dépôt où l'image est stockée.
   • IMAGE correspond au nom de l'image dans le dépôt.
   • TAG est le tag de la version de l'image que vous souhaitez extraire.
   • IMAGE-DIGEST est la valeur de hachage sha256 du contenu de l'image. Chaque version d'une image possède un condensé d'image unique. Dans la console Google Cloud , cliquez sur une image spécifique pour voir ses métadonnées. Le condensé y apparaît sous l'intitulé Condensé de l'image.

   Prenons l'exemple d'une image présentant les caractéristiques suivantes :

   • Emplacement du dépôt : us-west1
   • Nom du dépôt : my-repo
   • ID du projet : my-project
   • Nom de l'image : test-image
   • Tag : staging

   L'image permettant d'extraire l'image est la suivante :

   docker pull us-west1-docker.pkg.dev/my-project/my-repo/test-image:staging
   

Docker télécharge l'image spécifiée.

Si vous demandez une image à partir d'un dépôt distant, le dépôt distant télécharge et met en cache l'image à partir de la source en amont si aucune copie mise en cache n'existe.

Si vous demandez une image à partir d'un dépôt virtuel, Artifact Registry recherche l'image demandée dans les dépôts en amont. Si vous demandez une version disponible dans plusieurs dépôts en amont, Artifact Registry choisit un dépôt en amont à utiliser en fonction des paramètres de priorité configurés pour le dépôt virtuel.

Prenons l'exemple d'un dépôt virtuel avec les paramètres de priorité suivants pour les dépôts en amont:

• main-repo: priorité définie sur 100
• secondary-repo1: priorité définie sur 80.
• secondary-repo2: priorité définie sur 80.
• test-repo: priorité définie sur 20.

main-repo a la valeur de priorité la plus élevée. Le dépôt virtuel le recherche donc toujours en premier.

La priorité de secondary-repo1 et de secondary-repo2 est définie sur 80. Si une image demandée n'est pas disponible dans main-repo, Artifact Registry recherche ensuite dans ces dépôts. Étant donné qu'ils ont tous deux la même valeur de priorité, Artifact Registry peut choisir de diffuser une image de l'un ou l'autre des dépôts si la version est disponible dans les deux.

test-repo a la valeur de priorité la plus basse et servira un artefact stocké si aucun des autres dépôts en amont ne l'a pas.

Extraire des images avec crictl

crictl est un outil de ligne de commande utile aux développeurs d'environnement d'exécution CRI pour déboguer leur environnement d'exécution sans avoir à configurer les composants Kubernetes. Si vos nœuds Google Kubernetes Engine utilisent un environnement d'exécution containerisé, vous pouvez extraire des images d'Artifact Registry à l'aide de crictl.

Étant donné que crictl est principalement un outil de dépannage, certaines commandes Docker telles que le transfert ou le taggage d'images ne sont pas disponibles.

Pour extraire une image d'Artifact Registry:

1. Dans la console Google Cloud , accédez à la page Instances de VM.

   Accéder à la page "Instances de VM"

2. Connectez-vous en SSH au nœud que vous dépannez.

3. Obtenez un jeton d'accès pour l'authentification auprès du dépôt.

   curl -s "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" -H "Metadata-Flavor: Google"

4. Extraire l'image à l'aide de crictl pull --creds et de la valeur access_token

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE:TAG

   ou

   crictl pull --creds "oauth2accesstoken:ACCESS_TOKEN" LOCATION-docker.pkg.dev/PROJECT-ID/REPOSITORY/IMAGE@IMAGE-DIGEST

   La sortie ressemble à ceci :

   Image is up to date for sha256:0f25067aa9c180176967b4b50ed49eed096d43fa8c17be9a5fa9bff05933bee5

Étape suivante

• Découvrez comment gérer les tags et supprimer des images.
• Si vous souhaitez exécuter des conteneurs sur Compute Engine, familiarisez-vous avec les conteneurs sur Compute Engine.
• Utiliser crictl pour déboguer des nœuds Kubernetes
• Apprendre à utiliser crictl pour extraire des images à partir de dépôts Artifact Registry privés
• En savoir plus sur la configuration des registres d'images crictl