Gestion de Cluster Uncloud
Référence pour la CLI uc — une plateforme d'hébergement décentralisée utilisant des conteneurs Docker, un réseau maillé WireGuard et un proxy inverse Caddy.
Quand l'activer
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
Comment ça fonctionne
Uncloud exécute des services Docker sur des machines homologues connecté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 des 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 de base
- Aucun plan de contrôle central — toutes les machines sont des paires égales connectées par WireGuard
- Caddy s'exécute comme un service global sur chaque machine ; il obtient automatiquement les certificats TLS auprès de Let's Encrypt
- Réseau overlay — les services communiquent via
10.210.0.0/16par défaut ; DNS fourni à l'intérieur du maillage - Le Caddyfile est généré automatiquement — ne le modifiez 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 au cluster existant |
uc machine ls | Lister les machines |
uc machine update NAME --public-ip IP | Mettre à jour l'IP publique pour l'ingress |
uc machine rm NAME | Supprimer une machine |
Flags clés pour init : --name, --network 10.210.0.0/16, --no-caddy, --no-dns, --public-ip auto|IP|none
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 à partir de compose.yaml |
uc deploy --no-build | Déployer des images déjà poussées sans reconstruire |
uc deploy --recreate | Forcer la recréation du service |
uc scale SERVICE N | Définir le nombre de réplicas |
uc service logs SERVICE | Voir les logs |
uc service exec SERVICE | Ouvrir un 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 dans le 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 NAME -m MACHINE
uc volume rm NAME
Caddy
uc caddy config # Afficher le Caddyfile généré actuel (lecture seule)
uc caddy deploy # Déployer/mettre à niveau Caddy dans le cluster
DNS et 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 du cluster
uc ctx use prod # Changer de contexte
Publication de ports
HTTP/HTTPS (via le proxy inverse Caddy)
-p [nom_hôte:]port_conteneur[/protocole]
| Exemple | Signification |
|---|---|
-p 8080/https | HTTPS avec nom d'hôte automatique nom-service.domaine-du-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_hôte:]port_hôte:port_conteneur[/protocole]@host
| Exemple | Signification |
|---|---|
-p 5432:5432@host | TCP 5432 sur toutes les interfaces |
-p 127.0.0.1:5432:5432@host | TCP 5432 uniquement en boucle locale |
-p 53:5353/udp@host | UDP |
Extensions du fichier Compose
Uncloud ajoute ces extensions aux fonctionnalités standard de 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 complet multi-services
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 (hors cluster)
Pour exposer un périphérique externe (ex. BMC, NAS, interface de routeur) via Caddy sans exécuter de véritable conteneur :
1. Créez 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 brut : reverse_proxy http://192.168.1.x:port
2. Enregistrez-le comme un service nommé avec un conteneur factice :
uc service run \
--name device-bmc \
--caddyfile ~/device.caddyfile \
registry.k8s.io/pause:3.9
pause est un conteneur factice minimal — il ne fait rien, mais donne à Uncloud une entrée de service pour attacher le Caddyfile.
3. Vérifiez :
uc caddy config # Le bloc device.example.com devrait apparaître
--caddyfilene peut pas être combiné avec des ports publiés autres que@host.
Astuce DNS : Un enregistrement wildcard (*.votredomaine.com → ip-publique-du-cluster) signifie que tout nouveau sous-domaine fonctionne immédiatement — aucun changement DNS nécessaire par service.
DNS des services (interne)
Les services à l'intérieur du cluster se résolvent entre eux par leur nom :
| Nom DNS | Résout en |
|---|---|
nom-service | N'importe quel conteneur sain |
nom-service.internal | Idem |
rr.nom-service.internal | Round-robin |
nearest.nom-service.internal | D'abord local à la machine |
Mise à l'échelle et 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 tags d'image (dans compose.yaml)
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}
| Fonction | Sortie |
|---|---|
{{gitsha N}} | Les N premiers caractères du SHA du commit |
{{gitdate "format"}} | Date du commit Git au format Go |
{{date "format"}} | Date actuelle |
Workflows courants
Déploiement depuis les sources :
uc deploy # Build + push + deploy
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 interruption se font automatiquement ; Uncloud attend les vérifications de santé avant de terminer les anciens conteneurs.
Forcer la recréation :
uc deploy --recreate
Erreurs courantes
| Erreur | Correction |
|---|---|
| Modifier 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 acheminer 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 |