Configurer l'authentification pour Docker

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

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. Toutefois, vous devez vérifier que les autorisations requises sont configurées.

Avant de commencer

  1. Activez l'API Artifact Registry et installez la CLI gcloud. Pour savoir comment procéder, 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 Google Cloud CLI.
  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 d'accès à 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 :

gcloud credential helper
Configurez vos identifiants Artifact Registry à utiliser avec Docker directement dans gcloud. Bien que cette méthode d'authentification soit la plus simple, 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. Il est beaucoup plus rapide que l'assistant d'identification gcloud et utilise les identifiants par défaut de l'application (ADC) pour trouver 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. Étant donné que le jeton n'est valide que pendant 60 minutes, il constitue 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 outil d'aide à la connexion pour réduire le risque d'accès non autorisé à vos images de conteneurs. 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 contient différentes sections correspondant à 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 cet outil 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 de vos identifiants encodée en base64 dans la section auths du fichier.
credStore
Si vous avez configuré un magasin d'identifiants pour gérer vos identifiants, vous trouverez ses paramètres 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 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 à vos ressources de projet. Il configure Docker pour s'authentifier auprès des hôtes Artifact Registry dans tous les environnements où Google Cloud CLI est installé. Cloud Shell inclut la CLI Google Cloud et une version actuelle de Docker.

L'assistant d'identification gcloud est la méthode d'authentification la plus simple à configurer. Il configure Docker avec les identifiants de l'utilisateur ou du compte de service actifs dans votre session gcloud. Étant donné que cet outil d'aide à la connexion dépend de gcloud, il peut être considérablement plus lent que l'assistant d'identification 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 à la CLI gcloud 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
      

      • ACCOUNT est le compte de service que vous souhaitez utiliser avec Artifact Registry au format USERNAME@PROJECT-ID.iam.gserviceaccount.com. Si vous souhaitez utiliser un compte existant, vous pouvez afficher la liste des comptes de service sur la page Comptes de service de Google Cloud Console 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).
  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ôte 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ôtes 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 d'Artifact Registry sur un système où la CLI gcloud n'est pas disponible. Il est considérablement 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. Pour les opérations autres que le transfert et l'extraction d'images, telles que l'ajout de tags ou l'affichage 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 sur GitHub.

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

    VERSION=2.1.6
    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
    

    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ôte 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 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 aboutit, la sortie JSON renvoyée 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 temporaire pour s'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 les identifiants du 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.

    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. Attribuez le rôle Artifact Registry approprié au compte de service que vous souhaitez utiliser avec Artifact Registry.

  3. Générez un jeton d'accès pour le compte de service et authentifiez-vous à l'aide de l'une des options suivantes:

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

      Exécutez la commande suivante en remplaçant ACCOUNT par l'adresse e-mail de votre compte de service et LOCATIONl'emplacement régional ou multirégional du 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
      
    • 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. Générer un jeton et s'authentifier

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

        Linux

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

        Windows

        gcloud auth print-access-token |
            docker login -u oauth2accesstoken --password-stdin 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, une clé de 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.
  • Attribuez le rôle Artifact Registry spécifique 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 compilations de développement peut disposer du rôle de lecteur Artifact Registry pour un dépôt de production et du rôle de rédacteur d'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 :

    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é du compte de service au format JSON tel qu'il vous 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.