Los Edge Agents permiten gestionar entornos Docker remotos que no tienen conectividad directa bidireccional con Portainer Server. Son ideales para:

Hosts detrás de firewalls o NAT
Dispositivos IoT en ubicaciones remotas
Entornos edge computing
Sitios con conectividad limitada o intermitente

¿Cómo Funcionan?

A diferencia del Portainer Agent estándar (que requiere puerto 9001 accesible), el Edge Agent:

Inicia la conexión hacia Portainer Server (puerto 8000)
Mantiene un túnel para comunicación bidireccional
Polling periódico cuando la conexión se pierde
Modo async para operaciones cuando está offline

Requisitos

En Portainer Server

✅ Puerto 8000 expuesto y accesible desde Internet/red remota
✅ Dominio o IP pública (recomendado)
✅ Certificado SSL válido (recomendado para producción)

En el Host Remoto

✅ Docker instalado
✅ Conectividad saliente a Portainer Server (puerto 8000)
✅ NO requiere puertos abiertos hacia el host remoto

Habilitar Edge en Portainer Server

1. Exponer Puerto 8000

Edita docker-compose.yml y descomenta el puerto 8000:

services:
  portainer:
    container_name: portainer
    image: portainer/portainer-ce:lts
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - portainer_data:/data
    ports:
      - "9443:9443"
      - "8000:8000"  # ← Descomentar para Edge Agents
    networks:
      - portainer_network

2. Reiniciar Portainer

docker compose down
docker compose up -d

3. Verificar Puerto

# Verificar que el puerto está escuchando
sudo netstat -tulpn | grep :8000
# o con ss
ss -tulpn | grep :8000

4. Configurar Firewall

# UFW (Ubuntu/Debian)
sudo ufw allow 8000/tcp

# firewall-cmd (RHEL/CentOS/Fedora)
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

# iptables
sudo iptables -A INPUT -p tcp --dport 8000 -j ACCEPT
sudo iptables-save > /etc/iptables/rules.v4

Desplegar Edge Agent en Host Remoto

Desde la Interfaz de Portainer

Ir a Environments:
- Click en Environments en el menú lateral
- Click en Add environment
Seleccionar Tipo:
- Selecciona Docker Standalone
- Click en Start Wizard
Elegir Edge Agent:
- Selecciona la opción Edge Agent
- Elige tu sistema operativo (Linux / Windows WSL / Windows WCS)
Configurar Opciones:
- Name: Nombre descriptivo del entorno (ej: produccion-server1)
- Portainer server URL: https://portainer.tudominio.com o https://IP:9443
- Edge ID: Se genera automáticamente
- Polling interval: Frecuencia de sincronización (por defecto 5 segundos)

Copiar Comando:

Portainer generará un comando similar a este:

Linux / WSL:

docker run -d \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /var/lib/docker/volumes:/var/lib/docker/volumes \
  -v /:/host \
  -v portainer_agent_data:/data \
  --restart always \
  -e EDGE=1 \
  -e EDGE_ID=<tu-edge-id> \
  -e EDGE_KEY=<tu-edge-key> \
  -e EDGE_INSECURE_POLL=0 \
  --name portainer_edge_agent \
  portainer/agent:latest

Windows WCS:

docker run -d `
  -v \\.\pipe\docker_engine:\\.\pipe\docker_engine `
  -v portainer_agent_data:C:\ProgramData\Portainer `
  --restart always `
  -e EDGE=1 `
  -e EDGE_ID=<tu-edge-id> `
  -e EDGE_KEY=<tu-edge-key> `
  --name portainer_edge_agent `
  portainer/agent:latest

Ejecutar en Host Remoto:
- Conéctate por SSH al host remoto
- Pega y ejecuta el comando
- Espera a que el contenedor se descargue e inicie

Verificar Conexión

En el host remoto:

# Ver logs del Edge Agent
docker logs portainer_edge_agent

# Deberías ver mensajes como:
# [INFO] Edge agent started
# [INFO] Polling Portainer server
# [INFO] Successfully connected to Portainer server

En Portainer Server:

Ve a Environments
El nuevo entorno debería aparecer con estado Connected (punto verde)
Click en el entorno para gestionarlo

Configuración Avanzada

Intervalo de Polling Personalizado

docker run -d \
  # ... resto de opciones ...
  -e EDGE_POLL_INTERVAL=10s \  # Cambiar intervalo (default: 5s)
  portainer/agent:latest

⚠️ Nota: Intervalos muy cortos aumentan el tráfico de red.

Edge Agent con Host Management

Para habilitar funciones de gestión del host (CPU, memoria, procesos):

docker run -d \
  # ... resto de opciones ...
  -v /:/host \  # Montar filesystem del host
  portainer/agent:latest

Modo Inseguro (Solo para Desarrollo)

Si usas certificados autofirmados o HTTP:

docker run -d \
  # ... resto de opciones ...
  -e EDGE_INSECURE_POLL=1 \  # ⚠️ NO usar en producción
  portainer/agent:latest

Edge Agent con Docker Compose

Crear docker-compose.yml en el host remoto:

version: '3.8'

services:
  portainer_edge_agent:
    image: portainer/agent:latest
    container_name: portainer_edge_agent
    restart: always
    environment:
      EDGE: "1"
      EDGE_ID: "<tu-edge-id>"
      EDGE_KEY: "<tu-edge-key>"
      EDGE_INSECURE_POLL: "0"
      EDGE_POLL_INTERVAL: "5s"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - /var/lib/docker/volumes:/var/lib/docker/volumes
      - /:/host
      - portainer_agent_data:/data

volumes:
  portainer_agent_data:

Desplegar:

docker compose up -d

Edge Groups y Tags

Crear Edge Group

Los Edge Groups permiten agrupar múltiples entornos edge para gestión centralizada:

Ir a Edge Groups:
- Menú lateral → Edge Groups
- Click Add edge group
Configurar Grupo:
- Name: Nombre del grupo (ej: iot-devices)
- Endpoints: Seleccionar entornos edge a incluir
- Tags: Opcional, para filtrado avanzado
Deploy Stack a Grupo:
- Puedes desplegar stacks en todos los entornos del grupo simultáneamente
- Los cambios se sincronizan automáticamente

Edge Stacks

Los Edge Stacks son stacks Docker Compose que se despliegan en múltiples entornos edge:

Crear Edge Stack:
- Edge Compute → Edge Stacks → Add stack
Configurar Stack:
- Name: Nombre del stack
- Edge groups: Seleccionar grupos target
- Compose file: Pegar tu docker-compose.yml
Deployment type:
- Static: Se despliega una vez
- Git: Se sincroniza desde un repo Git
Pre-pull images: Descargar imágenes antes de desplegar (recomendado)

Edge Jobs

Ejecutar comandos en múltiples entornos edge:

Crear Edge Job:
- Edge Compute → Edge Jobs → Add edge job
Opciones:
- Basic: Comando simple
- Advanced: Scripts complejos
Scheduling:
- One-off: Se ejecuta una vez
- Recurring: Programado (cron-like)

Ejemplo:

# Actualizar todos los contenedores en entornos edge
docker compose pull
docker compose up -d

Troubleshooting

Edge Agent No Conecta

Verificar firewall en servidor:
```
sudo ufw status | grep 8000
```

Verificar puerto 8000 accesible: Desde el host remoto:

telnet <portainer-server-ip> 8000
# o
nc -zv <portainer-server-ip> 8000

Revisar logs:

docker logs portainer_edge_agent --tail 50

Certificado SSL Inválido

Si usas certificados autofirmados, usa EDGE_INSECURE_POLL=1 (solo desarrollo):

docker run -d \
  # ... resto de opciones ...
  -e EDGE_INSECURE_POLL=1 \
  portainer/agent:latest

Edge Agent Se Desconecta Frecuentemente

Aumentar timeout:
```
-e EDGE_POLL_TIMEOUT=30s
```
Verificar estabilidad de red:
```
ping -c 100 <portainer-server-ip>
```
Revisar recursos del host:
```
docker stats portainer_edge_agent
```

Actualizar Edge Agent

# Detener y eliminar contenedor actual
docker stop portainer_edge_agent
docker rm portainer_edge_agent

# Pull nueva imagen
docker pull portainer/agent:latest

# Re-ejecutar comando de despliegue con las mismas variables EDGE_ID y EDGE_KEY

⚠️ Importante: No cambies EDGE_ID o EDGE_KEY, o necesitarás re-agregar el entorno en Portainer.

Seguridad

Recomendaciones

✅ Usar HTTPS con certificados válidos
✅ NO usar EDGE_INSECURE_POLL=1 en producción
✅ Limitar acceso al puerto 8000 con firewall
✅ Rotar Edge Keys periódicamente (re-deploy agent)
✅ Monitorizar logs de conexiones sospechosas

Exponer Solo con VPN (Alternativa Segura)

Si no quieres exponer el puerto 8000 a Internet:

Configurar VPN (WireGuard, OpenVPN, Tailscale)
Conectar hosts remotos a la VPN
Configurar Portainer Server URL con IP privada de VPN
Edge Agents conectan a través del túnel VPN

Recursos adicionales:

Volver a: Página Principal | Instalación Avanzada