Configurer l'authentification auprès d'Artifact Registry pour Docker

Cette page explique comment configurer Docker pour s'authentifier auprès d'Artifact Registry dans les dépôts Docker.

Vous n'avez pas besoin de configurer l'authentification pour Cloud Build ou Google Cloud tels que Google Kubernetes Engine et Cloud Run, mais vous devez Vérifiez que les autorisations requises sont configurés.

Avant de commencer

1. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

2. (Facultatif) Configurez les valeurs par défaut pour les commandes de gcloud CLI.
3. Vérifiez que le compte utilisé pour l'authentification autorisations permettant d'accéder à Artifact Registry. Nous vous recommandons d'utiliser un compte de service plutôt qu'un compte utilisateur.
4. Installez Docker si ce n'est pas déjà fait. Docker est inclus dans Cloud Shell.

5. Docker nécessite un accès privilégié pour interagir avec les registres. Sous Linux ou Windows, ajoutez l'utilisateur que vous permet d'exécuter des commandes Docker dans le groupe de sécurité Docker. Cette étape n'est pas requise sous macOS, car Docker Desktop s'exécute sur une machine virtuelle en tant qu'utilisateur racine.

   Linux

   Le groupe de sécurité Docker s'appelle docker. Pour ajouter votre nom d'utilisateur, exécutez la commande suivante :

   sudo usermod -a -G docker ${USER}
   

   Windows

   Le groupe de sécurité Docker s'appelle docker-users. Pour ajouter un utilisateur à partir de l'invite de commande administrateur, exécutez la commande suivante :

   net localgroup docker-users DOMAIN\USERNAME /add
   

   Où

   • DOMAIN est votre domaine Windows.
   • USERNAME est votre nom d'utilisateur.

   Déconnectez-vous et reconnectez-vous pour que les modifications apportées à la liste des membres du groupe soient appliquées. Si vous utilisez une machine virtuelle, vous devrez peut-être la redémarrer pour que ces modifications prennent effet.

   Remarque : Le groupe de sécurité Docker dispose d'un accès équivalent à l'utilisateur racine ou à l'utilisateur administrateur. N'ajoutez que des utilisateurs de confiance nécessitant un accès à Docker. Pour pour en savoir plus sur les impacts de sécurité, consultez la section Sécurité du daemon Docker.

Choisir une méthode d'authentification

Les méthodes d'authentification suivantes sont disponibles :

Assistant d'identification de la gcloud CLI

Configurez vos identifiants Artifact Registry pour les utiliser avec Docker directement dans gcloud CLI. Il s'agit de la méthode d'authentification la plus simple, mais elle peut être plus lente que l'assistant d'identification autonome.

Assistant d'identification Docker autonome

Cette option permet principalement de configurer vos identifiants à utiliser avec Docker en l'absence de Google Cloud CLI. Elle est beaucoup plus rapide que la gcloud CLI. et utilise les identifiants par défaut de l'application (ADC) pour rechercher automatiquement les identifiants dans votre environnement.

Jeton d'accès

Vous pouvez générer un jeton d'accès de courte durée pour un compte de service, puis utiliser le jeton pour l'authentification par mot de passe. Puisque le jeton n'est valide que Il s'agit d'une option plus sûre qu'une clé de compte de service.

Clé de compte de service

Paire de clés gérée par l'utilisateur que vous pouvez utiliser comme identifiant pour de service géré. Les identifiants étant de longue durée, il s'agit de l'option la moins sécurisée de toutes les méthodes d'authentification disponibles.

Si possible, utilisez un jeton d'accès. ou un outil d'aide à la connexion pour réduire le risque d'accès non autorisé des images de conteneurs. Si vous devez utiliser une clé de compte de service, assurez-vous de suivre les bonnes pratiques de gestion des identifiants.

Avertissement : L'assistant d'identification Docker n'est compatible qu'avec Docker 18.03 ou une version ultérieure. Un bug existant dans les versions précédentes du client Docker ralentit considérablement les compilations docker build lorsque des assistants d'identification sont configurés.

Paramètres d'authentification dans le fichier de configuration Docker

Docker enregistre les paramètres d'authentification dans le fichier de configuration config.json.

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

Le fichier comporte des sections distinctes correspondant aux différentes méthodes d'authentification:

credHelpers

Si vous utilisez l'assistant d'identification Docker pour l'authentification Artifact Registry stocke les paramètres de l'assistant d'identification credHelpers du fichier.

auths

Si vous utilisez Docker pour vous connecter avec un jeton ou une clé de compte de service comme mot de passe, Docker stocke une version encodée en base64 de vos identifiants dans la section auths du fichier.

credStore

Si vous avez configuré un magasin d'identifiants pour gérer vos identifiants, les paramètres du magasin d'identifiants se trouvent dans la section credStore du fichier.

Lorsque Docker se connecte à un registre, il recherche d'abord un assistant d'identification associé à l'hôte. Par conséquent, si votre config.json inclut des paramètres de registre d'artefacts dans les sections credHelpers et auths, les paramètres de la section auths sont ignorés.

Assistant d'identification de la gcloud CLI

L'assistant d'identification de la gcloud CLI fournit un accès sécurisé et de courte durée à vos les ressources du projet. Il configure Docker pour s'authentifier auprès des hôtes Artifact Registry dans n'importe quel environnement où la Google Cloud CLI est installée. Cloud Shell comprend la Google Cloud CLI et une version actuelle de Docker.

L'assistant d'identification de la gcloud CLI est la méthode d'authentification la plus simple à configurer. Il configure Docker avec les identifiants de l'utilisateur actif ou du compte de service. dans votre session de gcloud CLI. Puisque cet assistant d'identification dépend gcloud CLI, il peut être beaucoup plus lent assistant d'identification autonome. Pour les builds automatisés avec des outils tiers ou des clients Docker disposant d'un grand nombre utilisez plutôt l'assistant d'identification autonome.

Pour vous authentifier auprès d'Artifact Registry :

1. Connectez-vous à la gcloud CLI en tant qu'utilisateur qui exécutera les commandes Docker.

   • Pour configurer l'authentification avec des identifiants utilisateur, exécutez la commande suivante :

     gcloud auth login
     

   • Pour configurer l'authentification avec des identifiants de compte de service, exécutez la commande suivante :

     gcloud auth activate-service-account ACCOUNT --key-file=KEY-FILE
     

     Où

     • ACCOUNT est le compte de service que vous souhaitez utiliser avec Artifact Registry au format [e-mail] Si vous souhaitez utiliser un compte existant, vous pouvez afficher la liste des services comptes sur le Comptes de service de la console Google Cloud ou à l'aide de la commande gcloud iam service-accounts list
     • KEY-FILE est le fichier de clé du compte de service. Pour en savoir plus sur la création d'une clé, consultez la documentation IAM (Identity and Access Management).
     Remarque : Les clés de compte de service constituent un risque pour la sécurité si elles ne sont pas gérées correctement. Dans la mesure du possible, vous devez choisir une alternative plus sécurisée aux clés de compte de service. Si vous devez vous authentifier avec une clé de compte de service, vous êtes responsable de la sécurité de la clé privée et des autres opérations décrites dans la section Bonnes pratiques pour la gestion des clés de compte de service. Si vous ne parvenez pas à créer une clé de compte de service, la création de clé de compte de service peut être désactivée pour votre organisation. Pour en savoir plus, consultez la page Gérer les ressources d'organisation sécurisées par défaut.

2. Exécutez la commande suivante :

   gcloud auth configure-docker HOSTNAME-LIST
   

   Où HOSTNAME-LIST est une liste de noms d'hôtes de dépôt séparés par une virgule, à ajouter à la configuration de l'assistant d'identification.

   Par exemple, pour ajouter les régions us-west1 et asia-northeast1, exécutez la commande suivante :

   gcloud auth configure-docker us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
   

   Les noms d'hôte spécifiés sont ajoutés à la configuration de l'assistant d'identification. Vous pourrez ajouter ultérieurement d'autres noms d'hôte à la configuration en exécutant la commande à nouveau.

   Pour afficher la liste des emplacements de dépôt acceptés, exécutez la commande suivante :

   gcloud artifacts locations list
   

3. La commande affiche la section credHelpers de votre fichier Docker actuel et la configuration mise à jour après l'ajout des noms d'hôte.

   Pour accepter les modifications de configuration, saisissez y.

   Vos identifiants sont enregistrés dans votre répertoire d'accueil utilisateur.

   • Linux : $HOME/.docker/config.json
   • Windows : %USERPROFILE%/.docker/config.json

4. Docker requiert que les assistants d'identification se trouvent dans le PATH système. Vérifiez que la commande gcloud se trouve dans le système PATH.

Remarque :Si vous exécutez normalement des commandes Docker sous Linux avec sudo, Docker recherche pour les identifiants Artifact Registry dans /root/.docker/config.json sur $HOME/.docker/config.json. Si vous souhaitez utiliser sudo avec des commandes docker au lieu d'utiliser le groupe de sécurité Docker, configurez plutôt les identifiants avec sudo gcloud auth configure-docker.

Assistant d'identification autonome

L'assistant d'identification Docker autonome configure Docker pour l'authentification vers Artifact Registry sur un système où la gcloud CLI n'est pas disponible. Il est beaucoup plus rapide que l'assistant d'identification de la gcloud CLI. et utilise les identifiants par défaut de l'application (ADC) pour trouver automatiquement dans votre environnement. Pour les opérations autres que le transfert et extraire des images, par exemple en leur ajoutant des tags ou en listant des images. Nous vous recommandons d'utiliser méthode d'authentification pour les builds automatisés avec des outils tiers ou Docker avec un grand nombre d'hôtes de registre configurés.

L'assistant d'identification Docker autonome récupère vos identifiants Artifact Registry et les écrit dans le fichier de configuration Docker. Ainsi, vous pouvez utiliser l'outil de ligne de commande Docker, docker, pour interagir directement avec Artifact Registry.

Pour utiliser l'assistant d'identification Docker :

1. Connectez-vous à l'ordinateur en tant que l'utilisateur qui exécutera les commandes Docker.

2. Téléchargez l'assistant d'identification Docker autonome depuis GitHub

   Vous pouvez éventuellement utiliser l'utilitaire de ligne de commande curl. Exemple :

   VERSION=2.1.25
   OS=linux  # or "darwin" for OSX, "windows" for Windows.
   ARCH=amd64  # or "386" for 32-bit OSs
   
   curl -fsSL "https://github.com/GoogleCloudPlatform/docker-credential-gcr/releases/download/v${VERSION}/docker-credential-gcr_${OS}_${ARCH}-${VERSION}.tar.gz" \
   | tar xz docker-credential-gcr \
   && chmod +x docker-credential-gcr && sudo mv docker-credential-gcr /usr/bin/
   

3. Configurez Docker pour qu'il utilise vos informations d'identification Artifact Registry lors de l'interaction avec Artifact Registry (action à effectuer une seule fois) :

   docker-credential-gcr configure-docker --registries=HOSTNAME-LIST
   

   Où HOSTNAME-LIST est une liste de dépôts séparés par une virgule à ajouter à la configuration de l'assistant d'identification.

   Par exemple, pour ajouter les régions us-west1 et asia-northeast1, exécutez la commande suivante :

   docker-credential-gcr configure-docker --registries=us-west1-docker.pkg.dev,asia-northeast1-docker.pkg.dev
   

   Les noms d'hôte spécifiés sont ajoutés à la configuration de l'assistant d'identification. Vous pouvez ajouter d'autres noms d'hôte à la configuration plus tard en exécutant à nouveau la commande.

   Pour afficher la liste des emplacements de dépôt acceptés, exécutez la commande suivante :

   gcloud artifacts locations list
   

   Pour en savoir plus, consultez la documentation de l'assistant d'identification Docker autonome sur GitHub.

   Remarque : Si vous exécutez généralement des commandes Docker sous Linux avec sudo, Docker recherche les identifiants Artifact Registry dans /root/.docker/config.json au lieu de $HOME/.docker/config.json. Si vous souhaitez utiliser sudo avec des commandes docker au lieu d'utiliser le groupe de sécurité Docker, configurez plutôt les identifiants avec sudo docker-credential-gcr configure-docker.

   Vos identifiants sont enregistrés dans votre répertoire d'accueil utilisateur.

   • Linux : $HOME/.docker/config.json
   • Windows : %USERPROFILE%/.docker/config.json

4. Docker requiert que les assistants d'identification se trouvent dans le PATH système. Vérifiez que la commande docker-credential-gcr se trouve dans le système PATH.

5. Pour vérifier que l'assistant d'identification peut récupérer votre les identifiants, exécutez la commande suivante:

   echo "https://HOSTNAME" | docker-credential-gcr get
   

   Remplacez HOSTNAME par un nom d'hôte que vous avez ajouté au configuration. Exemple :

   echo "https://us-west1-docker.pkg.dev" | docker-credential-gcr get
   

   Si la commande aboutit, la sortie JSON renvoyée inclut un jeton dans le champ Secret. Exemple :

   {"ServerURL":"https://us-west1-docker.pkg.dev","Username":"_dcgcr_2_0_0_token","Secret":"ya29..."}
   

Docker est à présent configuré pour s'authentifier avec Artifact Registry. Pour transmettre et extraire des images, assurez-vous que les autorisations sont correctement configurés.

Jeton d'accès

Vous pouvez générer un jeton d'accès OAuth de courte durée pour vous authentifier auprès d'Artifact Registry. Comme le jeton est valide pendant 60 minutes, vous devez la demander moins d'une heure avant de l'utiliser pour vous connecter à Artifact Registry.

Pour utiliser un jeton d'accès avec des identifiants de compte de service :

1. Créez un compte de service pour agir au nom de votre application ou sélectionnez un compte de service existant que vous utilisez pour l'automatisation.

2. Accordez le rôle Artifact Registry spécifique. au compte de service pour fournir l'accès au dépôt.

3. Générez un jeton d'accès pour le compte de service, puis authentifiez-vous:

   • Vous devez disposer des autorisations du rôle Créateur de jetons du compte de service (roles/iam.serviceAccountTokenCreator) jusqu'à emprunter l'identité d'un compte de service ; pour obtenir un jeton, puis vous authentifier en tant que compte de service.

     Exécutez la commande suivante en remplaçant ACCOUNT par votre adresse e-mail du compte de service et LOCATION régional ou multirégional emplacement de dans le dépôt.

     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 |
         docker login -u oauth2accesstoken --password-stdin https://LOCATION-docker.pkg.dev
     

Docker est désormais authentifié avec Artifact Registry.

Clé de compte de service

Remarque :Si possible, utilisez un jeton d'accès ou un assistant d'identification pour réduire le risque d'accès non autorisé à vos artefacts. Les clés de compte de service constituent un risque pour la sécurité si elles ne sont pas gérées correctement. Dans la mesure du possible, vous devez choisir une alternative plus sécurisée aux clés de compte de service. Si vous devez vous authentifier avec une clé de compte de service, vous êtes responsable de la sécurité de la clé privée et des autres opérations décrites dans la section Bonnes pratiques de gestion des clés de compte de service. Si vous ne parvenez pas à créer une clé de compte de service, la création de clé de compte de service peut être désactivée pour votre organisation. Pour en savoir plus, consultez Gérer les ressources d'organisation sécurisées par défaut

Toute personne ayant accès à une clé privée valide pour un compte de service peut accéder aux ressources via le compte de service. Notez que le cycle de vie de l'accès de la clé au compte de service (et par conséquent, aux données auxquelles le compte de service a accès) est indépendant du cycle de vie de l'utilisateur ayant téléchargé la clé.

Suivez les instructions ci-dessous pour limiter l'accès à vos dépôts :

• Créer des comptes de service dédiés permettant uniquement d'interagir avec les dépôts.
• Accordez le champ d'application Rôle Artifact Registry pour l'accès requis par le compte de service. Par exemple, un compte de service qui ne télécharge que des artefacts ne nécessite que le rôle de lecteur Artifact Registry.
• Configurez les autorisations de vos comptes de service dédiés sur chaque dépôt plutôt qu'au niveau du projet. Vous pouvez ensuite spécifier l'accès en fonction du contexte du dépôt. Par exemple, un compte de service pour les builds de développement peuvent disposer du rôle "Lecteur Artifact Registry" un dépôt de production et le rôle "Rédacteur Artifact Registry" un dépôt de préproduction.
• Suivez les bonnes pratiques de gestion des identifiants.

Pour créer un nouveau compte de service et une clé de compte de service à n'utiliser qu'avec les dépôts Artifact Registry, procédez comme suit :

1. Créez un compte de service pour agir au nom de votre application ou sélectionnez un compte de service existant que vous utilisez pour l'automatisation.

   Vous aurez besoin de l'emplacement du fichier de clé de compte de service pour configurer l'authentification avec Artifact Registry. Pour les comptes existants, vous pouvez afficher les clés et en créer sur la page "Comptes de service".

   Accéder à la page "Comptes de service"

   Remarque : Les clés de compte de service constituent un risque pour la sécurité si elles ne sont pas gérées correctement. Dans la mesure du possible, vous devez choisir une alternative plus sécurisée aux clés de compte de service. Si vous devez vous authentifier avec une clé de compte de service, vous êtes responsable de la sécurité de la clé privée et des autres opérations décrites dans la section Bonnes pratiques pour la gestion des clés de compte de service. Si vous ne parvenez pas à créer une clé de compte de service, la création de clé de compte de service peut être désactivée pour votre organisation. Pour en savoir plus, consultez la page Gérer les ressources d'organisation sécurisées par défaut.

2. Vous avez la possibilité d'encoder tous les contenus du fichier de clé en base64.

   Linux

   base64 FILE-NAME > NEW-FILE-NAME
   

   macOS

   base64 -i FILE-NAME -o NEW-FILE-NAME
   

   Windows

   Base64.exe -e FILE-NAME > NEW-FILE-NAME
   

   Où FILE-NAME correspond au nom de fichier de clé d'origine et NEW-FILE-NAME à votre fichier de clé encodé en base64.

3. Vérifiez que les autorisations sont correctement configurées pour le compte de service. Si vous utilisez le compte de service Compute Engine, vous devez configurer correctement les autorisations et les niveaux d'accès.

4. Utilisez la clé de compte de service pour configurer l'intégration avec Docker :

   Exécutez la commande suivante :

   Linux/macOS

   cat KEY-FILE | docker login -u KEY-TYPE --password-stdin \
   https://LOCATION-docker.pkg.dev
   

   Windows

   Get-Content KEY-FILE |
   docker login -u KEY-TYPE --password-stdin https://LOCATION-docker.pkg.dev
   

   Remplacez les éléments suivants :

   • KEY-TYPE est l'un des éléments suivants :
     • _json_key si vous utilisez la clé de compte de service au format JSON tel qu'il a été fourni lors de la création du fichier.
     • _json_key_base64 si vous avez codé en base64 l'ensemble du contenu du fichier.
   • KEY-FILE est le nom du fichier de clé du compte de service au format JSON.
   • LOCATION est le régional ou multirégional emplacement du dépôt où où l'image est stockée.

Docker est désormais authentifié avec Artifact Registry.