Transférer et extraire des images

Cette page explique comment transférer et extraire des images de conteneurs avec Docker. Il fournit également des informations sur l'extraction d'images avec l'outil crictl si vous tentez de résoudre des problèmes dans Google Kubernetes Engine.

Pour en savoir plus sur le déploiement dans des environnements d'exécution Google Cloud, consultez la page Déployer sur 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 access 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 dont vous avez besoin pour transférer et extraire des images, demandez à votre administrateur de vous attribuer les rôles IAM suivants dans le dépôt:

• Extraire des images : Lecteur Artifact Registry (roles/artifactregistry.reader)
• Taguez et transférez des images : Artifact Registry Writer (roles/artifactregistry.writer)

Pour en savoir plus sur l'attribution de rôles, consultez la section Gérer les accès.

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

Authentification auprès d'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 des éléments dont vous aurez besoin pour vous authentifier. Pour obtenir des instructions détaillées, consultez la page Configurer l'authentification pour Docker.

Utiliser un assistant d'identification

Pour l'assistant d'identification de la CLI gcloud ou l'assistant d'identification autonome, les hôtes Artifact Registry que vous utilisez doivent se trouver 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'il existe un grand nombre de registres configurés. Pour réduire le nombre de registres dans le fichier de configuration, vous devez ajouter les hôtes dont vous avez besoin au fichier.

Pour vérifier quels hôtes sont configurés, exécutez la commande suivante afin d'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 Artifact Registry configurés avec Docker. Les noms d'hôte se terminent par -docker.pkg.dev. L'exemple suivant montre quelques hôtes configurés pour l'assistant d'identification de la 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 ajouter l'hôte. Par exemple, la commande suivante ajoute us-east1-docker.pkg.dev.

• Assistant d'identification de la gcloud CLI:

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

• Assistant d'identification autonome

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

Un jeton d'accès

Pour l'authentification par jeton d'accès, vous devez générer un jeton et l'utiliser comme mot de passe à l'aide de la commande docker login. Les jetons sont valides pendant 60 minutes. Vous devez donc vous authentifier juste avant de taguer, transférer ou extraire des images.

L'exemple suivant génère un jeton d'accès à l'aide de l'emprunt d'identité du compte de service, puis l'authentification auprès d'Artifact Registry. Vous devez disposer des autorisations dans le 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 ne disposez pas des autorisations nécessaires pour emprunter l'identité d'un compte de service, vous pouvez l'activer dans votre session de 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 devez l'utiliser comme mot de passe à l'aide de 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-east1-docker.pkg.dev.

Linux

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

Windows

docker login -u _json_key_base64 --password-stdin https://us-east1-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 du dépôt:standard

Pour transférer une image locale vers un dépôt Docker standard, vous devez lui ajouter un tag correspondant au nom du dépôt, puis transférer l'image.

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'images, les tags et l'immuabilité des tags, consultez Versions d'images de conteneur.

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

Délai d'importation

Si vous vous authentifiez auprès d'Artifact Registry à l'aide d'un jeton d'accès, celui-ci n'est valide que pendant 60 minutes. Si vous pensez que le temps d'importation dépassera 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 du nom complet d'une image 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, par exemple us-east1 ou us.

   • 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.

   • REPOSITORY est le nom du dépôt où l'image est stockée.

   • IMAGE correspond au nom de l'image. Il 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-east1
   • 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-east1-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 du nom de l'image sur votre ordinateur local.

   Pour en savoir plus sur le format des noms d'image et sur la gestion des projets à l'échelle du domaine, consultez Noms des dépôts et des images.

3. Ajoutez à l'image locale le tag correspondant au 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 latest par défaut.

   Si le paramètre des tags d'image immuables est activé (Aperçu), 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-east1-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-east1-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 le client Docker, vérifiez que le nom d'hôte cible se trouve dans le 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 console Google Cloud pour afficher l'image.

• 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 résultat suivant montre des condensés d'images tronqués, mais la commande renvoie toujours le condensé complet des images.

   IMAGE                                                 DIGEST         CREATE_TIME          UPDATE_TIME
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:85f...  2019-04-10T15:08:45  2019-04-10T15:08:45
    us-east1-docker.pkg.dev/my-project/my-repo/my-image  sha256:238...  2019-04-10T17:23:53  2019-04-10T17:23:53
    us-east1-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 le client Docker, vérifiez que le nom d'hôte cible se trouve dans le 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, par exemple us-east1 ou us.
   • PROJECT 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.
   • REPOSITORY est le nom du dépôt où l'image est stockée.
   • IMAGE est le 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 afficher 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-east1
   • 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-east1-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, celui-ci télécharge et met en cache l'image à partir de la source en amont s'il n'existe pas de copie mise en cache.

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 ayant la 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 l'image demandée n'est pas disponible dans main-repo, Artifact Registry recherche ensuite ces dépôts. Étant donné qu'ils ont tous les deux la même valeur de priorité, Artifact Registry peut choisir de diffuser une image à partir de l'un ou l'autre des dépôts si la version est disponible dans les deux.

test-repo a la priorité la plus faible et diffuse un artefact stocké si aucun des autres dépôts en amont ne l'a.

Extraire des images avec crictl

crictl est un outil de ligne de commande utile qui permet aux développeurs d'environnements d'exécution CRI de 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 containerd, 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 l'ajout de tags à des images, ne sont pas disponibles.

Pour extraire une image d'Artifact Registry:

1. Dans Google Cloud Console, 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

Étapes suivantes

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