| name | uncloud |
| description | Uncloudクラスターの管理時に使用します — サービスのデプロイ、Caddyイングレスの設定、クラスター外デバイス向けの静的プロキシルートの追加、ポートの公開、スケーリング、ログの確認、または`uc` CLIによるマシンとボリュームの管理。 |
| origin | ECC |
Uncloudクラスター管理
uc CLIのリファレンス — Dockerコンテナ、WireGuardメッシュネットワーク、Caddyリバースプロキシを使用した分散型セルフホスティングプラットフォーム。
有効化するタイミング
以下の場合にUncloudクラスターを操作する際にこのスキルを使用してください：
uc machineでマシンをブートストラップまたは参加させる場合uc deployでComposeファイルからサービスをデプロイする場合- Uncloudを通じてHTTP、HTTPS、TCP、またはUDPポートを公開する場合
x-caddy、x-ports、または--caddyfileでCaddyイングレスを設定する場合- 外部LANデバイスをクラスタープロキシ経由でルーティングする場合
- ログ、サービス状態、ボリューム、DNS、またはマシン配置を確認する場合
仕組み
UncloudはWireGuardメッシュで接続されたピアマシン間でDockerサービスを実行します。各マシンは同等のクラスターメンバーであり、サービスはオーバーレイネットワーク上で通信し、Caddyはパブリックなhttp/HTTPSトラフィックを終端するためにグローバルに実行されます。ComposeファイルはUncloudの拡張機能を使用してイングレス、配置、および生成されたCaddy設定を行い、uc CLIはイメージの配布、スケジューリング、スケーリング、ログ、およびクラスター状態を処理します。
例
uc machine init user@host --name machine-1
uc service run --name web -p app.example.com:8080/https nginx:latest
uc deploy
コアコンセプト
- 中央コントロールプレーンなし — すべてのマシンはWireGuardで接続された同等のピア
- Caddyはすべてのマシンでグローバルサービスとして実行；Let's EncryptからTLSを自動取得
- オーバーレイネットワーク — サービスはデフォルトで
10.210.0.0/16経由で通信；メッシュ内でDNSを提供
- Caddyfileは自動生成 — 直接編集しないこと；代わりに
x-caddy / --caddyfileを使用する
CLIクイックリファレンス
マシン
| コマンド | 目的 |
|---|
uc machine init user@host | 最初のマシン / 新規クラスターのブートストラップ |
uc machine add user@host | 既存クラスターにマシンを参加させる |
uc machine ls | マシン一覧 |
uc machine update NAME --public-ip IP | イングレス用のパブリックIPを更新 |
uc machine rm NAME | マシンを削除 |
主なinitフラグ: --name、--network 10.210.0.0/16、--no-caddy、--no-dns、--public-ip auto\|IP\|none
サービス
| コマンド | 目的 |
|---|
uc service ls / uc ls | サービス一覧 |
uc service run IMAGE | 単一コンテナのサービスを実行 |
uc deploy | compose.yamlからデプロイ |
uc deploy --no-build | リビルドせずに既にプッシュされたイメージをデプロイ |
uc deploy --recreate | サービスの強制再作成 |
uc scale SERVICE N | レプリカ数を設定 |
uc service logs SERVICE | ログを表示 |
uc service exec SERVICE | コンテナにシェルで接続 |
uc service inspect SERVICE | 詳細情報 |
uc service rm SERVICE | サービスを削除（名前付きボリュームは保持） |
uc ps | クラスター全体のすべてのコンテナ |
イメージ
uc image push myapp:latest
uc image push myapp:latest -m machine1,machine2
uc images
ボリューム
uc volume ls
uc volume ls -m machine1
uc volume create NAME -m MACHINE
uc volume rm NAME
Caddy
uc caddy config
uc caddy deploy
DNS & コンテキスト
uc dns show
uc dns reserve
uc ctx ls
uc ctx use prod
ポートの公開
HTTP/HTTPS（Caddyリバースプロキシ経由）
-p [hostname:]container_port[/protocol]
| 例 | 意味 |
|---|
-p 8080/https | 自動service-name.cluster-domainホスト名でHTTPS |
-p app.example.com:8080/https | カスタムホスト名でHTTPS |
-p 8080/http | HTTPのみ、TLSなし |
TCP/UDP（ホストバウンド、Caddyをバイパス）
-p [host_ip:]host_port:container_port[/protocol]@host
| 例 | 意味 |
|---|
-p 5432:5432@host | すべてのインターフェースでTCP 5432 |
-p 127.0.0.1:5432:5432@host | ループバックのみTCP 5432 |
-p 53:5353/udp@host | UDP |
Composeファイルの拡張機能
UncloudはDockerComposeの上にこれらの拡張機能を追加します：
x-ports — ドメインを使用してポートを公開
services:
app:
image: app:latest
x-ports:
- example.com:8000/https
- www.example.com:8000/https
- api.example.com:9000/https
x-caddy — サービス用のカスタムCaddy設定
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$...
}
}
x-caddy内で使用可能なテンプレート関数：
{{upstreams [service] [port]}} — 正常なコンテナIP{{.Name}} — サービス名{{.Upstreams}} — すべてのサービス → IPのマップ
x-machines — 配置制約
services:
db:
image: postgres:18
x-machines: db-machine
app:
image: app:latest
x-machines:
- machine-1
- machine-2
マルチサービスの完全な例
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:
外部（クラスター外）デバイスへのルーティング
実際のコンテナを実行せずにCaddy経由で外部デバイス（例：BMC、NAS、ルーターUI）を公開するには：
1. Caddyfileスニペットを作成する（例：~/device.caddyfile）：
https://device.example.com {
reverse_proxy https://192.168.1.x {
transport http {
tls_insecure_skip_verify # 自己署名BMC証明書に必要
}
}
log
}
平文アップストリームの場合: reverse_proxy http://192.168.1.x:port
2. no-opコンテナで名前付きサービスとして登録する：
uc service run \
--name device-bmc \
--caddyfile ~/device.caddyfile \
registry.k8s.io/pause:3.9
pauseは最小限のno-opコンテナです — 何もしませんが、UncloudにCaddyfileを添付するためのサービスエントリを提供します。
3. 確認する：
uc caddy config
--caddyfileは非@hostの公開ポートと組み合わせることはできません。
DNSのヒント: ワイルドカードレコード（*.yourdomain.com → cluster-public-ip）を設定すると、新しいサブドメインが即座に機能します — サービスごとのDNS変更は不要です。
サービスDNS（内部）
クラスター内のサービスは名前で互いに解決できます：
| DNS名 | 解決先 |
|---|
service-name | 任意の正常なコンテナ |
service-name.internal | 同じ |
rr.service-name.internal | ラウンドロビン |
nearest.service-name.internal | マシンローカルを優先 |
スケーリング & グローバルサービス
uc scale web 5
uc scale web 1
services:
caddy:
deploy:
mode: global
イメージタグテンプレート（compose.yaml内）
image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}
image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}
| 関数 | 出力 |
|---|
{{gitsha N}} | コミットSHAの最初のN文字 |
{{gitdate "format"}} | Goフォーマットのgitコミット日時 |
{{date "format"}} | 現在の日時 |
一般的なワークフロー
ソースからデプロイ：
uc deploy
uc build --push && uc deploy --no-build
サービスを確認する：
uc inspect web
uc logs -f web
uc logs --since 1h web
uc exec web
uc exec web /bin/sh -c "env"
ゼロダウンタイムデプロイは自動的に行われます；Uncloudは古いコンテナを終了する前にヘルスチェックを待機します。
強制再作成：
uc deploy --recreate
よくあるミス
| ミス | 修正方法 |
|---|
| Caddyfileを直接編集する | composeのx-caddyまたはuc service runの--caddyfileを使用する |
| 自己署名証明書のHTTPSアップストリームをプロキシする | transport http { tls_insecure_skip_verify }を追加する |
uc caddy configにユーザー定義ブロックが表示されない | Caddy管理ソケットに到達不能 — uc inspect caddyとuc logs caddyを確認する |
| コンテナから外部LANのIPに到達できない | CaddyコンテナのホストがターゲットネットワークにルーティングできるかHER確認する |
uc service rm後にボリュームが失われた | 名前付きボリュームは保持される；匿名ボリュームのみ自動削除される |
