kube_cluster 0.21.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e702b334081767a62c208fcc0527bd69e531b1663c8f0073f5fd4cec5880263
-  data.tar.gz: fb4289693ab12e0a4ab9ed97d477d68440a5caae4a92f3ed6b8605daef59a430
+  metadata.gz: cff2cff26d95919ba88b763d17c91b4fd48b024e038bf5bcbaba269fbf549f6b
+  data.tar.gz: cb2b14a5cc86d623c2871517771f7b4e3ecfad529d8ac48093e573065fc80f9d
 SHA512:
-  metadata.gz: 614b806784409a283a0998004d19e5522b114a92d0b46798586f173eafd5718b88a66935f578a60406f6f779a4206c099d7bc8fee7f92429abad8c1facfbcaf1
-  data.tar.gz: b546741f901ee256ed2f603fa3ca76c348d2a728151e54a96a4206da81c710712684c541b8c65cd304b51c25ced7dbbb23578d697346b122ec9ce8f84047d3d1
+  metadata.gz: b6333f789ef8a88beaef674cc32752a42a885a300f5d6bb5ab09f14c2dcab973f111e5ccb20f360605177e24beb3eac69769cd2e85269e98907c162d217adf25
+  data.tar.gz: 2cf30bce0097d24f98a20691b99a3f47514581dde2642d4ec2d1dd04c0cf4daf5c660befdbf511976728e084a0083ec21eb283edd5b5c43b9f593946cbfb9204

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.1] - 2026-07-13
+
+### Added
+- `require "kube/cluster/standard"` — an aggregator that loads the entire
+  Standard tree at once, for projects that use most of it. The tree remains
+  opt-in (`require "kube/cluster"` alone does not load it), so resolve overrides
+  still take effect. The core auto-require now also skips this aggregator file.
+
+## [1.0.0] - 2026-07-13
+
+### Added
+- `Kube::Cluster.config` / `resolve` DSL backed by an internal resolve table
+  that `Kube::Cluster.[]` consults first, so a bare kind can be pinned to an
+  explicit `group/version/Kind` instead of whatever the schema registry lists
+  first.
+- Resolve-table pins for every bare kind referenced under
+  `kube/cluster/standard` — Perses (`v1alpha2`), Gateway API (`v1`), built-in
+  Kubernetes kinds, and the Metacontroller, CloudNativePG, External Secrets,
+  KubeVirt, k3s HelmChart, and VictoriaMetrics CRDs.
+- `config` warns when `Kube::Cluster::Standard` is already loaded, since those
+  classes have already bound their (now stale) superclasses.
+- Test guarding that every bare kind used in the standard tree is pinned in the
+  resolve table.
+
+### Changed
+- **Breaking:** the `kube/cluster/standard` tree is no longer auto-required by
+  `require "kube/cluster"`. Projects must require the specific standard classes
+  they use, so resolve overrides can be configured beforehand.
+
+### Fixed
+- `Standard::Perses::Perses` and `Standard::Perses::PersesDatasource` now resolve
+  to `perses.dev/v1alpha2` instead of the deprecated `v1alpha1` a bare-kind
+  lookup defaulted to.
+
+[1.0.0]: https://github.com/general-intelligence-systems/kube_cluster/releases/tag/v1.0.0

data/Gemfile.lock

@@ -1,10 +1,10 @@
 PATH
   remote: .
   specs:
-    kube_cluster (0.20.0)
+    kube_cluster (1.0.1)
       activesupport (~> 8.0)
       kube_kubectl (~> 2.0)
-      kube_schema (~> 1.8)
+      kube_schema (~> 1.9.2)
 
 GEM
   remote: https://rubygems.org/
@@ -132,7 +132,7 @@ GEM
       rubyshell (~> 1.5)
       shellwords (~> 0.2.2)
       string_builder (~> 1.2.2)
-    kube_schema (1.9.1)
+    kube_schema (1.9.2)
       json_schemer (~> 2.5.0)
       rubyshell (~> 1.5.0)
     localhost (1.8.0)

data/kube_cluster.gemspec

@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "scampi", "~> 1.0"
 
-  spec.add_dependency "kube_schema", "~> 1.9.1"
+  spec.add_dependency "kube_schema", "~> 1.9.2"
   spec.add_dependency "kube_kubectl", "~> 2.0"
   spec.add_dependency "activesupport", "~> 8.0"
 end

data/lib/kube/cluster/standard/gateway_api/http_route.rb

@@ -22,16 +22,16 @@ module Kube
         #
         #   Standard::GatewayApi::HTTPRoute.new(
         #     name:    "sourcebot",
-        #     gateway: "kremlin-email-https",
-        #     domains: ["sg.kremlin.email"],
+        #     gateway: "example-com-https",
+        #     domains: ["sg.example.com"],
         #     service: { namespace: "sourcebot", name: "sourcebot", port: 3000 },
-        #     middleware: "forwardauth-oauth2-proxy-kremlin",
+        #     middleware: "forwardauth-oauth2-proxy-example",
         #   )
         #
         # Many matches -> one backend (forgejo git smart-HTTP):
         #
         #   Standard::GatewayApi::HTTPRoute.new(
-        #     name: "forgejo-git", gateway: "cia-net-https", domains: ["git.cia.net"],
+        #     name: "forgejo-git", gateway: "example-net-https", domains: ["git.example.net"],
         #     regex:  ["/.+/info/refs", "/.+/git-upload-pack", "/.+/git-receive-pack"],
         #     prefix: ["/api", "/v2"],
         #     service: { namespace: "default", name: "forgejo-http", port: 3000 },
@@ -41,8 +41,8 @@ module Kube
         # Terminal http->https redirect (the `-http` sibling):
         #
         #   Standard::GatewayApi::HTTPRoute.new(
-        #     name: "sourcebot-http", gateway: "kremlin-email-http",
-        #     domains: ["sg.kremlin.email"], prefix: ["/"], redirect: true,
+        #     name: "sourcebot-http", gateway: "example-com-http",
+        #     domains: ["sg.example.com"], prefix: ["/"], redirect: true,
         #   )
         class HTTPRoute < Kube::Cluster["HTTPRoute"]
           GATEWAY_GROUP = "gateway.networking.k8s.io"
@@ -86,7 +86,10 @@ module Kube
 
             super() {
               metadata.name      = name
-              metadata.namespace = namespace
+              # A co-located route (namespace: nil) omits metadata.namespace so
+              # it lands in whatever namespace applies it; cross-namespace routes
+              # in kube-system set it explicitly.
+              metadata.namespace = namespace if namespace
 
               spec.hostnames  = hostnames
               spec.parentRefs = [{
@@ -175,10 +178,21 @@ module Kube
           # the backend (the cross-namespace model, which needs a ReferenceGrant
           # the caller supplies). Omitting it yields the co-located short form.
           def _backend(service)
-            ref = { group: "", kind: "Service", name: service.fetch(:name) }
-            ref[:namespace] = service[:namespace] if service[:namespace]
-            ref[:port]      = service.fetch(:port)
-            ref[:weight]    = service.fetch(:weight, 1)
+            ref = {}
+            # Cross-namespace backends carry the explicit group/kind/namespace
+            # (and need a ReferenceGrant); a co-located Service uses the bare
+            # short form. Emitting group/kind only in the former keeps both
+            # shapes byte-identical to the hand-written routes they replace.
+            if service[:namespace]
+              ref[:group]     = ""
+              ref[:kind]      = "Service"
+              ref[:name]      = service.fetch(:name)
+              ref[:namespace] = service[:namespace]
+            else
+              ref[:name] = service.fetch(:name)
+            end
+            ref[:port]   = service.fetch(:port)
+            ref[:weight] = service.fetch(:weight, 1)
             ref
           end
         end
@@ -195,8 +209,9 @@ describe "GatewayApi::HTTPRoute" do
   it "initializes without error" do
     route.(
       name:    "docuseal",
-      gateway: "kremlin-email-https",
-      domains: ["docuseal.kremlin.email"],
+      gateway: "example-com-https",
+      domains: ["docuseal.example.com"],
+      prefix:  ["/"],
       service: { namespace: "ai", name: "docuseal", port: 3000 },
     ).to_yaml.is_a?(String).should == true
   end
@@ -204,22 +219,23 @@ describe "GatewayApi::HTTPRoute" do
   it "wires the fixed traefik-gateway parentRef with the given section" do
     yaml = route.(
       name:    "docuseal",
-      gateway: "kremlin-email-https",
-      domains: ["docuseal.kremlin.email"],
+      gateway: "example-com-https",
+      domains: ["docuseal.example.com"],
+      prefix:  ["/"],
       service: { namespace: "ai", name: "docuseal", port: 3000 },
     ).to_yaml
 
     yaml.should.include "traefik-gateway"
-    yaml.should.include "kremlin-email-https"
-    yaml.should.include "docuseal.kremlin.email"
+    yaml.should.include "example-com-https"
+    yaml.should.include "docuseal.example.com"
     yaml.should.include "PathPrefix"
   end
 
   it "renders many typed matches onto one backend with timeouts" do
     yaml = route.(
       name:    "forgejo-git",
-      gateway: "cia-net-https",
-      domains: ["git.cia.net"],
+      gateway: "example-net-https",
+      domains: ["git.example.net"],
       regex:   ["/.+/info/refs", "/.+/git-upload-pack", "/.+/git-receive-pack"],
       prefix:  ["/api", "/v2"],
       service: { namespace: "default", name: "forgejo-http", port: 3000 },
@@ -236,8 +252,8 @@ describe "GatewayApi::HTTPRoute" do
   it "renders a terminal https redirect with no backend" do
     yaml = route.(
       name:    "sourcebot-http",
-      gateway: "kremlin-email-http",
-      domains: ["sg.kremlin.email"],
+      gateway: "example-com-http",
+      domains: ["sg.example.com"],
       prefix:  ["/"],
       redirect: true,
     ).to_yaml
@@ -250,8 +266,8 @@ describe "GatewayApi::HTTPRoute" do
   it "renders a custom redirect with ReplaceFullPath and a 302" do
     yaml = route.(
       name:    "forgejo-login",
-      gateway: "cia-net-https",
-      domains: ["git.cia.net"],
+      gateway: "example-net-https",
+      domains: ["git.example.net"],
       exact:   ["/user/login"],
       redirect: { path: "/user/oauth2/authelia", status: 302 },
     ).to_yaml
@@ -264,23 +280,25 @@ describe "GatewayApi::HTTPRoute" do
   it "chains multiple middlewares as ExtensionRef filters" do
     yaml = route.(
       name:    "docker-registry",
-      gateway: "cia-net-https",
-      domains: ["registry.cia.net"],
+      gateway: "example-net-https",
+      domains: ["registry.example.net"],
+      prefix:  ["/"],
       service: { namespace: "docker-registry", name: "docker-registry", port: 80 },
-      middleware: ["clear-site-data-cookies", "forwardauth-oauth2-proxy-cia"],
+      middleware: ["clear-site-data-cookies", "forwardauth-oauth2-proxy-example"],
     ).to_yaml
 
     yaml.scan(/ExtensionRef/).length.should == 2
     yaml.should.include "clear-site-data-cookies"
-    yaml.should.include "forwardauth-oauth2-proxy-cia"
+    yaml.should.include "forwardauth-oauth2-proxy-example"
   end
 
   it "renders a header modifier and a co-located short-form backend" do
     yaml = route.(
       name:      "sogo",
       namespace: "mail",
-      gateway:   "kremlin-email-https",
-      domains:   ["sogo.kremlin.email"],
+      gateway:   "example-com-https",
+      domains:   ["sogo.example.com"],
+      prefix:    ["/"],
       service:   { name: "sogo", port: 80 },
       header_modifier: { remove: ["x-webobjects-remote-user"] },
     ).to_yaml
@@ -292,8 +310,9 @@ describe "GatewayApi::HTTPRoute" do
   it "supports a websocket header match" do
     yaml = route.(
       name:    "chrome-tool-ws",
-      gateway: "kremlin-email-https",
-      domains: ["chrome-tool-ws.kremlin.email"],
+      gateway: "example-com-https",
+      domains: ["chrome-tool-ws.example.com"],
+      prefix:  ["/"],
       service: { namespace: "ai", name: "chrome-tool-ws", port: 8765 },
       headers: { "Upgrade" => "websocket" },
     ).to_yaml
@@ -305,12 +324,13 @@ describe "GatewayApi::HTTPRoute" do
   it "renders multiple hostnames on one route" do
     yaml = route.(
       name:    "git",
-      gateway: "cia-net-https",
-      domains: ["git.cia.net", "git.kremlin.email"],
+      gateway: "example-net-https",
+      domains: ["git.example.net", "git.example.com"],
+      prefix:  ["/"],
       service: { namespace: "default", name: "forgejo-http", port: 3000 },
     ).to_yaml
 
-    yaml.should.include "git.cia.net"
-    yaml.should.include "git.kremlin.email"
+    yaml.should.include "git.example.net"
+    yaml.should.include "git.example.com"
   end
 end

data/lib/kube/cluster/standard.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+#
+# Opt-in loader for the whole Standard tree.
+#
+# `require "kube/cluster"` deliberately does NOT auto-load the Standard classes
+# (so resolve overrides can be configured before they bind their superclasses).
+# Requiring this file pulls in every Standard class at once — the convenient
+# "give me all of them" entry point for projects that use most of the tree.
+require "kube/cluster"
+
+Dir.glob("#{__dir__}/standard/**/*.rb").sort.each do |path|
+  require path
+end

data/lib/kube/cluster/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Cluster
-    VERSION = "0.21.0"
+    VERSION = "1.0.1"
   end
 end

data/lib/kube/cluster.rb

@@ -20,6 +20,42 @@ module Kube
       Instance.new(kubeconfig: kubeconfig)
     end
 
+    # Internal table mapping a bare kind to the group/version/Kind it should
+    # resolve to. Consulted first by Kube::Cluster.[] so a bare lookup lands on
+    # a pinned version instead of whatever the schema registry defaults to.
+    def self.resolve_table
+      @resolve_table ||= {}
+    end
+
+    # Configure kind resolution:
+    #
+    #   Kube::Cluster.config do
+    #     resolve "Perses", to: "perses.dev/v1alpha2/Perses"
+    #   end
+    #
+    # Ordering matters: Kube::Cluster.[] memoizes per kind, and the Standard
+    # classes bind their superclass at definition time (e.g.
+    # `class Perses < Kube::Cluster["Perses"]`). A resolve therefore only takes
+    # effect for kinds looked up afterwards — so configure before requiring any
+    # kube/cluster/standard class. If Standard is already loaded, warn: its
+    # classes have already bound their (now stale) superclasses.
+    def self.config(&block)
+      if const_defined?(:Standard, false)
+        warn "Kube::Cluster::Standard was loaded before Kube::Cluster.config — " \
+          "resolve overrides will not affect the already-bound Standard classes."
+      end
+      Config.instance_eval(&block) if block
+      Config
+    end
+
+    module Config
+      module_function
+
+      def resolve(kind, to:)
+        Kube::Cluster.resolve_table[kind] = to
+      end
+    end
+
     # Returns an anonymous subclass of Kube::Cluster::Resource for the
     # given Kubernetes kind, mirroring Kube::Schema[kind] but with
     # dirty tracking, persistence, and resource helper methods.
@@ -27,6 +63,7 @@ module Kube
     #   Kube::Cluster["Deployment"].new { metadata.name = "web" }
     #
     def self.[](kind)
+      kind = resolve_table.fetch(kind, kind)
       @resource_classes ||= {}
       @resource_classes[kind] ||= begin
         schema_class = Kube::Schema[kind]
@@ -48,7 +85,108 @@ require "kube/cluster/middleware"
 require "kube/cluster/resource/dirty_tracking"
 require "kube/cluster/resource/persistence"
 
+# Kind resolution overrides. Registered here, at load time, so the pins are in
+# place before a project requires any kube/cluster/standard class (those bind
+# Kube::Cluster[kind] at definition time). The standard tree is deliberately not
+# auto-required below — projects require the specific classes they use.
+Kube::Cluster.config do
+  # Built-in Kubernetes kinds.
+  resolve "ConfigMap",                to: "v1/ConfigMap"
+  resolve "PersistentVolumeClaim",    to: "v1/PersistentVolumeClaim"
+  resolve "Secret",                   to: "v1/Secret"
+  resolve "Service",                  to: "v1/Service"
+  resolve "ServiceAccount",           to: "v1/ServiceAccount"
+  resolve "DaemonSet",                to: "apps/v1/DaemonSet"
+  resolve "Deployment",               to: "apps/v1/Deployment"
+  resolve "CronJob",                  to: "batch/v1/CronJob"
+  resolve "Job",                      to: "batch/v1/Job"
+  resolve "Role",                     to: "rbac.authorization.k8s.io/v1/Role"
+  resolve "RoleBinding",              to: "rbac.authorization.k8s.io/v1/RoleBinding"
+  resolve "CustomResourceDefinition", to: "apiextensions.k8s.io/v1/CustomResourceDefinition"
+
+  # Metacontroller.
+  resolve "CompositeController",      to: "metacontroller.k8s.io/v1alpha1/CompositeController"
+  resolve "DecoratorController",      to: "metacontroller.k8s.io/v1alpha1/DecoratorController"
+
+  # CloudNativePG.
+  resolve "Database",                 to: "postgresql.cnpg.io/v1/Database"
+
+  # External Secrets Operator.
+  resolve "ExternalSecret",           to: "external-secrets.io/v1/ExternalSecret"
+
+  # KubeVirt.
+  resolve "VirtualMachine",           to: "kubevirt.io/v1/VirtualMachine"
+
+  # k3s HelmChart.
+  resolve "HelmChart",                to: "helm.cattle.io/v1/HelmChart"
+
+  # VictoriaMetrics operator.
+  resolve "VLAgent",                  to: "operator.victoriametrics.com/v1/VLAgent"
+  resolve "VLSingle",                 to: "operator.victoriametrics.com/v1/VLSingle"
+  resolve "VMAgent",                  to: "operator.victoriametrics.com/v1beta1/VMAgent"
+  resolve "VMNodeScrape",             to: "operator.victoriametrics.com/v1beta1/VMNodeScrape"
+  resolve "VMServiceScrape",          to: "operator.victoriametrics.com/v1beta1/VMServiceScrape"
+  resolve "VMSingle",                 to: "operator.victoriametrics.com/v1beta1/VMSingle"
+
+  # Gateway API — pin to the stable v1 group/version.
+  resolve "GatewayClass",             to: "gateway.networking.k8s.io/v1/GatewayClass"
+  resolve "Gateway",                  to: "gateway.networking.k8s.io/v1/Gateway"
+  resolve "HTTPRoute",                to: "gateway.networking.k8s.io/v1/HTTPRoute"
+  resolve "GRPCRoute",                to: "gateway.networking.k8s.io/v1/GRPCRoute"
+  resolve "ReferenceGrant",           to: "gateway.networking.k8s.io/v1/ReferenceGrant"
+
+  # Perses operator — pin to v1alpha2 (bare kind defaults to deprecated v1alpha1).
+  resolve "Perses",                   to: "perses.dev/v1alpha2/Perses"
+  resolve "PersesDashboard",          to: "perses.dev/v1alpha2/PersesDashboard"
+  resolve "PersesDatasource",         to: "perses.dev/v1alpha2/PersesDatasource"
+  resolve "PersesGlobalDatasource",   to: "perses.dev/v1alpha2/PersesGlobalDatasource"
+end
+
+standard_root = "#{__dir__}/cluster/standard"
 Dir.glob("#{__dir__}/cluster/**/*.rb").sort.each do |path|
+  # The standard/ tree is opt-in — via `require "kube/cluster/standard"` or a
+  # specific class — so that resolve overrides can be configured beforehand.
+  # Skip both the tree and its aggregator loader (cluster/standard.rb).
+  next if path == "#{standard_root}.rb" || path.start_with?("#{standard_root}/")
+
   require path
 end
 
+__END__
+
+# Every Standard class binds its superclass at load time with a bare kind, e.g.
+# `class Perses < Kube::Cluster["Perses"]`. A bare kind resolves to whatever
+# version the schema registry lists first — sometimes a deprecated one (Perses
+# defaulted to v1alpha1) — so each such kind must be pinned in the resolve table
+# above. This fails if any bare kind under kube/cluster/standard is unpinned.
+describe "Kube::Cluster resolve table" do
+  it "pins every bare kind referenced under kube/cluster/standard" do
+    cluster_rb = Kube::Cluster.method(:[]).source_location.first
+    std_dir    = File.join(File.dirname(cluster_rb), "cluster", "standard")
+
+    # kind => ["relative/file.rb:lineno", ...], scanning only real code (the
+    # section before each file's own __END__), skipping commented-out classes.
+    referenced = {}
+    Dir.glob("#{std_dir}/**/*.rb").sort.each do |file|
+      head = File.read(file).split(/^__END__$\n?/, 2).first
+      head.each_line.with_index(1) do |line, lineno|
+        next if line =~ /\A\s*#/
+        line.scan(/Kube::Cluster\[\s*['"]([^'"]+)['"]\s*\]/) do |(ref)|
+          next if ref.include?("/") # already a fully-qualified GVK
+          (referenced[ref] ||= []) << "#{file.sub("#{std_dir}/", "")}:#{lineno}"
+        end
+      end
+    end
+
+    table   = Kube::Cluster.resolve_table
+    missing = referenced.reject { |kind, _| table.key?(kind) }
+
+    unless missing.empty?
+      report = missing.sort.map { |kind, locs| "  #{kind}  (#{locs.join(", ")})" }.join("\n")
+      raise "Bare kinds under kube/cluster/standard missing from the resolve table:\n#{report}"
+    end
+
+    missing.empty?.should == true
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kube_cluster
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Nathan K
@@ -43,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.1
+        version: 1.9.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.9.1
+        version: 1.9.2
 - !ruby/object:Gem::Dependency
   name: kube_kubectl
   requirement: !ruby/object:Gem::Requirement
@@ -96,6 +96,7 @@ files:
 - ".github/workflows/test.yaml"
 - ".gitignore"
 - ".rubocop.yml"
+- CHANGELOG.md
 - Gemfile
 - Gemfile.lock
 - LICENSE
@@ -197,6 +198,7 @@ files:
 - lib/kube/cluster/resource/extensions/custom_resource_definition.rb
 - lib/kube/cluster/resource/persistence.rb
 - lib/kube/cluster/script_command.rb
+- lib/kube/cluster/standard.rb
 - lib/kube/cluster/standard/cdi/data_volume.rb
 - lib/kube/cluster/standard/cloud_native_pg/cluster.rb
 - lib/kube/cluster/standard/cloud_native_pg/database_with_external_secret.rb