Modifications pour Docker

Ce document vous présente les différences entre Container Registry et Artifact Registry pour authentifier, transférer et récupérer des images de conteneur avec Docker.

Dans ce guide, les comparaisons portent sur les dépôts Artifact Registry pkg.dev, des dépôts Artifact Registry standards qui sont indépendants de Container Registry et compatibles avec toutes les fonctionnalités d'Artifact Registry.

Si votre administrateur a configuré des dépôts avec prise en charge du domaine gcr.io, les requêtes envoyées aux noms d'hôte gcr.io sont automatiquement redirigées vers un dépôt Artifact Registry correspondant. Pour utiliser un dépôt gcr.io hébergé sur Artifact Registry, vous devez disposer d'un rôle Artifact Registry approprié ou d'un rôle disposant d'autorisations équivalentes.

Pour en savoir plus sur les différences entre Container Registry et Artifact Registry lors de la création avec Cloud Build et du déploiement sur Cloud Run ou Google Kubernetes Engine, consultez la page Modifications pour Cloud Build, Cloud Run et GKE.

Utilisez ces informations pour vous aider à adapter les commandes, la configuration ou la documentation existantes axées sur Container Registry avec Docker.

Avant de commencer

Ce document suppose que vous disposez des éléments suivants:

1. Vous avez activé Artifact Registry dans votre projet.
2. Vous avez installé Docker. Docker est inclus dans Cloud Shell.

Présentation

De manière générale, le workflow d'utilisation de Docker avec Container Registry ou Artifact Registry est le même.

Container Registry	Artifact Registry
Administrateur Activer l'API Container Registry Ajoutez un hôte de registre, tel que "gcr.io", en transférant une image initiale vers l'hôte. Attribuez des rôles Cloud Storage au bucket de stockage pour que l'hôte du registre puisse accéder aux images.	Administrateur Activer l'API Artifact Registry Ajoutez un dépôt Docker. Attribuez des rôles Artifact Registry pour autoriser l'accès aux images.
Utilisateurs du registre Définissez l'image en tant que fichier Dockerfile. Créer l'image. Authentifiez-vous auprès du registre. Ajoutez un tag et transférez l'image vers le registre. Extrayez l'image du registre ou déployez-la dans un environnement d'exécution Google Cloud .	Utilisateurs du registre Définissez l'image en tant que fichier Dockerfile. Créer l'image. Authentifiez-vous auprès du registre. Ajoutez un tag et transférez l'image vers le registre. Extrayez l'image du registre ou déployez-la dans un environnement d'exécution Google Cloud .

Toutefois, un raccourci pour Container Registry consiste à combiner les rôles d'administrateur et d'utilisateur dans un seul workflow. Ce raccourci est courant dans les applications suivantes:

• Guides de démarrage rapide et tutoriels dans lesquels vous effectuez des tests dans un environnement où vous disposez d'autorisations étendues.
• Workflows qui utilisent Cloud Build, car le compte de service Cloud Build est autorisé à ajouter un hôte de registre dans le même Google Cloud projet.

Le workflow de raccourci se présente comme suit:

1. Activer l'API Container Registry.
2. Accordez des autorisations au compte qui accédera à Container Registry.

3. Authentifiez-vous auprès du registre. L'option d'authentification la plus simple consiste à utiliser l'assistant d'identification Docker dans Google Cloud CLI. Il s'agit d'une étape de configuration unique.

   gcloud auth configure-docker
   

4. Créez et taguez l'image. Par exemple, cette commande crée et tague l'image gcr.io/my-project/my-image:tag1:

   docker build -t gcr.io/my-project/my-image:tag1
   

5. Transférez l'image vers le registre. Exemple :

   docker push gcr.io/my-project/my-image:tag1
   

   Si l'hôte du registre gcr.io n'existe pas dans le projet, Container Registry ajoute l'hôte avant d'importer l'image.

6. Extrayez l'image du registre ou déployez-la dans un environnement d'exécution Google Cloud . Exemple :

   docker pull gcr.io/my-project/my-image:tag1
   

Ce workflow repose sur les raccourcis suivants:

• Le compte qui transfère des images dispose du rôle "Administrateur de l'espace de stockage" ou d'un rôle disposant des mêmes autorisations, comme "Propriétaire". Les autorisations étendues de ce rôle permettent un accès en lecture et en écriture pour tous les buckets de stockage d'un projet, y compris les buckets qui ne sont pas utilisés par Container Registry.
• Lorsque vous activez certaines Google Cloud API, l'API Container Registry est automatiquement activée. Cela signifie que les utilisateurs de ces services ont un accès implicite à Container Registry dans le même projet. Par exemple, les utilisateurs autorisés à exécuter des compilations dans Cloud Build peuvent transférer des images vers des dépôts et ajouter des hôtes de dépôt par défaut.

Dans Artifact Registry, la séparation est claire entre les rôles utilisateur administrateur et référentiel, ce qui modifie les étapes du workflow de compilation et de déploiement. Pour adapter le workflow Container Registry à Artifact Registry, effectuez les modifications suivantes. Chaque étape renvoie à des informations supplémentaires sur la modification du workflow.

1. Nouveau: activez l'API Artifact Registry.

   Vous devez activer l'API Artifact Registry. Cloud Build et les environnements d'exécution tels que Cloud Run et GKE n'activent pas automatiquement l'API pour vous.

2. Nouveau: créez le dépôt Docker cible s'il n'existe pas déjà. Vous devez créer un dépôt pour pouvoir y transférer des images. Le transfert d'une image ne peut pas déclencher la création d'un dépôt et le compte de service Cloud Build ne dispose pas des autorisations nécessaires pour créer des dépôts.

3. Accordez des autorisations au compte qui interagira avec Artifact Registry.

4. Modification: authentification au dépôt. Si vous utilisez l'assistant d'identification dans gcloud CLI, vous devez spécifier les hôtes que vous souhaitez ajouter à la configuration de votre client Docker. Par exemple, cette commande ajoute l'hôte us-central1-docker.pkg.dev:

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

5. Modifié: créez et taguez l'image.

   L'exemple de commande suivant est identique à celui de Container Registry, mais utilise un chemin d'accès de dépôt Artifact Registry pour l'image.

   docker build -t us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

6. Modification: transférez l'image vers le dépôt à l'aide du chemin d'accès Artifact Registry. Exemple :

   docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

7. Modification: extrayez l'image du dépôt à l'aide du chemin d'accès Artifact Registry. Exemple :

   docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:tag1
   

Activer l'API

Points essentiels :

• Vous devez activer l'API Artifact Registry en plus de l'API pour d'autres Google Cloud services tels que Cloud Build, Cloud Run et GKE.

La comparaison suivante décrit l'activation de l'API pour chaque service:

Container Registry

Vous devez activer l'API Container Registry avant d'utiliser Docker ou d'autres clients tiers avec Container Registry.

Lorsque vous activez les API Google Cloud suivantes, l'API Container Registry est également activée automatiquement:

• Environnement flexible App Engine
• Cloud Build
• Cloud Run Functions
• Cloud Run
• Analyse des conteneurs ou analyse à la demande dans l'analyse des artefacts
• Google Kubernetes Engine

Avec les autorisations par défaut, les utilisateurs autorisés à exécuter des builds dans Cloud Build, à analyser des conteneurs avec Artifact Analysis ou à déployer des conteneurs dans des environnements d'exécutionGoogle Cloud ont implicitement accès aux images de Container Registry lorsque le registre se trouve dans le même projet.

Artifact Registry

Vous devez activer l'API Artifact Registry avant d'utiliser des clients Docker ou d'autres Google Cloud services avec Artifact Registry.

Les services tels que Cloud Build, Cloud Run et GKE n'activent pas automatiquement l'API Artifact Registry.

Vous pouvez activer plusieurs API dans le même projet à l'aide de gcloud. Par exemple, pour activer l'API Cloud Build et l'API Artifact Registry, exécutez la commande suivante:

gcloud services enable
    artifactregistry.googleapis.com \
    cloudbuild.googleapis.com

Ajouter des registres et des dépôts

Points essentiels :

• Vous devez créer un dépôt Docker Artifact Registry avant de transférer une image vers celui-ci.

  Une étape de création de registre est souvent exclue de la documentation décrivant l'envoi d'images vers Container Registry, car un compte disposant d'autorisations Storage Admin peut ajouter un registre à un projet avec l'envoi initial à l'hôte du registre.

• Container Registry stocke toutes les images dans une seule région multirégionale dans le même bucket de stockage. Dans Artifact Registry, vous pouvez créer plusieurs dépôts dans la même région ou dans plusieurs régions avec des règles d'accès distinctes.

La comparaison suivante décrit la configuration des dépôts dans chaque service:

Container Registry

Dans Container Registry, vous pouvez ajouter jusqu'à quatre hôtes de registre à votre projet. Pour ajouter un hôte de registre, transférez la première image.

1. Pour ajouter un registre tel que gcr.io à votre projet, un compte disposant du rôle "Administrateur de l'espace de stockage" au niveau du projet envoie une image initiale.

   Par exemple, si l'hôte gcr.io n'existe pas dans le projet my-project, le transfert de l'image gcr.io/my-project/my-image:1.0 déclenche les étapes suivantes:

   1. Ajouter l'hôte gcr.io au projet
   2. Créez un bucket de stockage pour gcr.io dans le projet.
   3. Stocker l'image en tant que gcr.io/my-project/my-image:1.0

2. Après ce transfert initial, vous pouvez accorder des autorisations au bucket de stockage pour d'autres utilisateurs.

Dans un projet, un hôte de registre stocke toutes les images dans le même bucket de stockage. Dans l'exemple suivant, le projet my-project comporte deux images appelées web-app dans le registre gcr.io. L'une se trouve directement sous l'ID de projet my-project. L'autre image se trouve dans le dépôt team1.

gcr.io/my-project/web-app
gcr.io/my-project/team1/web-app

Artifact Registry

Un compte disposant du rôle Administrateur du dépôt Artifact Registry doit créer le dépôt avant de pouvoir y transférer des images. Vous pouvez ensuite accorder des autorisations au dépôt pour d'autres utilisateurs.

Dans Artifact Registry, chaque dépôt est une ressource distincte. Par conséquent, tous les chemins d'accès aux images doivent inclure un dépôt.

Chemins d'accès aux images valides:

us-central1-docker.pkg.dev/my-project/team1/web-app:1.0
us-central1-docker.pkg.dev/my-project/team2/web-app:1.0

Chemin d'accès à l'image non valide (ne comprend pas de dépôt) :

us-central1-docker.pkg.dev/my-project/web-app:1.0

Les exemples suivants montrent des situations où le transfert d'une image vers un dépôt manquant échoue.

• Transfert d'une image vers us-central1-docker.pkg.dev/my-project/team1 si us-central1-docker.pkg.dev/my-project/team1 n'existe pas.
• Transfert d'une image vers us-central1-docker.pkg.dev/my-project/team2 lorsque us-central1-docker.pkg.dev/my-project/team1 existe, mais que us-central1-docker.pkg.dev/my-project/team2 n'existe pas.

Accord d'autorisations...

Points essentiels :

• Attribuez le rôle Artifact Registry approprié au compte que vous utilisez avec Artifact Registry.
• Les servicesGoogle Cloud disposent d'un accès en lecture ou en écriture équivalent à Container Registry et Artifact Registry. Toutefois, le compte de service Cloud Build par défaut ne peut pas créer de dépôts.
• Container Registry prend en charge le contrôle des accès au niveau du bucket de stockage. Artifact Registry est compatible avec le contrôle des accès au niveau du dépôt.

La comparaison suivante décrit la configuration des autorisations dans chaque service:

Container Registry

Container Registry utilise les rôles Cloud Storage pour contrôler l'accès.

Lecteur des objets Storage au niveau du bucket de stockage

Extrayez (lisez) des images à partir des hôtes de registre existants du projet.

Rédacteur des anciens buckets de l'espace de stockage au niveau du bucket de stockage

Transférez (écriture) et extrayez (lecture) des images pour les hôtes de registre existants du projet.

Administrateur de l'espace de stockage au niveau du projet

Ajoutez un hôte de registre à un projet en transmettant une image initiale à l'hôte.

Après l'envoi initial de l'image vers un registre, vous accordez des rôles Cloud Storage aux autres comptes qui ont besoin d'accéder au bucket de stockage. Notez que tout compte disposant de toutes les autorisations du rôle "Storage Admin" peut lire, écrire et supprimer des buckets et des objets de stockage dans l'ensemble du projet.

Les autorisations d'un bucket de stockage s'appliquent à tous les dépôts du référentiel. Par exemple, tout utilisateur disposant d'autorisations de lecteur des objets Storage sur le bucket pour gcr.io/my-project peut lire les images de tous ces dépôts:

gcr.io/my-project/team1
gcr.io/my-project/team2
gcr.io/my-project/test
gcr.io/my-project/production

Artifact Registry

Artifact Registry dispose de ses propres rôles pour contrôler l'accès. Ces rôles permettent de séparer clairement les rôles d'administrateur et d'utilisateur de dépôt.

Seuls les comptes qui gèrent des dépôts doivent disposer du rôle "Administrateur de dépôts Artifact Registry" ou "Administrateur Artifact Registry".

Lecteur Artifact Registry

Répertoriez les artefacts et les dépôts. Téléchargez les artefacts.

Rédacteur Artifact Registry

Répertoriez les artefacts et les dépôts. Téléchargez des artefacts, importez de nouvelles versions d'artefacts et ajoutez ou mettez à jour des balises.

Administrateur de dépôts Artifact Registry

Autorisations Artifact Registry Writer et autorisations de supprimer des artefacts et des tags.

Administrateur Artifact Registry

Autorisations d'administrateur de dépôt Artifact Registry et autorisations de créer, mettre à jour, supprimer et accorder des autorisations aux dépôts.

Vous pouvez appliquer ces autorisations au niveau du dépôt. Exemple :

• Accorder l'accès à us-central1-docker.pkg.dev/my-project/team1 à l'équipe 1
• Accordez l'accès à us-central1-docker.pkg.dev/my-project/team2 à l'équipe 2.

Pour en savoir plus sur l'octroi d'autorisations Artifact Registry, consultez la documentation sur le contrôle des accès.

S'authentifier auprès du registre

Points essentiels :

• Artifact Registry est compatible avec les mêmes méthodes d'authentification que Container Registry.
• Pour l'assistant d'identification Docker, vous devez spécifier les hôtes à ajouter à la configuration du client Docker.
• Pour l'authentification à l'aide de docker login, utilisez l'hôte Artifact Registry au lieu d'un hôte Container Registry.

Utiliser l'assistant d'identification

La commande gcloud auth configure-docker et l'assistant d'identification autonome ne configurent Docker que pour les noms d'hôte *.gcr.io par défaut. Pour Artifact Registry, vous devez spécifier une liste des hôtes Artifact Registry que vous souhaitez ajouter à la configuration du client Docker.

Par exemple, pour configurer l'authentification auprès des dépôts Docker dans la région us-central1, exécutez la commande suivante:

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

Si vous ajoutez ultérieurement des dépôts dans us-east1 et asia-east1, vous devez exécuter à nouveau la commande pour ajouter les noms d'hôte régionaux correspondants à votre configuration Docker.

gcloud auth configure-docker us-east-docker.pkg.dev,asia-east1-docker.pkg.dev

Pour en savoir plus sur les méthodes d'authentification Artifact Registry, consultez la page Configurer l'authentification pour Docker.

Utiliser l'authentification par mot de passe

Lorsque vous vous connectez à Docker, utilisez le nom d'hôte Artifact Registry au lieu d'un nom d'hôte *.gcr.io. L'exemple suivant montre l'authentification avec une clé de compte de service encodée en base64 à l'hôte us-central1-docker.pkg.dev:

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

Créer et taguer des images

Points clés : - Artifact Registry utilise un nom d'hôte différent pour les dépôts.

Lorsque vous ajoutez un tag à une image, utilisez le chemin d'accès Artifact Registry au lieu du chemin d'accès Container Registry. Exemple :

docker tag my-image us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Transférer des images vers le registre

Points clés : - Dans Artifact Registry, le dépôt cible doit exister avant que vous ne transfériez une image vers celui-ci. - Artifact Registry utilise un nom d'hôte différent pour les dépôts.

Lorsque vous transférez une image, utilisez le chemin d'accès Artifact Registry au lieu du chemin d'accès Container Registry. Exemple :

docker push us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Extraire des images du registre

Point essentiel:

• Les noms d'hôte Artifact Registry sont différents des noms d'hôte Container Registry.

Lorsque vous récupérez une image, utilisez le chemin d'accès Artifact Registry au lieu du chemin d'accès Container Registry. Exemple :

docker pull us-central1-docker.pkg.dev/my-project/my-repo/my-image:1.0

Pour obtenir des exemples de déploiement d'images dans des environnements d'exécution tels que Cloud Run et GKE, consultez la section Déployer des images. Google Cloud