uncloud

Gestion de cluster Uncloud

Référence pour la CLI uc — une plateforme d'auto-hébergement décentralisée utilisant des conteneurs Docker, le maillage réseau WireGuard et le proxy inverse Caddy.

Quand activer cette compétence

Utilisez cette compétence lorsque vous travaillez avec des clusters Uncloud, en particulier pour :

• Amorcer ou joindre des machines avec uc machine
• Déployer des services à partir de fichiers Compose avec uc deploy
• Publier des ports HTTP, HTTPS, TCP ou UDP via Uncloud
• Configurer l'ingress Caddy avec x-caddy, x-ports ou --caddyfile
• Router des périphériques LAN externes via le proxy du cluster
• Inspecter les logs, l'état des services, les volumes, le DNS ou le placement des machines

Fonctionnement

Uncloud exécute des services Docker sur plusieurs machines reliées par un maillage WireGuard. Chaque machine est un membre égal du cluster ; les services communiquent sur le réseau overlay et Caddy s'exécute globalement pour terminer le trafic HTTP/HTTPS public. Les fichiers Compose peuvent utiliser les extensions Uncloud pour l'ingress, le placement et la configuration Caddy générée, tandis que la CLI uc gère la distribution des images, l'ordonnancement, la mise à l'échelle, les logs et l'état du cluster.

Exemples

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

Concepts clés

• Pas de plan de contrôle central — toutes les machines sont des pairs égaux connectés par WireGuard
• Caddy s'exécute comme un service global sur chaque machine ; obtient automatiquement les certificats TLS de Let's Encrypt
• Réseau overlay — les services communiquent via 10.210.0.0/16 par défaut ; DNS fourni à l'intérieur du maillage
• Le Caddyfile est autogénéré — ne l'éditez jamais directement ; utilisez x-caddy / --caddyfile à la place

---

Référence rapide de la CLI

Machines

Commande	Objectif
uc machine init user@host	Amorcer la première machine / nouveau cluster
uc machine add user@host	Joindre une machine à un cluster existant
uc machine ls	Lister les machines
uc machine update NOM --public-ip IP	Mettre à jour l'IP publique pour l'ingress
uc machine rm NOM	Supprimer une machine

Indicateurs init clés : --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|aucun

Services

Commande	Objectif
uc service ls / uc ls	Lister les services
uc service run IMAGE	Exécuter un service conteneur unique
uc deploy	Déployer depuis compose.yaml
uc deploy --no-build	Déployer des images déjà poussées sans reconstruction
uc deploy --recreate	Forcer la recréation des services
uc scale SERVICE N	Définir le nombre de réplicas
uc service logs SERVICE	Voir les logs
uc service exec SERVICE	Shell dans le conteneur
uc service inspect SERVICE	Informations détaillées
uc service rm SERVICE	Supprimer le service (conserve les volumes nommés)
uc ps	Tous les conteneurs du cluster

Images

uc image push myapp:latest                    # Pousser l'image locale vers toutes les machines
uc image push myapp:latest -m machine1,machine2  # Pousser vers des machines spécifiques
uc images                                     # Lister les images dans le cluster

Volumes

uc volume ls                  # Tous les volumes
uc volume ls -m machine1      # Sur une machine spécifique
uc volume create NOM -m MACHINE
uc volume rm NOM

Caddy

uc caddy config    # Afficher le Caddyfile généré actuel (lecture seule)
uc caddy deploy    # Déployer/mettre à niveau Caddy sur le cluster

DNS & Contexte

uc dns show        # Afficher le domaine réservé *.uncld.dev
uc dns reserve     # Réserver un nouveau domaine
uc ctx ls          # Lister les contextes de cluster
uc ctx use prod    # Changer de contexte

---

Publication de ports

HTTP/HTTPS (via le proxy inverse Caddy)

-p [nom_hote:]port_conteneur[/protocole]

Exemple	Signification
-p 8080/https	HTTPS avec nom d'hôte automatique nom-service.domaine-cluster
-p app.example.com:8080/https	HTTPS avec nom d'hôte personnalisé
-p 8080/http	HTTP uniquement, pas de TLS

TCP/UDP (lié à l'hôte, contourne Caddy)

-p [ip_hote:]port_hote:port_conteneur[/protocole]@hote

Exemple	Signification
-p 5432:5432@hote	TCP 5432 sur toutes les interfaces
-p 127.0.0.1:5432:5432@hote	TCP 5432 loopback uniquement
-p 53:5353/udp@hote	UDP

---

Extensions de fichier Compose

Uncloud ajoute ces extensions par-dessus Docker Compose :

x-ports — publier des ports avec des domaines

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

x-caddy — configuration Caddy personnalisée pour le service

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$...
        }
      }

Fonctions de template disponibles dans x-caddy :

• {{upstreams [service] [port]}} — IPs des conteneurs sains
• {{.Name}} — nom du service
• {{.Upstreams}} — carte de tous les services → IPs

x-machines — contraintes de placement

services:
  db:
    image: postgres:18
    x-machines: db-machine          # Nom de machine unique
  app:
    image: app:latest
    x-machines:
      - machine-1
      - machine-2

Exemple multi-services complet

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:

---

Routage vers des périphériques externes (non cluster)

Pour exposer un périphérique externe (ex. BMC, NAS, interface routeur) via Caddy sans exécuter de conteneur réel :

1. Créer un extrait de Caddyfile (ex. ~/device.caddyfile) :

https://device.example.com {
    reverse_proxy https://192.168.1.x {
        transport http {
            tls_insecure_skip_verify   # nécessaire pour les certificats BMC auto-signés
        }
    }
    log
}

Pour un amont en texte clair : reverse_proxy http://192.168.1.x:port

2. Enregistrer comme service nommé avec un conteneur no-op :

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

pause est un conteneur no-op minimal — il ne fait rien, mais donne à Uncloud une entrée de service pour attacher le Caddyfile.

3. Vérifier :

uc caddy config   # le bloc device.example.com devrait apparaître

--caddyfile ne peut pas être combiné avec des ports publiés non-@hote.

Astuce DNS : Un enregistrement wildcard (*.votredomaine.com → ip-publique-cluster) signifie que tout nouveau sous-domaine fonctionne immédiatement — aucun changement DNS par service nécessaire.

---

DNS des services (interne)

Les services à l'intérieur du cluster se résolvent par leur nom :

Nom DNS	Résout en
nom-service	Tout conteneur sain
nom-service.internal	Idem
rr.nom-service.internal	Round-robin
nearest.nom-service.internal	Priorité locale à la machine

---

Mise à l'échelle & Services globaux

uc scale web 5    # 5 réplicas (répartis sur les machines)
uc scale web 1    # Réduire

services:
  caddy:
    deploy:
      mode: global   # Un conteneur sur chaque machine

---

Templates de balises d'image (dans compose.yaml)

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

Fonction	Sortie
{{gitsha N}}	N premiers caractères du SHA du commit
{{gitdate "format"}}	Date du commit Git au format Go
{{date "format"}}	Date actuelle

---

Workflows courants

Déployer depuis les sources :

uc deploy                          # Build + push + déploiement
uc build --push && uc deploy --no-build   # Étapes séparées

Inspecter un service :

uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web                        # Ouvre un shell
uc exec web /bin/sh -c "env"       # Exécuter une commande spécifique

Les déploiements sans temps d'arrêt se font automatiquement ; Uncloud attend les health checks avant de terminer les anciens conteneurs.

Forcer la recréation :

uc deploy --recreate

---

Erreurs fréquentes

Erreur	Correction
Éditer le Caddyfile directement	Utilisez x-caddy dans le compose ou --caddyfile sur uc service run
Proxifier un amont HTTPS avec un certificat auto-signé	Ajoutez transport http { tls_insecure_skip_verify }
uc caddy config n'affiche aucun bloc défini par l'utilisateur	Le socket admin Caddy est inaccessible — vérifiez uc inspect caddy et uc logs caddy
Le service ne peut pas atteindre l'IP LAN externe depuis le conteneur	Vérifiez que l'hôte du conteneur Caddy peut router vers le réseau cible
Volumes perdus après uc service rm	Les volumes nommés persistent ; seuls les volumes anonymes sont automatiquement supprimés