La Docker API: qué es y cómo utilizarla es la interfaz que conecta el cliente docker con dockerd. La CLI la usa para consultar y gestionar imágenes, contenedores, redes y volúmenes; otras herramientas también pueden automatizar tareas mediante sus endpoints. En esta guía verás cómo funciona esa comunicación y qué riesgos implica exponerla.
La API también es una frontera de seguridad: quien puede controlarla normalmente puede crear contenedores y montar rutas del host. Mantén las pruebas locales y usa autenticación y TLS si necesitas acceso remoto.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Qué problema resuelve la Docker API
Problema: los comandos de Docker parecen acciones locales simples, pero en realidad necesitan comunicarse con un servicio que gestiona imágenes, contenedores, redes, volúmenes y configuración.
Qué aporta Docker: la API expone una forma estándar de hablar con el daemon. La CLI oficial la usa, y otras herramientas también pueden usarla para automatizar operaciones o consultar el estado del motor.
| Pieza | Qué hace | Ejemplo |
|---|---|---|
| Docker CLI | Cliente que traduce comandos a peticiones. | docker ps, docker run, docker build. |
| Docker API | Interfaz HTTP del daemon. | Endpoints para contenedores, imágenes, redes y versión. |
| dockerd | Daemon que recibe peticiones y coordina Docker Engine. | Gestiona objetos y delega en runtimes. |
| Socket Unix | Canal local habitual en Linux. | /var/run/docker.sock. |
Docker API: cómo la utiliza la CLI
Cuando ejecutas un comando, la CLI prepara una petición para el daemon. Por ejemplo, listar contenedores no significa que la CLI lea todos los procesos por su cuenta: pide esa información al servidor de Docker.
docker ps
# La CLI usa la API del daemon por debajo para pedir información similar.Esta separación ayuda a entender errores típicos: si la parte Server de docker version falla, normalmente el problema no está en el comando, sino en la comunicación con el daemon o en el servicio Docker.
Consultas básicas de Docker API con el socket Unix
En Linux, el daemon suele escuchar en un socket Unix local. Puedes consultarlo con curl sin abrir un puerto de red. Obtén la versión de API negociada por el cliente con docker version –format ‘{{.Client.APIVersion}}’. El ejemplo asigna ese valor a API_VERSION y lo incorpora en cada ruta, así no dependes de un número ficticio. La CLI oficial negocia la comunicación automáticamente; los clientes propios deben usar una versión compatible con el daemon.
API_VERSION="$(docker version --format '{{.Client.APIVersion}}')"
curl --unix-socket /var/run/docker.sock "http://localhost/v${API_VERSION}/_ping"
curl --unix-socket /var/run/docker.sock "http://localhost/v${API_VERSION}/version"
curl --unix-socket /var/run/docker.sock "http://localhost/v${API_VERSION}/containers/json"- /_ping comprueba si el daemon responde; el bloque construye la ruta con el prefijo de versión del servidor.
- /version muestra información del servidor y de la API.
- /containers/json lista los contenedores en ejecución; añade ?all=1 para incluir también los detenidos.
El endpoint /version devuelve información del servidor y de la API. Comprueba que la consulta responde antes de automatizarla y mantén el cliente alineado con una versión compatible del daemon. La CLI oficial se encarga de negociar la comunicación automáticamente.
Importante: poder leer el socket normalmente implica permisos altos. No des acceso a /var/run/docker.sock a usuarios o contenedores si no entiendes el impacto.
Automatización y casos de uso
- Paneles internos que muestran contenedores, imágenes o consumo de recursos.
- Herramientas de CI/CD que construyen imágenes o preparan entornos efímeros.
- Scripts de auditoría que consultan versión, contenedores o configuración.
- Integraciones que necesitan reaccionar ante eventos del daemon.
Aun así, no conviertas la API en un atajo inseguro. Muchas tareas se pueden resolver con la CLI, Compose o herramientas ya preparadas sin exponer el daemon a la red.
Riesgos de seguridad de Docker API
Exponer TCP sin protección
Abrir el daemon por TCP sin TLS ni autenticación fuerte es peligroso. Si alguien alcanza ese endpoint, puede crear contenedores, montar rutas del host o manipular imágenes.
# Ejemplo de riesgo: NO expongas esto sin TLS y control de acceso
dockerd -H tcp://0.0.0.0:2375Montar el socket en contenedores
Montar /var/run/docker.sock dentro de un contenedor puede parecer cómodo para automatizar despliegues, pero ese contenedor podría controlar el host a través del daemon. Es una decisión de seguridad, no solo una opción técnica.
Permisos del grupo docker
En muchos sistemas, pertenecer al grupo docker permite hablar con el daemon local. Trátalo como un permiso sensible y no como un simple acceso de usuario normal.
Errores comunes
- Confundir Docker API con Docker Hub API: una habla con tu daemon; la otra con servicios de registro o cuentas.
- Pensar que la API solo sirve para desarrolladores avanzados; también ayuda a entender cómo trabaja la CLI.
- Abrir el puerto 2375 para “probar rápido” y olvidarlo expuesto.
- Dar acceso al socket a contenedores de terceros sin aislar ni auditar el riesgo.
- Depurar un error de CLI sin comprobar primero si el daemon responde.
Documentación oficial y recursos
- Docker Engine API reference: referencia oficial de endpoints.
- Docker Engine API overview: explicación oficial de uso de la API.
- Protect the Docker daemon socket: guía oficial sobre seguridad del socket.
- dockerd CLI reference: opciones oficiales del daemon.
Lecciones relacionadas del curso
- Docker Engine: entiende el motor que expone la API.
- qué es dockerd: repasa el daemon que recibe las peticiones.
- qué problema resuelve Docker: vuelve a la base antes de profundizar en internals.
