k8s-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37dcb752eb0c0b10dd35af27b071e5dad054674e111cff16a60e49b78e7de64b
+  data.tar.gz: '0867da799bf1c8914940bccae887f22d976e67826271d05313d965bf6aec8f15'
+SHA512:
+  metadata.gz: '039460cf0b175fbb51f160ce454cb9abe54e0001fb5d974f5b9da24c4c55750aa9e39326157d7306c319e08c64556284dfe994618642b374ab00e03c258465ec'
+  data.tar.gz: 124d5016d3e90068fe6ca03241c6cba6364bf956ee564324cf6d0329426f824b1a27e916e9234f279aacc216ae8450178e3f4ec437a5ef311c8f2cce199b9f28

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Change Log
+
+`k8s-rails` の全 notable な変更はこのファイルに記録する。
+
+## 0.1.0
+
+- **M0**: gem 骨子（gemspec / Gemfile / Rakefile / version / require 構造）
+- **M1**: Configuration + Client（lazy connect・K1 BearerToken 橋渡し）・例外体系
+  （`Unavailable` / `NotFound` / `ApiError` + `ReadOnlyError` / `RedeclarationError`）
+- **M2**: CRD 宣言 DSL + Resource（`list` / `find` / `find_or_nil` / `create` / `patch`、
+  `readonly` は明示 boolean、再宣言は `RedeclarationError`）
+- **M3**: 計測（ActiveSupport::Notifications 経由、無効時 no-op）+ README + rubocop
+- **M4**: consumer Rails アプリの K8s サービス移行で動作検証
+  （実クラスタ microk8s v1.33.13）
+- 応答は常に文字列キー（K2）・純 Ruby `Normalizer`（ActiveSupport 非依存）
+- 対応 Ruby: `>= 3.3, < 4.0`（下限は kruby 1.36.x の `>= 3.3`。上限は
+  未検証の Ruby 4.x を宣言から除外するため。4.0 / 3.5 対応は v0.2 以降
+  で検証の上宣言に含める）。
+  CI（GitHub Actions）で 3.3.0 / 3.3.8 / 3.4.10 の matrix 検証
+- 対応 Kubernetes サーバ: v1.33.x で実クラスタ検証済み（README 参照）
+- 公開導線: owner のローカル PC から手動 `gem push`（rake 全緑確認 +
+  CHANGELOG 確定後に実施。CI の自動公開は行わない）

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dorian - Takahiro Ishida
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,201 @@
+# k8s-rails
+A Kubernetes API / CRD convention layer for Rails applications.
+
+`k8s-rails` provides the **connection, CRD access, and error-handling convention
+layer** for Rails applications that talk to the Kubernetes API.
+
+[![Test](https://github.com/doridoridoriand/k8s-rails/actions/workflows/test.yml/badge.svg)](https://github.com/doridoridoriand/k8s-rails/actions/workflows/test.yml)
+[![Gem Version](https://badge.fury.io/rb/k8s-rails.svg)](https://rubygems.org/gems/k8s-rails)
+
+For the design rationale, see the [design document (docs/design.md)](docs/design.md) (KBR-DESIGN-001).
+
+## Requirements
+
+| Item | Supported range | Notes |
+|------|-----------------|-------|
+| Ruby | `>= 3.3, < 4.0` | Floor: kruby 1.36.x requires Ruby 3.3. Upper bound: unverified Ruby 4.x is excluded from the declared range. CI verifies the declared range with a 3.3.0 / 3.3.8 / 3.4.10 matrix |
+| kruby | `~> 1.36.0` | The official Kubernetes OpenAPI client |
+| Kubernetes server | **Verified on v1.33.x** (a real cluster, microk8s v1.33.13, 2026-09-21) | kruby 1.36.x is a 1.36-series client. Newer servers (1.36, etc.) use the same API (CustomObjects API v1), so compatibility is expected, but has not yet been verified against a real cluster |
+| Dependencies | **kruby only** at runtime | ActiveSupport is used only for optional [instrumentation](#instrumentation-optional-activesupport) (no-op when absent) |
+
+## Installation
+
+```ruby
+# Gemfile
+gem "k8s-rails", "~> 0.1"
+```
+
+```ruby
+require "k8s-rails"
+K8sRails::VERSION # => "0.1.0"
+```
+
+`require` is side-effect-free and needs no cluster. kruby itself is loaded
+lazily on the first `K8sRails.client` / `K8sRails.connected?` / CRD operation
+(**lazy connect**), so the gem can be required even when no cluster is
+reachable.
+
+## Quick start
+
+```ruby
+# config/initializers/k8s-rails.rb
+K8sRails.configure do |config|
+  config.namespace = "team-a" # default namespace (can be overridden per declaration or per call)
+end
+
+# Declare the CRD you work with (group / version / plural / kind are never guessed)
+Workflow = K8sRails.crd(
+  group:  "argoproj.io",
+  version: "v1alpha1",
+  plural: "workflows",
+  kind:   "Workflow",
+  readonly: false, # default true; false enables create/patch
+)
+```
+
+```ruby
+Workflow.list                 # => [{"name" => "...", "labels" => {...}}, ...]
+Workflow.find("wf-1")         # same shape / raises K8sRails::NotFound when absent
+Workflow.find_or_nil("wf-1")  # same, but returns nil instead of raising
+Workflow.create({ metadata: { name: "wf-1" } })                     # readonly: false only
+Workflow.patch("wf-1", [{ op: "replace", path: "/spec/a", value: 2 }]) # readonly: false only
+
+K8sRails.connected?          # true on success; raises on failure
+```
+
+## Configuration
+
+```ruby
+K8sRails.configure do |config|
+  config.namespace = "team-a"          # default namespace (default: "default")
+  # config.connection = my_config      # pass a Kubernetes::Configuration directly (optional)
+  # config.instrumentation = false     # disable instrumentation (default true; only effective when ActiveSupport is present)
+  # config.api_client = stub           # test-only: inject a transport (see [Testing](#testing))
+end
+```
+
+- `configure` is effective **only once**. A second call prints a warning and is
+  ignored (use `K8sRails.reset!` to reset the configuration, the cached
+  transport, and declared CRDs — primarily for tests).
+- Connection resolution order: `config.api_client` (test injection) →
+  `config.connection` → `Kubernetes::Configuration.default_config`
+  (automatic in-cluster → KUBECONFIG detection).
+
+## CRD declaration and access
+
+`plural` / `kind` are **never guessed** (many CRDs do not follow the obvious
+naming convention). Re-declaring the same kind raises
+`K8sRails::RedeclarationError` (configuration-mistake detection).
+
+Return values are **always string-keyed hashes**. kruby returns symbol keys,
+but Rails-side JSON/views work with string keys, so the gem normalizes
+internally in pure Ruby (no ActiveSupport dependency). Every method accepts a
+`namespace:` argument to override the namespace from the declaration.
+
+`readonly` must be an **explicit boolean** (`nil` or other values raise
+`ArgumentError`). Writes are enabled **only** by `readonly: false`, so a
+missing flag can never fail open.
+
+## Connectivity check
+
+```ruby
+K8sRails.connected?  # true on success; raises K8sRails::Unavailable / ApiError on failure
+                      # a lightweight /version-equivalent check
+```
+
+It never returns `false` — a connection failure surfaces as an exception
+(handle it with `rescue`). The actual API connection is established lazily on
+the first API call.
+
+## Exception hierarchy
+
+```
+K8sRails::Error < StandardError
+├── K8sRails::Unavailable   # transport-layer failure (DNS/timeout/connection refused; kruby 1.36.x reports it as ApiError code 0)
+├── K8sRails::NotFound      # HTTP 404
+├── K8sRails::ApiError      # other API errors (401/403/409/422/5xx); holds #code and #response
+├── K8sRails::ReadOnlyError      # create/patch called on a readonly: true declaration
+└── K8sRails::RedeclarationError # re-declaration of an already-declared CRD kind
+```
+
+Recommended caller pattern:
+
+```ruby
+begin
+  Workflow.list
+rescue K8sRails::Unavailable
+  # cluster-side problem → "unable to load" fallback UI, etc.
+rescue K8sRails::ApiError => e
+  # inspect e.code / e.response to determine the cause
+end
+```
+
+## Instrumentation (optional ActiveSupport)
+
+When `config.instrumentation = true` (the default) and ActiveSupport is loaded,
+each API call is published as a `k8s-rails.request` notification (no-op when
+ActiveSupport is absent):
+
+```
+k8s-rails.request
+  payload: { operation:, group:, version:, plural:, namespace:, duration_ms:,
+             status: "ok" | "unavailable" | "api_error" }
+```
+
+In a Rails app you can subscribe with `ActiveSupport::Notifications`:
+
+```ruby
+ActiveSupport::Notifications.subscribe("k8s-rails.request") do |name, start, finish, id, payload|
+  Rails.logger.info("[k8s-rails] #{payload[:operation]} #{payload[:plural]} (#{payload[:duration_ms]}ms) #{payload[:status]}")
+end
+```
+
+## Testing
+
+The test suite needs **no cluster**. Tests inject a transport stub via
+`config.api_client`. The stub is wrapped internally by an adapter, so it just
+implements the same four methods as kruby's `CustomObjectsApi`:
+
+```ruby
+class StubTransport
+  def list_namespaced_custom_object(group, version, namespace, plural) = { items: [] }
+  def get_namespaced_custom_object(group, version, namespace, plural, name) = {}
+  def create_namespaced_custom_object(group, version, namespace, plural, body) = {}
+  def patch_namespaced_custom_object(group, version, namespace, plural, name, body) = {}
+end
+
+K8sRails.configure { |c| c.api_client = StubTransport.new }
+```
+
+## Development
+
+```
+bundle install
+bundle exec rake   # rspec + rubocop
+```
+
+## Known issue: kruby 1.36 bearer-token key mismatch
+
+kruby 1.36.x's in-cluster / KUBECONFIG configuration writes the bearer token
+to `api_key['authorization']`, but `Configuration#auth_settings` reads
+`api_key['BearerToken']` for the `Authorization` header. Because the keys do
+not match, **the Authorization header ends up empty and requests fail with
+401** when using kruby's configuration directly.
+
+k8s-rails automatically copies `authorization` to `BearerToken` when building
+its client (the design document calls this the "K1 bridge"), so connections
+through k8s-rails are unaffected (it does not overwrite an already-set
+`BearerToken`). If you see 401s from a cluster connection that relies on
+kruby's own configuration behavior (outside this gem), check this token-key
+issue first.
+
+## Roadmap (v0.2+)
+
+- Ruby 3.5 / 4.0 support (after verifying against the stable releases, then
+  widening the declared range and the CI matrix)
+- CI-based E2E tests using kind
+- watch (streaming) support, under consideration
+
+## License
+
+MIT ([LICENSE](LICENSE))

data/docs/design.md

@@ -0,0 +1,383 @@
+# k8s-rails 設計書
+
+- 文書番号: KBR-DESIGN-001
+- 版: 0.1.10（案）
+- 日付: 2026-09-15
+- 対象リポジトリ: k8s-rails（本設計の実装先）
+- ライセンス: MIT（LICENSE は main に既存）
+
+---
+
+## 1. 目的
+
+Rails アプリが Kubernetes API を扱う際の**接続・CRD アクセス・障害処理の規約層**を
+gem（`k8s-rails`）として提供する。
+
+起点となった実際の Rails アプリ実装には、公式 `kruby` クライアントを
+Rails アプリで実運用する過程で得られた知見が実装として固定されている:
+
+| # | 知見（実運用で確認済み） |
+|---|---|
+| K1 | in-cluster（ServiceAccount）と KUBECONFIG の接続自動切替は `Kubernetes::Configuration.default_config` が担うが、**kruby 1.36 では in-cluster 時の `api_key['authorization']`（Bearer トークン）が `auth_settings` が読む `api_key['BearerToken']` に書かれず、Authorization ヘッダが欠落して 401 になる**。この橋渡しを忘れると本番（in-cluster）で必ず失敗する |
+| K2 | kruby はシンボルキーの Hash を返す。Rails 側（JSON/ビュー）では文字列キーで扱うため、文字列キーへの統一変換が必須（gem 内部で処理: ActiveSupport 存在時は `deep_stringify_keys`、無ければ純 Ruby の再帰変換。Rails 無し環境でも成立、§5.2） |
+| K3 | クラスタが到達不能な場合、呼び出し側（ビュー等）が生の `kruby` 例外を扱うと 500 になる。接続不能 / リソース不在 / API エラーを**gem 側の例外体系**で格納し、Rails 側はそれを素通し表示できる規約が必要 |
+| K4 | read-only（get/list）と操作（create/patch/update）は障害時の影響度が異なるため、**フェーズごとに API を分離**する運用（read-only のみ → 操作追加）が事実上のベストプラクティス |
+| K5 | CRD へのアクセスは group/version/plural をハードコードしがち。宣言でメソッドを生成すると typo による 404 を減らせる |
+
+本 gem はこれらを**規約として標準化**し、(a) 新規 Rails アプリが 5 行程度の設定で
+K8s CRD を扱えるようにし、(b) 実際の consumer アプリをこの gem に移行して両方向で検証する。
+
+## 2. スコープ
+
+### 2.1 本設計で扱うもの
+
+- gem `k8s-rails` のアーキテクチャ・公開 API の設計
+- 依存ポリシー（kruby pin、ActiveSupport の扱い）
+- 例外体系・障害時の挙動定義
+- テスト戦略（スタブによるユニットテスト、クラスタ不要）
+- v0.1 / v0.2 のリリース境界
+- consumer アプリへの移行手順（v0.1 検証の受け皿）
+
+### 2.2 非スコープ（本設計の外）
+
+- core v1 リソース（Pod / Deployment / Service 等）のフルサポート — CRD 中心の gem。core v1 は built-in リソースであり CustomObjects API では扱えない（`group=""`/`version="v1"` の宣言は**無効**）ため、別途 core API 経路が必要。v0.1 では対象外（将来候補、§11）
+- **watch（ストリーム）** — v0.1 では非対応。kruby の watch は get/list より成熟度が低く、初版の API 保証範囲から外す（§11 で v0.2 候補）
+- アプリの**デプロイ**（helm / kustomize 生成等） — `kuby-core` の領域
+- RBAC 権限の付与・管理 — 呼び出しアプリ側の ClusterRole/Role の責務
+- 複数クラスタ同時接続 — v0.1 は単一クラスタ前提（§11 展望）
+
+### 2.3 前提
+
+| # | 前提 |
+|---|------|
+| P1 | 実行環境は Kubernetes 1.27 以降を想定。API は 1.27〜1.31 系で動作確認 |
+| P2 | クライアントは `kruby`（公式 OpenAPI クライアント系）。consumer アプリと同一の `~> 1.36.0` を基本 pin |
+| P3 | 認証は (a) in-cluster ServiceAccount、(b) KUBECONFIG の 2 パターンのみを扱う。exec plugin / 他方式は v0.1 で保証しない |
+| P4 | consumer アプリの K8s 利用（Argo Workflows / CronWorkflow 等の CRD）が、本 gem の移行検証の**最初かつ最低限のユースケース**である |
+
+## 3. 全体構成
+
+```
+┌────────────────────────────────────────────────────┐
+│ Rails アプリ（呼び出し側）                            │
+│  K8sRails.configure { |c| c.namespace = "app" }   │
+│  K8sRails.crd(group:, version:, plural:, kind:)   │
+│                                                     │
+│  MyApp::Workflow.list / .find / .create / .patch    │
+└──────────────────────────┬─────────────────────────┘
+                           │ 例外: K8sRails::Unavailable / ::NotFound / ::ApiError
+┌──────────────────────────┴─────────────────────────┐
+│ k8s-rails（本 gem）                                  │
+│  ┌──────────────┐  ┌──────────────┐  ┌───────────┐ │
+│  │ Config        │  │ Client       │  │ CRD       │ │
+│  │ (initializer) │→ │ (接続解決+橋 │→ │ Resource  │ │
+│  │               │  │ 渡し+計測)   │  │ (メソッド生成)│
+│  └──────────────┘  └──────┬───────┘  └─────┬─────┘ │
+│                           │                │        │
+│  例外体系: Unavailable / NotFound / ApiError│        │
+│  計測: ActiveSupport::Notifications (任意)    │        │
+└──────────────────────────┴────────────────┼────────┘
+                           │                │
+┌──────────────────────────┴────────────────┴────────┐
+│ kruby (~> 1.36.0) → Kubernetes API Server           │
+│  (in-cluster SA token | KUBECONFIG)                 │
+└────────────────────────────────────────────────────┘
+```
+
+データフローの原則:
+
+- 呼び出しアプリは kruby に**直接触れない**（例外はテスト用注入のみ）。
+  `K8sRails::Client` を挟むことで、kruby の API 変化・キー種別問題は gem 内部に封じ込める。
+- クラスタ未接続でも gem のロード・設定は**副作用なし**で完了する（lazy connect）。
+  接続は最初の API 呼び出し時（§5.2）。
+
+## 4. ディレクトリ構成（gem 本体）
+
+```
+k8s-rails/
+├── k8s-rails.gemspec
+├── Gemfile                  # gemspec 参照 + 開発依存 (rspec, rubocop)
+├── Rakefile
+├── README.md
+├── LICENSE                  # 既にある MIT（Dorian - Takahiro Ishida）
+├── docs/
+│   └── design.md            # 本設計書
+├── lib/
+│   ├── k8s-rails.rb         # エントリ。require 集 + モジュール定義
+│   └── k8s_rails/
+│       ├── version.rb       # VERSION = "0.1.0"
+│       ├── configuration.rb # Config: namespace, connection, 計測 ON/OFF
+│       ├── client.rb        # 接続解決・BearerToken 橋渡し・計測ラップ
+│       ├── crd.rb           # K8sRails.crd 宣言 → Resource 生成
+│       ├── resource.rb      # list/find/create/patch（生成先の基底クラス）
+│       └── errors.rb        # Unavailable / NotFound / ApiError
+├── spec/
+│   ├── spec_helper.rb
+│   ├── k8s_rails_spec.rb    # 設定 / lazy connect
+│   ├── client_spec.rb       # 橋渡し・計測・例外変換
+│   ├── crd_spec.rb          # 宣言 → メソッド生成
+│   └── resource_spec.rb     # list/find/create/patch の整形
+└── examples/
+    └── rails-app/           # 最小 Rails 7.1 例（consumer 移行の雛形兼用）
+```
+
+## 5. 公開 API 設計
+
+### 5.1 設定
+
+```ruby
+# config/initializers/k8s-rails.rb
+K8sRails.configure do |config|
+  config.namespace = ENV.fetch("K8S_NAMESPACE", "default")
+  # 任意上書き（省略時は default_config の自動検出: in-cluster → KUBECONFIG）
+  # config.connection = Kubernetes::Configuration.default_config
+  # config.instrumentation = true   # 既定 true（ActiveSupport 存在時のみ有効）
+end
+```
+
+設定項目:
+
+| キー | 既定 | 説明 |
+|---|---|---|
+| `namespace` | `"default"` | CRD 宣言が namespace 未指定時のデフォルト |
+| `connection` | `nil`（自動検出） | `Kubernetes::Configuration` インスタンス。認証を上書きする場合に指定 |
+| `api_client` | `nil` | **テスト専用**: kruby の `CustomObjectsApi` と同型の 4 メソッド（`get_namespaced_custom_object` / `list_namespaced_custom_object` / `create_namespaced_custom_object` / `patch_namespaced_custom_object`）を実装する素のオブジェクト。指定時は `Client.build` が接続解決をスキープして `StringKeyedAdapter` で包んで使う（§5.2・§9） |
+| `instrumentation` | `true` | `ActiveSupport::Notifications` で計測する（§8） |
+
+- 設定は `K8sRails.configure` で**一度だけ**。再実行は警告（`Warning`）+ 無視。
+- `K8sRails.reset!`（テスト用）で接続キャッシュ・宣言済 CRD を破棄できる。
+
+### 5.2 接続
+
+```ruby
+K8sRails::Client.build   # → Kubernetes::CustomObjectsApi（lazy。初回呼び出し時に接続）
+K8sRails.connected?      # → 成功時は true。失敗は K8sRails::Unavailable / ApiError を raise
+                          #   （false を返す経路なし）。/version 相当の軽量確認
+                          #   （kruby 1.36.x の VersionApi#get_code（GET /version/）1 回）
+```
+
+`Client.build` が内部で行うこと（consumer アプリの K8s サービスの custom objects 生成部を移設）:
+
+0. `config.api_client` があれば（テスト注入、§5.1）それを直接返し、以降の接続解決をスキップ
+1. `config.connection` があればそれ、なければ `Kubernetes::Configuration.default_config`
+2. **K1 橋渡し**: `api_key['authorization']` が `api_key['BearerToken']` に書かれていなければ複製
+3. `Kubernetes::ApiClient` → `Kubernetes::CustomObjectsApi` を生成し、**文字列キー化**（K2）を API レスポンス後に行う。ActiveSupport 非依存の gem 内部の純 Ruby 再帰変換（`K8sRails::Normalizer`）を使う（v0.1.1 以降: 常に Normalizer。`deep_stringify_keys` 経路は廃止）
+4. **接続レベルの失敗**（DNS 失敗 / タイムアウト / 接続拒否等）は `K8sRails::Unavailable` に変換して `raise`（リトライはしない）。**kruby 1.36.x ではこれらの転送失敗は HTTP ステータスが無いため `Kubernetes::ApiError`（`code == 0`）として surfacing する**（§5.4 の変換表参照）。認可失敗（401/403）は §5.4 により `K8sRails::ApiError`
+
+### 5.3 CRD 宣言
+
+```ruby
+# config/initializers/k8s-rails_crd.rb（またはアプリケーションクラス内）
+Workflow = K8sRails.crd(
+  group:  "argoproj.io",
+  version: "v1alpha1",
+  plural: "workflows",
+  kind:   "Workflow",
+  namespace: K8sRails.config.namespace,   # 省略可
+  readonly: false,                          # 既定 true。false で create/patch 有効化（K4）
+)
+```
+
+宣言で生成されるメソッド（全て class メソッド。各メソッドは任意の `namespace:` 引数を受け取り、宣言時のデフォルト namespace を上書き可能）:
+
+| メソッド | 引数 | 戻り値 | readonly 制限 |
+|---|---|---|---|
+| `list` | `{}` | `[{"name" => "...", "labels" => {}, "spec" => {}, "status" => {}}, ...]`（**文字列キー**） | 常に有効 |
+| `find(name)` | 必須 | 同型 or `K8sRails::NotFound`（raise） | 常に有効 |
+| `create(attributes)` | CRD body hash | 作成済みオブジェクト（文字列キー） | `readonly: false` のみ |
+| `patch(name, operations)` | JSON Patch 操作配列 | 更新済みオブジェクト | `readonly: false` のみ |
+
+- **戻り値は常に文字列キーの Hash**（K2 の規約を API 契約として固定）。
+  `find` は存在しない場合 `K8sRails::NotFound` を raise（consumer アプリ側が `return nil` にしていたのは
+  呼び出し側の都合。gem としては例外が明示的）。「存在しない場合は nil」が欲しい場合は
+  `find_or_nil(name)` を併設する。
+- `plural` / `kind` は自動推測しない（`workflows` / `Workflow` 等、推測が外れる CRD が多い）。
+  宣言で必ず指定する（K5）。
+- 同名 CRD の再宣言は `K8sRails::RedeclarationError`（設定ミス検出）。
+
+### 5.4 例外体系（K3）
+
+```ruby
+K8sRails::Error < StandardError
+├── K8sRails::Unavailable   # 接続不能・タイムアウト・DNS 失敗等（クラスタ起因）
+├── K8sRails::NotFound      # リソース不在（HTTP 404）
+├── K8sRails::ApiError      # その他の API エラー（401/403/409/422 等）。#code と #response を保持
+├── K8sRails::ReadOnlyError      # readonly: true 宣言で create/patch が呼ばれた（設定ミス）
+└── K8sRails::RedeclarationError # 同名 CRD の再宣言（設定ミス）
+```
+
+変換規則:
+
+| kruby 側 | → gem 側 |
+|---|---|
+| kruby 転送層例外（DNS 失敗 / タイムアウト / 接続拒否等。kruby 1.36.x では **`ApiError`（`code == 0`）** として surfacing） | `Unavailable` |
+| その他の `StandardError`（プログラミング/設定ミス、例: `NoMethodError`） | そのまま伝播（変換せず隠さない） |
+| `Kubernetes::ApiError` code 404 | `NotFound` |
+| `Kubernetes::ApiError` その他 | `ApiError`（code / response body を保持） |
+| 宣言時に `readonly: true` で create/patch を呼ばれた | `K8sRails::ReadOnlyError`（**設定ミス**なので raise せずには済ませない） |
+
+呼び出しアプリ（Rails）側の推奨パターン:
+
+```ruby
+begin
+  workflows = Workflow.list
+rescue K8sRails::Unavailable => e
+  render "k8s_unavailable"        # consumer アプリの「K8s 未接続」バナー相当
+rescue K8sRails::NotFound
+  redirect_to root_path, alert: "Workflow が見つかりません"
+end
+```
+
+## 6. 依存ポリシー
+
+| 依存 | 制約 | 理由 |
+|---|---|---|
+| Ruby | `>= 3.3, < 4.0` | 下限: kruby 1.36.x が `required_ruby_version ">= 3.3"` を宣言（RubyGems API で実測 2026-09-21、1.36.0.1〜1.36.4.1 全バージョン）。上限: 「宣言した Ruby minor を必ず CI で検証する」方針（レビュー対応・2026-09-21）— 2026-09-21 時点で Ruby 4.0 は stable（v4.0.7）だが未検証、3.5 は preview（v3_5_0_preview1）のため、宣言範囲を 3.x に限定。4.0 / 3.5 対応は v0.2 以降で検証の上宣言に含める |
+| `kruby` | `~> 1.36.0` | consumer アプリと同一 pin。`~> 1.36.0` は 1.36.x のみ許可（`~> 1.36` 形式は 1.37 以降も許容してしまうため使用しない）。新しめの kruby に対応する場合は §7 の確認事項（client.rb 4 メソッド・K1 橋渡し）を済ませてから明示的に上げ替える |
+| `activesupport` | **任意**（`>= 7.0`） | `defined?(ActiveSupport::Notifications)` でガード（計測のみ、§8）。Rails 無し環境（Cron スクリプト等）でも動作する必要がある — レスポンスの文字列キー化（K2）はこれに依存せず、gem 内部の純 Ruby 変換で担う（§5.2） |
+| `rspec` / `rubocop` | 開発依存 | spec / lint |
+
+- kruby への依存は **`K8sRails::Client` に閉じ込める**（§7）。
+  kruby 上げ替え時の修正箇所を 1 ファイルに限定し、CHANGELOG に「対応 kruby」を明記する。
+
+## 7. 実装規約（kruby 変化への耐性）
+
+- `lib/k8s_rails/client.rb` **のみ**が `require "kubernetes"` してよい。
+  他のファイルは kruby 定数・クラスを参照しない。
+- kruby の `CustomObjectsApi` メソッド呼び出しは `client.rb` 内の
+  `*_namespaced_custom_object` の 4 メソッド（`get_namespaced_custom_object` 等）に集約する。`resource.rb` は
+  `K8sRails.client.get(group, version, ns, plural, name)` のような **gem 内部 API** だけを使う。
+- kruby 上げ替え時の作業は (1) client.rb 4 メソッドのシグネチャ確認、
+  (2) K1 橋渡しの要否確認、に収まることをテスト（§9）で担保する。
+
+## 8. 計測（ActiveSupport 任意）
+
+`instrumentation: true` かつ ActiveSupport 存在時、各 API 呼び出しを計測する:
+
+```
+k8s-rails.request  payload: { operation: :list, group:, version:, plural:, namespace:
+                               # operation は symbol（:list / :find / :create / :patch）
+                               duration_ms:  # float（ミリ秒・小数点 2 桁）
+                               status: "ok" | "unavailable" | "api_error" }
+```
+
+- `status` は **文字列**（`"ok"` / `"unavailable"` / `"api_error"`）、
+  `operation` は **symbol**。例外は notification を発した上で **そのまま raise**
+  される（計測は swallow しない）。
+
+- Rails アプリではこの notification を `ActiveSupport::Notifications` /
+  `log_subscription` で拾える（ログ・ダッシュボード表示）。
+- ActiveSupport 無い環境（または `instrumentation: false`）では no-op。
+  この場合も **ブロックの戻り値はそのまま返る**（`nil` にはならない）。
+
+## 9. テスト戦略（クラスタ不要）
+
+| レイヤー | 手法 | 対象 |
+|---|---|---|
+| ユニット | `K8sRails.config.api_client` に**スタブ**（kruby `CustomObjectsApi` と同型の 4 メソッド `get_namespaced_custom_object` / `list_namespaced_custom_object` / `create_namespaced_custom_object` / `patch_namespaced_custom_object` を実装する素のオブジェクト。`StringKeyedAdapter` がこの形式を呼ぶ）を注入 | client（橋渡し・例外変換）、resource（整形・readonly 制限）、crd（メソッド生成） |
+| 設定 | spec 間で `K8sRails.reset!` | 宣言の破棄・再接続 |
+| 集積（任意） | GitHub Actions で **kind**（または既存 microk8s に接続するジョブ）で実クラスタ E2E | v0.1 の必須ではない。**推奨**: consumer アプリ移行時の検証を兼ねる |
+
+- 本設計では CI は `rspec` + `rubocop` のみを必須とし、kind E2E は v0.2 以降で
+  GitHub Actions の追加として扱う（実クラスタへの接続 CI はネットワーク依存のため採用しない）。
+
+## 10. リリース計画
+
+| バージョン | 内容 | 出口基準 |
+|---|---|---|
+| **v0.1** | §5 の公開 API（CRD 宣言 / list / find / create / patch / 例外 / 計測 / スタブテスト）+ README | rspec 全緑 + **consumer アプリの K8s サービスを `k8s-rails` に移行して動作確認**（§12） |
+| v0.2 | watch（`watch` メソッド、kruby の watch サポート上）、core v1 built-in リソース対応（CustomObjects API では不可なため別途 core API 経路、§2.2）、kind E2E の CI 化 | v0.1 運用 1 ヶ月後のフィードバック |
+| v0.3 | （展望）複数クラスタ（ネームスペース化された client 集合）、リトライポリシー | — |
+
+v0.1 の milestone 分割（開発セッション向けのタスク単位目安）:
+
+1. M0 — gem 骨子: gemspec / Gemfile / Rakefile / version / require 構造（rspec が回せる状態）
+2. M1 — Configuration + reset!（K1 橋渡しを含む Client 実装、例外変換）
+3. M2 — CRD 宣言 DSL + Resource（list / find / find_or_nil / create / patch、readonly 制限）
+4. M3 — 計測 + README + rubocop 設定
+5. M4 — consumer アプリへの移行と検証（§12）
+
+## 11. 展望・検討事項（v0.1 では確定しない）
+
+- **watch**: kruby の watch はストリーム処理であり、Rails のリクエスト応答型には不向き。
+  導入するなら「watch 開始 → メッセージをキュー / NotificationCenter 相当に流す」の
+  形で、ポーリング置き換えのユースケース（consumer アプリの 30 秒ポーリング等）から設計する。
+- **複数クラスタ**: `K8sRails.cluster("prod") { ... }` のような名前付き client 集合。
+  現時点で需要がないため v0.1 では単一クラスタ。
+- **retries / timeout**: kruby の `Kubernetes::Configuration` には接続タイムアウトが
+  設定できる。v0.1 は既定値 + README 記載のみで、gem 独自のバックオフは持たない
+  （Rails 側の middleware / sidekiq retry で吸収するのが慣習）。
+- **OpenTelemetry**: `instrumentation` を notification 経由にしているため、
+  OTel instrumentation を別途足せる状態に留める（v0.1 で実装しない）。
+
+## 12. consumer アプリへの移行（v0.1 検証）
+
+実際の consumer Rails アプリの K8s サービス（kruby 直接利用）を `k8s-rails` に置き換えて動作を確認する:
+
+1. `Gemfile` に `gem "k8s-rails", path: "../k8s-rails"`（開発期間限定。公開後は registry 版）
+2. initializer に CRD 宣言（Argo Workflows / CronWorkflow 等の該当 CRD、
+   `readonly: false`（操作系があるため））
+3. K8s サービス内の kruby 呼び出しを `K8sRails` 経由に置換。**整形メソッド
+   （summary 系）は consumer アプリ側に残す**
+   （アプリ固有の表示ロジックのため、gem には載せない）
+4. 例外: consumer アプリの Unavailable 相当を `K8sRails::Unavailable` に alias/
+   rescue 統一
+5. 検証: consumer アプリのテスト + K8s 読取が KUBECONFIG 経由で
+   従来通り表示されること（実クラスタへの手動確認）
+
+移行後も K8s サービスを**整形ラッパーとして残す**（コントローラの呼び出し先を変えない、
+PR の差分を最小化）。
+
+## 13. 命名・公開
+
+- **gem 名 / リポジトリ名: `k8s-rails`**（RubyGems で空きを確認済み 2026-09-21）。
+  当初の名 `kuberails` は **push 時の類似名チェックで却下**された
+  （RubyGems は名前のハイフンを無視して比較し、`kube-rails`（2015 年の旧 gem・
+  取得済み）と正規化すると同一文字列になるため使用不可）。命名規則は
+  **gem 名 = ハイフン**（`k8s-rails`）・**モジュール = CamelCase**（`K8sRails`）・
+  **ファイル / ディレクトリ = snake_case**（`lib/k8s_rails/`。エントリのみ
+  `lib/k8s-rails.rb` と require 名に合わせたハイフン）で統一する
+- GitHub: `doridoridoriand/k8s-rails`（org `k8s-rails` は他者が使用済み。個人アカウント配下）
+- 公開は v0.1 完成後、**ローカル PC から手動 `gem push`**（kruby と同様の運用方針・
+  2026-09-21 確定）。CI による自動公開は行わない。
+  - 手順（owner がローカル PC で実施）:
+    1. `bundle exec rake`（spec + rubocop）が全緑であることを確認
+    2. CHANGELOG.md の該当バージョン節を確定（「Unreleased」のまま公開しない）
+    3. `gem signin`（RubyGems アカウント・未作成なら先に作成）
+    4. `gem build k8s-rails.gemspec` → `gem push k8s-rails-<VERSION>.gem`
+  - 未取得の gem は**初回 push が所有権の取得**（`gem owner` は `--add` による
+    **追加** owner のみで、位置引数に user を取る構文は存在しない・
+    gem 4.0.7 `gem owner --help` で実測 2026-09-21）
+  - 公開直前に tag を切って **remote へ push** すると追溯性が高い
+    （`git tag v<VERSION> && git push origin v<VERSION>`）。
+    GitHub 上でリリースコミットと tag が対応付けられ、
+    公開した gem のバージョンがどのコミットに基づくかを追跡できる。
+    tag 名と gemspec の `VERSION` は一致させる
+  - テスト CI（`.github/workflows/test.yml`）は push / PR 時に rspec + rubocop を実行。
+    gemspec の宣言範囲（`>= 3.3, < 4.0`）を matrix で検証:
+    3.3.0（下限・kruby 1.36.x の `>= 3.3`）・3.3.8（開発）・
+    3.4.10（3.x 系の最新 stable・2026-09-21 時点。3.5 は preview、
+    4.0 は宣言範囲外のため未検証・v0.2 以降で検討）。
+    **宣言範囲を常に matrix がカバーする**こと（`< 4.0` 上限により、
+    4.x のリリースは宣言範囲外。stable 化された新 3.x minor が出たら
+    matrix への追加を忘れないこと）。
+    テストはクラスタ不要（§9・スタブ注入）のため v0.1 は runner 上のユニットのみ。
+    kind / 実クラスタ E2E の CI 化は v0.2 対象（§9・§10）
+- `README` に「kruby pin」「対応 k8s バージョン（実測 v1.33.x で検証済み）」「K1 橋渡しの背景」
+  を明記する（検索でヒットする重要な注意点のため）
+
+## 14. 承認・変更履歴
+
+| 版 | 日付 | 変更 | 承認 |
+|---|---|---|---|
+| 0.1 | 2026-09-15 | 初版（案）。実際の Rails アプリ実装の知見 K1–K5 を基に作成 | 未承認 |
+| 0.1.1 | 2026-09-18 | PR #1 レビュー対応: 文字列キー化の純 Ruby 経路（ActiveSupport 非依存）、401/403→ApiError 統一、`throw`→`raise`、core v1 を built-in 扱いに修正、`~> 1.36.0` に統一、テスト注入の `api_client` 追加、例外ツリーに `ReadOnlyError`/`RedeclarationError` 追記、初期化子例を汎用化 | レビュー反映済み |
+| 0.1.2 | 2026-09-18 | M1 実装にあたって kruby 1.36.2.1 を実機確認した差分を反映: `connected?` の endpoint を `VersionApi#get_code`（GET /version/）に修正、転送失敗（DNS/timeout/接続拒否）が `ApiError(code == 0)` として surfacing することを §5.2/§5.4 に明記、文字列キー化を常に `Normalizer`（`deep_stringify_keys` 経路廃止）に統一 | 実装反映済み |
+| 0.1.3 | 2026-09-20 | M3 実装に伴う §8 の軽微明確化: notification の `operation` は symbol・`status` は文字列であること、例外は発火後そのまま raise（swallow しない）こと、no-op 時（AS 無 / instrumentation: false）もブロック値がそのまま返ること。加えて `connected?` の戻り値記述を実装に合わせ修正（false を返す経路なし・失敗は raise）、テストスタブのメソッド名を kruby `CustomObjectsApi` 形式（`*_namespaced_custom_object`）に修正 | 実装反映済み |
+| 0.1.4 | 2026-09-21 | リリース準備（§13）: 公開導線を手動 `gem push` から**タグ基準の GitHub Actions**（`test.yml` / `publish.yml`）に更新、README に検証済み k8s サーババージョン（v1.33.x / microk8s v1.33.13）を追記、CHANGELOG.md を同梱、gemspec に `source_code_uri` / `changelog_uri` / `allowed_push_host` メタ情報を追加 | 実装反映済み |
+| 0.1.5 | 2026-09-21 | PR #11 レビュー対応（Codex P2 + Copilot M/L 3 系統）: ①未取得 gem の owner 取得手順を「初回 push が所有権取得」に修正（`gem owner k8s-rails <user>` は無効構文・`gem owner --help` 実測、`--add` は追加のみ）・publish.yml / §13 ②テスト CI を Ruby 3.3.x matrix に（**`>= 3.2` は kruby 1.36.x の `>= 3.3` と非整合だったため、§6・gemspec・README の Ruby 下限を 3.3 に改訂**・RubyGems API で 1.36.x 全 7 バージョン実測）③tag 前の CHANGELOG 確定を手順化（publish workflow は CHANGELOG を書き換えないため） | 実装反映済み |
+| 0.1.6 | 2026-09-21 | PR #11 レビュー第 2 波対応（Copilot ×2）: ①publish workflow に `verify` job（サポート Ruby 全バージョンの rake matrix）を追加し push job を `needs: verify` でゲート化（独立 Test workflow は tag 時に gem push をブロックできないため）・§13 ②テスト matrix の下限を 3.3.1 から **3.3.0** に（gemspec `>= 3.3` は 3.3.0 を含むため、宣言された最低バージョンを実際に検証） | 実装反映済み |
+| 0.1.7 | 2026-09-21 | PR #11 レビュー第 3 波対応（Copilot ×1）: `>= 3.3` が Ruby 3.4+ も含むため、テスト / verify matrix に **3.4.10（最新 stable・ruby-lang.org 実測）** を追加（3.3.0 / 3.3.8 / 3.4.10 の 3 系統）。新しい stable minor が出た際の matrix 追加を §13 に手順として明記 | 実装反映済み |
+| 0.1.8 | 2026-09-21 | PR #11 レビュー第 4 波対応（Copilot ×3）: 指摘（「Ruby 3.5 が stable 化したため matrix に追加せよ」）を検証した結果 **3.5 は preview であり claim は誤り**（ruby/ruby タグ `v3_5_0_preview1`・2026-09-21 実測）と判明。ただし指摘の根本（宣言と検証範囲のズレ）は**Ruby 4.0 が stable（v4.0.7）だったため**実際に存在した。対策として宣言範囲を **`>= 3.3, < 4.0` に改訂**（gemspec / §6 / README / CHANGELOG）し、宣言範囲 = matrix 検証範囲（3.3.0 / 3.3.8 / 3.4.10）を一致。4.0 / 3.5 対応は v0.2 以降で検証の上宣言に含める方針 | 実装反映済み |
+| 0.1.9 | 2026-09-21 | public リポジトリ化の準備: ①公開導線を**ローカル PC から手動 `gem push`** に変更（kruby と同様の運用方針・CI 自動公開は廃止、publish workflow を削除、test workflow の push/PR テストのみ残す）②§13 公開手順の手動化（tag は追溯性のため推奨）③内部 consumer アプリの名称・構造への言及を §1〜§14 全箇所から除去し「consumer アプリ」に一般化 | 実装反映済み |
+| 0.1.10 | 2026-09-21 | PR #12 レビュー対応（Copilot）: §13 の公開手順で tag の **remote への push**（`git push origin v<VERSION>`）が欠落しており、GitHub 上のリリースコミットとの対応付け（追溯性）が確保できないとの指摘を反映 | 実装反映済み |