uncloud

Gestión de Clúster Uncloud

Referencia para la CLI uc — una plataforma de autoalojamiento descentralizada que utiliza contenedores Docker, redes en malla WireGuard y el proxy inverso Caddy.

Cuándo Activarlo

Usa este skill cuando trabajes con clústeres Uncloud, especialmente para:

• Inicializar o unir máquinas con uc machine
• Desplegar servicios desde archivos Compose con uc deploy
• Publicar puertos HTTP, HTTPS, TCP o UDP a través de Uncloud
• Configurar el proxy inverso Caddy con x-caddy, x-ports o --caddyfile
• Enrutar dispositivos LAN externos a través del proxy del clúster
• Inspeccionar registros, estado del servicio, volúmenes, DNS o ubicación de máquinas

Cómo Funciona

Uncloud ejecuta servicios Docker en máquinas pares conectadas mediante una malla WireGuard. Cada máquina es un miembro igual del clúster; los servicios se comunican en la red superpuesta y Caddy se ejecuta globalmente para terminar el tráfico HTTP/HTTPS público. Los archivos Compose pueden usar extensiones de Uncloud para entrada, ubicación y configuración generada de Caddy, mientras que la CLI uc gestiona la distribución de imágenes, la planificación, el escalado, los registros y el estado del clúster.

Ejemplos

uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy

Conceptos Clave

• Sin plano de control central — todas las máquinas son pares iguales conectados por WireGuard
• Caddy se ejecuta como un servicio global en cada máquina; obtiene automáticamente certificados TLS de Let's Encrypt
• Red superpuesta — los servicios se comunican a través de 10.210.0.0/16 por defecto; DNS proporcionado dentro de la malla
• El Caddyfile se genera automáticamente — nunca lo edites directamente; usa x-caddy / --caddyfile en su lugar

---

Referencia Rápida de CLI

Máquinas

Comando	Propósito
uc machine init user@host	Inicializar primera máquina / nuevo clúster
uc machine add user@host	Unir máquina al clúster existente
uc machine ls	Listar máquinas
uc machine update NAME --public-ip IP	Actualizar IP pública para entrada
uc machine rm NAME	Eliminar máquina

Indicadores clave de init: --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|none

Servicios

Comando	Propósito
uc service ls / uc ls	Listar servicios
uc service run IMAGE	Ejecutar un servicio de un solo contenedor
uc deploy	Desplegar desde compose.yaml
uc deploy --no-build	Desplegar imágenes ya enviadas sin reconstruir
uc deploy --recreate	Forzar recreación del servicio
uc scale SERVICE N	Establecer número de réplicas
uc service logs SERVICE	Ver registros
uc service exec SERVICE	Acceder al shell del contenedor
uc service inspect SERVICE	Información detallada
uc service rm SERVICE	Eliminar servicio (conserva volúmenes con nombre)
uc ps	Todos los contenedores en el clúster

Imágenes

uc image push myapp:latest                    # Enviar imagen local a todas las máquinas
uc image push myapp:latest -m machine1,machine2  # Enviar a máquinas específicas
uc images                                     # Listar imágenes en el clúster

Volúmenes

uc volume ls                  # Todos los volúmenes
uc volume ls -m machine1      # En una máquina específica
uc volume create NAME -m MACHINE
uc volume rm NAME

Caddy

uc caddy config    # Mostrar el Caddyfile generado actual (solo lectura)
uc caddy deploy    # Desplegar/actualizar Caddy en todo el clúster

DNS y Contexto

uc dns show        # Mostrar dominio reservado *.uncld.dev
uc dns reserve     # Reservar un nuevo dominio
uc ctx ls          # Listar contextos del clúster
uc ctx use prod    # Cambiar de contexto

---

Publicación de Puertos

HTTP/HTTPS (a través del proxy inverso Caddy)

-p [hostname:]container_port[/protocol]

Ejemplo	Significado
-p 8080/https	HTTPS con nombre de host automático service-name.cluster-domain
-p app.example.com:8080/https	HTTPS con nombre de host personalizado
-p 8080/http	Solo HTTP, sin TLS

TCP/UDP (vinculado al host, omite Caddy)

-p [host_ip:]host_port:container_port[/protocol]@host

Ejemplo	Significado
-p 5432:5432@host	TCP 5432 en todas las interfaces
-p 127.0.0.1:5432:5432@host	TCP 5432 solo en bucle local
-p 53:5353/udp@host	UDP

---

Extensiones de Archivos Compose

Uncloud añade estas extensiones sobre Docker Compose:

x-ports — publicar puertos con dominios

services:
  app:
    image: app:latest
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
      - api.example.com:9000/https

x-caddy — configuración personalizada de Caddy para el servicio

services:
  app:
    image: app:latest
    x-caddy: |
      example.com {
        redir https://www.example.com{uri} permanent
      }
      www.example.com {
        reverse_proxy {{upstreams 8000}} {
          import common_proxy
        }
        basic_auth /admin/* {
          admin $2a$14$...
        }
      }

Funciones de plantilla disponibles dentro de x-caddy:

• {{upstreams [service] [port]}} — IPs de contenedores saludables
• {{.Name}} — nombre del servicio
• {{.Upstreams}} — mapa de todos los servicios a IPs

x-machines — restricciones de ubicación

services:
  db:
    image: postgres:18
    x-machines: db-machine          # Nombre de una sola máquina
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2

Ejemplo completo de múltiples servicios

services:
  api:
    build: ./api
    x-ports:
      - api.example.com:3000/https
    environment:
      DATABASE_URL: postgres://db:5432/mydb

  web:
    build: ./web
    x-ports:
      - example.com:8000/https
      - www.example.com:8000/https
    environment:
      API_URL: http://api:3000

  db:
    image: postgres:18
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/postgresql/data
    x-machines: db-machine

volumes:
  db-data:

---

Enrutamiento a Dispositivos Externos (No del Clúster)

Para exponer un dispositivo externo (por ejemplo, BMC, NAS, interfaz de router) a través de Caddy sin ejecutar un contenedor real:

1. Crear un fragmento de Caddyfile (por ejemplo, ~/device.caddyfile):

https://device.example.com {
    reverse_proxy https://192.168.1.x {
        transport http {
            tls_insecure_skip_verify   # necesario para certificados BMC autofirmados
        }
    }
    log
}

Para upstream en texto plano: reverse_proxy http://192.168.1.x:port

2. Registrar como servicio con nombre con contenedor no operativo:

uc service run \
  --name device-bmc \
  --caddyfile ~/device.caddyfile \
  registry.k8s.io/pause:3.9

pause es un contenedor mínimo no operativo: no hace nada, pero le da a Uncloud una entrada de servicio para adjuntar el Caddyfile.

3. Verificar:

uc caddy config   # El bloque device.example.com debería aparecer

--caddyfile no se puede combinar con puertos publicados que no sean @host.

Consejo de DNS: Un registro comodín (*.yourdomain.com → cluster-public-ip) hace que cualquier nuevo subdominio funcione inmediatamente, sin necesidad de cambios de DNS por servicio.

---

DNS del Servicio (Interno)

Los servicios dentro del clúster se resuelven entre sí por nombre:

Nombre DNS	Resuelve a
service-name	Cualquier contenedor saludable
service-name.internal	Igual
rr.service-name.internal	Round-robin
nearest.service-name.internal	Primero en la misma máquina

---

Escalado y Servicios Globales

uc scale web 5    # 5 réplicas (distribuidas entre máquinas)
uc scale web 1    # Reducir escala

services:
  caddy:
    deploy:
      mode: global   # Un contenedor en cada máquina

---

Plantillas de Etiquetas de Imagen (en compose.yaml)

image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}

Función	Salida
{{gitsha N}}	Primeros N caracteres del hash del commit
{{gitdate "formato"}}	Fecha del commit en formato Go
{{date "formato"}}	Fecha actual

---

Flujos de Trabajo Comunes

Desplegar desde el código fuente:

uc deploy                          # Construir + enviar + desplegar
uc build --push && uc deploy --no-build   # Pasos separados

Inspeccionar un servicio:

uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # Abre shell
uc exec web /bin/sh -c "env"       # Ejecutar comando específico

Despliegues sin tiempo de inactividad ocurren automáticamente; Uncloud espera a las comprobaciones de salud antes de terminar contenedores antiguos.

Forzar recreación:

uc deploy --recreate

---

Errores Comunes

Error	Solución
Editar el Caddyfile directamente	Usa x-caddy en compose o --caddyfile en uc service run
Proxy de un upstream HTTPS con certificado autofirmado	Añade transport http { tls_insecure_skip_verify }
uc caddy config no muestra bloques definidos por el usuario	El socket de administración de Caddy no es accesible — verifica uc inspect caddy y uc logs caddy
El servicio no puede alcanzar la IP LAN externa desde el contenedor	Verifica que el host del contenedor Caddy pueda enrutar a la red de destino
Volúmenes perdidos después de uc service rm	Los volúmenes con nombre persisten; solo se eliminan automáticamente los volúmenes anónimos