k8s-rails 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 37dcb752eb0c0b10dd35af27b071e5dad054674e111cff16a60e49b78e7de64b
-  data.tar.gz: '0867da799bf1c8914940bccae887f22d976e67826271d05313d965bf6aec8f15'
+  metadata.gz: 708bfa5afaf656a7fb64a0ab781ef429eaa3f643d049d209941260178d6859d8
+  data.tar.gz: e9a0184c46ad0e5afd2f66bfdb1857d7f170c9a573825363a6910087ff4b8995
 SHA512:
-  metadata.gz: '039460cf0b175fbb51f160ce454cb9abe54e0001fb5d974f5b9da24c4c55750aa9e39326157d7306c319e08c64556284dfe994618642b374ab00e03c258465ec'
-  data.tar.gz: 124d5016d3e90068fe6ca03241c6cba6364bf956ee564324cf6d0329426f824b1a27e916e9234f279aacc216ae8450178e3f4ec437a5ef311c8f2cce199b9f28
+  metadata.gz: e54a31eee779538219001aec14d679ca11ff2ec2334f7f97a4f6bcb77d274b4b477a032e092daa85333f318656dc2f00feb45d1f163aeb76e36196dfd985ba20
+  data.tar.gz: 77ccd48603ee30f6145855fb6808001042bc5dd0cd74f6172a247fa6e2acef6bcde07a1ce21f497b9d823bf9b50f036ceb83aaa36daaabe5c85c07175e6b70ef

data/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 `k8s-rails` の全 notable な変更はこのファイルに記録する。
 
+## 0.2.0
+
+- **cluster-scoped CRD サポート**（#17）: `K8sRails.crd` に `scope: :namespaced`
+  （既定）/ `:cluster` を追加。cluster-scoped CRD（ClusterIssuer 等）は
+  `scope: :cluster`（`namespace:` 併用不可）で宣言し、`list_cluster` /
+  `find_cluster` / `find_or_nil_cluster` / `create_cluster` /
+  `patch_cluster` を使う。スコープと非対称な呼び出し（namespaced 宣言で
+  `*_cluster` / cluster 宣言で素のメソッド）は `ArgumentError`。
+  transport は kruby の `*_cluster_custom_object` 4 メソッドを新たに利用。
+- **`configure` のアトミック契約**（#16）: 「一度だけ」はブロックが
+  正常終了した場合のみ成立。ブロックが異常終了した（任意の例外 —
+  `LoadError` / `ScriptError` を含む — / `throw` / non-local return 等）
+  場合は設定済みフラグがリセットされ、後続の `configure` は通常どおり
+  実行される。異常終了前に書き込まれた属性は残存する（再実行ブロックは
+  依存する属性を全て設定する責務を負う。ロールバックはしない）。
+- **`connected?` の注入契約**（#18）: `config.api_client` 注入時は
+  I/O なしで `true`（注入トランスポートが接続面そのもの）。
+  非注入時は従来どおり VersionApi プローブ。
+- **接続設定探索順序の修正**（#19）: README / 設計書 / 設定コメントの
+  自動検出順序を kruby 1.36.x の loader 実装順
+  （**KUBECONFIG → `~/.kube/config` → in-cluster**、in-cluster は最後）
+  に修正（従来の「in-cluster → KUBECONFIG」記述は誤り）。kruby 上げ替え
+  時の再確認手順を設計書 §7 に追加。
+- テスト注入スタブ（`config.api_client`）の契約: namespaced 4 メソッド ＋
+  cluster 4 メソッド（namespaced 宣言のみ使う場合は前者 4 メソッドで足りる）。
+- 設計書 KBR-DESIGN-001 v0.1.12（案）へ更新（§5.1 / §5.2 / §5.3 / §6 /
+  §7 / §9 / §14）。
+
 ## 0.1.0
 
 - **M0**: gem 骨子（gemspec / Gemfile / Rakefile / version / require 構造）

data/README.md

@@ -22,12 +22,12 @@ For the design rationale, see the [design document (docs/design.md)](docs/design
 
 ```ruby
 # Gemfile
-gem "k8s-rails", "~> 0.1"
+gem "k8s-rails", "~> 0.2"
 ```
 
 ```ruby
 require "k8s-rails"
-K8sRails::VERSION # => "0.1.0"
+K8sRails::VERSION # => "0.2.0"
 ```
 
 `require` is side-effect-free and needs no cluster. kruby itself is loaded
@@ -74,12 +74,21 @@ K8sRails.configure do |config|
 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).
+- `configure` is effective **only once** — but only when the block returns
+  normally. If the block exits abnormally (any exception, including
+  `LoadError`; `throw`; non-local return), the "configured" flag is reset,
+  so a later `configure` runs normally. Note that attribute writes made
+  before the abnormal exit **remain** on the shared configuration (a
+  partially applied state is possible); a re-run block should set every
+  attribute it depends on.
+  A second call on an already-configured gem 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).
+  (automatic detection in kruby 1.36.x: `KUBECONFIG` → `~/.kube/config` →
+  in-cluster. Note in-cluster is tried **last**, after the file-based
+  sources — re-verify `kruby`'s loader when upgrading kruby).
 
 ## CRD declaration and access
 
@@ -89,13 +98,44 @@ naming convention). Re-declaring the same kind raises
 
 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.
+internally in pure Ruby (no ActiveSupport dependency). Every namespaced
+method accepts a `namespace:` argument to override the namespace from the
+declaration (the `*_cluster` methods take no `namespace:` — see
+[Cluster-scoped CRDs](#cluster-scoped-crds)).
 
 `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.
 
+### Cluster-scoped CRDs
+
+Both namespaced and cluster-scoped CRDs are supported. Declare a
+cluster-scoped CRD (ClusterIssuer, ClusterWorkflowTemplate, ...) with
+`scope: :cluster` and **without** `namespace:` (combining the two raises
+`ArgumentError`):
+
+```ruby
+ClusterIssuer = K8sRails.crd(
+  group:  "cert-manager.io",
+  version: "v1",
+  plural: "clusterissuers",
+  kind:   "ClusterIssuer",
+  scope:  :cluster,          # cluster-scoped endpoints (no namespace)
+)
+
+ClusterIssuer.list_cluster               # all objects cluster-wide
+ClusterIssuer.find_cluster("letsencrypt")
+ClusterIssuer.find_or_nil_cluster("x")
+ClusterIssuer.create_cluster({ ... })    # readonly: false only
+ClusterIssuer.patch_cluster("letsencrypt", [{ ... }])  # readonly: false only
+```
+
+On a `scope: :namespaced` declaration (the default) the `*_cluster` methods
+raise `ArgumentError` — the CRD is namespaced, so the cluster endpoints would
+404 anyway. For a cluster-scoped declaration, use the `*_cluster` methods
+(the plain `list`/`find`/... would call the namespaced endpoints and 404, so
+they raise `ArgumentError` there as well).
+
 ## Connectivity check
 
 ```ruby
@@ -107,6 +147,11 @@ 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.
 
+When a test transport is injected via `config.api_client`, `connected?`
+returns `true` without any network I/O — the injected transport **is** the
+connection surface, so probing a real endpoint would contradict the Resource
+operations that the same injection serves.
+
 ## Exception hierarchy
 
 ```
@@ -154,7 +199,9 @@ end
 
 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`:
+implements the same methods as kruby's `CustomObjectsApi` — the four
+`*_namespaced_custom_object` methods, plus (for cluster-scoped declarations)
+the four `*_cluster_custom_object` methods:
 
 ```ruby
 class StubTransport
@@ -162,11 +209,19 @@ class StubTransport
   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) = {}
+
+  def list_cluster_custom_object(group, version, plural) = { items: [] }
+  def get_cluster_custom_object(group, version, plural, name) = {}
+  def create_cluster_custom_object(group, version, plural, body) = {}
+  def patch_cluster_custom_object(group, version, plural, name, body) = {}
 end
 
 K8sRails.configure { |c| c.api_client = StubTransport.new }
 ```
 
+With a transport injected, `K8sRails.connected?` returns `true` without
+network I/O (see [Connectivity check](#connectivity-check)).
+
 ## Development
 
 ```
@@ -189,7 +244,7 @@ through k8s-rails are unaffected (it does not overwrite an already-set
 kruby's own configuration behavior (outside this gem), check this token-key
 issue first.
 
-## Roadmap (v0.2+)
+## Roadmap (v0.3+)
 
 - Ruby 3.5 / 4.0 support (after verifying against the stable releases, then
   widening the declared range and the CI matrix)

data/docs/design.md

@@ -1,7 +1,7 @@
 # k8s-rails 設計書
 
 - 文書番号: KBR-DESIGN-001
-- 版: 0.1.10（案）
+- 版: 0.1.12（案）
 - 日付: 2026-09-15
 - 対象リポジトリ: k8s-rails（本設計の実装先）
 - ライセンス: MIT（LICENSE は main に既存）
@@ -41,7 +41,7 @@ K8s CRD を扱えるようにし、(b) 実際の consumer アプリをこの gem
 ### 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 候補）
+- **watch（ストリーム）** — v0.1 では非対応。kruby の watch は get/list より成熟度が低く、初版の API 保証範囲から外す（§10 で v0.3 対象）
 - アプリの**デプロイ**（helm / kustomize 生成等） — `kuby-core` の領域
 - RBAC 権限の付与・管理 — 呼び出しアプリ側の ClusterRole/Role の責務
 - 複数クラスタ同時接続 — v0.1 は単一クラスタ前提（§11 展望）
@@ -80,7 +80,8 @@ K8s CRD を扱えるようにし、(b) 実際の consumer アプリをこの gem
                            │                │
 ┌──────────────────────────┴────────────────┴────────┐
 │ kruby (~> 1.36.0) → Kubernetes API Server           │
-│  (in-cluster SA token | KUBECONFIG)                 │
+│  (KUBECONFIG | ~/.kube/config | in-cluster SA token) │
+│  ※kruby 1.36.x の探索順序は左→右（in-cluster は最後）  │
 └────────────────────────────────────────────────────┘
 ```
 
@@ -105,7 +106,7 @@ k8s-rails/
 ├── lib/
 │   ├── k8s-rails.rb         # エントリ。require 集 + モジュール定義
 │   └── k8s_rails/
-│       ├── version.rb       # VERSION = "0.1.0"
+│       ├── version.rb       # VERSION = "0.2.0"
 │       ├── configuration.rb # Config: namespace, connection, 計測 ON/OFF
 │       ├── client.rb        # 接続解決・BearerToken 橋渡し・計測ラップ
 │       ├── crd.rb           # K8sRails.crd 宣言 → Resource 生成
@@ -129,7 +130,8 @@ k8s-rails/
 # config/initializers/k8s-rails.rb
 K8sRails.configure do |config|
   config.namespace = ENV.fetch("K8S_NAMESPACE", "default")
-  # 任意上書き（省略時は default_config の自動検出: in-cluster → KUBECONFIG）
+  # 任意上書き（省略時は default_config の自動検出。kruby 1.36.x の探索順序は
+  # KUBECONFIG → ~/.kube/config → in-cluster で、in-cluster が最後）
   # config.connection = Kubernetes::Configuration.default_config
   # config.instrumentation = true   # 既定 true（ActiveSupport 存在時のみ有効）
 end
@@ -140,11 +142,18 @@ 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） |
+| `connection` | `nil`（自動検出） | `Kubernetes::Configuration` インスタンス。認証を上書きする場合に指定。省略時の探索順序（kruby 1.36.x の loader 実装順）: **KUBECONFIG → `~/.kube/config` → in-cluster**（in-cluster はファイル系が両方無効な場合の**最後**。kruby 上げ替え時に loader を再確認すること — §7） |
+| `api_client` | `nil` | **テスト専用**: kruby の `CustomObjectsApi` と同型のメソッド（namespaced 4 メソッド `get_namespaced_custom_object` / `list_namespaced_custom_object` / `create_namespaced_custom_object` / `patch_namespaced_custom_object` ＋ cluster 4 メソッド `get_cluster_custom_object` / `list_cluster_custom_object` / `create_cluster_custom_object` / `patch_cluster_custom_object`）を実装する素のオブジェクト（namespaced 宣言のみを使う場合は namespaced 4 メソッドで足りる）。指定時は `Client.build` が接続解決をスキープして `StringKeyedAdapter` で包んで使う（§5.2・§9） |
 | `instrumentation` | `true` | `ActiveSupport::Notifications` で計測する（§8） |
 
 - 設定は `K8sRails.configure` で**一度だけ**。再実行は警告（`Warning`）+ 無視。
+  **「一度だけ」はブロックが正常終了した場合に限る**: ブロックが異常終了した
+  （任意の例外送出 — `LoadError` / `ScriptError` を含む — / `throw` /
+  non-local return 等）場合は設定済みフラグがリセットされ、後続の `configure`
+  は通常どおり実行される。ただし異常終了前に書き込まれた属性は共有 Configuration
+  に**残存する**（部分的な設定状態になり得るため、再実行ブロックは依存する属性を
+  全て設定する責務を負う。アトミックなロールバックは行わない — Configuration
+  は純データで 4 属性のみのため、複写＋スワップの複雑さに見合わない）。
 - `K8sRails.reset!`（テスト用）で接続キャッシュ・宣言済 CRD を破棄できる。
 
 ### 5.2 接続
@@ -154,6 +163,8 @@ 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 回）
+                          #   `config.api_client` 注入時は I/O なしで true（§5.1 の
+                          #   注入が接続面そのものだから。Resource 操作と整合させる）
 ```
 
 `Client.build` が内部で行うこと（consumer アプリの K8s サービスの custom objects 生成部を移設）:
@@ -164,6 +175,11 @@ K8sRails.connected?      # → 成功時は true。失敗は K8sRails::Unavailab
 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`
 
+`connected?` の解決順序:
+
+0. `config.api_client` があれば（テスト注入、§5.1）**I/O なしで `true` を返す**。注入されたトランスポートが接続面そのもののため、実エンドポイントへのプローブは同一注入下の Resource 操作と矛盾する（#18 対応）。クラスタ到達性の真の確認が必要な場合は注入を解除した環境で行う
+1. 以下 `Client.build` と同一（`config.connection` → `default_config` → K1 橋渡し → VersionApi プローブ）
+
 ### 5.3 CRD 宣言
 
 ```ruby
@@ -176,9 +192,19 @@ Workflow = K8sRails.crd(
   namespace: K8sRails.config.namespace,   # 省略可
   readonly: false,                          # 既定 true。false で create/patch 有効化（K4）
 )
+
+# cluster-scoped CRD（ClusterIssuer / ClusterWorkflowTemplate 等）は
+# scope: :cluster を付け、namespace: は省略する（併用は ArgumentError）
+ClusterIssuer = K8sRails.crd(
+  group:  "cert-manager.io",
+  version: "v1",
+  plural: "clusterissuers",
+  kind:   "ClusterIssuer",
+  scope: :cluster,
+)
 ```
 
-宣言で生成されるメソッド（全て class メソッド。各メソッドは任意の `namespace:` 引数を受け取り、宣言時のデフォルト namespace を上書き可能）:
+宣言で生成されるメソッド（全て class メソッド。namespaced 系は任意の `namespace:` 引数を受け取り、宣言時のデフォルト namespace を上書き可能）:
 
 | メソッド | 引数 | 戻り値 | readonly 制限 |
 |---|---|---|---|
@@ -186,6 +212,17 @@ Workflow = K8sRails.crd(
 | `find(name)` | 必須 | 同型 or `K8sRails::NotFound`（raise） | 常に有効 |
 | `create(attributes)` | CRD body hash | 作成済みオブジェクト（文字列キー） | `readonly: false` のみ |
 | `patch(name, operations)` | JSON Patch 操作配列 | 更新済みオブジェクト | `readonly: false` のみ |
+| `list_cluster` | `{}` | 同上（クラスタ横断。`namespace:` なし） | 常に有効 |
+| `find_cluster(name)` | 必須 | 同上 or `K8sRails::NotFound` | 常に有効 |
+| `create_cluster(attributes)` | CRD body hash | 作成済みオブジェクト | `readonly: false` のみ |
+| `patch_cluster(name, operations)` | JSON Patch 操作配列 | 更新済みオブジェクト | `readonly: false` のみ |
+
+スコープの契約（#17 対応）:
+
+- `scope: :namespaced`（既定）の宣言では `*_cluster` メソッドは `ArgumentError`（CRD が namespaced のためクラスタ endpoint を呼んでも 404 になるだけ）。
+- `scope: :cluster` の宣言では素の `list` / `find` / `create` / `patch` は `ArgumentError`（namespaced endpoint を呼ぶと 404 になるだけ。`namespace:` 引数は意味を持たない）。
+- 宣言時に `scope: :cluster` と `namespace:` を併用した場合は `ArgumentError`（設定ミスの fail fast）。
+- transport は kruby の `*_cluster_custom_object` 4 メソッド（`namespace` 非持参の endpoint）を使う。テスト注入スタブは 2 セット 8 メソッドを実装する（§9）。
 
 - **戻り値は常に文字列キーの Hash**（K2 の規約を API 契約として固定）。
   `find` は存在しない場合 `K8sRails::NotFound` を raise（consumer アプリ側が `return nil` にしていたのは
@@ -232,8 +269,8 @@ end
 
 | 依存 | 制約 | 理由 |
 |---|---|---|
-| 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 橋渡し）を済ませてから明示的に上げ替える |
+| 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.3 で検証の上宣言に含める（§10） |
+| `kruby` | `~> 1.36.0` | consumer アプリと同一 pin。`~> 1.36.0` は 1.36.x のみ許可（`~> 1.36` 形式は 1.37 以降も許容してしまうため使用しない）。新しめの kruby に対応する場合は §7 の確認事項（client.rb 8 メソッド（namespaced 4 + cluster 4）・K1 橋渡し・`default_config` 探索順序）を済ませてから明示的に上げ替える |
 | `activesupport` | **任意**（`>= 7.0`） | `defined?(ActiveSupport::Notifications)` でガード（計測のみ、§8）。Rails 無し環境（Cron スクリプト等）でも動作する必要がある — レスポンスの文字列キー化（K2）はこれに依存せず、gem 内部の純 Ruby 変換で担う（§5.2） |
 | `rspec` / `rubocop` | 開発依存 | spec / lint |
 
@@ -245,10 +282,15 @@ end
 - `lib/k8s_rails/client.rb` **のみ**が `require "kubernetes"` してよい。
   他のファイルは kruby 定数・クラスを参照しない。
 - kruby の `CustomObjectsApi` メソッド呼び出しは `client.rb` 内の
-  `*_namespaced_custom_object` の 4 メソッド（`get_namespaced_custom_object` 等）に集約する。`resource.rb` は
+  `*_namespaced_custom_object` の 4 メソッド（`get_namespaced_custom_object` 等）と
+  `*_cluster_custom_object` の 4 メソッド（`get_cluster_custom_object` 等）に集約する。
+  `resource.rb` は
   `K8sRails.client.get(group, version, ns, plural, name)` のような **gem 内部 API** だけを使う。
-- kruby 上げ替え時の作業は (1) client.rb 4 メソッドのシグネチャ確認、
-  (2) K1 橋渡しの要否確認、に収まることをテスト（§9）で担保する。
+- kruby 上げ替え時の作業は (1) client.rb 8 メソッド（namespaced 4 + cluster 4）のシグネチャ確認、
+  (2) K1 橋渡しの要否確認、(3) **`Kubernetes::Configuration.default_config` の探索順序確認**
+  （kruby 1.36.x の loader 実装順は **KUBECONFIG → `~/.kube/config` → in-cluster** で in-cluster が
+  最後。README / 設計書 / 設定コメントがこの順序を明記しているため、loader が変わった場合は
+  全箇所を同期する — #19 対応）に収まることをテスト（§9）で担保する。
 
 ## 8. 計測（ActiveSupport 任意）
 
@@ -274,11 +316,11 @@ k8s-rails.request  payload: { operation: :list, group:, version:, plural:, names
 
 | レイヤー | 手法 | 対象 |
 |---|---|---|
-| ユニット | `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（メソッド生成） |
+| ユニット | `K8sRails.config.api_client` に**スタブ**（kruby `CustomObjectsApi` と同型のメソッド。namespaced 4 メソッド `get_namespaced_custom_object` / `list_namespaced_custom_object` / `create_namespaced_custom_object` / `patch_namespaced_custom_object` ＋ cluster 4 メソッド `get_cluster_custom_object` / `list_cluster_custom_object` / `create_cluster_custom_object` / `patch_cluster_custom_object` を実装する素のオブジェクト。`StringKeyedAdapter` がこの形式を呼ぶ）を注入 | client（橋渡し・例外変換）、resource（整形・readonly 制限・スコープ制限）、crd（メソッド生成・scope 検証） |
 | 設定 | spec 間で `K8sRails.reset!` | 宣言の破棄・再接続 |
 | 集積（任意） | GitHub Actions で **kind**（または既存 microk8s に接続するジョブ）で実クラスタ E2E | v0.1 の必須ではない。**推奨**: consumer アプリ移行時の検証を兼ねる |
 
-- 本設計では CI は `rspec` + `rubocop` のみを必須とし、kind E2E は v0.2 以降で
+- 本設計では CI は `rspec` + `rubocop` のみを必須とし、kind E2E は v0.3 で
   GitHub Actions の追加として扱う（実クラスタへの接続 CI はネットワーク依存のため採用しない）。
 
 ## 10. リリース計画
@@ -286,8 +328,9 @@ k8s-rails.request  payload: { operation: :list, group:, version:, plural:, names
 | バージョン | 内容 | 出口基準 |
 |---|---|---|
 | **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.2** | #16–#19 の公開 API 拡充・修正（cluster-scoped CRD `scope:` + `*_cluster` メソッド、`configure` のアトミック契約、`connected?` の注入契約、kruby loader 探索順序の修正）。設計書 v0.1.12（案） | rspec 全緑（クラスタ不要）+ 公開 gem push（v0.1.0 と同導線） |
+| v0.3 | watch（`watch` メソッド、kruby の watch サポート上）、core v1 built-in リソース対応（CustomObjects API では不可なため別途 core API 経路、§2.2）、kind E2E の CI 化、Ruby 3.5 / 4.0 対応（検証の上宣言範囲・matrix を拡大） | v0.2 運用のフィードバック |
+| v0.4 | （展望）複数クラスタ（ネームスペース化された client 集合）、リトライポリシー | — |
 
 v0.1 の milestone 分割（開発セッション向けのタスク単位目安）:
 
@@ -357,12 +400,12 @@ PR の差分を最小化）。
     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 以降で検討）。
+    4.0 は宣言範囲外のため未検証・v0.3 で検討）。
     **宣言範囲を常に matrix がカバーする**こと（`< 4.0` 上限により、
     4.x のリリースは宣言範囲外。stable 化された新 3.x minor が出たら
     matrix への追加を忘れないこと）。
     テストはクラスタ不要（§9・スタブ注入）のため v0.1 は runner 上のユニットのみ。
-    kind / 実クラスタ E2E の CI 化は v0.2 対象（§9・§10）
+    kind / 実クラスタ E2E の CI 化は v0.3 対象（§9・§10）
 - `README` に「kruby pin」「対応 k8s バージョン（実測 v1.33.x で検証済み）」「K1 橋渡しの背景」
   を明記する（検索でヒットする重要な注意点のため）
 
@@ -381,3 +424,5 @@ PR の差分を最小化）。
 | 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 上のリリースコミットとの対応付け（追溯性）が確保できないとの指摘を反映 | 実装反映済み |
+| 0.1.11 | 2026-09-22 | Issue #16–#19 対応: ①#16 `configure` の例外送出時は設定済みフラグをリセット（「一度だけ」はブロック正常終了時にのみ成立）。例外前に書かれた属性は残存することを契約として明文化（§5.1）②#17 `scope: :namespaced`（既定）/ `:cluster` を宣言 API に追加。cluster 系 4 メソッド（`list_cluster` / `find_cluster` / `find_or_nil_cluster` / `create_cluster` / `patch_cluster`）と双方向の ArgumentError 契約（§5.3）。transport は kruby の `*_cluster_custom_object` 4 メソッドを新たに使用③#18 `connected?` は `config.api_client` 注入時に I/O なしで `true`（§5.2）。注入下で Resource 操作と接続確認の挙動を一致させる④#19 kruby 1.36.x の loader 実装順（**KUBECONFIG → `~/.kube/config` → in-cluster**）を README / 設計書 / 設定コメントに明記し、§7 の上げ替え確認事項に探索順序の再確認を追加（in-cluster は最後。従来の「in-cluster → KUBECONFIG」記述は誤り） | 実装反映済み |
+| 0.1.12 | 2026-09-22 | PR #20 レビュー対応（Codex P2 + Copilot M/L 4 系統）: ①#16 のリセット範囲を `rescue StandardError` から**任意の異常終了**（`LoadError` / `ScriptError` / `throw` / non-local return 等）に拡大（成功マーカー + `ensure` で実装、spec 2 件追加）。§5.1 / README の契約文言も「任意の異常終了」に修正②README の「`namespace:` 引数を受け取る」記述を namespaced メソッドに限定（`*_cluster` は受け付けない）③§6 の kruby 上げ替え確認事項を 8 メソッド + 探索順序に同期④`api_client` 注入スタブの契約を namespaced 4 + cluster 4 の 8 メソッドに統一（§5.1 表 / configuration.rb コメント / §9） | 実装反映済み |

data/lib/k8s-rails.rb

@@ -23,14 +23,22 @@ module K8sRails
 
     # Configure the gem. Runs once — a second call warns and is ignored
     # (design §5.1). Yields the Configuration object.
+    #
+    # Atomicity contract: "runs once" holds only when the block returns
+    # normally. If the block exits abnormally (any exception — including
+    # LoadError/ScriptError — throw, non-local return, ...), the flag is
+    # reset, so a later `configure` call re-runs normally. However,
+    # attribute writes made before the exit REMAIN on the shared
+    # Configuration — a failed block may leave a partially applied state;
+    # the re-run block is responsible for setting every attribute it
+    # depends on (documented in design §5.1).
     def configure
       if @configured
         warn "[K8sRails] K8sRails.configure called more than once; ignoring the second call."
         return config
       end
 
-      @configured = true
-      yield config
+      run_configure_block { yield config }
       config
     end
 
@@ -57,9 +65,10 @@ module K8sRails
     # Declare a CRD and return its Resource class (design §5.3, K5).
     #   Workflow = K8sRails.crd(group: "argoproj.io", version: "v1alpha1",
     #                            plural: "workflows", kind: "Workflow")
+    # Cluster-scoped CRDs: pass scope: :cluster (and no namespace:).
     # Re-declaring the same kind raises K8sRails::RedeclarationError.
-    def crd(group:, version:, plural:, kind:, namespace: nil, readonly: true)
-      CRD.declare(group:, version:, plural:, kind:, namespace:, readonly:)
+    def crd(group:, version:, plural:, kind:, namespace: nil, readonly: true, scope: :namespaced)
+      CRD.declare(group:, version:, plural:, kind:, namespace:, readonly:, scope:)
     end
 
     # Design §8: run an API call inside a `k8s-rails.request` notification.
@@ -106,6 +115,25 @@ module K8sRails
     def instrumentation_enabled?
       config.instrumentation && defined?(ActiveSupport::Notifications)
     end
+
+    private
+
+    # Runs the configure block with the configured-once contract (§5.1):
+    # the flag is set only if the block returns normally. ANY abnormal exit
+    # (StandardError, LoadError/ScriptError, throw, non-local return, other
+    # Exception subclasses) resets it so a later `configure` re-runs — but
+    # attribute writes made before the exit remain on the shared
+    # Configuration.
+    def run_configure_block
+      @configured = true
+      ok = false
+      begin
+        yield
+        ok = true
+      ensure
+        @configured = false unless ok
+      end
+    end
   end
 
   # Whether the kruby-dependent client file has actually been required yet

data/lib/k8s_rails/client.rb

@@ -14,6 +14,11 @@ module K8sRails
   #   api.get(group, version, namespace, plural, name)
   #   api.create(group, version, namespace, plural, body)
   #   api.patch(group, version, namespace, plural, name, body)
+  #   # cluster-scoped (namespace argument omitted, design §5.3)
+  #   api.list_cluster(group, version, plural)
+  #   api.get_cluster(group, version, plural, name)
+  #   api.create_cluster(group, version, plural, body)
+  #   api.patch_cluster(group, version, plural, name, body)
   #
   # Connection is LAZY: `build` does no network I/O — it only resolves a
   # `Kubernetes::Configuration` and builds an in-memory `CustomObjectsApi`.
@@ -44,7 +49,15 @@ module K8sRails
       # Lightweight connectivity probe (design §5.2). Performs one lightweight
       # `/version` call via VersionApi and returns true on success. Raises
       # K8sRails::Unavailable / ApiError on failure (the app may rescue).
+      #
+      # Injection contract: when `config.api_client` is set (test injection),
+      # the injected transport IS the connection surface — there is no real
+      # network to probe, so this returns true without I/O. This keeps
+      # `connected?` consistent with Resource operations under injection
+      # (design §5.2).
       def connected?
+        return true if K8sRails.config.api_client
+
         config = build_configuration
         # The probe also authenticates — apply the K1 bridge or the Authorization
         # header would be empty on clusters where /version requires auth.
@@ -150,6 +163,43 @@ module K8sRails
         end
       end
 
+      # Cluster-scoped variants (design §5.3): the same four operations on
+      # kruby's *_cluster_custom_object endpoints (no namespace in the path).
+      # An injected test double must implement both the *_namespaced_* and
+      # *_cluster_* quadruples.
+
+      def list_cluster(group, version, plural)
+        handle do
+          Normalizer.stringify(
+            @transport.list_cluster_custom_object(group, version, plural)
+          )
+        end
+      end
+
+      def get_cluster(group, version, plural, name)
+        handle do
+          Normalizer.stringify(
+            @transport.get_cluster_custom_object(group, version, plural, name)
+          )
+        end
+      end
+
+      def create_cluster(group, version, plural, body)
+        handle do
+          Normalizer.stringify(
+            @transport.create_cluster_custom_object(group, version, plural, body)
+          )
+        end
+      end
+
+      def patch_cluster(group, version, plural, name, body)
+        handle do
+          Normalizer.stringify(
+            @transport.patch_cluster_custom_object(group, version, plural, name, body)
+          )
+        end
+      end
+
       private
 
       def handle

data/lib/k8s_rails/configuration.rb

@@ -13,13 +13,17 @@ module K8sRails
     attr_accessor :namespace
 
     # Kubernetes::Configuration インスタンス。省略時は default_config の自動
-    # 検出（in-cluster → KUBECONFIG）。認証を上書きする場合に指定する。
+    # 検出（kruby 1.36.x の実装順: KUBECONFIG → ~/.kube/config → in-cluster。
+    # kruby 更新時にこの順序が変更されていないか loader を再確認すること）。
+    # 認証を上書きする場合に指定する。
     attr_accessor :connection
 
-    # テスト専用（§5.1）。CustomObjectsApi と同型の 4 メソッド
-    # （`get_namespaced_custom_object` 等の *_namespaced_custom_object 4 メソッド）を実装した素の
+    # テスト専用（§5.1）。CustomObjectsApi と同型の 8 メソッド
+    # （namespaced 4 メソッド `get_namespaced_custom_object` 等 ＋ cluster 4
+    # メソッド `get_cluster_custom_object` 等）を実装した素の
     # オブジェクトを指定すると、Client.build は接続解決をスキープしてこれを
-    # 内部トランスポートとして使う。
+    # 内部トランスポートとして使う（namespaced 宣言だけを使う場合は
+    # namespaced 4 メソッドのみの実装で足りる）。
     attr_accessor :api_client
 
     # ActiveSupport::Notifications での計測の ON/OFF（§8。M3 で実装）。

data/lib/k8s_rails/crd.rb

@@ -12,6 +12,9 @@ module K8sRails
   #     readonly: false,                        # default true
   #   )
   #
+  # Cluster-scoped CRDs (ClusterIssuer, ClusterWorkflowTemplate, ...) use
+  # `scope: :cluster` — `namespace` must be omitted (design §5.3).
+  #
   # `crd` returns a `Resource` subclass with the coordinates bound; the same
   # class is registered under its kind name so a second declaration of the
   # same kind raises K8sRails::RedeclarationError (config-mistake detection).
@@ -30,12 +33,24 @@ module K8sRails
     # kind are explicit — never guessed). `readonly` must be an explicit
     # boolean: mutations are enabled ONLY by `readonly: false` (design §5.3 /
     # K4), so nil/other values fail fast instead of silently allowing writes.
-    def self.declare(group:, version:, plural:, kind:, namespace: nil, readonly: true)
+    # `scope` is :namespaced (default) or :cluster; `namespace` and
+    # `scope: :cluster` are mutually exclusive (a cluster CRD has no
+    # namespace to bind).
+    def self.declare(group:, version:, plural:, kind:, namespace: nil, readonly: true, scope: :namespaced)
       unless [true, false].include?(readonly)
         raise ArgumentError,
               "readonly must be true or false (got #{readonly.inspect}) — mutations require an explicit readonly: false"
       end
 
+      unless %i[namespaced cluster].include?(scope)
+        raise ArgumentError, "scope must be :namespaced or :cluster (got #{scope.inspect})"
+      end
+
+      if scope == :cluster && !namespace.nil?
+        raise ArgumentError,
+              "namespace cannot be combined with scope: :cluster — cluster-scoped CRDs have no namespace"
+      end
+
       if registered.key?(kind)
         raise RedeclarationError, "CRD kind #{kind} is already declared — re-declaration is a configuration mistake"
       end
@@ -46,7 +61,8 @@ module K8sRails
         plural: plural,
         kind: kind,
         namespace: namespace,
-        readonly: readonly
+        readonly: readonly,
+        scope: scope
       )
       registered[kind] = resource
       resource

data/lib/k8s_rails/resource.rb

@@ -10,13 +10,13 @@ module K8sRails
   # touches kruby itself (§7).
   #
   #   Workflow = K8sRails.crd(group: "argoproj.io", version: "v1alpha1",
-  #                            plural: "workflows", kind: "Workflow")
-  #   Workflow.list
-  #   Workflow.find("wf-1")
+  #                           plural: "workflows", kind: "Workflow")
   class Resource
     # Bind declared coordinates to a fresh anonymous subclass. `namespace`
     # may be nil — resolved from `K8sRails.config.namespace` at call time.
-    def self.declare(group:, version:, plural:, kind:, namespace: nil, readonly: true)
+    # `scope` is :namespaced (default) or :cluster (design §5.3); cluster
+    # declarations must not set `namespace`.
+    def self.declare(group:, version:, plural:, kind:, namespace: nil, readonly: true, scope: :namespaced)
       Class.new(self) do
         define_singleton_method(:group_name) { group }
         define_singleton_method(:version_name) { version }
@@ -24,13 +24,16 @@ module K8sRails
         define_singleton_method(:kind_name) { kind }
         define_singleton_method(:declared_namespace) { namespace }
         define_singleton_method(:readonly?) { readonly }
+        define_singleton_method(:cluster_scoped?) { scope == :cluster }
       end
     end
 
     class << self
-      # All objects in the namespace. Returns an array of string-keyed Hashes
-      # (design §5.3: `[{ "name" => "...", ... }]`).
+      # All objects in the namespace (namespaced declarations only —
+      # cluster-scoped declarations raise ArgumentError). Returns an array
+      # of string-keyed Hashes (design §5.3: `[{"name" => "...", ...}]`).
       def list(namespace: resolved_namespace)
+        assert_namespaced
         K8sRails.instrument(:list, instrument_meta(namespace)) do
           transport.list(group_name, version_name, namespace, plural_name)["items"] || []
         end
@@ -38,6 +41,7 @@ module K8sRails
 
       # One object by name. Raises K8sRails::NotFound when absent.
       def find(name, namespace: resolved_namespace)
+        assert_namespaced
         K8sRails.instrument(:find, instrument_meta(namespace)) do
           transport.get(group_name, version_name, namespace, plural_name, name)
         end
@@ -53,6 +57,7 @@ module K8sRails
       # Create from a CRD body hash. `readonly: true` declarations raise
       # K8sRails::ReadOnlyError (K4).
       def create(attributes, namespace: resolved_namespace)
+        assert_namespaced
         assert_writable
         K8sRails.instrument(:create, instrument_meta(namespace)) do
           transport.create(group_name, version_name, namespace, plural_name, attributes)
@@ -61,12 +66,57 @@ module K8sRails
 
       # JSON Patch a named object. Same readonly restriction as `create`.
       def patch(name, operations, namespace: resolved_namespace)
+        assert_namespaced
         assert_writable
         K8sRails.instrument(:patch, instrument_meta(namespace)) do
           transport.patch(group_name, version_name, namespace, plural_name, name, operations)
         end
       end
 
+      # Cluster-scoped variants (design §5.3). Available on EVERY declared
+      # class; a `scope: :namespaced` declaration raises ArgumentError (its
+      # CRD is namespaced, so cluster endpoints 404 anyway).
+      # All objects cluster-wide. Returns an array of string-keyed Hashes.
+      def list_cluster
+        assert_cluster_scoped
+        K8sRails.instrument(:list, instrument_meta(nil)) do
+          transport.list_cluster(group_name, version_name, plural_name)["items"] || []
+        end
+      end
+
+      # One cluster-scoped object by name. Raises K8sRails::NotFound when absent.
+      def find_cluster(name)
+        assert_cluster_scoped
+        K8sRails.instrument(:find, instrument_meta(nil)) do
+          transport.get_cluster(group_name, version_name, plural_name, name)
+        end
+      end
+
+      # Like `find_cluster`, but returns nil instead of raising on NotFound.
+      def find_or_nil_cluster(name)
+        find_cluster(name)
+      rescue NotFound
+        nil
+      end
+
+      # Create a cluster-scoped object. Same readonly restriction as `create`.
+      def create_cluster(attributes)
+        assert_cluster_scoped
+        assert_writable
+        K8sRails.instrument(:create, instrument_meta(nil)) do
+          transport.create_cluster(group_name, version_name, plural_name, attributes)
+        end
+      end
+
+      # JSON Patch a cluster-scoped object. Same readonly restriction.
+      def patch_cluster(name, operations)
+        assert_cluster_scoped
+        assert_writable
+        K8sRails.instrument(:patch, instrument_meta(nil)) do
+          transport.patch_cluster(group_name, version_name, plural_name, name, operations)
+        end
+      end
+
       private
 
       # Notification metadata for design §8 (`k8s-rails.request`).
@@ -80,15 +130,30 @@ module K8sRails
         declared_namespace || K8sRails.config.namespace
       end
 
-      def transport
-        K8sRails.client
-      end
+      # Endless method: keeps the class under the ClassLength budget while
+      # delegating to the shared transport (design §5.2).
+      def transport = K8sRails.client
 
       def assert_writable
         return unless readonly?
 
         raise ReadOnlyError, "#{kind_name} is declared readonly — create/patch are disabled (K4)"
       end
+
+      def assert_cluster_scoped
+        return if cluster_scoped?
+
+        raise ArgumentError,
+              "#{kind_name} is namespaced — *_cluster methods require a scope: :cluster declaration"
+      end
+
+      def assert_namespaced
+        return unless cluster_scoped?
+
+        raise ArgumentError,
+              "#{kind_name} is declared scope: :cluster — use the *_cluster methods " \
+              "(there is no namespace endpoint for a cluster-scoped CRD)"
+      end
     end
   end
 end

data/lib/k8s_rails/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module K8sRails
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: k8s-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dorian - Takahiro Ishida