Configurer l'authentification pour Docker

Cette page explique comment configurer Docker pour qu'il s'authentifie auprès des dépôts Docker Artifact Registry.

Vous n'avez pas besoin de configurer l'authentification pour les environnements d'exécution Cloud Build ou Google Cloud tels que Google Kubernetes Engine et Cloud Run, mais vous devez vérifier que les autorisations requises sont configurées. (Installation de Python groupée).

Avant de commencer

  1. Activez l'API Artifact Registry et installez le SDK Cloud. Pour obtenir des instructions, consultez la page Activer et désactiver le service.
  2. Si le dépôt cible n'existe pas, créez un dépôt.
  3. Installez et initialisez le SDK Cloud.
  4. (Facultatif) Configurez des valeurs par défaut pour les commandes gcloud.
  5. Vérifiez que le compte que vous utilisez pour l'authentification dispose des autorisations requises pour accéder à Artifact Registry. Nous vous recommandons d'utiliser un compte de service plutôt qu'un compte utilisateur.
  6. Installez Docker si ce n'est pas encore fait. Docker est inclus dans Cloud Shell.
  7. 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
    

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

Choisir une méthode d'authentification

Les méthodes d'authentification suivantes sont disponibles :

Outil d'aide à la connexion gcloud
Configurez vos identifiants Artifact Registry à utiliser avec Docker directement dans gcloud. 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 du SDK Cloud. Il est nettement plus rapide que l'assistant d'identification gcloud et utilise les identifiants par défaut de l'application (ADC) pour rechercher automatiquement des 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 l'utiliser pour l'authentification par mot de passe. Comme le jeton n'est valide que pendant 60 minutes, 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 un compte de service. 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.

Lorsque cela est possible, utilisez un jeton d'accès ou un assistant d'identification pour réduire le risque d'accès non autorisé à vos images de conteneur. Si vous devez utiliser une clé de compte de service, assurez-vous de suivre les bonnes pratiques de gestion des identifiants.

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 pour les différentes méthodes d'authentification:

credHelpers
Si vous utilisez l'assistant d'identification Docker pour s'authentifier, Artifact Registry stocke les paramètres de l'assistant d'identification dans la section 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 leauths du fichier.
credStore
Si vous avez configuré un stockage 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. Ainsi, si votre fichier config.json inclut des paramètres Artifact Registry dans les sections credHelpers et auths, les paramètres de la section auths sont ignorés.

Assistant d'identification gcloud

L'assistant d'identification gcloud fournit un accès sécurisé et de courte durée aux ressources de votre projet. Il configure Docker de façon à s'authentifier auprès des hôtes Artifact Registry dans tous les environnements où le SDK Cloud est installé. Cloud Shell inclut le SDK Cloud et une version actuelle de Docker.

Il s'agit de 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 gcloud. Étant donné que cet assistant d'identification dépend de l'outil gcloud, il peut être considérablement plus lent que l'assistant autonome. Pour les builds automatisés avec des outils tiers ou des clients Docker disposant d'un grand nombre d'hôtes de registre configurés, utilisez plutôt l'assistant d'identification autonome.

Pour vous authentifier auprès d'Artifact Registry :

  1. Connectez-vous au SDK Cloud 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 nom du compte de service au format USERNAME@PROJECT-ID.iam.gserviceaccount.com. Vous pouvez afficher les comptes de service existants sur la page Comptes de service de Cloud Console ou avec 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).
  2. Exécutez la commande suivante :

    gcloud auth configure-docker HOSTNAME-LIST
    

    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-central1 et asia-northeast1, exécutez la commande suivante :

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

    Les noms d'hôtes spécifiés sont ajoutés à la configuration de l'assistant d'identification. Vous pourrez ajouter d'autres noms d'hôte à la configuration ultérieurement 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
    
  3. La commande affiche la section credHelpers de votre configuration Docker actuelle et la configuration mise à jour après l'ajout des noms d'hôte spécifiés.

    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.

Assistant d'identification autonome

L'assistant d'identification Docker autonome configure Docker pour s'authentifier auprès de Artifact Registry sur un système sur lequel le SDK Cloud n'est pas disponible. Il est nettement plus rapide que l'assistant d'identification gcloud et utilise l'identifiant par défaut de l'application (ADC) pour rechercher automatiquement des identifiants dans votre environnement. Pour les opérations autres que le transfert et l'extraction d'images, tels que l'ajout de tags ou le référencement d'images. Nous vous recommandons d'utiliser cette méthode d'authentification pour les builds automatisés avec des outils tiers ou des clients Docker disposant d'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 à partir de GitHub.

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

    VERSION=2.1.0
    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 --to-stdout ./docker-credential-gcr \
    > /usr/bin/docker-credential-gcr && chmod +x /usr/bin/docker-credential-gcr
    
  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
    

    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-central1 et asia-northeast1, exécutez la commande suivante :

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

    Les noms d'hôtes spécifiés sont ajoutés à la configuration de l'assistant d'identification. Vous pourrez ajouter d'autres noms d'hôte à la configuration ultérieurement 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.

    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 bien récupérer vos 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é à la configuration. Exemple :

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

    Si la commande réussit, le résultat JSON renvoyé inclut un jeton dans le champ Secret. Exemple :

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

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

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 le 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, 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"

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

  3. Générez un jeton d'accès pour le compte de service en utilisant l'une des options suivantes:

    • Si vous disposez des autorisations du rôle Créateur de jetons de compte de service (roles/iam.serviceAccountTokenCreator), vous pouvez emprunter l'identité d'un compte de service pour obtenir un jeton. s'authentifier en tant que compte de service ;

      Linux

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

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

      Windows

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

      gcloud auth print-access-token
          --impersonate-service-account ACCOUNT
      
      ya29.8QEQIfY_...
      
      docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
      https://LOCATION-docker.pkg.dev
      
    • Activez un compte de service dans votre session gcloud, puis obtenez un jeton d'accès.

      1. Activez le compte de service que vous souhaitez utiliser. Remplacez ACCOUNT par l'adresse e-mail de votre compte de service et KEY-FILE par le nom de fichier de votre clé de compte de service.

        gcloud auth activate-service-account ACCOUNT \
            --key-file=KEY-FILE
        
      2. Obtenez un jeton d'accès en tant qu'identifiant lorsque vous vous authentifiez auprès d'Artifact Registry avec Docker.

      3. Générer un jeton et s'authentifier auprès du dépôt

        Linux

        Exécutez la commande suivante en remplaçant LOCATION par l'emplacement régional ou multirégional du dépôt.

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

        Windows

        Exécutez la commande suivante en remplaçant LOCATION par l'emplacement régional ou multirégional du dépôt.

        gcloud auth print-access-token
        ya29.8QEQIfY_...
        
        docker login -u oauth2accesstoken -p "ya29.8QEQIfY_..." \
            https://LOCATION-docker.pkg.dev
        

Docker est désormais authentifié avec Artifact Registry.

Clé de compte de service

Une clé de compte de service est une paire de clés à longue durée de vie que vous pouvez utiliser comme identifiant de compte de service. Contrairement au jeton d'accès OAuth, la clé du compte de service n'expire pas. Vous êtes responsable de la sécurité de la clé privée et des autres opérations de gestion des clés, par exemple leur rotation.

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 rôle Artifact Registry spécifique à 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 compilations de développement peut avoir le rôle de lecteur Artifact Registry pour un dépôt de production et le rôle de rédacteur Artifact Registry pour 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"

  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
    

    FILE-NAME est le nom du fichier de clé d'origine et NEW-FILE-NAME est 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 :

    Linux/macOS

    Exécutez la commande suivante :

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

    Ou, pour les clients Docker plus anciens non compatibles avec --password-stdin :

    docker login -u KEY-TYPE -p "$(cat FILE-NAME.json)" \
    https://LOCATION-docker.pkg.dev
    

    Où :

    • KEY-TYPE est l'un des éléments suivants :
      • _json_key si vous utilisez la clé du 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 l'emplacement régional ou multirégional du dépôt où l'image est stockée.

    Windows

    Exécutez la commande suivante :

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

    Ou, pour les clients Docker plus anciens non compatibles avec --password-stdin :

    set /p PASS=<KEY-FILE
    docker login -u KEY-TYPE -p "%PASS%" https://LOCATION-docker.pkg.dev
    

    Où :

    • KEY-TYPE est l'un des éléments suivants :
      • _json_key si vous utilisez la clé du 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 l'emplacement régional ou multirégional du dépôt où l'image est stockée.

Docker est désormais authentifié avec Artifact Registry.