Paso a paso: habilitar y depurar IPv6 en containers Docker y la red bridge en Debian (guía práctica)

Docker & Containers · Por Kevin Marcondes · Publicado el 22/10/2026 · 9 min de lectura

Esta guía paso a paso para habilitar y depurar IPv6 en containers Docker y la red bridge en Debian muestra, desde cero, cómo activar soporte en kernel/sysctl, ajustar daemon.json, crear una bridge con IPv6 y validar conectividad. Levantarás containers con direcciones IPv6 y tendrás un roteiro de diagnóstico para rutas, firewall y problemas de asignación.

Requisitos previos y cómo funciona IPv6 en Docker

Necesitas acceso root en el host Debian y Docker instalado. Si falta, instálalo siguiendo esta guía: cómo instalar Docker y Docker Compose.

Docker solo asigna IPv6 si el daemon tiene IPv6 activado y la red dispone de una subred IPv6. Por defecto, el bridge “docker0” solo trae IPv4.

Para redes internas, usa direcciones ULA (fd00::/8). Para tráfico global, lo ideal es disponer de un prefijo que el proveedor rote al host.

Si reinicias Docker, los containers en ejecución se detendrán. Planifica una ventana y usa Compose para levantar los servicios rápidamente.

Esta es una guía práctica y directa para habilitar y depurar IPv6 en containers Docker y bridge network en Debian, con foco en pruebas y diagnóstico.

• Acceso root o sudo al servidor Debian
• Docker y Docker Compose instalados
• Posible prefijo IPv6 público enrutado (para Internet IPv6)
• Copia de seguridad de /etc/docker/daemon.json si ya existe
• Ventana para reiniciar el servicio Docker

1) Verifica soporte IPv6 en el host Debian

Antes de tocar Docker, confirma que el kernel no tenga IPv6 deshabilitado y que existan rutas v6 en el host. Si el host no tiene IPv6 global, aún puedes usar ULA internamente.

Si el comando de disable_ipv6 retorna 1, IPv6 está desactivado. Lo habilitaremos en el siguiente paso.

# 1. Checar se o IPv6 está habilitado no kernel
sysctl net.ipv6.conf.all.disable_ipv6

# 2. Ver endereços IPv6 do host (global e link-local)
ip -6 addr show

# 3. Rotas IPv6
ip -6 route

# 4. Teste de conectividade externa IPv6 (opcional)
ping -6 -c 2 2606:4700:4700::1111 || true

2) Activa IPv6 y forwarding en el kernel (sysctl)

Habilita IPv6 en el host y el forwarding entre interfaces. Esto permite que el bridge de Docker intercambie paquetes IPv6. Aplicar sysctl afecta la red; ejecuta en una ventana segura.

Define accept_ra=2 para permitir enrutamiento aun con RA. En servidores, esto evita perder la ruta por defecto cuando forwarding está activo.

cat >/etc/sysctl.d/10-ipv6-docker.conf <<'EOF'
net.ipv6.conf.all.disable_ipv6 = 0
net.ipv6.conf.default.disable_ipv6 = 0
net.ipv6.conf.all.forwarding = 1
net.ipv6.conf.default.forwarding = 1
net.ipv6.conf.all.accept_ra = 2
net.ipv6.conf.default.accept_ra = 2
EOF

# Aplica tudo que está em /etc/sysctl.d
sysctl --system

3) Habilita IPv6 en el daemon de Docker (daemon.json)

Activa IPv6 en Docker y define un rango ULA para la asignación de direcciones. Docker usará ese rango para redes bridge cuando estén configuradas con IPv6.

Si ya existe daemon.json, fusiona los campos manualmente para no perder configuraciones. Reiniciar Docker detiene containers en ejecución.

mkdir -p /etc/docker
cat >/etc/docker/daemon.json <<'EOF'
{
  "ipv6": true,
  "fixed-cidr-v6": "fd00:dead:beef::/48",
  "ip6tables": true
}
EOF

# Reinicie o Docker (interrompe containers em execução)
systemctl restart docker && systemctl status --no-pager docker

4) Crea una bridge Docker con subred IPv6 dedicada

Crea una red bridge explícita con IPv6. Separa subredes por entorno para evitar conflictos. La gateway IPv6 del bridge será la dirección del host en esa red.

Después de crearla, inspecciona la red para confirmar la presencia de Subnet y Gateway IPv6.

# Cria uma rede bridge com IPv4 e IPv6
# Ajuste as faixas conforme sua política de endereçamento
NETWORK_NAME=brv6

docker network create \
  --driver bridge \
  --subnet 172.18.0.0/16 \
  --ipv6 \
  --subnet fd00:dead:beef:1::/64 \
  --gateway fd00:dead:beef:1::1 \
  "$NETWORK_NAME"

# Verifique a configuração
docker network inspect "$NETWORK_NAME" | grep -E 'IPv6|Subnet|Gateway' -n

5) Levanta containers y prueba IPv6 (Docker Compose)

Puedes habilitar IPv6 directamente en Compose definiendo la red con enable_ipv6 y IPAM. En este ejemplo, la red la crea el Compose y el servicio recibe IPv6 automáticamente.

Después de levantarlo, entra en el container y verifica la dirección y la ruta por defecto IPv6.

# docker-compose.yml
version: "3.9"
services:
  app:
    image: alpine:3
    command: ["sh","-lc","ip -6 addr show dev eth0; ip -6 route; sleep 3600"]
    networks:
      - brv6

networks:
  brv6:
    driver: bridge
    enable_ipv6: true
    ipam:
      config:
        - subnet: 172.19.0.0/16
        - subnet: fd00:dead:beef:2::/64
          gateway: fd00:dead:beef:2::1

6) Depuración: rutas, reglas de firewall y logs de Docker

Si el container no recibe IPv6, confirma si la red fue creada con IPv6 y si el daemon tiene ipv6=true. A continuación, comprueba rutas y reglas de firewall.

Debian usa iptables-nft por defecto. Docker manipula reglas ip6tables cuando ip6tables=true. Adapta tu política de firewall para permitir el tráfico del bridge.

Para hardening del host y cgroup v2 en Docker, consulta: cgroup v2 + systemd para Docker y checklist de seguridad para VPS.

• Confirma IPv6 en la red: docker network inspect
• Revisa rutas en host y container
• Repasa ip6tables/nftables por bloqueos
• Consulta logs de Docker por errores de red

# Inspecione a rede
docker network inspect brv6

# Rotas IPv6 no host
ip -6 route

# Regras IPv6 (iptables-nft)
ip6tables -L -n -v | sed -n '1,120p'

# (Opcional) Ver regras nftables
nft list ruleset | grep -i ip6 || true

# Logs recentes do Docker
journalctl -u docker --since -2h | tail -n +1

7) Checklist de verificación y pruebas prácticas

Sigue este checklist para confirmar el funcionamiento. Si un ítem falla, vuelve un paso y revisa la configuración.

Monitorea el entorno de forma continua. Para métricas y paneles con Compose, consulta: Prometheus y Grafana con Docker Compose.

Esta guía paso a paso para habilitar y depurar IPv6 en containers Docker y bridge network en Debian garantiza que valides cada capa: kernel, daemon, red y aplicación.

• docker info muestra IPv6: true
• docker network inspect lista Subnet y Gateway IPv6
• El container tiene dirección fd00:... en eth0
• El container puede hacer ping -6 al gateway del bridge
• El host puede hacer ping -6 al container por dirección ULA
• Existen rutas IPv6 en host y container

8) Problemas comunes y soluciones rápidas

Al activar IPv6 en containers, aparecen errores frecuentes. Aquí tienes las correcciones típicas. No prometas NAT66 sin evaluar riesgos; es preferible un prefijo enrutado por el proveedor.

Para reducir la indisponibilidad al reiniciar Docker en producción, considera estrategias como blue-green con Compose: blue-green con Compose.

Si necesitas repasar el flujo completo, vuelve a la guía paso a paso y valida cada etapa.

• Container solo tiene fe80:: (link-local): recrea la red con --ipv6 y IPAM v6 en Compose.
• Sin Internet IPv6 usando ULA: pide un /64 enrutado al proveedor o usa un túnel. NAT66 es posible, pero no estandarizado y complejo.
• Forwarding desactivado: asegúrate de net.ipv6.conf.all.forwarding=1 y aplica sysctl --system.
• Firewall bloqueando: revisa las chains IPv6 y permite el tránsito del bridge según tu política.
• daemon.json sobrescrito: fusiona las claves; reinicia Docker tras validar el JSON.
• Cambios desaparecen al reiniciar: usa archivos en /etc/sysctl.d y no edites solo en runtime.

Preguntas frecuentes

¿Docker trae IPv6 habilitado por defecto?

No. Debes activar "ipv6": true en daemon.json y usar redes bridge creadas con IPv6. Sin eso, los containers solo reciben IPv4. Después, crea la red con una subred fd00::/64 o define enable_ipv6 en Docker Compose.

¿Necesito que mi VPS tenga IPv6 público para usar IPv6 en los containers?

Solo si quieres tráfico IPv6 hacia Internet. Para comunicación interna entre host y containers, ULA (fd00::/8) funciona. Para Internet, lo ideal es un prefijo público enrutado hacia el host.

¿Se puede activar IPv6 solo desde Docker Compose?

Sí. Define enable_ipv6: true en la red del Compose y configura IPAM con una subred IPv6. El daemon de Docker también debe tener ipv6=true; de lo contrario Docker no asignará direcciones v6.

¿Uso iptables o nftables con Docker e IPv6 en Debian?

Debian usa iptables-nft por defecto. Docker gestiona reglas ip6tables cuando ip6tables=true. Ajusta tu política de firewall para permitir el tráfico de las bridges. Verifica con ip6tables -L -n -v y nft list ruleset.

¿Reiniciar Docker causa indisponibilidad? ¿Cómo minimizarlo?

Sí, reiniciar Docker detiene containers. Planifica una ventana de mantenimiento y orquesta el regreso con Compose. Estrategias como blue-green ayudan a reducir el impacto en producción; consulta el tutorial de blue-green con Compose.

Ver también

• Tutorial: configurar mTLS entre Traefik y servicios en Docker Compose usando smallstep CA y certificados automáticos — paso a paso
• Tutorial: integrar Sentry en el pipeline de deploy con GitHub Actions para subir source maps automáticamente y generar issues (PHP y JavaScript) — paso a paso
• Configurar retención y compresión de logs de contenedores Docker con journald + logrotate + rsyslog en VPS con poco disco
• Tutorial: configurar GitHub Actions para tests de integración con PostgreSQL en contenedores efímeros y rollback automático de migrations — guía práctica