feat: Service を LoadBalancer 対応にしローカル LB の IP で管理画面へアクセス可能に (v2.1.263-a)

- templates/service.yaml: service.type 既定を LoadBalancer に。annotations (kube-vip の VIP 指定等) / loadBalancerIP / loadBalancerClass / loadBalancerSourceRanges / externalTrafficPolicy / nodePort / labels を追加。 Ingress 機能は変更なし（LoadBalancer と併用可） - values.yaml / values.schema.json: service ブロックを拡張 - templates/NOTES.txt: LoadBalancer の EXTERNAL-IP 案内を追加 - examples/loadbalancer-oauth.values.yaml: Ingress 無効 + LB + source range 制限 + サブスクリプション認証 (authMode: oauth) の構成例を追加 - README: 「Claude 認証（API 課金なし / サブスクリプション）」「管理画面へのアクセス（LoadBalancer / Ingress）」セクションを追加。claude setup-token → anthropic.authMode: oauth（CLAUDE_CODE_OAUTH_TOKEN 注入）でローカル実行と同一挙動 - helm lint / template 検証済み
2026-09-08 14:01:34 +09:00
parent 71d8db5b09
commit cd7092be17
9 changed files with 323 additions and 15 deletions
@@ -21,6 +21,8 @@ Raspberry Pi などの ARM ベアメタル Kubernetes を主な対象にして
 - [アーキテクチャ](#アーキテクチャ)
 - [セッションのライフサイクル](#セッションのライフサイクル)
 - [セキュリティモデル](#セキュリティモデル)
+- [Claude 認証（API 課金なし / サブスクリプション）](#claude-認証api-課金なし--サブスクリプション)
+- [管理画面へのアクセス（LoadBalancer / Ingress）](#管理画面へのアクセスloadbalancer--ingress)
 - [インストール](#インストール)
 - [使い方](#使い方)
 - [values リファレンス](#values-リファレンス)
@@ -32,7 +34,7 @@ Raspberry Pi などの ARM ベアメタル Kubernetes を主な対象にして
  - [git — 接続先と認証アイデンティティ](#git--接続先と認証アイデンティティ)
  - [session — 使い捨てセッション](#session--使い捨てセッション)
  - [networkPolicy](#networkpolicy)
-  - [ingress / service](#ingress--service)
+  - [service / ingress](#ingress--service)
 - [セッションイメージ](#セッションイメージ)
 - [運用](#運用)
 - [トラブルシューティング](#トラブルシューティング)
@@ -111,13 +113,120 @@ manager / gateway / session-entrypoint の実体は `files/` にあり、`.Files
 > **注意** — `values.yaml` に API キーや秘密鍵を書いてコミットしないでください。`helm get values` /
 > CI ログ / Git 履歴に残ります。`existingSecret` か CI からの `--set` を使ってください。

+## Claude 認証（API 課金なし / サブスクリプション）
+
+このチャートは **Claude の API（従量課金）を使わずに**、ローカルの Claude Code と同じ
+**サブスクリプション認証（Pro / Max プラン）** で動かせます。セッション内の `claude` の
+挙動・機能はローカル実行と同一です（同じ CLI・同じログイン方式）。
+
+1. 手元の PC（Claude にログイン済み）で長期トークンを発行:
+
+   ```bash
+   claude setup-token
+   ```
+
+   ブラウザで承認すると `CLAUDE_CODE_OAUTH_TOKEN` として使える長期トークンが表示されます。
+
+2. それをチャートに渡す（`authMode: oauth`）:
+
+   ```bash
+   helm upgrade --install claude-code cafepieters/claude-code -n claude-code --create-namespace \
+     -f examples/loadbalancer-oauth.values.yaml \
+     --set anthropic.oauthToken="<発行されたトークン>"
+   ```
+
+   Secret にしておく場合:
+
+   ```bash
+   kubectl -n claude-code-sessions create secret generic claude-oauth \
+     --from-literal=CLAUDE_CODE_OAUTH_TOKEN="<トークン>"
+   # values: anthropic.existingSecret=claude-oauth
+   ```
+
+| 方式 | values | 認証情報 | 課金 |
+|---|---|---|---|
+| **サブスクリプション（推奨）** | `anthropic.authMode: oauth` | `anthropic.oauthToken`（`claude setup-token`） | Claude プランの利用枠を消費（API 課金なし） |
+| API キー | `anthropic.authMode: apiKey` | `anthropic.apiKey`（`sk-ant-...`） | API 従量課金 |
+
+- トークンは **セッション NS の Secret** に保存され、セッション Pod へ環境変数
+  `CLAUDE_CODE_OAUTH_TOKEN` として注入されます（`values.yaml` に平文で書かない）。
+- 利用枠はローカルの Claude Code と共有です。複数セッションを同時に走らせると
+  プランのレート上限に早く達する点に注意してください。
+- トークンには有効期限があります。失効したら `claude setup-token` で再発行し
+  `helm upgrade --set anthropic.oauthToken=...`（または Secret 更新 + Pod 再起動）します。
+
+## 管理画面へのアクセス（LoadBalancer / Ingress）
+
+管理画面（gateway）への到達経路は 2 つあり、**併用できます**。既定は LoadBalancer です。
+
+### A. LoadBalancer でローカルネットワークの IP を使う（既定・Ingress 不要）
+
+`service.type: LoadBalancer`（既定）にすると、クラスタの LB 実装
+（**kube-vip** / MetalLB / Cilium LB-IPAM など）がローカルネットワークの IP を払い出します。
+その IP をブラウザで開くだけでアクセスできます。ドメインも Ingress も TLS 終端も不要です。
+
+```yaml
+ingress:
+  enabled: false                 # Ingress は張らない
+service:
+  type: LoadBalancer
+  port: 80
+  annotations:
+    kube-vip.io/loadbalancerIPs: "192.168.9.50"   # 払い出す VIP（空きアドレス）
+    kube-vip.io/vipHost: "cpi11"
+  loadBalancerSourceRanges:      # 接続元をローカルセグメントに限定（第一の防御線）
+    - 192.168.9.0/24
+  externalTrafficPolicy: Local   # 実クライアント IP を保持
+```
+
+```bash
+kubectl -n claude-code get svc claude-code       # EXTERNAL-IP を確認
+# → http://<EXTERNAL-IP>/ をブラウザで開く
+```
+
+| キー | 説明 |
+|---|---|
+| `service.type` | `LoadBalancer`（既定）/ `ClusterIP` / `NodePort` |
+| `service.port` | 待受ポート（既定 `80`） |
+| `service.annotations` | LB 実装へのヒント（kube-vip の VIP 指定、MetalLB のプール指定など） |
+| `service.loadBalancerIP` | 払い出す IP を直接指定（annotations 指定を推奨） |
+| `service.loadBalancerSourceRanges` | 接続を許可する CIDR。**Ingress を張らない構成では必ず設定して接続元を絞る** |
+| `service.loadBalancerClass` | 複数 LB 実装がある場合の指定 |
+| `service.externalTrafficPolicy` | `Local` で実クライアント IP を保持 |
+| `service.nodePort` | `type: NodePort` 時の固定ポート |
+
+> **セキュリティ** — LoadBalancer は L3/L4 でネットワークに口を開けます。`loadBalancerSourceRanges`
+> で接続元を絞り、`auth.mode` は `token`（既定）以上にしてください。VIP セグメントは
+> ルーターの DHCP 範囲と重複させないこと。
+
+### B. Ingress でドメインアクセス（従来どおり維持）
+
+`ingress.enabled: true` で Ingress を作成します。A と同時に有効化しても構いません。
+WebSocket 用に `proxy-read-timeout` / `proxy-send-timeout` を既定 `3600` に設定します
+（`ingress.annotations` で上書き可）。TLS は `ingress.tls` で設定します。
+
+```yaml
+ingress:
+  enabled: true
+  className: nginx
+  hosts:
+    - host: claude-code.example.com
+      paths: [{ path: /, pathType: Prefix }]
+  tls:
+    - secretName: claude-code-tls
+      hosts: [claude-code.example.com]
+```
+
 ## インストール

 ### 前提

 - Kubernetes 1.25+（PodSecurity admission）、NetworkPolicy 対応 CNI（Calico / Cilium など）
- Ingress コントローラー（外部公開する場合。WebSocket を通すため read/send timeout を延長）
- `ANTHROPIC_API_KEY`（または `claude setup-token` で発行した OAuth トークン）
+- 管理画面の公開方法に応じて **どちらか**:
+  - LoadBalancer 実装（kube-vip / MetalLB / Cilium LB-IPAM など） … 既定
+  - Ingress コントローラー … `ingress.enabled: true` の場合
+  - どちらも無い場合は `service.type: ClusterIP` + `kubectl port-forward` で利用可
+- Claude の認証情報 … `claude setup-token` の OAuth トークン（推奨）または `ANTHROPIC_API_KEY`

 ### Helm リポジトリから

@@ -130,6 +239,22 @@ helm upgrade --install claude-code cafepieters/claude-code \
  --set anthropic.apiKey="$ANTHROPIC_API_KEY"
 ```

+### ローカル LB の IP + サブスクリプション認証（API 不要・推奨構成）
+
+```bash
+claude setup-token   # 手元の PC で長期 OAuth トークンを発行
+
+helm upgrade --install claude-code cafepieters/claude-code \
+  -n claude-code --create-namespace \
+  -f examples/loadbalancer-oauth.values.yaml \
+  --set anthropic.oauthToken="<発行されたトークン>" \
+  --set-file git.identities.gitea-ssh.sshPrivateKey=P:/Claude/.ssh/id_claude \
+  --set-file git.identities.gitea-ssh.knownHosts=./known_hosts.gitea
+```
+
+`examples/loadbalancer-oauth.values.yaml` は Ingress 無効・`service.type: LoadBalancer` +
+kube-vip の VIP 指定 + `loadBalancerSourceRanges` によるローカルセグメント限定の構成です。
+
 ### ローカルチャートから（GitHub 公開リポジトリだけ触る最小構成）

 ```bash
@@ -159,11 +284,11 @@ ssh-keyscan 192.168.9.65 > known_hosts.gitea

 ## 使い方

-1. アクセス（Ingress 無効ならポートフォワード）:
-
-   ```bash
-   kubectl -n claude-code port-forward svc/claude-code 8080:80
-   ```
+1. 管理画面を開く:
+   - **LoadBalancer（既定）**: `kubectl -n claude-code get svc claude-code` の `EXTERNAL-IP` を
+     ブラウザで開く（`http://<IP>/`）
+   - **Ingress**: 設定したドメイン（`https://claude-code.example.com/`）
+   - **どちらも無効**: `kubectl -n claude-code port-forward svc/claude-code 8080:80` → `http://localhost:8080/`

 2. `auth.mode: token` の場合、トークンを取得して UI に貼り付け（または `?token=` で開く）:

@@ -288,9 +413,8 @@ GitHub でも Gitea でも GitLab でも、SSH か HTTPS トークンで認証

 ### ingress / service

-`ingress.enabled: true` で Ingress を作成。WebSocket 用に `proxy-read-timeout` /
-`proxy-send-timeout` を既定 `3600` に設定します（`ingress.annotations` で上書き可）。
-`service.type` は `ClusterIP` 既定。
+→ [管理画面へのアクセス（LoadBalancer / Ingress）](#管理画面へのアクセスloadbalancer--ingress) を参照。
+`service.type` の既定は `LoadBalancer`、`ingress.enabled` の既定は `false`（両者は併用可）。

 ## セッションイメージ

@@ -368,5 +492,6 @@ docker buildx build --platform linux/amd64,linux/arm64 \

 | バージョン | Claude Code | 変更内容 |
 |---|---|---|
+| 2.1.263-a | 2.1.263 | Service を `LoadBalancer` 対応（kube-vip 等でローカル LB の IP から管理画面へアクセス、`loadBalancerSourceRanges` で接続元制限、既定を `LoadBalancer` に変更）。Ingress は従来どおり併用可。API を使わないサブスクリプション認証（`claude setup-token` → `authMode: oauth`）の手順を README に追記 |
 | 2.1.263 | 2.1.263 | 自動更新 |
 | 2.1.259 | 2.1.259 | 初版。gateway + manager + 使い捨て session Pod + reaper、GitHub/Gitea 対応、アイドル自動破棄、NetworkPolicy / RBAC 最小化 / restricted PodSecurity |