Koubou App contract
結論¶
工房はprivate yu-min3/koubou repoのapp-base用valuesと追加resourcesで配備する。kensan-labにはapp-projectのApplication登録だけを置き、共通Deployment/Service/HTTPRouteを再実装しない。共有DNS・Gateway・SSOの変更をこのPRに混ぜない。配備は手動syncとし、以下の前提が満たされるまで運転開始しない。
旧PR案のnetwork/koubou-entry、platform-project、共有Gateway認可へのhost追加、工房専用DestinationRule/SealedSecret、新LAN DNSは今回のdiffから削除した。旧案は未マージ・未配備であり、既存リソースのpruneは発生しない。
App/Platformの契約¶
| 項目 | Appが所有 | Platformが提供 |
|---|---|---|
| 配備 | private repoのchart/valuesと固定commit | Argo CD、app-project、repo参照権限 |
| 通信 | app-koubou内relay/Service/route/NetworkPolicy、senseへのCA/SAN検証 | gateway-prodのHTTPS・既定SSO、許可されたroute接続 |
| 認証 | senseの本人sub/group/署名検証、内部session | Keycloak本人認証、署名済みID token、callback登録 |
| 名前解決 | 必要なhostとGateway IPを要求 | LAN端末のDNS解決。DHCPや共通DNSはApp管理外 |
namespaceはApp resourcesが所有しPrune=false。PVCなし。App内relayからsenseへTLSを張るためEndpointSliceやGateway用DestinationRuleを追加しない。既存SSO契約を使うため共有AuthorizationPolicyに工房hostを追記しない。
候補URL: https://koubou.app.yu-min3.com(LAN Gateway 192.168.0.243)。まだ利用不可。App側の仕様・導入手順はprivate repoの deploy/app-entry.md。
Platformに足りない要素・確認事項¶
| ID | 現状/不足 | 当面の導入条件 | 継続改善の契約 | 担当 |
|---|---|---|---|---|
| P001 | private repoの参照権限は既存org credential templateの仕組みがあるが、工房repoへの実アクセス未検証 | Argo CDが工房の固定commitを読めることを確認。資格値は取得/表示しない | repo登録時に接続確認まで返す | Platform |
| P002 | Keycloakのcallback登録はhostごとのPlatform操作 | 工房App hostのcallback/weborigin登録を別Platform変更として行う | Appがhostを申請し、Platformが承認/登録/検証結果を返す。共有realmをAppが変更しない | Platform、公開/認証変更の判断はYu |
| P003 | OAuth2 routeのReferenceGrantがapp-kensan/app-konroを個別列挙 | app-koubouのHTTPRoute→auth-system/oauth2-proxy参照を別変更で許可 | App登録とcross-namespace認証参照許可を一緒に処理する。全namespaceへの無条件許可にはしない | Platform |
| P004 | LANスマホ用の名前解決がなく、Mac hostsに依存 | 工房host→.243と認証hostのLAN解決を提供 | LAN DNSを共有基盤として設計・独立PRで提供。Appはレコード要求だけを渡す | Platform、DHCP切替はYu |
| P005 | app-baseにcommand/argsと追加volume/mountの指定がない | 共通chart PR #543はレビュー/CI後にマージ済み | Appが共通templateを複製せずvaluesで設定できる | Platform |
| P006 | 既存App Gatewayが検証済みJWTを除去し、senseへ本人の署名が届かない | draft PR #544でJWT転送契約とP002/P003の登録を分離。Yu判断後に導入 | Appへ署名済み本人IDを渡し、App側でも検証できる | Platform、共有SSOの判断はYu |
P001は機能がないと断定せず確認事項。P002/P003は既存の手動登録契約が残っている。P004がスマホ導入の不足。これらを工房Appが直接作る構成にはしない。外部host TLSはAppのConfigMapで設定する。app-baseに必要な汎用機能はP005として別PRに分離する。
採用・却下¶
| 判定 | 案 | 理由 |
|---|---|---|
| 採用 | private app-base用valuesと追加resources+既存gateway-prod | Appの追加で共有認可のhost列挙を編集しない。App資源はapp-project内に収まる |
| 採用 | App relayがsense TLSを検証 | App固有CAをAppへ閉じ、EndpointSlice権限の拡大や共有DestinationRuleを不要にする |
| 却下 | 工房専用入口をnetwork/platform-projectへ置く | AppがPlatform権限に依存し、repo独立の要件を満たさない |
| 却下 | このApp PRでLAN DNS/DHCPまで導入する | 宅内全体への影響をAppの変更と分離して判断できない |
検証と残作業¶
既存app-baseと工房valuesはHelm lint/render、schema検証、上流imageのamd64/arm64 manifest確認を実施。Platform登録はAppProjectの許可kind/namespaceと整合する。実SSO・sense・Gateway datapath・スマホは未検証。P001〜P006とsense側導入を満たしてから手動syncし、本人ログイン/登録/停止と拒否経路を実測する。
壊れうるもの/戻し方¶
このPRの旧infra案は未配備のため、その削除による既存namespace/PVC/DNSのpruneはない。新Appはauto-sync/finalizerなし、ApplicationとnamespaceにはPrune=false。手動配備後にAppを止める場合はApp内route/relayだけを対象とし、共有Gateway/SSO/DNSは削除しない。
Yuの未決事項¶
このdraft PRでは共有Platform変更の承認を求めない。不足要素を別のPlatform改善として具体化してからレビューする。マージ前の本人確認条件を維持する。
共通Helm chartの利用¶
工房側の独自Deployment/Service/HTTPRoute templatesは削除した。Argo CDは既存app-baseとprivate工房values/resourcesをmulti-sourceで組み合わせる。汎用chartの不足(起動指定、追加mount、API token制御、listener指定)は別draft PR #543で扱う。既存kensan/konro/canaryのrenderが旧chartと同じ構造であることを確認した。工房固有のConfigMap・Namespace・NetworkPolicyだけがprivate repoに残る。
導入前レビューとsense実測¶
独立レビューはchart/multi-source/selectors/TLS設定に確定P0/P1なし。P006は Istio 1.27.3実装 と Envoy JWT契約 で確認した。PR544の共有認証変更はこのApp登録PRと分離し、未適用。
senseのTLS adapterはlan-sso-v3でactive/running、公開CA/SAN検証と未認証401を実測。systemdのroot:root0440 credential形式を限定許可する修正・拒否試験を追加し、installer成功条件も実TLS応答へ変更。これはSSO全経路の合格ではない。private repoの直接取得とLAN DNSは未確認/未提供の条件として残る。
2026-10-10 導入条件の更新¶
| 条件 | 現在の状態 | 残る確認 |
|---|---|---|
| 共通chart・JWT転送・認証参照 | PR543/544はマージ済み。chartは62cabffeへ固定 | GitOps実反映と本人SSO |
| 宅内DNS | .247が稼働。YuがDHCPにPrimary .247/Secondary .1を設定、Mac反映と内部/外部UDP/TCP解決を実測 | 工房route作成後の名前解決とスマホ確認。障害時切替は未検証 |
| sense本人検証 | koubou-lan-sso.service稼働、TLS8790。sense限定hostsでauth.yu-mins.comを.242へ解決し、TLS検証付きJWKS取得成功 | 実際の本人JWTで拒否/許可を確認 |
| private repo取得 | 専用read-only deploy keyとSealedSecretをPR545へ準備。App参照はSSHへ変更 | Yuの承認後に公開鍵登録、PR545反映、固定commit取得 |
公開DNSの変更は不要。App routeを共通chartから作るとLAN DNSに自動登録される。Appの手動syncはPR545と本PRの承認・GitOps反映確認後に実施する。家族の端末で障害時のDNS切替がどう動くかは別途確認が必要。