Cómo comenzar a utilizar la API del motor de Docker

Docker Engine expone una API REST que puede usar para controlar sus contenedores sin la docker CLI. La API expone una funcionalidad equivalente mediante llamadas de red HTTP. Puede crear secuencias de comandos para operaciones comunes de Docker utilizando su lenguaje de programación favorito o controlar de forma remota uno de sus hosts. La CLI se basa internamente en la misma API para proporcionar sus comandos integrados.

En este artículo, veremos los conceptos básicos para habilitar y usar la API. Si tiene un caso de uso específico en mente, consulte el Documentación de referencia de la API para identificar los puntos finales que necesita.

Habilitación de la API de Docker Engine

La API está integrada con Docker Engine. Cualquier host de Docker en funcionamiento ya está preparado para atender las interacciones de la API. Para exponer el servicio, debe vincular el demonio Docker a un socket TCP, así como, o en lugar de, el socket Unix predeterminado. comienzo dockerd con el -H bandera para especificar los sockets para escuchar:

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

Este comando expone la API en el puerto 2375. El socket predeterminado de Unix se mantiene, por lo que la CLI de Docker seguirá funcionando sin ninguna reconfiguración. El puerto 2375 se usa para Docker por convención; no dude en cambiarlo para adaptarlo a su entorno.

Puede hacer que Docker siempre comience con esta configuración editando su systemd archivo de configuración del servicio. Editar o crear /etc/systemd/system/docker.service.d/options.confencuentra el ExecStart y modifíquelo para incluir sus banderas adicionales:

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

recarga tu systemd configuración para aplicar el cambio:

sudo systemctl daemon-reload

Ahora está listo para interactuar con la API de Docker Engine en 127.0.0.1:2375.

Una nota sobre la seguridad

Los pasos anteriores exponen la API sin protección alguna. Cualquiera con acceso al puerto 2375 en su host puede enviar comandos arbitrarios al demonio Docker, iniciar nuevos contenedores, llenar su disco con imágenes o destruir cargas de trabajo existentes.

Debe configurar su firewall para bloquear las conexiones al puerto a menos que esté exponiendo Docker intencionalmente en su red. Si desea habilitar el acceso remoto, debe configurar TLS para que el socket del daemon limite el acceso a los clientes autenticados.

Cuando TLS está habilitado, deberá instalar la autoridad de certificación de su daemon en cada uno de sus clientes. Deberá proporcionar el certificado de cliente y la clave de cliente con cada solicitud que realice. Los pasos a seguir dependerán de la herramienta que esté utilizando. Aquí hay un ejemplo para curl:

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

Es posible que no necesite vincular un socket TCP en absoluto según su caso de uso. Si su cliente es compatible con los sockets de Unix, puede usar el existente de Docker para realizar sus conexiones:

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

Esta puede ser una opción más segura que arriesgarse a la exposición no intencional de un socket TCP.

Uso de la API

los usos de la API puntos finales versionados para que pueda anclar versiones específicas de formatos de solicitud y respuesta. Debe indicar la versión que está utilizando al comienzo de cada URL de punto final. v1.41 es la última versión presente en las compilaciones de producción de Docker en el momento de escribir este artículo.

http://127.0.0.1:2375/v1.41

Los puntos finales de la API se agrupan en unidades funcionales REST. Estos se asignan a los tipos de objetos fundamentales de Docker, como contenedores, imágenes y volúmenes. Por lo general, puede encontrar las API para un tipo de objeto específico dentro de la URL base que comienza con su nombre:

# APIs related to container operations
http://127.0.0.1:2375/v1.41/containers

La API usa JSON para todos los intercambios de datos con su cliente HTTP. Los puntos finales aceptan cuerpos de solicitud JSON y emiten respuestas JSON a cambio. Esto debería simplificar el manejo de datos dentro de sus aplicaciones, ya que puede usar la biblioteca JSON incluida con su entorno de programación. Herramientas como jq se puede usar para condensar, filtrar y clasificar respuestas si está experimentando en su terminal.

Puntos finales comunes

Como la API replica la funcionalidad de la CLI de Docker, hay demasiados puntos finales posibles para cubrirlos todos aquí. En su lugar, demostraremos algunas de las opciones más utilizadas relacionadas con la funcionalidad principal de Docker.

Listado de Contenedores

La lista completa de contenedores en el host se puede obtener de la /containers/json punto final:

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

De manera predeterminada, muestra solo contenedores en ejecución. Agregar all=true a la cadena de consulta para incluir también contenedores detenidos. Limite el número total de contenedores devueltos con el limit parámetro, como limit=10. Solo se incluirán los 10 contenedores creados más recientemente.

Varios diferentes filtros están disponibles para reducir la lista a contenedores con atributos particulares. Estos se establecen con la siguiente sintaxis:

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

Esta URL devuelve la información asociada con el demo envase. Otros filtros se pueden expresar de manera similar, como {"status":["running","paused"]} para obtener contenedores en ejecución y en pausa o {"health=["healthy"]} solo para recipientes sanos.

Inicio de un nuevo contenedor

Iniciar un contenedor es un proceso de dos etapas cuando se utiliza la API. Primero debe crear el contenedor, luego iniciarlo en una llamada API separada.

Crea tu contenedor haciendo un POST solicitar a la /containers/create punto final Esto necesita un cuerpo JSON con campos que correspondan a las banderas aceptadas por el docker run Comando CLI.

Aquí hay un ejemplo mínimo de cómo crear un contenedor:

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

La respuesta JSON incluirá el ID del nuevo contenedor y cualquier advertencia que surja de su creación. Enviar el ID en una llamada al /containers/:id/start punto final:

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

El contenedor ahora se ejecutará en el host de Docker.

limpieza de contenedores

Retire los contenedores detenidos emitiendo un POST solicitar a la /containers/prune punto final:

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

Se le emitirá una respuesta JSON con ContainersDeleted y SpaceReclaimed campos. ContainersDeleted es una matriz de los ID de contenedor que se eliminaron correctamente. SpaceReclaimed le informa el espacio de almacenamiento total liberado en bytes.

Este extremo acepta dos parámetros de cadena de consulta para restringir la operación. los until El parámetro limita la eliminación a los contenedores creados antes de un tiempo determinado, como until=10m o until=2022-03-01. los label opción filtros a contenedores con o sin etiquetas dadas; ajuste label=demo=example sólo retirará los envases con la demo=example etiqueta.

Listado de imágenes

los /images/json endpoint se utiliza para enumerar las imágenes almacenadas en el host de Docker:

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

Puede usar filtros para modificar el contenido de la respuesta. Estos se proporcionan como un objeto JSON en el filters parámetro de cadena de consulta, de manera similar a la API de lista de contenedores. Una opción destacable es reference que selecciona la imagen con una etiqueta dada: filters={"reference":"hello-world:latest"}.

Imágenes de edificios

Puede usar la API para crear nuevas imágenes de Docker a partir de Dockerfiles. los /build punto final se debe enviar un tar archivo. El contenido de este archivo se utilizará como contexto de construcción de la imagen. El archivo debe incluir Dockerfile que contenga las instrucciones para la compilación.

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

El comando anterior enviará context.tar al demonio Docker y crea una imagen usando el Dockerfile dentro de. La imagen será etiquetada como example-image:latest y almacenado en el host de Docker.

Este punto final acepta muchos parámetros de cadena de consulta adicionales que coinciden con la funcionalidad del docker build CLI. Éstos incluyen dockerfile=path/to/dockerfilepara especificar la ruta al Dockerfile del contexto de compilación, rm=trueque elimina los contenedores intermedios creados por la compilación, y pull=true para probar y adquirir versiones actualizadas de las imágenes a las que hace referencia Dockerfile.

La API requiere que su cliente permanezca conectado hasta que se complete la compilación. La compilación se cancelará si la red cae y la conexión se cierra.

Listado de registros de eventos de Daemon

los /events La API muestra los datos del registro de eventos del daemon a los que también se puede acceder con el docker events Comando CLI. Este punto final transmite eventos en tiempo real a medida que ocurren.

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

Se exponen varios tipos diferentes de eventos, incluidas las creaciones de contenedores, las etiquetas de imágenes, los montajes de volúmenes y los cambios de red. Puede filtrar a un tipo específico de evento usando el type campo de la filters parámetro de consulta:

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

También es posible restringir eventos relacionados con un objeto específico:

# Get events pertaining to the container with ID abc123
curl http://127.0.0.1:2375/v1.41/events?filters={'container':'id'}

Otros dos parámetros de cadena de consulta, since y untille permite especificar un rango de marca de tiempo para mostrar eventos históricos dentro.

Obtener información del sistema

La API de Docker Engine se puede utilizar para obtener información sobre el host físico en el que se ejecuta:

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

Este punto final proporciona detalles extensos que describen el estado actual y la configuración del host y el demonio de Docker. Los campos en la respuesta incluyen recuentos de la cantidad de contenedores en ejecución, en pausa y detenidos, la ruta al directorio de instalación de Docker, detalles del hardware y del sistema operativo, y la configuración de Swarm del servidor cuando está operando dentro de un clúster.

Conclusión

La API del motor Docker le brinda una forma de enviar comandos al demonio Docker de su host a través de HTTP. Esto simplifica la creación de secuencias de comandos de interacciones programáticas sin depender de comportamientos específicos de la CLI de Docker. La API también se puede usar para administrar de forma remota sus servidores Docker para mejorar la supervisión y facilitar el mantenimiento.

Si bien llamar a la API debería ser sencillo, debe prestar atención a las protecciones de seguridad en torno a su socket TCP. Evite exponer el socket en su red a menos que esté protegido con TLS para que solo los clientes aprobados puedan conectarse. Omitir esta etapa de configuración adicional podría resultar costoso si un intruso descubre su instancia de daemon y comienza a emitir comandos.

Puede hacer que sea aún más fácil usar la API dentro de sus propias aplicaciones al adoptar uno de los SDK. Hay disponible una opción oficial o proporcionada por la comunidad para todos los lenguajes de programación populares, incluidos C, C#, C++, Go, Java, NodeJS, PHP, Python y Ruby. Los SDK envuelven los extremos de la API en clases y funciones convenientes para llamar desde su código, lo que reduce la cantidad de repeticiones necesarias para interactuar con una instalación de Docker.

Deja un comentario

En esta web usamos cookies para personalizar tu experiencia de usuario.    Política de cookies
Privacidad