Introducción y arquitectura

Portainer es una herramienta de administración para plataformas de contenedores. Su valor no está en correr contenedores —de eso ya se encargan Docker o Kubernetes— sino en gobernarlos: darte una UI y una API para desplegar, observar, controlar accesos y estandarizar configuraciones sobre uno o cientos de hosts.

El problema que resuelve

Sin Portainer, administrar contenedores significa SSH a cada host, recordar la sintaxis de docker run, leer logs con docker logs, y no tener forma sencilla de dar acceso parcial a un compañero. A medida que crecen los hosts y el equipo, esto no escala.

Portainer centraliza todo eso:

• Una interfaz web para las operaciones cotidianas.
• Una API REST completa para automatizar.
• Control de acceso para que cada persona vea solo lo suyo.
• Plantillas y stacks para desplegar de forma repetible.

CE vs BE

Portainer se distribuye en dos ediciones desde la misma base de código:

	Community Edition (CE)	Business Edition (BE)
Precio	Gratis, open source	Licencia (gratis hasta 3 nodos)
Gestión Docker/Swarm/K8s	✅	✅
Stacks, templates, registries	✅	✅
Edge Agents	✅	✅
RBAC granular (roles por recurso)	❌ (solo admin/usuario)	✅
OAuth, LDAP/AD, SAML	❌	✅
Registry management avanzado	Básico	✅
Activity logs / auditoría	❌	✅
Soporte oficial	Comunidad	✅

Regla práctica: empezá con CE. Si necesitás permisos por recurso, integración con tu directorio corporativo o auditoría, evaluás BE. La licencia BE es gratuita hasta 3 nodos, así que podés probarla sin costo.

Versiones: LTS vs STS

Portainer publica dos canales:

• LTS (Long-Term Support): estable, parches de seguridad por ~1 año. En 2026 la línea es 2.39 LTS. Es la recomendada para producción.
• STS (Short-Term Support): incorpora funciones nuevas antes (ej. 2.42 STS), con ventana de soporte más corta.

En las instalaciones usamos la etiqueta :lts de la imagen para fijarnos al canal estable.

Arquitectura: Server y Agent

Portainer tiene dos componentes:

flowchart TD
    U["Navegador / API"] --> S["Portainer Server<br/>(UI + API + base de datos)"]
    S -->|"socket local"| D1["Docker del propio host"]
    S -->|"túnel / API"| A1["Agent en host remoto"]
    S -->|"túnel / API"| A2["Agent en cluster Swarm"]
    S -->|"túnel / API"| A3["Agent en Kubernetes"]
    S -.->|"Edge tunnel saliente"| E1["Edge Agent<br/>(detrás de NAT/firewall)"]

• Portainer Server: el cerebro. Aloja la UI, la API y su base de datos embebida (BoltDB). Se instala una sola vez.
• Portainer Agent: un proceso ligero que se despliega en cada entorno remoto que quieras gestionar. Expone la API del host (o del cluster) al Server. En Swarm y Kubernetes, el agent también federa la información de todos los nodos.
• Edge Agent: una variante del agent pensada para hosts que no podés alcanzar directamente (detrás de NAT o firewall). En vez de que el Server se conecte al host, el Edge Agent inicia un túnel saliente hacia el Server. Lo vemos en el capítulo 11.

El Server puede gestionar su entorno local (vía el socket de Docker montado) y, además, cualquier número de entornos remotos vía agents.

Tipos de entorno (environments)

Un “environment” en Portainer es cualquier plataforma de contenedores que conectás:

• Docker Standalone: un host con Docker.
• Docker Swarm: un cluster Swarm (varios nodos).
• Kubernetes: un cluster de K8s.
• Edge: cualquiera de los anteriores, pero conectado por túnel Edge.
• ACI: Azure Container Instances (gestión limitada).

Todos se administran desde el mismo Server y la misma UI; cambia el conjunto de operaciones disponibles según la plataforma.

Casos de uso donde brilla

• Homelab / self-hosting: gestionar Jellyfin, Nextcloud, Pi-hole, etc. en un servidor casero sin vivir en SSH.
• Equipos pequeños sin plataforma dedicada: dar a devs una UI para desplegar y depurar sin acceso root al host.
• Flotas Edge: cientos de dispositivos remotos (retail, IoT, sucursales) gestionados desde un panel central.
• Adopción gradual de Kubernetes: una UI amigable para equipos que recién migran de Docker a K8s.

Lo que NO es Portainer

• No es un orquestador: no reemplaza a Swarm ni a Kubernetes, se monta sobre ellos.
• No es un sistema de CI/CD completo: hace despliegue desde Git y webhooks, pero no corre pipelines de build/test.
• No es un reemplazo de observabilidad profunda: muestra logs y stats básicos, pero no sustituye a Prometheus/Grafana o a un APM.

---

Anterior → Índice · Siguiente → Capítulo 2: Instalación