Comment démarrer avec l’API Docker Engine

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

Dans cet article, nous examinerons les bases de l’activation et de l’utilisation de l’API. Si vous avez un cas d’utilisation spécifique en tête, reportez-vous à la documentation de référence de l’API pour identifier les points de terminaison dont vous avez besoin.

Activation de l’API de Docker Engine

L’API est intégrée à Docker Engine. Tout hôte Docker fonctionnel est déjà prêt à répondre aux interactions API. Pour exposer le service, vous devez lier le démon Docker à un socket TCP en plus ou à la place du socket Unix par défaut. Commencer dockerd avec le -H drapeau pour spécifier les 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 par défaut est conservé afin que la CLI Docker continue à fonctionner sans aucune reconfiguration. Le port 2375 est utilisé pour Docker par convention ; n’hésitez pas à le modifier en fonction de votre environnement.

Vous pouvez faire en sorte que Docker démarre toujours avec ces paramètres en modifiant son systemd fichier de configuration des services. Modifier ou créer /etc/systemd/system/docker.service.d/options.conftrouvez le ExecStart ligne et modifiez-la pour inclure vos drapeaux supplémentaires :

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

Rechargez votre systemd configuration pour appliquer le changement :

sudo systemctl daemon-reload

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

Une note sur la 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 d’images ou détruire des charges de travail existantes.

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

Lorsque TLS est activé, vous devez installer l’autorité de certification de votre démon sur chacun de vos clients. Vous devrez fournir le certificat client et la clé client avec chaque demande que vous faites. 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 en fonction de votre cas d’utilisation. Si votre client prend en charge les sockets Unix, vous pouvez utiliser celui existant de Docker pour établir vos connexions :

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

Cela peut être un choix plus sûr que de risquer d’exposer involontairement un socket TCP.

Utilisation de l’API

L’API utilise des points de terminaison versionnés afin que vous puissiez épingler des versions spécifiques des formats de demande et de réponse. Vous devez indiquer 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 unités fonctionnelles REST. Ceux-ci correspondent aux types d’objets fondamentaux de Docker tels que les conteneurs, les images et les volumes. Vous pouvez généralement trouver les API pour 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 tous les échanges de données avec votre client HTTP. Les points de terminaison acceptent les corps de requête JSON et émettent des réponses JSON en retour. Cela devrait simplifier la gestion des données dans vos applications car vous pouvez utiliser la bibliothèque JSON incluse dans votre environnement de programmation. Des outils comme jq peut être utilisé pour condenser, filtrer et trier les réponses si vous expérimentez dans votre terminal.

Points finaux communs

Comme l’API réplique la fonctionnalité de la CLI de Docker, il y a 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 concernant les fonctionnalités de base de Docker.

Répertorier les conteneurs

La liste complète des conteneurs sur l’hôte peut être obtenue auprès du /containers/json point final :

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

Par défaut, il n’affiche que les conteneurs en cours d’exécution. Ajouter all=true à la chaîne de requête pour inclure également les conteneurs arrêtés. Limiter le nombre total de contenants retournés avec le limit paramètre, tel que limit=10. Seuls les 10 conteneurs les plus récemment créés seront inclus.

Plusieurs filtres différents sont disponibles pour élaguer la liste aux conteneurs avec des attributs particuliers. Ceux-ci sont définis avec la syntaxe suivante :

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

Cette URL renvoie les informations associées au demo récipient. D’autres filtres peuvent être exprimés de manière similaire, tels que {"status":["running","paused"]} pour obtenir des conteneurs en cours d’exécution et en pause ou {"health=["healthy"]} uniquement pour les contenants sains.

Démarrer un nouveau conteneur

Le démarrage d’un conteneur est un processus en deux étapes lors de l’utilisation de l’API. Vous devez d’abord créer le conteneur, puis le démarrer dans un appel d’API séparé.

Créez votre contenant en faisant un POST demande au /containers/create point final. Cela nécessite un corps JSON avec des champs qui correspondent aux drapeaux acceptés par le docker run Commande CLI.

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

curl http://127.0.0.1:2375/v1.41/containers/create 
    -X POST 
    -H "Content-Type: application/json" 
    -d '{"Image": "example-image:latest"}'

La réponse JSON inclura l’ID du nouveau conteneur et tous les avertissements résultant de sa création. Envoyez l’ID lors d’un appel au /containers/:id/start point final :

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

Le conteneur sera désormais exécuté sur l’hôte Docker.

Nettoyer les conteneurs

Retirez les conteneurs arrêtés en émettant un POST demande au /containers/prune point final :

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

Vous recevrez une réponse JSON avec ContainersDeleted et SpaceReclaimed des champs. ContainersDeleted est un tableau des ID de conteneur qui ont été supprimés avec succès. SpaceReclaimed vous informe de l’espace de stockage total libéré en octets.

Ce point de terminaison accepte deux paramètres de chaîne de requête pour limiter l’opération. La until paramètre limite la suppression aux conteneurs créés avant une heure donnée, tels que until=10m ou until=2022-03-01. La label filtres d’option aux conteneurs avec ou sans étiquettes données ; paramètre label=demo=example supprimera uniquement les conteneurs avec le demo=example étiquette.

Liste des images

La /images/json endpoint est 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. Ceux-ci sont fournis sous la forme d’un objet JSON dans le filters paramètre de chaîne de requête, similaire à l’API de liste de conteneurs. Une option remarquable est reference qui sélectionne l’image avec un tag donné : filters={"reference":"hello-world:latest"}.

Images de bâtiments

Vous pouvez utiliser l’API pour créer de nouvelles images Docker à partir de Dockerfiles. La /build point final doit recevoir un tar archive. Le contenu de cette archive sera utilisé comme contexte de construction de l’image. L’archive doit inclure Dockerfile contenant les instructions pour la 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.tar au démon Docker et créez une image à l’aide de Dockerfile dans. L’image sera étiquetée comme example-image:latest et stocké sur l’hôte Docker.

Ce point de terminaison accepte de nombreux paramètres de chaîne de requête supplémentaires qui correspondent à la fonctionnalité du docker build CLI. Ceux-ci inclus dockerfile=path/to/dockerfilepour spécifier le chemin d’accès au Dockerfile du contexte de construction, rm=truequi supprime les conteneurs intermédiaires créés par le build, et pull=true pour essayer d’acquérir des versions mises à jour des images référencées par le Dockerfile.

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

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

La /events L’API fait apparaître les données du journal des événements du démon qui sont également accessibles avec le docker events Commande 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 exposés, notamment les créations de conteneurs, les balises d’image, les montages de volume et les modifications de réseau. Vous pouvez filtrer sur un type d’événement spécifique à l’aide de la type domaine de la filters paramètre de requête :

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

Il est également possible de contraindre à des événements relatifs à 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'}

Deux autres paramètres de chaîne de requête, since et untilvous permettent de spécifier une plage d’horodatages pour y 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 détails détaillés 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, suspendus 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 Swarm du serveur lorsqu’il fonctionne 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 simplifie la création de scripts d’interactions programmatiques sans dépendre de comportements Docker CLI spécifiques. L’API peut également être utilisée pour gérer à distance vos serveurs Docker pour une surveillance améliorée et une maintenance simplifiée.

Bien que l’appel de l’API soit simple, vous devez faire attention aux protections de sécurité autour de votre socket TCP. Évitez d’exposer le socket sur votre réseau à moins qu’il ne soit sécurisé avec TLS afin que seuls les clients approuvés puissent se connecter. Omettre cette étape de configuration supplémentaire pourrait s’avérer coûteux si un intrus 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 propres applications en adoptant l’un des SDK. Une option officielle ou fournie par la communauté est disponible pour tous les langages de programmation populaires, y compris C, C#, C++, Go, Java, NodeJS, PHP, Python et Ruby. Les SDK enveloppent les points de terminaison de l’API dans des classes et des fonctions pratiques à appeler à partir de votre code, réduisant ainsi la quantité de passe-partout nécessaire pour interagir avec une installation Docker.