Uncloud クラスタ管理

Uncloud クラスタ管理 は何をしますか？

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

アクティベートするタイミング

このスキルは、Uncloud クラスタを操作するとき、特に以下の場合に使用します。

• uc machine を使用したマシンのブートストラップや参加
• uc deploy を使用した Compose ファイルからのサービスのデプロイ
• Uncloud を介した HTTP、HTTPS、TCP、UDP ポートの公開
• x-caddy、x-ports、--caddyfile を使用した Caddy Ingress の設定
• 外部 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:

---

外部（非クラスタ）デバイスへのルーティング

実際のコンテナを実行せずに、外部デバイス（例：BMC、NAS、ルーターUI）を Caddy 経由で公開するには:

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   # device.example.com ブロックが表示されるはず

--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    # 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"}}	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 コンテナのホストがターゲットネットワークにルーティングできることを確認
uc service rm 後にボリュームが失われる	名前付きボリュームは保持されます。削除されるのは匿名ボリュームのみです