Comment démarrer avec l’API Docker Engine

Docker Engine fournit une API REST que vous pouvez utiliser pour gérer vos conteneurs sans dockerCLI. L’API fournit des fonctionnalités équivalentes à l’aide d’appels réseau HTTP. Vous pouvez créer des opérations Docker standard à l’aide de votre langage de programmation préféré ou gérer l’un de vos hôtes à distance. La CLI s’appuie en interne sur la même API pour fournir ses commandes intégrées.

Dans cet article, nous aborderons les bases de l’activation et de l’utilisation de l’API. Si vous avez un cas d’utilisation spécifique à l’esprit, veuillez vous référer à la documentation de référence de l’API pour déterminer les points de terminaison dont vous avez besoin.

Activation de l’API du moteur Docker

L’API est intégrée à Docker Engine. Tout hôte Docker en cours d’exécution est déjà prêt à interagir avec l’API. Pour exposer le service, vous devez lier le démon Docker à un socket TCP, ainsi qu’au socket Unix par défaut ou à la place. Commencez dockerdpar un -Hindicateur pour spécifier sur quelles sockets écouter :

sudo dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375

Cette commande expose l’API sur le port 2375. Le socket Unix est conservé par défaut, de sorte que la CLI Docker continuera à fonctionner sans aucune reconfiguration. Le port 2375 est utilisé par convention pour Docker ; n’hésitez pas à le modifier pour l’adapter à votre environnement.

Vous pouvez faire en sorte que Docker démarre toujours avec ces paramètres en modifiant systemdle fichier de configuration du service. Modifiez ou créez /etc/systemd/system/docker.service.d/options.conf, recherchez ExecStartla ligne et modifiez-la pour inclure des indicateurs supplémentaires :

[Service]

ExecStart=/usr/bin/dockerd -H unix:///var/run/docker.sock -H tcp://0.0.0.0:2375

Rechargez systemdla configuration pour appliquer les modifications :

sudo systemctl daemon-reload

Vous êtes maintenant prêt à interagir avec l’API Docker Engine dans 127.0.0.1:2375.

Consigne de sécurité

Les étapes ci-dessus exposent l’API sans aucune protection. Toute personne ayant accès au port 2375 sur votre hôte peut envoyer des commandes arbitraires au démon Docker, démarrer de nouveaux conteneurs, remplir votre disque avec des images ou supprimer des charges de travail existantes.

Vous devez configurer votre pare-feu pour bloquer les connexions au port, sauf si vous exposez intentionnellement Docker à votre réseau. Si vous souhaitez activer l’accès à distance, vous devez configurer TLS sur le socket démon pour limiter l’accès aux clients authentifiés.

Lorsque TLS est activé, vous devrez installer l’autorité de certification de votre démon sur chacun de vos clients. Vous devrez fournir un certificat client et une clé client avec chaque demande que vous ferez. Les étapes à suivre dépendent de l’outil que vous utilisez. Voici un exemple pour curl:

curl https://127.0.0.1:2375/v1.41/containers/json --cert client-cert.pem --key client-key.pem

Vous n’aurez peut-être pas du tout besoin de lier un socket TCP, selon votre cas d’utilisation. Si votre client prend en charge les sockets Unix, vous pouvez utiliser un socket Docker existant pour vous connecter :

curl --unix-socket /var/run/docker.sock http://localhost/v1.41/containers

Cela peut être un choix plus sûr que le risque d’ouvrir par inadvertance un socket TCP.

Utilisation de l’API

L’API utilise des points de terminaison versionnés afin que vous puissiez vous lier à des versions spécifiques des formats de demande et de réponse. Vous devez spécifier la version que vous utilisez au début de chaque URL de point de terminaison. La v1.41 est la dernière version présente dans les versions de production de Docker au moment de la rédaction.

http://127.0.0.1:2375/v1.41

Les points de terminaison d’API sont regroupés en blocs fonctionnels REST. Ils correspondent aux types d’objets Docker de base tels que les conteneurs, les images et les volumes. Vous pouvez généralement trouver l’API d’un type d’objet spécifique dans l’URL de base qui commence par son nom :

# APIs related to container operations

http://127.0.0.1:2375/v1.41/containers

L’API utilise JSON pour toutes les communications avec votre client HTTP. Les points de terminaison acceptent les corps de requête JSON et renvoient des réponses JSON. Cela devrait faciliter le traitement des données dans vos applications puisque vous pouvez utiliser la bibliothèque JSON incluse avec votre environnement de programmation. Des outils similaires jqpeuvent être utilisés pour compresser, filtrer et trier les réponses si vous expérimentez avec votre terminal.

Points finaux communs

Étant donné que l’API réplique la fonctionnalité de l’interface de ligne de commande Docker, il existe trop de points de terminaison possibles pour tous les couvrir ici. Au lieu de cela, nous allons démontrer quelques-unes des options les plus couramment utilisées liées aux fonctionnalités principales de Docker.

Liste des conteneurs

Une liste complète des conteneurs sur l’hôte peut être obtenue à partir du point de /containers/jsonterminaison :

curl http://127.0.0.1:2375/v1.41/containers/json

Par défaut, il affiche uniquement les conteneurs en cours d’exécution. Ajoutez all=trueà la chaîne de requête pour inclure également les conteneurs arrêtés. Limitez le nombre total de conteneurs renvoyés limitpar un paramètre, tel que limit=10. Seuls les 10 derniers conteneurs créés seront inclus.

Plusieurs filtres différents sont disponibles pour réduire la liste aux conteneurs avec des attributs spécifiques. Ils sont installés avec la syntaxe suivante :

curl http://127.0.0.1:2375/v1.41/containers/json?filters={"name":"demo"}

Cette URL renvoie des informations relatives au democonteneur. D’autres filtres peuvent être exprimés de manière similaire, par exemple {"status":["running","paused"]}pour démarrer et mettre en pause des conteneurs, ou {"health=["healthy"]}uniquement des conteneurs sains.

Démarrer un nouveau conteneur

L’exécution d’un conteneur est un processus en deux étapes lors de l’utilisation de l’API. Vous devez d’abord créer un conteneur, puis l’exécuter dans un appel d’API séparé.

Créez votre conteneur en envoyant POSTune demande au point de /containers/createterminaison. Cela nécessite un corps JSON avec des champs correspondant aux drapeaux acceptés par la docker runcommande CLI.

Voici un exemple minimal de création d’un conteneur :

curl http://127.0.0.1:2375/v1.41/containers/create

-X POSTE

-H « Type de contenu : application/json »

-d '{"Image": "example-image:latest"}'

La réponse JSON inclura l’ID du nouveau conteneur et tous les avertissements générés lors de sa création. Envoyez l’ID dans un appel au point de /containers/:id/startterminaison :

curl http://127.0.0.1:2375/v1.41/containers/abc123/start -X POST

Le conteneur va maintenant s’exécuter sur l’hôte Docker.

Nettoyage de conteneur

Supprimez les conteneurs arrêtés en envoyant POSTune requête au point de /containers/pruneterminaison :

curl http://127.0.0.1:2375/v1.41/containers/prune -X POST

Vous recevrez une réponse JSON avec les champs ContainersDeletedet . est un tableau d’ID de conteneurs qui ont été supprimés avec succès. vous informe de la quantité totale de mémoire libérée en octets.SpaceReclaimedContainersDeletedSpaceReclaimed

Ce point de terminaison accepte deux paramètres de chaîne de requête pour restreindre l’opération. Le paramètre untillimite la suppression aux conteneurs créés avant l’heure spécifiée, tels que until=10mou until=2022-03-01. L’option labelfiltre les conteneurs avec ou sans les étiquettes spécifiées ; le réglage label=demo=examplene supprimera que les conteneurs avec demo=examplel’étiquette.

Liste d’images

Le point de terminaison /images/jsonest utilisé pour énumérer les images stockées sur l’hôte Docker :

curl http://127.0.0.1:2375/v1.41/images/json

Vous pouvez utiliser des filtres pour modifier le contenu de la réponse. Ils sont fournis en tant qu’objet JSON dans filtersun paramètre de chaîne de requête, similaire à l’API Container List. Une option intéressante consiste à referencesélectionner une image avec une balise donnée : filters={"reference":"hello-world:latest"}.

Construire des images

Vous pouvez utiliser l’API pour créer de nouvelles images Docker à partir de Dockerfiles. L’ archive /builddoit être envoyée au point de terminaison . tarLe contenu de cette archive sera utilisé comme contexte de création d’image. L’archive doit contenir un Dockerfile avec les instructions de construction.

cat context.tar | curl http://127.0.0.1:2375/v1.41/build?t=example-image:latest -X POST

La commande ci-dessus enverra context.tarau démon Docker et construira l’image en utilisant l’ Dockerfileintérieur. L’image sera étiquetée example-image:latestet enregistrée sur l’hôte Docker.

Ce point de terminaison accepte une variété d’options de chaîne de requête supplémentaires pour correspondre à la fonctionnalité docker buildde l’interface de ligne de commande. Celles-ci incluent dockerfile=path/to/dockerfilede spécifier le chemin d’accès au Dockerfile du contexte de génération rm=true, qui supprime les conteneurs intermédiaires créés par la génération, et pull=trued’essayer d’obtenir des versions mises à jour des images référencées par le Dockerfile.

L’API exige que votre client reste connecté jusqu’à ce que la construction soit terminée. La construction sera annulée si le réseau tombe en panne et que la connexion est fermée.

Liste des journaux d’événements de démon

L’API /eventsaffiche les données du journal des événements du démon, qui sont également disponibles via la docker eventscommande CLI. Ce point de terminaison diffuse les événements en temps réel au fur et à mesure qu’ils se produisent.

curl http://127.0.0.1:2375/v1.41/events

Plusieurs types d’événements différents sont fournis, notamment la création de conteneurs, les balises d’image, les montages de volumes et les modifications de réseau. Vous pouvez filtrer les événements d’un type spécifique à l’aide du typechamp filtersparamètre de requête :

# Only get container events

curl http://127.0.0.1:2375/v1.41/events?filters={'type':'container'}

Vous pouvez également restreindre les événements liés à un objet spécifique :

# Get events pertaining to the container with ID abc123

curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}

Les deux autres paramètres de chaîne de requête sinceet untilvous permettent de spécifier une plage d’horodatages pour afficher les événements historiques.

Obtenir des informations sur le système

L’API Docker Engine peut être utilisée pour obtenir des informations sur l’hôte physique sur lequel elle s’exécute :

curl http://127.0.0.1:2375/v1.41/info

Ce point de terminaison fournit des informations détaillées décrivant l’état et la configuration actuels de l’hôte et du démon Docker. Les champs de la réponse incluent le nombre de conteneurs en cours d’exécution, en pause et arrêtés, le chemin d’accès au répertoire d’installation de Docker, les détails du matériel et du système d’exploitation, ainsi que la configuration du serveur Swarm lorsqu’il s’exécute dans un cluster.

Conclusion

L’API Docker Engine vous permet d’envoyer des commandes au démon Docker de votre hôte via HTTP. Cela facilite la création de scripts d’interactions programmatiques sans s’appuyer sur certains comportements Docker CLI. L’API peut également être utilisée pour gérer à distance les serveurs Docker pour une surveillance améliorée et une maintenance simplifiée.

Bien que l’appel de l’API soit facile, vous devez faire attention à la sécurisation de votre socket TCP. Évitez d’ouvrir un socket sur votre réseau à moins qu’il ne soit sécurisé avec TLS afin que seuls les clients approuvés puissent s’y connecter. Ignorer cette étape de configuration supplémentaire peut s’avérer coûteux si un attaquant découvre votre instance de démon et commence à émettre des commandes.

Vous pouvez rendre encore plus facile l’utilisation de l’API dans vos applications en implémentant l’un des . Pour tous les langages de programmation courants, y compris C, C#, C++, Go, Java, NodeJS, PHP, Python et Ruby, une version officielle ou fournie par la communauté est disponible. Les SDK encapsulent les points de terminaison d’API dans des classes et des fonctions pratiques à appeler à partir du code, réduisant ainsi le passe-partout requis pour interagir avec une installation Docker.