Migration manuelle vers les dépôts gcr.io dans Artifact Registry

Ce document explique comment configurer manuellement les dépôts gcr.io dans Artifact Registry.

Si vous souhaitez créer des dépôts gcr.io dans Artifact Registry à l'aide de clés de chiffrement gérées par le client (CMEK), suivez les étapes décrites dans Avant de commencer, puis les instructions de la section Créer manuellement un dépôt.

Avant de commencer

1. Installez la Google Cloud CLI si elle n'est pas déjà installée. Pour une installation existante, exécutez la commande suivante pour mettre à jour les composants vers les dernières versions :

   gcloud components update
   

2. Activez les API Artifact Registry et Resource Manager. gcloud CLI utilise l'API Resource Manager pour vérifier si vous disposez de l'une des autorisations requises.

   Exécutez la commande suivante :

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

3. En savoir plus sur les tarifs d'Artifact Registry avant de commencer la transition.

Rôles requis

Pour obtenir les autorisations nécessaires pour configurer les dépôts gcr.io, demandez à votre administrateur de vous accorder les rôles IAM suivants :

• Pour créer des dépôts Artifact Registry et accorder l'accès à des dépôts individuels : Administrateur Artifact Registry (roles/artifactregistry.admin) sur le projet Google Cloud
• Pour afficher et gérer la configuration Container Registry existante appliquée aux buckets de stockage Cloud Storage : Administrateur de l'espace de stockage (roles/storage.admin) sur le projet Google Cloud
• Pour créer un dépôt gcr.io la première fois que vous transférez une image vers un nom d'hôte gcr.io : Rédacteur de dépôt Artifact Registry avec création lors de l'envoi (roles/artifactregistry.createOnPushWriter) sur le projet Google Cloud
• Pour accorder l'accès au dépôt au niveau du projet : Administrateur IAM de projet (roles/resourcemanager.projectIamAdmin) sur le projet Google Cloud
• Pour lister les services activés dans une organisation : Lecteur d'éléments Cloud (roles/cloudasset.viewer) sur l'organisation

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

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

Limites

Les limites suivantes s'appliquent aux dépôts Artifact Registry gcr.io :

• Lorsque vous passez de Container Registry à Artifact Registry, vous ne pouvez pas mapper un hôte Container Registry à un dépôt Artifact Registry dans un autre projet.

• Chaque nom d'hôte Container Registry ne correspond qu'à un seul dépôt gcr.io Artifact Registry dans la même multirégion.

• Les noms des dépôts gcr.io sont prédéfinis et vous ne pouvez pas les modifier.

Si vous avez besoin de mieux contrôler l'emplacement de vos dépôts, vous pouvez passer aux dépôts pkg.dev dans Artifact Registry. Étant donné que les dépôts pkg.dev ne sont pas compatibles avec le domaine gcr.io, cette approche de transition nécessite plus de modifications de votre automatisation et de vos workflows existants. Pour en savoir plus sur les différences entre les fonctionnalités, consultez Choisir une option de transition.

Créer des dépôts

Créez des dépôts gcr.io pour pouvoir configurer l'accès pour vos utilisateurs et copier les images Container Registry existantes dans Artifact Registry avant d'activer la redirection.

Création manuelle d'un dépôt

Créez manuellement des dépôts gcr.io si vous souhaitez utiliser des clés de chiffrement gérées par le client (CMEK) pour chiffrer le contenu des dépôts ou s'il existe une contrainte d'emplacement dans votre organisationGoogle Cloud qui empêche la création de ressources dans des emplacements spécifiques.

Pour créer manuellement un dépôt gcr.io :

1. Si vous utilisez CMEK, créez la clé que vous utiliserez avec ce dépôt et accordez les autorisations requises pour utiliser la clé. Consultez Activer les clés de chiffrement gérées par le client.

2. Ajoutez le dépôt.

   Console

   1. Ouvrez la page Dépôts dans la console Google Cloud .

      Ouvrir la page "Dépôts"

   2. Cliquez sur Créer un dépôt.

   3. Spécifiez le nom du dépôt.

      Nom d'hôte Container Registry	Nom du dépôt Artifact Registry
      gcr.io	gcr.io
      asia.gcr.io	asia.gcr.io
      eu.gcr.io	eu.gcr.io
      us.gcr.io	us.gcr.io

   4. Spécifiez Docker comme format de dépôt.

   5. Sous Type d'emplacement, spécifiez la région multiple pour le dépôt :

      Nom d'hôte Container Registry	Emplacement du dépôt Artifact Registry	Nom du dépôt Artifact Registry
      gcr.io	us	gcr.io
      asia.gcr.io	asia	asia.gcr.io
      eu.gcr.io	europe	eu.gcr.io
      us.gcr.io	us	us.gcr.io

   6. Ajoutez une description pour le dépôt. N'incluez pas de données sensibles, car les descriptions des dépôts ne sont pas chiffrées.

   7. Dans la section Chiffrement, choisissez le mécanisme de chiffrement du dépôt.

      • Google-managed encryption key : chiffre le contenu du dépôt avec un Google-owned and Google-managed encryption key.
      • Clé gérée par le client : chiffre le contenu du dépôt à l'aide d'une clé que vous contrôlez via Cloud Key Management Service. Pour obtenir des instructions sur la configuration de la clé, consultez la page Configurer des CMEK pour les dépôts.

   8. Cliquez sur Create (Créer).

   gcloud

   Exécutez la commande suivante pour créer un dépôt :

   gcloud artifacts repositories create REPOSITORY \
       --repository-format=docker \
       --location=LOCATION \
       --description=DESCRIPTION \
       --kms-key=KMS-KEY
   

   Remplacez les valeurs suivantes :

   • REPOSITORY est le nom du dépôt.

     Nom d'hôte Container Registry	Nom du dépôt Artifact Registry
     gcr.io	gcr.io
     asia.gcr.io	asia.gcr.io
     eu.gcr.io	eu.gcr.io
     us.gcr.io	us.gcr.io

   • LOCATION est la région multiple du dépôt :

     Nom d'hôte Container Registry	Emplacement du dépôt Artifact Registry	Nom du dépôt Artifact Registry
     gcr.io	us	gcr.io
     asia.gcr.io	asia	asia.gcr.io
     eu.gcr.io	europe	eu.gcr.io
     us.gcr.io	us	us.gcr.io

   • DESCRIPTION est une description du dépôt. N'incluez pas de données sensibles, car les descriptions des dépôts ne sont pas chiffrées.

   • KMS-KEY est le chemin d'accès complet à la clé de chiffrement Cloud KMS, si vous utilisez une clé de chiffrement gérée par le client pour chiffrer le contenu du dépôt. Le chemin est au format suivant :

     projects/KMS-PROJECT/locations/KMS-LOCATION/keyRings/KEY-RING/cryptoKeys/KEY

     Remplacez les valeurs suivantes :

     • KMS-PROJECT est le projet dans lequel votre clé est stockée.
     • KMS-LOCATION correspond à l'emplacement de la clé.
     • KEY-RING correspond au nom du trousseau de clés.
     • KEY correspond au nom de la clé.

   Pour vérifier que le dépôt a bien été créé, listez vos dépôts à l'aide de la commande suivante :

   gcloud artifacts repositories list
   

Avant de rediriger le trafic vers vos nouveaux dépôts, vous devez vous assurer que votre automatisation existante peut accéder au dépôt. L'étape suivante consiste à configurer les autorisations pour accorder l'accès aux dépôts.

Accorder des autorisations sur les dépôts

Container Registry utilise les rôles Cloud Storage pour contrôler les accès. Artifact Registry dispose de ses propres rôles IAM. Ces rôles séparent plus clairement les rôles de lecture, d'écriture et d'administration des dépôts que Container Registry.

Pour mapper rapidement les autorisations existantes accordées sur les buckets de stockage aux rôles Artifact Registry suggérés, utilisez l'outil de mappage des rôles.

Vous pouvez également afficher la liste des principaux ayant accès aux buckets de stockage à l'aide de la console Google Cloud .

1. Dans la console Google Cloud , accédez à la page Buckets de Cloud Storage.
   

   Accéder à la page "Buckets"

2. Cliquez sur le bucket de stockage de l'hôte de registre que vous souhaitez afficher. Dans les noms de buckets, PROJECT-ID correspond à l'ID de votre projetGoogle Cloud.

   • gcr.io: artifacts.PROJECT-ID.appspot.com
   • asia.gcr.io: asia.artifacts.PROJECT-ID.appspot.com
   • eu.gcr.io: eu.artifacts.PROJECT-ID.appspot.com
   • us.gcr.io: us.artifacts.PROJECT-ID.appspot.com

3. Cliquez sur l'onglet Autorisations.

4. Dans l'onglet "Autorisations", cliquez sur le sous-onglet Afficher par rôle.

5. Développez un rôle pour afficher les comptes principaux qui disposent de ce rôle.

La liste inclut les rôles IAM attribués directement au bucket et les rôles hérités du projet parent. En fonction du rôle, vous pouvez choisir le rôle Artifact Registry le plus approprié à attribuer.

Cloud Storage et rôles de base

Accordez aux utilisateurs et aux comptes de service qui accèdent actuellement à Container Registry l'accès aux dépôts Artifact Registry. Pour les rôles Cloud Storage hérités du projet parent, vous devez vérifier que le principal utilise actuellement Container Registry. Il est possible que certains principaux n'accèdent qu'à d'autres buckets Cloud Storage qui ne sont pas liés à Container Registry.

Les rôles de base "Propriétaire", "Éditeur" et "Lecteur" qui existaient avant IAM offrent un accès limité aux buckets Storage. Ils n'accordent pas naturellement un accès aux ressources Cloud Storage, comme leurs noms peuvent suggérer, et fournissent des autorisations supplémentaires pour d'autres services Google Cloud . Identifiez les utilisateurs et les comptes de service qui ont besoin d'accéder à Artifact Registry, puis utilisez le tableau de mappage des rôles pour vous aider à attribuer les rôles appropriés si l'accès à Artifact Registry est justifié.

Le tableau suivant mappe les rôles Artifact Registry en fonction des autorisations accordées par les rôles Cloud Storage prédéfinis pour l'accès à Container Registry.

Accès requis	Rôle actuel	Rôle Artifact Registry	Où attribuer le rôle
Extraire des images uniquement (lecture seule)	Lecteur des objets de l'espace de stockage (roles/storage.objectViewer)	Lecteur Artifact Registry (roles/artifactregistry.reader)	Dépôt Artifact Registry ou projet Google Cloud
Transférer et extraire des images (lecture et écriture) Supprimer des images	Rédacteur des anciens buckets de l'espace de stockage (roles/storage.legacyBucketWriter)	Administrateur de dépôts Artifact Registry (roles/artifactregistry.repoAdmin)	Dépôt Artifact Registry ou projet Google Cloud
Créez un dépôt gcr.io dans Artifact Registry la première fois qu'une image est transférée vers un nom d'hôte gcr.io dans un projet.	Administrateur de l'espace de stockage (roles/storage.admin)	Administrateur de dépôt Artifact Registry avec création lors de l'envoi (roles/artifactregistry.createOnPushRepoAdmin)	Google Cloud projet
Créer, gérer et supprimer des dépôts	Administrateur de l'espace de stockage (roles/storage.admin)	Administrateur Artifact Registry (roles/artifactregistry.admin)	Google Cloud projet

Rôles d'agent de service hérités du projet

Les comptes de service par défaut pour les services Google Cloud ont leurs propres rôles accordés au niveau du projet. Par exemple, l'agent de service pour Cloud Run dispose du rôle "Agent de service Cloud Run".

Dans la plupart des cas, ces rôles d'agent de service contiennent des autorisations par défaut équivalentes pour Container Registry et Artifact Registry. Vous n'avez pas besoin d'apporter de modifications supplémentaires si vous exécutez Artifact Registry dans le même projet que votre service Container Registry existant.

Consultez la documentation de référence sur les rôles d'agent de service pour en savoir plus sur les autorisations associées à ces rôles.

Rôles personnalisés

Utilisez le tableau de mapping des rôles pour vous aider à choisir le rôle à attribuer aux utilisateurs ou aux comptes de service en fonction du niveau d'accès dont ils ont besoin.

Pour obtenir des instructions sur l'attribution de rôles Artifact Registry, consultez Configurer des rôles et des autorisations.

Copier des conteneurs à partir de Container Registry

Nous vous recommandons d'utiliser notre outil de migration automatique pour copier vos images de Container Registry vers Artifact Registry.

Si vous souhaitez utiliser d'autres outils pour copier vos images, consultez Copier des images à partir de Container Registry.

Configurer d'autres fonctionnalités

Cette section décrit la configuration d'autres fonctionnalités que vous avez peut-être configurées dans Container Registry.

Artifact Analysis

Artifact Analysis est compatible avec Container Registry et Artifact Registry. Les deux produits utilisent les mêmes API Artifact Analysis pour les métadonnées d'image et l'analyse des failles, ainsi que les mêmes sujets Pub/Sub pour les notifications Artifact Analysis.

Toutefois, les actions suivantes ne se produisent que lorsque la redirection est activée :

• Analyse automatique des dépôts gcr.io dans Artifact Registry.
• Inclure l'activité du dépôt gcr.io dans les notifications Pub/Sub.

Vous pouvez continuer à utiliser les commandes gcloud container images pour lister les notes et les occurrences associées aux chemins d'image gcr.io.

Notifications Pub/Sub

Artifact Registry publie les modifications apportées dans le même sujet gcr que Container Registry. Aucune configuration supplémentaire n'est requise si vous utilisez déjà Pub/Sub avec Container Registry dans le même projet qu'Artifact Registry. Toutefois, Artifact Registry ne publie pas de messages pour les dépôts gcr.io tant que vous n'avez pas activé la redirection.

Si vous configurez Artifact Registry dans un projet distinct, le sujet gcr peut ne pas exister. Pour obtenir des instructions de configuration, consultez la section Configurer les notifications Pub/Sub.

Activer la redirection du trafic gcr.io

Après avoir créé vos dépôts gcr.io et configuré les autorisations et l'authentification pour vos clients tiers, vous pouvez activer la redirection du trafic gcr.io.

Si vous rencontrez un problème après avoir activé la redirection, vous pouvez réacheminer le trafic vers Container Registry en exécutant la commande gcloud artifacts settings disable-upgrade-redirection, puis réactiver la redirection une fois le problème résolu.

Vérifier les autorisations pour activer la redirection

Pour activer la redirection, vous devez disposer des autorisations suivantes au niveau du projet :

• artifactregistry.projectsettings.update : autorisations permettant de modifier les paramètres du projet Artifact Registry. Cette autorisation est associée au rôle Administrateur Artifact Registry (roles/artifactregistry.admin).
• storage.buckets.update : autorisations permettant de mettre à jour les buckets de stockage dans l'ensemble du projet. Cette autorisation est incluse dans le rôle Administrateur de l'espace de stockage (roles/storage.admin).

Si vous ne disposez pas de ces autorisations, demandez à un administrateur de vous les accorder au niveau du projet.

Les commandes suivantes accordent les rôles "Administrateur Artifact Registry" et "Administrateur de l'espace de stockage" sur un projet.

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/artifactregistry.admin'

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member='user:PRINCIPAL' \
    --role='roles/storage.admin'

Remplacez les valeurs suivantes :

• PROJECT_ID est Google Cloud l'ID du projet.
• PRINCIPAL est l'adresse e-mail du compte que vous mettez à jour. Par exemple, my-user@example.com

Valider la configuration du projet

Pour valider la configuration de votre projet, exécutez la commande suivante :

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID --dry-run

Remplacez PROJECT_ID par votre Google Cloud ID de projet.

Artifact Registry recherche les dépôts qui correspondent aux noms d'hôte Container Registry.

Bien qu'Artifact Registry puisse créer les dépôts gcr.io manquants pour vous lorsque vous activez la redirection, nous vous recommandons de les créer d'abord afin de pouvoir effectuer les actions suivantes avant d'activer la redirection :

• Configurez les autorisations au niveau du dépôt.
• Copiez les images de Container Registry que vous souhaitez continuer à utiliser.
• Effectuez toute configuration supplémentaire.

Activer la redirection

Pour activer la redirection du trafic gcr.io :

Pour activer la redirection, exécutez la commande suivante :

gcloud artifacts settings enable-upgrade-redirection \
    --project=PROJECT_ID

Remplacez PROJECT_ID par votre Google Cloud ID de projet.

Artifact Registry commence à activer la redirection.

Pour vérifier l'état actuel de la redirection, exécutez la commande suivante :

gcloud artifacts settings describe

Lorsque la redirection est activée, le résultat est le suivant :

legacyRedirectionState: REDIRECTION_FROM_GCR_IO_ENABLED

Tout le trafic vers gcr.io, asia.gcr.io, eu.gcr.io et us.gcr.io est redirigé, même si vous n'avez pas créé de dépôts gcr.io pour tous les noms d'hôte Container Registry. Si vous transférez une image vers un nom d'hôte qui ne possède pas de dépôt Artifact Registry correspondant, Artifact Registry crée le dépôt si vous disposez d'un rôle avec l'autorisation artifactregistry.repositories.createOnPush. Les rôles prédéfinis Auteur Create-on-push (artifactregistry.createOnPushWriter) et Administrateur de dépôt Create-on-push (artifactregistry.createOnPushRepoAdmin) disposent de cette autorisation.

Une fois la redirection activée, vous pouvez tester votre automatisation et vérifier que vous pouvez transférer et extraire des images à l'aide de vos nouveaux dépôts gcr.io.

Valider la redirection

Vérifiez que les requêtes pull et push sur les noms d'hôte gcr.io fonctionnent.

1. Transférez une image de test vers l'un de vos dépôts gcr.io à l'aide de son chemin d'accès gcr.io.

   1. Ajoutez un tag à l'image à l'aide du chemin d'accès gcr.io. Par exemple, cette commande ajoute le tag us.gcr.io/my-project/test-image à l'image local-image :

      docker tag local-image us.gcr.io/my-project/test-image
      

   2. Transférez l'image que vous avez taguée. Par exemple, cette commande transfère l'image us.gcr.io/my-project/test-image :

      docker push us.gcr.io/my-project/test-image
      

2. Listez les images du dépôt pour vérifier que l'image a bien été importée. Par exemple, pour lister les images dans us.gcr.io/my-project, exécutez la commande suivante :

   gcloud container images list --repository=us.gcr.io/my-project
   

3. Récupérez l'image depuis le dépôt à l'aide de son chemin d'accès Container Registry. Par exemple, cette commande extrait l'image us.gcr.io/my-project/test-image.

   docker pull us.gcr.io/my-project/test-image
   

Après ce test initial, vérifiez que votre automatisation existante pour créer et déployer des images fonctionne comme prévu, y compris :

• Les utilisateurs et les comptes de service qui utilisent Container Registry peuvent toujours transférer, extraire et déployer des images lorsque la redirection est activée.
• Votre automatisation ne transfère les images que vers les dépôts existants.
• Si l'analyse des failles Artifact Analysis est activée, elle identifie les images présentant des failles dans les dépôts gcr.io.
• Si vous utilisez l'autorisation binaire, vos stratégies existantes fonctionnent correctement pour les images déployées à partir de dépôts gcr.io.
• Les abonnements Pub/Sub configurés incluent les notifications de modification de vos dépôts gcr.io.

Nettoyer les images Container Registry

Lorsque la redirection est activée, les commandes permettant de supprimer des images dans les chemins d'accès gcr.io suppriment les images dans le dépôt gcr.io Artifact Registry correspondant. Les commandes de suppression d'images dans les chemins d'accès gcr.io ne suppriment pas les images stockées sur les hôtes Container Registry.

Pour supprimer toutes les images Container Registry de manière sécurisée, supprimez les buckets Cloud Storage pour chaque nom d'hôte Container Registry.

Pour supprimer chaque bucket de stockage Container Registry :

gcloud storage rm gs://BUCKET-NAME --recursive

Removing gs://artifacts.my-project.appspot.com/...

Si d'autres services Google Cloud sont en cours d'exécution dans le même projet Google Cloud, laissez l'API Container Registry activée. Si vous essayez de désactiver l'API Container Registry. Container Registry affiche un avertissement si d'autres services avec une dépendance configurée sont activés dans le projet. La désactivation de l'API Container Registry désactive automatiquement tous les services du même projet ayant une dépendance configurée, même si vous n'utilisez pas actuellement Container Registry avec ces services.

Étapes suivantes

• Consultez le guide de démarrage rapide de Docker.
• En savoir plus sur les dépôts gcr.io