uncloud

Gestión de Clúster Uncloud

Referencia para la CLI uc — una plataforma de auto-hosting descentralizada que utiliza contenedores Docker, malla de red WireGuard y proxy inverso Caddy.

Cuándo Activarla

Usa esta habilidad 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 ingress de Caddy con x-caddy, x-ports o --caddyfile
• Enrutar dispositivos LAN externos a través del proxy del clúster
• Inspeccionar logs, estado de servicios, volúmenes, DNS o ubicación de máquinas

Cómo Funciona

Uncloud ejecuta servicios Docker en máquinas pares conectadas por 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 tráfico público HTTP/HTTPS. Los archivos Compose pueden usar extensiones de Uncloud para ingress, ubicación y configuración generada de Caddy, mientras que la CLI uc maneja la distribución de imágenes, planificación, escalado, logs y estado del clúster.

Ejemplos

uc machine init usuario@host --name maquina-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 conectadas por WireGuard
• Caddy se ejecuta como un servicio global en cada máquina; obtiene TLS automáticamente de Let's Encrypt
• Red superpuesta — los servicios se comunican mediante 10.210.0.0/16 por defecto; DNS proporcionado dentro de la malla
• Caddyfile se autogenera — nunca lo edites directamente; usa x-caddy / --caddyfile en su lugar

---

Referencia Rápida de la CLI

Máquinas

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

Banderas 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 IMAGEN	Ejecutar un servicio de un solo contenedor
uc deploy	Desplegar desde compose.yaml
uc deploy --no-build	Desplegar imágenes ya subidas sin reconstruir
uc deploy --recreate	Forzar recreación del servicio
uc scale SERVICIO N	Establecer número de réplicas
uc service logs SERVICIO	Ver logs
uc service exec SERVICIO	Acceder al shell del contenedor
uc service inspect SERVICIO	Información detallada
uc service rm SERVICIO	Eliminar servicio (conserva volúmenes con nombre)
uc ps	Todos los contenedores en todo el clúster

Imágenes

uc image push miapp:latest                    # Subir imagen local a todas las máquinas
uc image push miapp:latest -m maquina1,maquina2  # Subir 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 maquina1      # En una máquina específica
uc volume create NOMBRE -m MAQUINA
uc volume rm NOMBRE

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 *.uncld.dev reservado
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 (mediante proxy inverso de Caddy)

-p [nombre_host:]puerto_contenedor[/protocolo]

Ejemplo	Significado
-p 8080/https	HTTPS con nombre de host automático nombre-servicio.dominio-cluster
-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 [ip_host:]puerto_host:puerto_contenedor[/protocolo]@host

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

---

Extensiones del Archivo 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 [servicio] [puerto]}} — IPs de contenedores saludables
• {{.Name}} — nombre del servicio
• {{.Upstreams}} — mapa de todos los servicios → 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:
      - maquina-1
      - maquina-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 (Fuera del Clúster)

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

1. Crea un fragmento de Caddyfile (ej. ~/dispositivo.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:puerto

2. Regístralo como un servicio con nombre con un contenedor sin operación:

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

pause es un contenedor mínimo sin operación — no hace nada, pero le da a Uncloud una entrada de servicio para adjuntar el Caddyfile.

3. Verifica:

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 (*.sudominio.com → ip-publica-cluster) significa que cualquier nuevo subdominio funciona de inmediato — 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
nombre-servicio	Cualquier contenedor saludable
nombre-servicio.internal	Igual
rr.nombre-servicio.internal	Round-robin
nearest.nombre-servicio.internal	Primero el de la máquina local

---

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: miapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: miapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}

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

---

Flujos de Trabajo Comunes

Desplegar desde el código fuente:

uc deploy                          # Construir + subir + 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 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 admin de Caddy no es accesible — verifica uc inspect caddy y uc logs caddy
El servicio no puede alcanzar una 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