Comment se connecter à Docker Hub et aux registres privés avec la CLI Docker

Une nouvelle installation de Docker utilise par défaut les interactions publiques avec Docker Hub. La connexion vous permet d’accéder à votre contenu privé et de bénéficier de limites de débit moins restrictives pour l’API Docker.

Dans ce guide, nous montrerons comment se connecter à la CLI Docker, couvrant à la fois l’authentification Docker Hub et vos propres registres privés. Nous examinerons également certains des problèmes courants liés au stockage des informations d’identification de Docker.

Connexion à Docker Hub

La connexion à Docker Hub permet à la CLI Docker d’accéder au contenu privé accessible à votre compte. Cela vous donnera également le seuil de limite de taux plus élevé de 200 extractions d’images par six heures, au lieu des 100 extractions par six heures offertes aux clients non authentifiés.

Utilisez le docker login commande pour fournir vos informations d’identification et vous authentifier auprès du serveur :

$ docker login
Username: 
Password:

Vous serez invité à entrer votre nom d’utilisateur et votre mot de passe de manière interactive. Docker essaiera de se connecter à Docker Hub en utilisant les informations d’identification. Tu verras Login Succeeded si les détails sont acceptés. Docker stockera le jeton d’authentification émis dans votre .docker/config.json dossier.

$ docker login

Login Succeeded

Jetons d’accès pour les connexions 2FA

Les comptes Docker Hub avec l’authentification à deux facteurs activée doivent utiliser un jeton d’accès au lieu d’un mot de passe. À l’aide de l’interface utilisateur Web de Docker Hub, cliquez sur l’icône de votre profil en haut à droite et choisissez « Paramètres du compte » dans le menu. Utilisez la barre latérale gauche pour passer à l’onglet « Sécurité ».

Cliquez sur le bouton bleu « Nouveau jeton d’accès » pour créer un jeton d’accès personnel. Prenez soin de noter la clé de jeton qui s’affiche car vous ne pourrez pas la récupérer à l’avenir. Utilisez ce jeton au lieu de votre mot de passe habituel lorsque vous exécutez docker login de retour dans la CLI.

Connexions non interactives

Vous pouvez fournir votre nom d’utilisateur et votre mot de passe en tant qu’indicateurs de ligne de commande :

$ docker login --username demo --password example

Ceci est utile lorsque vous vous connectez par programmation ou dans le cadre d’un pipeline CI. Pour augmenter la sécurité, utilisez le --password-stdin flag pour demander à Docker de lire votre mot de passe à partir de STDIN. Cela vous permet d’insérer un fichier de mot de passe, empêchant ainsi la capture de texte brut dans votre historique de shell et les journaux de travaux CI.

$ cat password.txt | docker login --username demo --password-stdin

Connexion à des registres privés

docker login vous permet également de vous connecter à des registres auto-hébergés. Indiquez le nom d’hôte et le port de votre registre comme premier argument de la commande. Docker Hub est toujours utilisé lorsqu’aucun argument n’est donné.

$ docker login registry.example.com
Username: 
Password:

Vous pouvez toujours utiliser le --username, --passwordet --password-stdin flags lorsque vous travaillez avec des registres personnalisés. Vous pouvez être connecté à plusieurs registres simultanément – répétez docker login commande autant de fois que nécessaire.

Ajout manuel d’informations d’identification

Parfois, vous souhaiterez peut-être vous connecter manuellement à un registre en ajoutant un jeton d’authentification existant au fichier de configuration de Docker. Cela peut être utile dans les environnements CI où vous souhaitez fournir un jeton pré-obtenu en tant que variable de pipeline.

Vous pouvez ajouter vous-même des jetons d’authentification en modifiant votre .docker/config.json dossier. Ajoutez une nouvelle clé pour votre registre dans le auths champ en haut du fichier. Fournissez un objet comme valeur de la clé ; cet objet a besoin d’un seul auth propriété qui contient votre jeton. Voici un exemple pour le registry.example.com enregistrement:

{
    "auths": {
        "registry.example.com": {
            "auth": "aWxtaW9ud..."
        }
    }
}

Vous pouvez ajouter un jeton Docker Hub en utilisant https://index.docker.io/v1/ comme URL de registre.

Plusieurs comptes pour un seul registre

Une limitation importante du mécanisme d’authentification est son exigence que les registres soient mappés un à un avec les comptes d’utilisateurs. Il n’est pas possible nativement d’être connecté simultanément à plusieurs utilisateurs du même registre. Ceci est souvent souhaitable lorsque vous utilisez un registre privé qui sépare les autorisations en projets ou en équipes.

Vous pouvez atténuer le problème en divisant vos informations d’identification en plusieurs fichiers de configuration. La CLI Docker utilise le --config drapeau ou DOCKER_CONFIG variable d’environnement pour déterminer le fichier à charger pour chaque invocation.

# Authenticate as user-1
$ docker --config ~/docker/user-1.conf login registry.example.com --username user-1 --password foobar

# Authenticate as user-2
$ docker --config ~/docker/user-2.conf login registry.example.com --username user-2 --password foobar

# Pull an image from registry.example.com as user-1
$ docker --config ~/docker/user-1.conf pull my-team/my-project:latest

# Push an image to registry.example.com as user-2
$ docker --config ~/docker/user-2.conf push my-team/my-project:latest

Lorsque vous avez de nombreux projets sur lesquels travailler, vous pouvez utiliser un alias de shell ou une fonction pour réécrire docker à une commande qui sélectionne automatiquement le bon fichier de configuration pour votre répertoire de travail.

alias docker="docker --config ~/docker/$(basename $PWD).conf $1"

Aides aux informations d’identification

Docker stocke vos informations d’identification de manière non sécurisée dans ~/.docker/config.json par défaut. Vous pouvez ajouter plus de protection en intégrant un utilitaire d’aide aux informations d’identification. Les assistants activés peuvent gérer les informations d’identification store, getet erase commandes émises par Docker en réponse aux opérations CLI.

Vous pouvez associer un registre à un utilitaire d’assistance particulier à l’aide de la credHelpers champ dans votre fichier de configuration :

{
    "credHelpers": {
        "registry.example.com": "pass"
    }
}

Cet exemple utilise le pass assistant d’identification pour stocker les informations d’identification pour registry.example.com dans Pass au lieu du fichier de configuration. L’assistant Pass est fourni dans le cadre de Docker docker-credential-helpers bundle qui comprend également des intégrations avec le trousseau de clés de macOS, le gestionnaire d’informations d’identification de Windows et le service secret D-Bus.

Déconnecter

Vous pouvez vous déconnecter en supprimant manuellement la section du registre de votre .docker/config.json fichier ou en utilisant le docker logout commande.

$ docker logout

Comme docker login, les déconnexions ciblent Docker Hub par défaut. Vous pouvez vous déconnecter d’un registre privé en passant son nom d’hôte comme seul argument de la commande :

$ docker logout registry.example.com

Problèmes communs

La plupart des problèmes d’authentification Docker proviennent d’informations d’identification manquantes ou non valides. Si vous vous êtes déjà connecté mais que l’authentification ne fonctionne pas, essayez de vous déconnecter et de vous reconnecter :

$ docker logout
# OR
$ docker logout registry.example.com

$ docker login
# OR
$ docker login registry.example.com

Des informations d’identification constamment rejetées peuvent indiquer un problème avec votre compte de registre. Dans le cas de Docker Hub, vérifiez que vous avez suivi les instructions ci-dessus pour utiliser un jeton d’accès personnel au lieu d’un mot de passe avec des comptes protégés par 2FA.

Une confusion peut également survenir lorsque vous avez plusieurs fichiers de configuration Docker. Vérifiez que vous utilisez le --config drapeau ou DOCKER_CONFIG variable d’environnement pour charger la bonne à chaque fois que vous poussez et tirez vos images.

Sommaire

La connexion de Docker CLI à votre compte Docker Hub ou à un registre privé est généralement mieux gérée par le docker login commande. Vous pouvez fournir des informations d’identification de manière interactive, sous forme d’indicateurs ou via un fichier de mots de passe canalisé. Assurez-vous d’utiliser un jeton d’accès personnel au lieu de votre mot de passe si vous avez activé l’authentification à deux facteurs.

Bien qu’il existe une prise en charge transparente de l’authentification auprès de plusieurs registres, travailler avec plusieurs comptes à partir d’un registre est plus fastidieux. Essayez d’utiliser des fichiers de configuration séparés dans la mesure du possible ou configurez votre registre avec des comptes d’utilisateurs spécialement adaptés à chacun de vos environnements.