kube_schema 1.3.10 → 1.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec9dd9097e79e7347dad7507a4670448598cbabf88d5347f4f54304cbdea582e
-  data.tar.gz: 0d0fc8aad770317f4e1a666e62b5a884433165dd84aebafcb7ba759c8e37ede2
+  metadata.gz: f145d4e219013c8c1f0091ce99d7a2a10d1700201e77c6ed2d3d26db140206b0
+  data.tar.gz: 0114343af9ef19eb9f7496ed0506859126cef3912bb593c855c36565550dd504
 SHA512:
-  metadata.gz: 9d1b2444bed18ac8c17c9e383e4f5e063b032cde1ac18a6528e8de363af63f750ff00b0010198165f73e0c0c782f2fdf4f9b69afb0e3ac0051272e993d97d507
-  data.tar.gz: 7fdfcd1388bfe2eda4097602ff9397c3564b84921133806f7784a947e6a7fab9a88ece0d6497a24a6327924f6cd2ba5be948b4ae878cbaa43009e7f6bd0a067a
+  metadata.gz: cd5ee4e5f81546204cc2ff1040131a3cb09f4d512a4230adcaab86f7a2db0c65d0ec3034fc6613461f8de2eb549ea7c2e297da6e3de5ddc107f23629afe93727
+  data.tar.gz: cf4e3bf4b4a913ccc5108fe42c274c350d7d09db67fdc195028f6f0ddd513d82fa0799674d453cdfd7f3e7c086739c4150175cd7c62b5b7ab5ffca90e8b32b3f

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kube_schema (1.3.10)
+    kube_schema (1.4.0)
       json_schemer (~> 2.5.0)
       rubyshell (~> 1.5.0)
 

data/examples/sub_specs.rb

@@ -0,0 +1,412 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Demonstrates Kube::Schema::SubSpec — typed, schema-validated wrappers
+# for non-resource Kubernetes definitions (Container, Volume, Probe, etc.).
+#
+# SubSpec objects validate against the OpenAPI JSON Schema and auto-coerce
+# to plain hashes when placed inside Resource specs.
+#
+# Run:  bundle exec ruby examples/sub_specs.rb
+
+require_relative "../lib/kube/schema"
+
+SubSpec  = Kube::Schema::SubSpec
+Manifest = Kube::Schema::Manifest
+
+puts "=" * 60
+puts "Kube::Schema::SubSpec Examples"
+puts "=" * 60
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  1. CONTAINER — the core use case
+# ══════════════════════════════════════════════════════════════
+
+app = SubSpec["Container"].new {
+  self.name  = "app"
+  self.image = "myapp:1.4.2"
+  self.imagePullPolicy = "IfNotPresent"
+  self.command = ["/usr/bin/myapp"]
+  self.args    = ["--config", "/etc/myapp/config.yaml"]
+  self.ports = [
+    { name: "http",    containerPort: 8080, protocol: "TCP" },
+    { name: "metrics", containerPort: 9090, protocol: "TCP" }
+  ]
+  self.env = [
+    { name: "LOG_LEVEL",  value: "info" },
+    { name: "WORKERS",    value: "4" },
+    { name: "DB_PASSWORD", valueFrom: { secretKeyRef: { name: "db-creds", key: "password" } } }
+  ]
+  self.resources.requests = { cpu: "100m", memory: "128Mi" }
+  self.resources.limits   = { cpu: "500m", memory: "256Mi" }
+  self.volumeMounts = [
+    { name: "config", mountPath: "/etc/myapp",  readOnly: true },
+    { name: "data",   mountPath: "/var/data" }
+  ]
+  self.livenessProbe = {
+    httpGet: { path: "/healthz", port: 8080 },
+    initialDelaySeconds: 10,
+    periodSeconds: 30
+  }
+  self.readinessProbe = {
+    httpGet: { path: "/ready", port: 8080 },
+    initialDelaySeconds: 5,
+    periodSeconds: 10
+  }
+  self.securityContext.runAsNonRoot = true
+  self.securityContext.readOnlyRootFilesystem = true
+  self.securityContext.allowPrivilegeEscalation = false
+}
+
+puts "1. Container: #{app.name}"
+puts "   image: #{app.image}"
+puts "   ports: #{app.ports.map { |p| p[:name] }.join(", ")}"
+puts "   valid? #{app.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  2. CONTAINER PORT — typed port definitions
+# ══════════════════════════════════════════════════════════════
+
+http_port = SubSpec["ContainerPort"].new {
+  self.name          = "http"
+  self.containerPort = 8080
+  self.protocol      = "TCP"
+}
+
+grpc_port = SubSpec["ContainerPort"].new(
+  name: "grpc", containerPort: 9090, protocol: "TCP"
+)
+
+puts "2. ContainerPorts:"
+puts "   - #{http_port.name}: #{http_port.containerPort}"
+puts "   - #{grpc_port.name}: #{grpc_port.containerPort}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  3. ENV VAR — plain values and valueFrom references
+# ══════════════════════════════════════════════════════════════
+
+env_plain = SubSpec["EnvVar"].new(name: "APP_ENV", value: "production")
+
+env_secret = SubSpec["EnvVar"].new {
+  self.name = "DB_PASSWORD"
+  self.valueFrom.secretKeyRef = { name: "db-creds", key: "password" }
+}
+
+env_configmap = SubSpec["EnvVar"].new {
+  self.name = "LOG_FORMAT"
+  self.valueFrom.configMapKeyRef = { name: "app-config", key: "log_format" }
+}
+
+env_field = SubSpec["EnvVar"].new {
+  self.name = "POD_NAME"
+  self.valueFrom.fieldRef = { fieldPath: "metadata.name" }
+}
+
+puts "3. EnvVars:"
+[env_plain, env_secret, env_configmap, env_field].each do |e|
+  puts "   - #{e.name}: valid? #{e.valid?}"
+end
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  4. VOLUME + VOLUME MOUNT — paired definitions
+# ══════════════════════════════════════════════════════════════
+
+config_volume = SubSpec["Volume"].new {
+  self.name = "config"
+  self.configMap = { name: "app-config" }
+}
+
+secret_volume = SubSpec["Volume"].new {
+  self.name = "tls-certs"
+  self.secret = { secretName: "tls-secret" }
+}
+
+data_volume = SubSpec["Volume"].new {
+  self.name = "data"
+  self.emptyDir = { sizeLimit: "1Gi" }
+}
+
+pvc_volume = SubSpec["Volume"].new(
+  name: "storage",
+  persistentVolumeClaim: { claimName: "app-pvc" }
+)
+
+config_mount = SubSpec["VolumeMount"].new(
+  name: "config", mountPath: "/etc/app", readOnly: true
+)
+
+tls_mount = SubSpec["VolumeMount"].new {
+  self.name      = "tls-certs"
+  self.mountPath = "/etc/tls"
+  self.readOnly  = true
+}
+
+data_mount = SubSpec["VolumeMount"].new(
+  name: "data", mountPath: "/var/data"
+)
+
+puts "4. Volumes:"
+[config_volume, secret_volume, data_volume, pvc_volume].each do |v|
+  puts "   - #{v.name}: valid? #{v.valid?}"
+end
+puts "   Mounts:"
+[config_mount, tls_mount, data_mount].each do |m|
+  puts "   - #{m.name} -> #{m.mountPath}"
+end
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  5. PROBE — liveness, readiness, startup
+# ══════════════════════════════════════════════════════════════
+
+http_probe = SubSpec["Probe"].new {
+  self.httpGet = { path: "/healthz", port: 8080 }
+  self.initialDelaySeconds = 15
+  self.periodSeconds       = 20
+  self.timeoutSeconds      = 3
+  self.failureThreshold    = 3
+}
+
+tcp_probe = SubSpec["Probe"].new {
+  self.tcpSocket = { port: 5432 }
+  self.initialDelaySeconds = 5
+  self.periodSeconds       = 10
+}
+
+exec_probe = SubSpec["Probe"].new {
+  self.exec = { command: ["/bin/sh", "-c", "pg_isready -U postgres"] }
+  self.initialDelaySeconds = 10
+  self.periodSeconds       = 30
+}
+
+grpc_probe = SubSpec["Probe"].new {
+  self.grpc = { port: 50051 }
+  self.periodSeconds = 10
+}
+
+puts "5. Probes:"
+puts "   - HTTP:  valid? #{http_probe.valid?}"
+puts "   - TCP:   valid? #{tcp_probe.valid?}"
+puts "   - Exec:  valid? #{exec_probe.valid?}"
+puts "   - gRPC:  valid? #{grpc_probe.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  6. SECURITY CONTEXT — hardened container
+# ══════════════════════════════════════════════════════════════
+
+hardened = SubSpec["SecurityContext"].new {
+  self.runAsNonRoot             = true
+  self.runAsUser                = 1000
+  self.runAsGroup               = 1000
+  self.readOnlyRootFilesystem   = true
+  self.allowPrivilegeEscalation = false
+  self.capabilities = { drop: ["ALL"] }
+  self.seccompProfile = { type: "RuntimeDefault" }
+}
+
+puts "6. SecurityContext:"
+puts "   runAsUser: #{hardened.runAsUser}"
+puts "   readOnlyRootFilesystem: #{hardened.readOnlyRootFilesystem}"
+puts "   valid? #{hardened.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  7. TOLERATION + TOPOLOGY SPREAD CONSTRAINT
+# ══════════════════════════════════════════════════════════════
+
+gpu_toleration = SubSpec["Toleration"].new(
+  key: "nvidia.com/gpu", operator: "Exists", effect: "NoSchedule"
+)
+
+spot_toleration = SubSpec["Toleration"].new {
+  self.key      = "kubernetes.azure.com/scalesetpriority"
+  self.operator = "Equal"
+  self.value    = "spot"
+  self.effect   = "NoSchedule"
+}
+
+zone_spread = SubSpec["TopologySpreadConstraint"].new {
+  self.maxSkew           = 1
+  self.topologyKey       = "topology.kubernetes.io/zone"
+  self.whenUnsatisfiable = "DoNotSchedule"
+  self.labelSelector = { matchLabels: { app: "web" } }
+}
+
+puts "7. Scheduling:"
+puts "   Tolerations:"
+puts "   - #{gpu_toleration.key}: valid? #{gpu_toleration.valid?}"
+puts "   - #{spot_toleration.key}: valid? #{spot_toleration.valid?}"
+puts "   TopologySpreadConstraint:"
+puts "   - #{zone_spread.topologyKey}: valid? #{zone_spread.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  8. SERVICE PORT — for Service specs
+# ══════════════════════════════════════════════════════════════
+
+svc_http = SubSpec["ServicePort"].new(
+  name: "http", port: 80, targetPort: 8080, protocol: "TCP"
+)
+
+svc_https = SubSpec["ServicePort"].new {
+  self.name        = "https"
+  self.port        = 443
+  self.targetPort  = 8443
+  self.protocol    = "TCP"
+  self.appProtocol = "kubernetes.io/h2c"
+}
+
+puts "8. ServicePorts:"
+puts "   - #{svc_http.name}: #{svc_http.port} -> #{svc_http.targetPort}"
+puts "   - #{svc_https.name}: #{svc_https.port} -> #{svc_https.targetPort}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+#  9. COMPOSING A FULL DEPLOYMENT — tying it all together
+# ══════════════════════════════════════════════════════════════
+
+# Build typed sub-specs
+web_container = SubSpec["Container"].new {
+  self.name  = "web"
+  self.image = "nginx:1.27-alpine"
+  self.ports = [http_port.to_h]
+  self.resources.requests = { cpu: "50m",  memory: "64Mi" }
+  self.resources.limits   = { cpu: "200m", memory: "128Mi" }
+  self.volumeMounts = [config_mount.to_h, tls_mount.to_h]
+  self.livenessProbe  = http_probe.to_h
+  self.readinessProbe = http_probe.to_h
+  self.securityContext = hardened.to_h
+}
+
+sidecar = SubSpec["Container"].new {
+  self.name  = "log-shipper"
+  self.image = "fluent/fluent-bit:3.2"
+  self.resources.requests = { cpu: "25m",  memory: "32Mi" }
+  self.resources.limits   = { cpu: "100m", memory: "64Mi" }
+  self.volumeMounts = [data_mount.to_h]
+  self.securityContext = hardened.to_h
+}
+
+# Compose into a Deployment — SubSpec instances auto-coerce
+deployment = Kube::Schema["Deployment"].new {
+  metadata.name      = "web"
+  metadata.namespace = "production"
+  metadata.labels    = { app: "web", tier: "frontend" }
+
+  spec.replicas = 3
+  spec.selector.matchLabels = { app: "web" }
+  spec.strategy.type = "RollingUpdate"
+  spec.strategy.rollingUpdate = { maxSurge: 1, maxUnavailable: 0 }
+
+  spec.template.metadata.labels = { app: "web", tier: "frontend" }
+
+  # Auto-coercion: SubSpec instances become plain hashes automatically
+  spec.template.spec.containers = [web_container, sidecar]
+  spec.template.spec.volumes    = [config_volume, secret_volume, data_volume]
+
+  spec.template.spec.tolerations = [spot_toleration]
+  spec.template.spec.topologySpreadConstraints = [zone_spread]
+
+  spec.template.spec.securityContext.fsGroup    = 1000
+  spec.template.spec.securityContext.runAsGroup = 1000
+  spec.template.spec.serviceAccountName = "web"
+  spec.template.spec.terminationGracePeriodSeconds = 30
+}
+
+# Also compose a Service using typed ServicePorts
+service = Kube::Schema["Service"].new {
+  metadata.name      = "web"
+  metadata.namespace = "production"
+  metadata.labels    = { app: "web" }
+  spec.selector = { app: "web" }
+  spec.type     = "ClusterIP"
+  spec.ports    = [svc_http, svc_https]
+}
+
+puts "9. Composed resources:"
+puts "   Deployment: #{deployment.metadata[:name]} (#{deployment.spec[:replicas]} replicas)"
+puts "   - containers: #{deployment.to_h[:spec][:template][:spec][:containers].map { |c| c[:name] }.join(", ")}"
+puts "   - volumes: #{deployment.to_h[:spec][:template][:spec][:volumes].map { |v| v[:name] }.join(", ")}"
+puts "   - valid? #{deployment.valid?}"
+puts
+puts "   Service: #{service.metadata[:name]}"
+puts "   - ports: #{service.to_h[:spec][:ports].map { |p| "#{p[:name]}:#{p[:port]}" }.join(", ")}"
+puts "   - valid? #{service.valid?}"
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+# 10. VALIDATION — catching errors on sub-specs
+# ══════════════════════════════════════════════════════════════
+
+puts "10. Validation examples:"
+
+# Missing required field: Container requires "name"
+bad_container = SubSpec["Container"].new(image: "nginx")
+puts "    Container without name: valid? #{bad_container.valid?}"
+
+begin
+  bad_container.valid!
+rescue Kube::ValidationError => e
+  puts "    Error: #{e.errors.length} error(s)"
+  puts "    #{e.message.lines.grep(/required/).first&.strip}"
+end
+puts
+
+# Wrong type: ports should be an array
+bad_ports = SubSpec["Container"].new(name: "app", ports: "not-an-array")
+puts "    Container with string ports: valid? #{bad_ports.valid?}"
+puts
+
+# VolumeMount missing required fields
+bad_mount = SubSpec["VolumeMount"].new(name: "data")
+puts "    VolumeMount without mountPath: valid? #{bad_mount.valid?}"
+
+begin
+  bad_mount.valid!
+rescue Kube::ValidationError => e
+  puts "    #{e.message.lines.grep(/required/).first&.strip}"
+end
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+# 11. DISCOVERY — what sub-specs are available?
+# ══════════════════════════════════════════════════════════════
+
+instance = Kube::Schema::Instance.new("1.34")
+all_defs = instance.list_definitions
+
+puts "11. Discovery:"
+puts "    Total definitions available: #{all_defs.length}"
+puts "    Container-related:"
+all_defs.select { |d| d.include?("Container") }.each { |d| puts "      - #{d}" }
+puts "    Volume-related:"
+all_defs.select { |d| d.start_with?("Volume") }.each { |d| puts "      - #{d}" }
+puts
+
+
+# ══════════════════════════════════════════════════════════════
+# 12. YAML OUTPUT
+# ══════════════════════════════════════════════════════════════
+
+manifest = Manifest.new(deployment, service)
+
+puts "=" * 60
+puts "YAML Output:"
+puts "=" * 60
+puts manifest.to_yaml

data/lib/kube/schema/instance.rb

@@ -27,6 +27,7 @@ module Kube
 
       def initialize(version)
         @resource_classes = {}
+        @sub_spec_classes = {}
 
         unless Gem::Version.correct?(version)
           raise UnknownVersionError,
@@ -71,6 +72,39 @@ module Kube
         (gvk_index.keys + Schema.custom_schemas.keys).uniq.sort
       end
 
+      # Look up a sub-spec definition by short name (e.g. "Container",
+      # "ContainerPort", "Volume", "Probe"). Returns a class that
+      # inherits from Kube::Schema::SubSpec.
+      #
+      # Also accepts a full definition key like
+      # "io.k8s.api.core.v1.Container" for disambiguation.
+      #
+      #   instance.sub_spec("Container")     # => SubSpec subclass
+      #   instance.sub_spec("ContainerPort") # => SubSpec subclass
+      #
+      def sub_spec(name)
+        @sub_spec_classes[name] ||= begin
+          definition_key = find_definition_key(name)
+
+          if definition_key.nil?
+            raise "No definition found for #{name}!" \
+              "\nUse #list_definitions to see available definitions for v#{version}."
+          end
+
+          ref_schema = schemer.ref("#/definitions/#{definition_key}")
+          build_sub_spec_class(ref_schema, name)
+        end
+      end
+
+      # All available definition short names for this version.
+      #
+      # @return [Array<String>] sorted, deduplicated short names
+      def list_definitions
+        schemer.value.fetch("definitions", {}).keys
+          .map { |k| k.split(".").last }
+          .uniq.sort
+      end
+
       private
 
         # The JSONSchemer instance for this version's Swagger document.
@@ -214,6 +248,62 @@ module Kube
           end
         end
 
+        # Resolve a short name like "Container" to its full definition key
+        # "io.k8s.api.core.v1.Container".
+        #
+        # Strategy:
+        #   1. Exact match on full key (for power users)
+        #   2. Short-name match on last segment
+        #   3. Prefer stable API versions (v1 > v1beta1 > v1alpha1)
+        def find_definition_key(name)
+          definitions = schemer.value.fetch("definitions", {})
+
+          # Exact full-key match
+          return name if definitions.key?(name)
+
+          # Short-name matches (last segment after final ".")
+          candidates = definitions.keys.select { |k| k.split(".").last == name }
+          return nil if candidates.empty?
+          return candidates.first if candidates.size == 1
+
+          # Disambiguation: prefer stable versions, then beta, then alpha
+          candidates.min_by { |k|
+            version_segment = k.split(".")[-2].to_s
+            case version_segment
+            when /\Av\d+\z/ then [0, version_segment]
+            when /beta/      then [1, version_segment]
+            when /alpha/     then [2, version_segment]
+            else                  [3, version_segment]
+            end
+          }
+        end
+
+        # Build a SubSpec subclass from a JSONSchemer instance and a
+        # human-readable definition name (for error messages).
+        def build_sub_spec_class(schema_instance, definition_name)
+          Class.new(::Kube::Schema::SubSpec) do
+            @schema = schema_instance
+            @definition_name = definition_name
+            @schema_properties = @schema.value.fetch("properties", {}).keys.map(&:to_sym)
+
+            def self.schema
+              @schema || superclass.schema
+            end
+
+            def self.definition_name
+              @definition_name
+            end
+
+            def self.schema_properties
+              @schema_properties
+            end
+
+            schema_instance.value.fetch("properties", {}).keys.each do |prop|
+              define_method(prop.to_sym) { @data[prop.to_sym] }
+            end
+          end
+        end
+
         # Called by Kube::Schema.register and reset_custom_schemas! to
         # invalidate cached resource classes so new registrations take effect.
         def clear_resource_cache!

data/lib/kube/schema/resource.rb

@@ -105,6 +105,8 @@ module Kube
 
         def deep_compact(obj)
           case obj
+          when Kube::Schema::SubSpec
+            deep_compact(obj.to_h)
           when Hash
             obj.each_with_object({}) do |(k, v), result|
               compacted = deep_compact(v)

data/lib/kube/schema/sub_spec.rb

@@ -0,0 +1,485 @@
+# frozen_string_literal: true
+
+module Kube
+  module Schema
+    # A lightweight, schema-validated wrapper for non-resource Kubernetes
+    # definitions — things like Container, ContainerPort, Volume, Probe,
+    # etc. that live inside resource specs but have no apiVersion/kind.
+    #
+    # SubSpec validates against the OpenAPI JSON Schema definition and
+    # produces a plain Hash via #to_h, suitable for embedding directly
+    # inside Resource specs.
+    #
+    #   container = Kube::Schema::SubSpec["Container"].new {
+    #     name = "app"
+    #     image = "nginx:1.27"
+    #     ports = [{ containerPort: 80 }]
+    #   }
+    #
+    #   container.valid?  # => true
+    #   container.to_h    # => { name: "app", image: "nginx:1.27", ... }
+    #
+    # SubSpec instances auto-coerce when placed inside a Resource —
+    # no explicit .to_h is needed:
+    #
+    #   spec.template.spec.containers = [container]
+    #
+    class SubSpec
+
+      def initialize(hash = {}, &block)
+        deep_symbolize_keys(hash).then do |symbolized|
+          @data = {}
+
+          self.class.schema_properties.each do |property|
+            if symbolized.key?(property)
+              @data[property] = symbolized.delete(property)
+            end
+          end
+        end
+
+        if block_given?
+          @data.instance_exec(&block)
+        end
+      end
+
+      # Gets overridden by the factory in Kube::Schema::Instance
+      def self.schema
+        raise "Kube::Schema::SubSpec should NOT be instantiated directly"
+      end
+
+      def self.schema_properties
+        raise "Kube::Schema::SubSpec should NOT be instantiated directly"
+      end
+
+      def self.definition_name
+        raise "Kube::Schema::SubSpec should NOT be instantiated directly"
+      end
+
+      def valid?
+        if self.class.schema.nil?
+          true
+        else
+          self.class.schema.valid?(deep_stringify_keys(to_h))
+        end
+      end
+
+      # Like #valid? but raises Kube::ValidationError with details on failure.
+      def valid!
+        if self.class.schema.nil?
+          true
+        else
+          data = deep_stringify_keys(to_h)
+          errors = self.class.schema.validate(data).to_a
+
+          unless errors.empty?
+            raise Kube::ValidationError.new(errors,
+              kind: self.class.definition_name,
+              manifest: data
+            )
+          end
+
+          true
+        end
+      end
+
+      # Returns the sub-spec data as a plain Hash.
+      def to_h
+        data = deep_compact(@data)
+        data.reject { |_, v| v.is_a?(Hash) && v.empty? }
+      end
+
+      def ==(other)
+        other.is_a?(SubSpec) && to_h == other.to_h
+      end
+
+      # Look up a sub-spec definition by short name.
+      #
+      #   Kube::Schema::SubSpec["Container"]
+      #   Kube::Schema::SubSpec["ContainerPort"]
+      #   Kube::Schema::SubSpec["Volume"]
+      #
+      class << self
+        def [](name)
+          version = Schema.schema_version || Schema::DEFAULT_VERSION
+          instance = Schema[version]
+          instance.sub_spec(name)
+        end
+      end
+
+      private
+
+        def deep_compact(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), result|
+              compacted = deep_compact(v)
+              result[k] = compacted unless compacted.nil?
+            end
+          when Array
+            obj.map { |v| deep_compact(v) }
+          else
+            obj
+          end
+        end
+
+        def deep_stringify_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), result|
+              result[k.to_s] = deep_stringify_keys(v)
+            end
+          when Array
+            obj.map { |v| deep_stringify_keys(v) }
+          else
+            obj
+          end
+        end
+
+        def deep_symbolize_keys(obj)
+          case obj
+          when Hash
+            obj.each_with_object({}) do |(k, v), result|
+              result[k.to_sym] = deep_symbolize_keys(v)
+            end
+          when Array
+            obj.map { |v| deep_symbolize_keys(v) }
+          else
+            obj
+          end
+        end
+    end
+  end
+end
+
+if __FILE__ == $0
+  require "bundler/setup"
+  require "rspec/autorun"
+  require "kube/schema"
+
+  RSpec.describe Kube::Schema::SubSpec do
+    describe ".[]" do
+      it "returns a Class that subclasses SubSpec" do
+        klass = described_class["Container"]
+        expect(klass).to be_a(Class)
+        expect(klass).to be < described_class
+      end
+
+      it "caches sub-spec classes by name" do
+        a = described_class["Container"]
+        b = described_class["Container"]
+        expect(a).to be(b)
+      end
+
+      it "resolves ContainerPort" do
+        klass = described_class["ContainerPort"]
+        expect(klass).to be < described_class
+      end
+
+      it "resolves Probe" do
+        klass = described_class["Probe"]
+        expect(klass).to be < described_class
+      end
+
+      it "resolves Volume" do
+        klass = described_class["Volume"]
+        expect(klass).to be < described_class
+      end
+
+      it "resolves EnvVar" do
+        klass = described_class["EnvVar"]
+        expect(klass).to be < described_class
+      end
+
+      it "resolves ResourceRequirements" do
+        klass = described_class["ResourceRequirements"]
+        expect(klass).to be < described_class
+      end
+
+      it "resolves a full definition key" do
+        klass = described_class["io.k8s.api.core.v1.Container"]
+        expect(klass).to be < described_class
+      end
+
+      it "raises for an unknown definition" do
+        expect { described_class["ThisDoesNotExist999"] }.to raise_error(RuntimeError, /No definition found/)
+      end
+    end
+
+    describe ".definition_name" do
+      it "returns the short name used to look up the sub-spec" do
+        klass = described_class["Container"]
+        expect(klass.definition_name).to eq("Container")
+      end
+    end
+
+    describe ".schema" do
+      it "has a schema attached" do
+        klass = described_class["Container"]
+        expect(klass.schema).not_to be_nil
+      end
+    end
+
+    describe ".schema_properties" do
+      it "lists known properties as symbols" do
+        klass = described_class["Container"]
+        props = klass.schema_properties
+        expect(props).to include(:name, :image, :ports, :env, :resources)
+      end
+    end
+
+    describe "#initialize" do
+      let(:klass) { described_class["Container"] }
+
+      it "accepts a hash" do
+        sub = klass.new(name: "app", image: "nginx")
+        expect(sub.to_h).to include(name: "app", image: "nginx")
+      end
+
+      it "accepts string keys" do
+        sub = klass.new("name" => "app", "image" => "nginx")
+        expect(sub.to_h).to include(name: "app", image: "nginx")
+      end
+
+      it "creates an empty sub-spec when no arguments are given" do
+        sub = klass.new
+        expect(sub.to_h).to eq({})
+      end
+
+      it "accepts a block for DSL-style initialization" do
+        sub = klass.new {
+          self.name = "app"
+          self.image = "nginx:1.27"
+        }
+        expect(sub.to_h).to include(name: "app", image: "nginx:1.27")
+      end
+
+      it "supports nested DSL" do
+        sub = klass.new {
+          self.name = "app"
+          self.image = "nginx"
+          self.resources.requests = { cpu: "100m", memory: "128Mi" }
+          self.resources.limits = { cpu: "500m", memory: "256Mi" }
+        }
+        expect(sub.to_h[:resources][:requests]).to eq({ cpu: "100m", memory: "128Mi" })
+      end
+
+      it "ignores unknown properties" do
+        sub = klass.new(name: "app", bogus_field: "ignored")
+        expect(sub.to_h).to eq({ name: "app" })
+      end
+    end
+
+    describe "accessor methods" do
+      let(:klass) { described_class["Container"] }
+
+      it "defines reader methods for schema properties" do
+        sub = klass.new(name: "app", image: "nginx")
+        expect(sub.name).to eq("app")
+        expect(sub.image).to eq("nginx")
+      end
+
+      it "returns nil for unset properties" do
+        sub = klass.new(name: "app")
+        expect(sub.image).to be_nil
+      end
+    end
+
+    describe "#valid?" do
+      let(:klass) { described_class["Container"] }
+
+      it "returns true for valid data" do
+        sub = klass.new(name: "app", image: "nginx")
+        expect(sub.valid?).to be true
+      end
+
+      it "returns false for data violating the schema" do
+        sub = klass.new(name: "app", ports: "not_an_array")
+        expect(sub.valid?).to be false
+      end
+
+      it "returns false when required fields are missing" do
+        # Container requires 'name'
+        sub = klass.new(image: "nginx")
+        expect(sub.valid?).to be false
+      end
+    end
+
+    describe "#valid!" do
+      let(:klass) { described_class["Container"] }
+
+      it "returns true for valid data" do
+        sub = klass.new(name: "app")
+        expect(sub.valid!).to be true
+      end
+
+      it "raises ValidationError for invalid data" do
+        sub = klass.new(image: "nginx")
+        expect { sub.valid! }.to raise_error(Kube::ValidationError)
+      end
+
+      it "includes the definition name in the error" do
+        sub = klass.new(image: "nginx")
+        expect { sub.valid! }.to raise_error(Kube::ValidationError, /Container/)
+      end
+
+      it "shows which required keys are missing" do
+        sub = klass.new(image: "nginx")
+        expect { sub.valid! }.to raise_error(Kube::ValidationError) do |error|
+          expect(error.message).to include("name is required but missing")
+        end
+      end
+    end
+
+    describe "#to_h" do
+      let(:klass) { described_class["Container"] }
+
+      it "returns a plain Hash" do
+        sub = klass.new(name: "app", image: "nginx")
+        h = sub.to_h
+        expect(h).to be_a(Hash)
+        expect(h).to eq({ name: "app", image: "nginx" })
+      end
+
+      it "strips empty sub-hashes" do
+        sub = klass.new(name: "app")
+        expect(sub.to_h).to eq({ name: "app" })
+      end
+
+      it "does NOT include apiVersion or kind" do
+        sub = klass.new(name: "app")
+        expect(sub.to_h).not_to have_key(:apiVersion)
+        expect(sub.to_h).not_to have_key(:kind)
+      end
+
+      it "preserves nested structure" do
+        sub = klass.new {
+          self.name = "app"
+          self.image = "nginx"
+          self.ports = [{ containerPort: 80 }]
+        }
+        expect(sub.to_h[:ports]).to eq([{ containerPort: 80 }])
+      end
+    end
+
+    describe "#==" do
+      let(:klass) { described_class["Container"] }
+
+      it "considers two sub-specs equal when their data matches" do
+        a = klass.new(name: "app", image: "nginx")
+        b = klass.new(name: "app", image: "nginx")
+        expect(a).to eq(b)
+      end
+
+      it "considers two sub-specs unequal when their data differs" do
+        a = klass.new(name: "app", image: "nginx")
+        b = klass.new(name: "other", image: "nginx")
+        expect(a).not_to eq(b)
+      end
+
+      it "is not equal to a plain Hash" do
+        sub = klass.new(name: "app")
+        expect(sub).not_to eq({ name: "app" })
+      end
+    end
+
+    describe "auto-coercion in Resource" do
+      it "auto-coerces SubSpec instances inside Resource arrays" do
+        container = described_class["Container"].new {
+          self.name = "app"
+          self.image = "nginx:1.27"
+          self.ports = [{ containerPort: 80 }]
+        }
+
+        deploy = Kube::Schema["Deployment"].new {
+          metadata.name = "web"
+          spec.replicas = 1
+          spec.selector.matchLabels = { app: "web" }
+          spec.template.metadata.labels = { app: "web" }
+          spec.template.spec.containers = [container]
+        }
+
+        h = deploy.to_h
+        containers = h[:spec][:template][:spec][:containers]
+        expect(containers).to be_an(Array)
+        expect(containers.first).to be_a(Hash)
+        expect(containers.first[:name]).to eq("app")
+        expect(containers.first[:image]).to eq("nginx:1.27")
+      end
+
+      it "produces valid YAML with auto-coerced SubSpec" do
+        container = described_class["Container"].new {
+          self.name = "nginx"
+          self.image = "nginx:1.27"
+          self.ports = [{ containerPort: 80 }]
+        }
+
+        deploy = Kube::Schema["Deployment"].new {
+          metadata.name = "web"
+          spec.replicas = 1
+          spec.selector.matchLabels = { app: "web" }
+          spec.template.metadata.labels = { app: "web" }
+          spec.template.spec.containers = [container]
+        }
+
+        yaml = deploy.to_yaml
+        parsed = YAML.safe_load(yaml)
+        expect(parsed["spec"]["template"]["spec"]["containers"].first["name"]).to eq("nginx")
+      end
+
+      it "handles multiple SubSpec instances in an array" do
+        app = described_class["Container"].new(name: "app", image: "app:latest")
+        sidecar = described_class["Container"].new(name: "sidecar", image: "sidecar:latest")
+
+        deploy = Kube::Schema["Deployment"].new {
+          metadata.name = "web"
+          spec.replicas = 1
+          spec.selector.matchLabels = { app: "web" }
+          spec.template.metadata.labels = { app: "web" }
+          spec.template.spec.containers = [app, sidecar]
+        }
+
+        containers = deploy.to_h[:spec][:template][:spec][:containers]
+        expect(containers.size).to eq(2)
+        expect(containers.map { |c| c[:name] }).to eq(["app", "sidecar"])
+      end
+
+      it "works mixed with plain hashes" do
+        container = described_class["Container"].new(name: "typed", image: "typed:latest")
+
+        deploy = Kube::Schema["Deployment"].new {
+          metadata.name = "web"
+          spec.replicas = 1
+          spec.selector.matchLabels = { app: "web" }
+          spec.template.metadata.labels = { app: "web" }
+          spec.template.spec.containers = [
+            container,
+            { name: "plain", image: "plain:latest" }
+          ]
+        }
+
+        containers = deploy.to_h[:spec][:template][:spec][:containers]
+        expect(containers.map { |c| c[:name] }).to eq(["typed", "plain"])
+      end
+    end
+
+    describe "disambiguation" do
+      it "prefers stable API versions over beta/alpha" do
+        # MatchCondition exists in v1, v1alpha1, and v1beta1
+        klass = described_class["MatchCondition"]
+        expect(klass).to be < described_class
+        expect(klass.schema).not_to be_nil
+      end
+    end
+
+    describe "Instance#list_definitions" do
+      it "returns a sorted array of short definition names" do
+        instance = Kube::Schema::Instance.new("1.34")
+        defs = instance.list_definitions
+        expect(defs).to be_an(Array)
+        expect(defs).not_to be_empty
+        expect(defs).to include("Container", "ContainerPort", "Probe", "Volume")
+        expect(defs).to eq(defs.sort)
+      end
+    end
+  end
+end

data/lib/kube/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Schema
-    VERSION = "1.3.10"
+    VERSION = "1.4.0"
   end
 end

data/lib/kube/schema.rb

@@ -4,6 +4,7 @@ require_relative 'monkey_patches'
 require_relative 'errors'
 require_relative 'schema/version'
 require_relative 'schema/resource'
+require_relative 'schema/sub_spec'
 require_relative 'schema/instance'
 require_relative 'schema/manifest'
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kube_schema
 version: !ruby/object:Gem::Version
-  version: 1.3.10
+  version: 1.4.0
 platform: ruby
 authors:
 - Nathan K
@@ -113,6 +113,7 @@ files:
 - examples/basic.rb
 - examples/custom_crds.rb
 - examples/manifest.rb
+- examples/sub_specs.rb
 - examples/vcluster.rb
 - flake.lock
 - flake.nix
@@ -123,6 +124,7 @@ files:
 - lib/kube/schema/instance.rb
 - lib/kube/schema/manifest.rb
 - lib/kube/schema/resource.rb
+- lib/kube/schema/sub_spec.rb
 - lib/kube/schema/version.rb
 - lib/kube/schema/version.rb.erb
 - schemas/crd-definitions.json