claude
1bd0fec23a
gateway(nginx) + manager(python 標準ライブラリ) + セッションごとの使い捨て Pod + reaper CronJob の構成。ブラウザ(PC/スマホ)からアクセスし、セッション単位で 独立した Alpine コンテナに Git リポジトリ(GitHub/Gitea など)をチェックアウトして 編集・検証・プッシュする。無操作が続いたセッションは Pod ごと自動破棄。 - セキュリティ: セッション NS 分離 / restricted PodSecurity / RBAC はセッション NS の pods,services のみの Role / セッション Pod は SA トークン非マウント・非 root・ readOnlyRootFilesystem・drop ALL caps・seccomp / NetworkPolicy で egress を DNS+HTTPS+SSH に限定 / Git ホスト allow-list / ResourceQuota+LimitRange - ライフサイクル: idleTimeout(Pod 内ウォッチドッグ + manager 回収) / maxLifetime (activeDeadlineSeconds) / maxSessions / 予備の孤児掃除 CronJob - 認証: token(既定) / basic / forward(外部SSO) / none。WebSocket は Cookie トークン - Claude 認証: ANTHROPIC_API_KEY または CLAUDE_CODE_OAUTH_TOKEN - CI: helm-release.yaml(未リリース版のみ tag+release+publish) / image-update-and-release.yaml(週次 npm 追従) / session-image.yaml(multi-arch build) - files/ 実体を .Files.Get で ConfigMap 化。helm lint / template 検証済み
93 lines
6.0 KiB
Markdown
93 lines
6.0 KiB
Markdown
# CLAUDE.md — claude-code Helm Chart
|
||
|
||
## リポジトリ概要
|
||
|
||
Alpine Linux ベースの軽量コンテナで **Claude Code をリモート実行** するための Helm チャート。
|
||
ブラウザ（PC / スマートフォン）からアクセスし、**セッションごとに独立した使い捨て Pod** で
|
||
Git リポジトリ（GitHub / Gitea など互換 Git 全般）をチェックアウト・編集・検証・プッシュする。
|
||
一定時間アイドルなセッション Pod は自動破棄される。Raspberry Pi などの ARM ベアメタル運用を想定。
|
||
|
||
- **Gitea リポジトリ**: `ssh://git@192.168.9.65/helmchart/claude-code`
|
||
- **Helm リポジトリ**: `https://git.cafepieters.com/api/packages/helmchart/helm`
|
||
- **セッションイメージ**: `git.cafepieters.com/helmchart/claude-code/session:<appVersion>`（CI で publish）
|
||
|
||
## アーキテクチャ（要点）
|
||
|
||
| コンポーネント | 実体 | 役割 |
|
||
|---|---|---|
|
||
| `gateway` | `nginxinc/nginx-unprivileged:alpine` | 単一入口。認証（token/basic/forward）、WebSocket リバースプロキシ、アクティビティ計測 |
|
||
| `manager` | `python:3.x-alpine`（標準ライブラリのみ） | セッション CRUD API、Web UI、アイドル/寿命回収ループ。in-cluster SA で K8s API を直接操作 |
|
||
| `session` | Alpine + node + git + ttyd + claude-code | セッションごとに作られる使い捨て Pod。`git clone` → `claude`（ttyd） → `claude-verify`/`claude-push` |
|
||
| `reaper` CronJob | `manager` イメージ `--reap-once` | manager 障害時の保険となる孤児掃除 |
|
||
|
||
- 制御プレーンはリリース NS、セッション Pod は専用 NS（`sessionsNamespace.name`）に分離。
|
||
- manager の RBAC はセッション NS の `pods` / `services` に限定した Role のみ（ClusterRole 不使用）。
|
||
- セッション Pod は **API サーバー到達不可**（`automountServiceAccountToken: false`）、
|
||
非 root / `readOnlyRootFilesystem` / drop ALL caps / seccomp RuntimeDefault、
|
||
egress は DNS + git ホスト + `api.anthropic.com` のみ（NetworkPolicy）。
|
||
- ファイル実体は `files/`（`.Files.Get` で ConfigMap 化）: `manager.py` / `session-entrypoint.sh`
|
||
/ `gateway.conf.template` / `gateway-entrypoint.sh` / `Dockerfile.session`。
|
||
|
||
## 実行環境について
|
||
|
||
**Helm はこのマシンにインストールされていない。** ローカルで `helm lint` / `template` は実行できない。
|
||
テンプレートの検証はステージングのクラスタか CI（`helm-release.yaml` の lint ステップ）で行う。
|
||
|
||
## Git 運用ルール（このリポジトリで厳守）
|
||
|
||
1. **機能を追加・変更したら、必ず `README.md` を更新してから作業完了とする。**
|
||
- values の新設キー、挙動変更、セキュリティ影響は README の該当セクションと
|
||
values リファレンス表へ反映する。
|
||
2. **変更は必ず Git Commit / Push する。**
|
||
- 作業単位ごとにコミットし、`origin/main` へ push するまでが作業完了。
|
||
3. **コミットメッセージに Claude クレジット（`Co-Authored-By` 等）を付けない。**
|
||
- `user.name = Claude` でコミットされるため、ユーザー名で判別可能。
|
||
4. `git pull` で取り込んだ変更は常に尊重する。revert して push することは禁止。
|
||
不適切と思われる場合はユーザーに改善提案を提示し、承認を得てから対応する。
|
||
|
||
### Git Commit 情報
|
||
|
||
| 項目 | 値 |
|
||
|------|-----|
|
||
| user.name | `Claude` |
|
||
| user.email | `claude@cafepieters.com` |
|
||
| SSH キー | `P:/Claude/.ssh/id_claude` |
|
||
| core.sshCommand | `ssh -i P:/Claude/.ssh/id_claude -F P:/Claude/.ssh/config -o StrictHostKeyChecking=no` |
|
||
|
||
## リリースフロー
|
||
|
||
- **バージョン番号**: `Chart.yaml` の `version` / `appVersion` は
|
||
**主アプリ = Claude Code CLI（`@anthropic-ai/claude-code` の npm 最新版）と同一**にする。
|
||
- **ワークフロー（3 本、他 Helm チャートプロジェクトと同じ思想）**
|
||
- `helm-release.yaml` — `main` への push で発火。`helm lint` の後、`Chart.yaml` の version が
|
||
未リリース（Gitea リリース・Package Registry 双方に存在しない）なら タグ + Gitea リリース +
|
||
チャート publish。リリース済みなら lint のみで終了（再 publish しない）。
|
||
- `image-update-and-release.yaml` — 毎週月曜 3:00 JST。npm の Claude Code 最新版と
|
||
base image（nginx / python）の最新 Alpine タグを確認。Claude Code 更新時は
|
||
`values.yaml` / `Chart.yaml` / README 履歴を更新しコミット → タグ + リリース + publish。
|
||
base image のみ更新時は `values.yaml` を更新してコミットのみ（**リリースなし**）。
|
||
- `session-image.yaml` — `files/Dockerfile.session` 等の変更、または上記による `Chart.yaml`
|
||
更新で発火。セッションイメージを `linux/amd64,linux/arm64` でビルドして
|
||
Gitea Container Registry（`helmchart/claude-code/session:<appVersion>` + `latest`）へ push。
|
||
- **手動リリース（臨時）**: 改修作業などで必要な場合はバージョン末尾にアルファベットを付与する
|
||
（例 `2.1.259` → `2.1.259-a` → `2.1.259-b`）。対応する `CHANGELOG-<version>.md` を追加し、
|
||
README の「バージョン履歴」にも 1 行追加する。
|
||
|
||
## 必要な Gitea Secrets
|
||
|
||
| シークレット名 | 用途 |
|
||
|---|---|
|
||
| `GITEA_TOKEN` | Gitea API（リリース作成・タグ操作） |
|
||
| `REGISTRY_USER` | Gitea Package / Container Registry ユーザー名 |
|
||
| `REGISTRY_TOKEN` | Gitea Package / Container Registry トークン（`docker login` にも使用） |
|
||
|
||
## 改修履歴
|
||
|
||
### 初版（2026-09-03, v2.1.259）
|
||
|
||
チャート新規作成。gateway + manager + 使い捨て session Pod + reaper CronJob の構成で、
|
||
ブラウザからの Claude Code リモート実行、GitHub/Gitea 両対応、アイドル自動破棄、
|
||
NetworkPolicy / RBAC 最小化 / restricted PodSecurity を実装。
|
||
|
||
**対象ファイル**: 全ファイル（初期コミット）
|