uncloud

Uncloud クラスター管理

uc CLI のリファレンス — Docker コンテナ、WireGuard メッシュネットワーキング、Caddy リバースプロキシを使用した分散型セルフホスティングプラットフォーム。

有効化タイミング

Uncloud クラスターを操作する際にこのスキルを使用します。特に以下の場合:

• uc machine でのマシンのブートストラップや参加
• Compose ファイルからの uc deploy によるサービスのデプロイ
• Uncloud 経由での HTTP、HTTPS、TCP、UDP ポートの公開
• x-caddy、x-ports、または --caddyfile を使用した Caddy イングレスの設定
• クラスタープロキシを介した外部 LAN デバイスのルーティング
• ログ、サービス状態、ボリューム、DNS、マシン配置の確認

動作の仕組み

Uncloud は WireGuard メッシュで接続されたピアマシン上で Docker サービスを実行します。各マシンはクラスターの同等のメンバーであり、サービスはオーバーレイネットワーク上で通信し、Caddy はパブリックな HTTP/HTTPS トラフィックを終端するためにグローバルに実行されます。Compose ファイルでは、イングレス、配置、生成された Caddy 設定に Uncloud 拡張を使用でき、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    # 現在生成されている Caddyfile を表示（読み取り専用）
uc caddy deploy    # クラスター全体に Caddy をデプロイ/アップグレード

DNS とコンテキスト

uc dns show        # 予約済みの *.uncld.dev ドメインを表示
uc dns reserve     # 新しいドメインを予約
uc ctx ls          # クラスターコンテキストを一覧表示
uc ctx use prod    # コンテキストを切り替え

---

ポート公開

HTTP/HTTPS（Caddy リバースプロキシ経由）

-p [ホスト名:]コンテナポート[/プロトコル]

例	意味
-p 8080/https	自動 サービス名.クラスタードメイン ホスト名で HTTPS
-p app.example.com:8080/https	カスタムホスト名で HTTPS
-p 8080/http	HTTP のみ、TLS なし

TCP/UDP（ホストバインド、Caddy をバイパス）

-p [ホストIP:]ホストポート:コンテナポート[/プロトコル]@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 は Docker Compose に以下の拡張を追加します:

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:ポート

2. 名前付きサービスとして登録（no-op コンテナ）:

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

pause は最小限の no-op コンテナです — 何も行いませんが、Caddyfile をアタッチするためのサービスエントリを Uncloud に提供します。

3. 確認:

uc caddy config   # device.example.com ブロックが表示されるはずです

--caddyfile は、@host 以外の公開ポートと組み合わせることはできません。

DNS ヒント: ワイルドカードレコード（*.yourdomain.com → クラスターパブリックIP）を使用すると、新しいサブドメインは即座に機能します — サービスごとに DNS 変更は不要です。

---

サービス DNS（内部）

クラスター内のサービスは、名前でお互いを解決します:

DNS 名	解決先
service-name	正常な任意のコンテナ
service-name.internal	同上
rr.service-name.internal	ラウンドロビン
nearest.service-name.internal	同一マシン優先

---

スケーリングとグローバルサービス

uc scale web 5    # 5 レプリカ（マシン間で分散）
uc scale web 1    # スケールダウン

services:
  caddy:
    deploy:
      mode: global   # すべてのマシンに 1 コンテナ

---

イメージタグテンプレート（compose.yaml 内）

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

関数	出力
{{gitsha N}}	コミット SHA の先頭 N 文字
{{gitdate "format"}}	Git コミット日時（Go 形式）
{{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 コンテナのホストがターゲットネットワークにルーティングできることを確認する
uc service rm 後にボリュームが失われる	名前付きボリュームは保持されます。匿名ボリュームのみ自動削除されます