Docker Registry

Registry local y privado

Un registry privado es una solución autogestionada para almacenar y distribuir imágenes Docker dentro de una organización, sin depender de servicios externos como Docker Hub. Docker proporciona una imagen oficial llamada registry que permite desplegar un registry completamente funcional en minutos.

Esta solución resulta especialmente valiosa en entornos empresariales donde se necesita control total sobre las imágenes, cumplimiento de políticas de seguridad, o cuando se trabaja en redes aisladas sin acceso a internet.

Imagen oficial registry

Docker mantiene una imagen oficial llamada registry que puedes encontrar en Docker Hub. Esta imagen está basada en Alpine Linux y proporciona todas las funcionalidades necesarias para un registry de producción.

docker pull registry:3

La imagen registry:3 es la versión estable recomendada, que incluye todas las características necesarias para un despliegue empresarial. Esta imagen es extremadamente ligera, ocupando menos de 20MB, y está optimizada para un arranque rápido.

Ejecución básica

El despliegue más sencillo de un registry privado se realiza con un solo comando:

docker run -d -p 5000:5000 --name registry registry:3

Este comando despliega el registry en el puerto 5000, que es el puerto estándar para registries privados. El registry estará inmediatamente disponible en localhost:5000 y listo para recibir imágenes.

Para verificar que el registry está funcionando correctamente:

# Verificar estado del contenedor
docker ps

# Comprobar logs del registry
docker logs registry

# Verificar endpoint de salud
curl http://localhost:5000/v2/

El endpoint /v2/ debe devolver una respuesta vacía con código HTTP 200, indicando que la API v2 está activa y funcionando.

Almacenamiento persistente

Por defecto, el registry almacena las imágenes en el directorio /var/lib/registry dentro del contenedor. Para persistir los datos entre reinicios del contenedor, es esencial montar un volumen:

docker run -d \
  -p 5000:5000 \
  --restart=unless-stopped \
  --name registry \
  -v /opt/registry-data:/var/lib/registry \
  registry:3

Este montaje garantiza que todas las imágenes subidas al registry se mantengan disponibles aunque el contenedor se reinicie o actualice. El directorio /opt/registry-data en el host contendrá toda la estructura de datos del registry.

La estructura de almacenamiento sigue el formato:

/var/lib/registry/
├── docker/
│   └── registry/
│       └── v2/
│           ├── repositories/
│           └── blobs/

Subir y descargar imágenes

Para utilizar el registry privado, las imágenes deben etiquetarse con el hostname y puerto del registry:

# Etiquetar una imagen existente
docker tag nginx:latest localhost:5000/nginx:latest

# Subir al registry privado
docker push localhost:5000/nginx:latest

El proceso de descarga sigue la misma lógica:

# Descargar desde el registry privado
docker pull localhost:5000/nginx:latest

# Listar imágenes en el registry
curl -X GET http://localhost:5000/v2/_catalog

Namespaces y organización

Los registries privados soportan namespaces que permiten organizar las imágenes por equipos, proyectos o propósitos:

# Imágenes por equipo
docker tag myapp:latest localhost:5000/frontend-team/myapp:v1.0
docker tag database:latest localhost:5000/backend-team/database:v2.1

# Imágenes por entorno
docker tag myapp:latest localhost:5000/production/myapp:stable
docker tag myapp:latest localhost:5000/staging/myapp:latest

Esta organización facilita la gestión de permisos y el control de acceso cuando se implementen posteriormente capas de autenticación y autorización.

Endpoints de gestión

El registry expone varios endpoints útiles para administración y monitoreo:

Listar repositorios disponibles:

curl -X GET http://localhost:5000/v2/_catalog

Obtener tags de un repositorio específico:

curl -X GET http://localhost:5000/v2/nginx/tags/list

Verificar existencia de un manifest:

curl -I http://localhost:5000/v2/nginx/manifests/latest

Estos endpoints proporcionan una interfaz HTTP completa para integrar el registry con herramientas de automatización, scripts de despliegue, o sistemas de monitoreo.

Configuración avanzada de almacenamiento

Para entornos de producción, el registry puede configurarse con diferentes backends de almacenamiento mediante variables de entorno:

docker run -d \
  -p 5000:5000 \
  --name registry \
  -v /opt/registry-data:/var/lib/registry \
  -e REGISTRY_STORAGE_DELETE_ENABLED=true \
  -e REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/var/lib/registry \
  registry:3

La variable REGISTRY_STORAGE_DELETE_ENABLED=true permite eliminar imágenes del registry, una característica que está deshabilitada por defecto por motivos de seguridad.

Un registry privado básico proporciona una base sólida para la distribución interna de imágenes, ofreciendo control completo sobre el almacenamiento y acceso a las imágenes Docker de una organización.

Autenticación y TLS

La seguridad en un registry privado es fundamental cuando se despliega en entornos de producción o se expone a través de la red. Docker Registry soporta múltiples métodos de autenticación y cifrado TLS para proteger tanto el acceso como la transmisión de datos.

Autenticación básica HTTP

La forma más sencilla de proteger un registry privado es mediante autenticación básica HTTP. Este método requiere que los usuarios proporcionen credenciales válidas antes de poder interactuar con el registry.

Primero, debemos crear un archivo de usuarios con htpasswd:

# Instalar htpasswd si no está disponible
sudo apt-get install apache2-utils

# Crear archivo de usuarios
mkdir -p /opt/registry-auth
htpasswd -Bbn admin secretpassword > /opt/registry-auth/htpasswd

El flag -B utiliza bcrypt para el hash de la contraseña, proporcionando mayor seguridad que MD5. El flag -n evita que se solicite la contraseña interactivamente.

Ahora podemos desplegar el registry con autenticación habilitada:

docker run -d \
  -p 5000:5000 \
  --restart=unless-stopped \
  --name registry \
  -v /opt/registry-data:/var/lib/registry \
  -v /opt/registry-auth:/auth \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  registry:3

Configuración del cliente Docker

Una vez habilitada la autenticación, los clientes deben autenticarse antes de realizar operaciones:

# Login en el registry privado
docker login localhost:5000
Username: admin
Password: secretpassword

# Las credenciales se almacenan en ~/.docker/config.json
cat ~/.docker/config.json

Tras el login exitoso, todas las operaciones de push y pull funcionarán normalmente:

# Subir imagen autenticada
docker push localhost:5000/nginx:latest

# Descargar imagen autenticada  
docker pull localhost:5000/nginx:latest

Certificados TLS autofirmados

Para cifrar la comunicación entre cliente y registry, necesitamos configurar TLS. Comenzamos creando certificados autofirmados para desarrollo y testing:

# Crear directorio para certificados
mkdir -p /opt/registry-certs

# Generar clave privada
openssl genrsa -out /opt/registry-certs/domain.key 4096

# Generar certificado autofirmado
openssl req -new -x509 -days 365 -key /opt/registry-certs/domain.key \
  -out /opt/registry-certs/domain.crt \
  -subj "/C=ES/ST=Madrid/L=Madrid/O=MyCompany/CN=localhost"

El parámetro CN=localhost debe coincidir con el hostname que utilizarán los clientes para acceder al registry.

Registry con TLS habilitado

Desplegamos el registry configurado para usar los certificados TLS:

docker run -d \
  -p 5000:5000 \
  --restart=unless-stopped \
  --name secure-registry \
  -v /opt/registry-data:/var/lib/registry \
  -v /opt/registry-auth:/auth \
  -v /opt/registry-certs:/certs \
  -e "REGISTRY_AUTH=htpasswd" \
  -e "REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm" \
  -e "REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd" \
  -e "REGISTRY_HTTP_TLS_CERTIFICATE=/certs/domain.crt" \
  -e "REGISTRY_HTTP_TLS_KEY=/certs/domain.key" \
  registry:3

Ahora el registry estará disponible en https://localhost:5000 con cifrado TLS completo.

Configuración de cliente para TLS

Para certificados autofirmados, Docker necesita confiar explícitamente en el certificado:

# Crear directorio para certificados de Docker
sudo mkdir -p /etc/docker/certs.d/localhost:5000

# Copiar certificado público
sudo cp /opt/registry-certs/domain.crt /etc/docker/certs.d/localhost:5000/ca.crt

# Reiniciar Docker daemon
sudo systemctl restart docker

Alternativamente, podemos configurar Docker para omitir la verificación TLS en desarrollo:

# Editar configuración de Docker daemon
sudo nano /etc/docker/daemon.json

# Añadir registry inseguro
{
  "insecure-registries": ["localhost:5000"]
}

# Reiniciar Docker
sudo systemctl restart docker

Autenticación y TLS combinados

Con ambas características habilitadas, el flujo de trabajo completo incluye autenticación segura:

# Login con HTTPS
docker login https://localhost:5000
Username: admin
Password: secretpassword

# Todas las comunicaciones están cifradas
docker push localhost:5000/myapp:secure
docker pull localhost:5000/myapp:secure

Verificación de configuración TLS

Podemos verificar que el cifrado TLS está funcionando correctamente:

# Comprobar certificado del servidor
openssl s_client -connect localhost:5000 -servername localhost

# Verificar endpoints con curl
curl -k -u admin:secretpassword https://localhost:5000/v2/

# Verificar catálogo de imágenes
curl -k -u admin:secretpassword https://localhost:5000/v2/_catalog

El flag -k en curl ignora errores de certificado para pruebas con certificados autofirmados.

Certificados de autoridades certificadoras

Para entornos de producción, se recomienda utilizar certificados emitidos por una autoridad certificadora reconocida:

# Estructura de certificados para CA válida
/etc/docker/certs.d/myregistry.company.com:5000/
├── client.cert    # Certificado cliente (opcional)
├── client.key     # Clave privada cliente (opcional)  
└── ca.crt         # Certificado CA raíz

Configuración avanzada de autenticación

El registry soporta múltiples usuarios en el mismo archivo htpasswd:

# Añadir usuarios adicionales
htpasswd -B /opt/registry-auth/htpasswd developer
htpasswd -B /opt/registry-auth/htpasswd qa-team
htpasswd -B /opt/registry-auth/htpasswd devops

# Verificar usuarios creados
cat /opt/registry-auth/htpasswd

Cada usuario podrá autenticarse independientemente, aunque todos tendrán acceso completo al registry. Para control de acceso granular por repositorio, se requieren soluciones de autorización más avanzadas fuera del alcance de esta lección.

La combinación de autenticación básica y TLS proporciona una base de seguridad sólida para registries privados, asegurando que solo usuarios autorizados puedan acceder a las imágenes y que toda la comunicación esté cifrada.