kube_schema 1.3.1 → 1.3.4

data/lib/kube/schema/instance.rb

@@ -39,44 +39,47 @@ module Kube
 
       # Look up a resource by kind (e.g. "Deployment", "NetworkPolicy").
       # Returns a class that inherits from Kube::Schema::Resource.
+      #
+      # Custom schemas registered via Kube::Schema.register take precedence
+      # over built-in definitions, allowing users to override or extend the
+      # schema for any kind.
       def [](kind)
         @resource_classes[kind] ||= begin
-          entry = find_gvk_entry(kind)
-
-          if entry.nil?
-            raise "No resource schema found for #{kind}!" \
-              "\nUse #list_resources to see available kinds for v#{version}."
-          end
-
-          ref_schema = schemer.ref("#/definitions/#{entry[:definition_key]}")
-          defaults = entry[:defaults].freeze
-
-          Class.new(::Kube::Schema::Resource) do
-            @schema = ref_schema
-            @defaults = defaults
-
-            def self.schema
-              @schema || superclass.schema
+          # Custom schemas win over built-in definitions.
+          custom = find_custom_entry(kind)
+          if custom
+            build_resource_class(custom[:schema], custom[:defaults])
+          else
+            entry = find_gvk_entry(kind)
+
+            if entry.nil?
+              raise "No resource schema found for #{kind}!" \
+                "\nUse #list_resources to see available kinds for v#{version}."
             end
 
-            def self.defaults
-              @defaults || superclass.defaults
-            end
+            ref_schema = schemer.ref("#/definitions/#{entry[:definition_key]}")
+            build_resource_class(ref_schema, entry[:defaults].freeze)
           end
         end
       end
 
-      # All available resource kinds for this version.
+      # All available resource kinds for this version, including any
+      # custom schemas registered via Kube::Schema.register.
       #
       # @return [Array<String>] sorted kind names
       def list_resources
-        gvk_index.keys.sort
+        (gvk_index.keys + Schema.custom_schemas.keys).uniq.sort
       end
 
       private
 
         # The JSONSchemer instance for this version's Swagger document.
         # Cached at the class level so it's built once per version.
+        #
+        # After loading the base Swagger JSON, merges in any extra definition
+        # files found in the schemas directory (e.g. crd-definitions.json,
+        # loft-definitions.json). These files are flat JSON objects where keys
+        # are definition names and values are OpenAPI v2 schema objects.
         def schemer
           self.class.schemers[@version] ||= begin
             path = File.join(SCHEMAS_DIR, "v#{version}.json")
@@ -87,7 +90,26 @@ module Kube
                 "\nUse `Kube::Schema.schema_versions` to get a list."
             end
 
-            JSONSchemer.schema(JSON.parse(File.read(path)))
+            schema = JSON.parse(File.read(path))
+
+            # Merge extra definition files (*-definitions.json) into the
+            # base schema so CRD and aggregated-API types (e.g. loft,
+            # gateway-api) are available alongside built-in k8s types.
+            Dir.glob(File.join(SCHEMAS_DIR, "*-definitions.json")).each do |defs_path|
+              extra = JSON.parse(File.read(defs_path))
+              schema["definitions"] ||= {}
+              schema["definitions"].merge!(extra)
+            end
+
+            # Kubernetes OpenAPI v2 defines IntOrString as "type": "string"
+            # with "format": "int-or-string". This is a limitation of
+            # OpenAPI v2 which cannot express union types. Patch the
+            # definition so JSONSchemer accepts both integers and strings.
+            if (int_or_str = schema.dig("definitions", "io.k8s.apimachinery.pkg.util.intstr.IntOrString"))
+              int_or_str["type"] = ["string", "integer"]
+            end
+
+            JSONSchemer.schema(schema)
           end
         end
 
@@ -151,6 +173,52 @@ module Kube
 
           nil
         end
+
+        # Find a custom schema entry by kind (case-insensitive).
+        # Returns the { schema:, defaults: } hash or nil.
+        def find_custom_entry(kind)
+          registry = Schema.custom_schemas
+          return registry[kind] if registry.key?(kind)
+
+          registry.each do |k, v|
+            return v if k.downcase == kind.downcase
+          end
+
+          nil
+        end
+
+        # Build a Resource subclass from a JSONSchemer instance and defaults hash.
+        def build_resource_class(schema_instance, defaults)
+          Class.new(::Kube::Schema::Resource) do
+            @schema = schema_instance
+            @defaults = defaults
+            @schema_properties = @schema.value["properties"].keys.map(&:to_sym)
+
+            def self.schema
+              @schema || superclass.schema
+            end
+
+            def self.defaults
+              @defaults || superclass.defaults
+            end
+
+            def self.schema_properties
+              @schema_properties
+            end
+
+            schema_instance.value["properties"].keys.then do |properties|
+              properties.each do |prop|
+                define_method(prop.to_sym) { @data[prop.to_sym] }
+              end
+            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!
+          @resource_classes.clear
+        end
     end
   end
 end

data/lib/kube/schema/manifest.rb

@@ -90,8 +90,32 @@ module Kube
       # File I/O
       # -------------------------------------------------------------------
 
+      # Parse a YAML string containing one or more Kubernetes resource
+      # documents and return a Manifest populated with typed Resource objects.
+      #
+      # Each document's "kind" is resolved via Kube::Schema.parse to
+      # produce the correct Resource subclass (e.g. Deployment, Service).
+      # Documents without a recognized "kind" fall back to a bare Resource.
+      #
+      #   yaml = `helm template my-release bitnami/nginx`
+      #   manifest = Kube::Schema::Manifest.parse(yaml)
+      #   manifest.first.class  #=> Kube::Schema::Resource (Deployment subclass)
+      #
+      # @param yaml_string [String] multi-document YAML
+      # @return [Manifest]
+      def self.parse(yaml_string)
+        docs = if YAML.respond_to?(:safe_load_stream)
+                 YAML.safe_load_stream(yaml_string, permitted_classes: [Symbol])
+               else
+                 YAML.load_stream(yaml_string)
+               end
+
+        resources = docs.compact.map { |doc| parse_doc(doc) }
+        new(*resources)
+      end
+
       # Read a YAML file containing one or more Kubernetes resource documents
-      # and return a Manifest populated with Resource objects.
+      # and return a Manifest populated with typed Resource objects.
       #
       #   manifest = Kube::Schema::Manifest.open("deploy.yaml")
       #   manifest.count  #=> 3
@@ -108,7 +132,7 @@ module Kube
                  YAML.load_stream(contents)
                end
 
-        resources = docs.compact.map { |doc| Resource.new(doc) }
+        resources = docs.compact.map { |doc| parse_doc(doc) }
         new(*resources, filename: path)
       end
 
@@ -127,6 +151,16 @@ module Kube
         path
       end
 
+      # Parse a single YAML document hash into a typed Resource.
+      #
+      # @param doc [Hash] a parsed YAML document
+      # @return [Resource]
+      # @raise [RuntimeError] if the kind is not recognized
+      def self.parse_doc(doc)
+        Kube::Schema.parse(doc)
+      end
+      private_class_method :parse_doc
+
       private
 
         # Deep-stringify keys for clean YAML output.

data/lib/kube/schema/resource.rb

@@ -11,12 +11,16 @@ module Kube
           # Therefore, they are ONLY ever set from the self.defaults
           # property.
           deep_symbolize_keys(hash).then do |symbolized|
-            config = defaults.merge({
-              metadata: symbolized.delete(:metadata) || {},
-              spec: symbolized.delete(:spec) || {},
-            })
-
-            @data = config
+            @data = defaults
+
+            # This is extracting "top-level" properties from the input hash
+            # such as [apiVersion, spec, metadata, roleRef, ...]
+            # We then ignore the rest of the attributes by design.
+            self.class.schema_properties.each do |property|
+              if symbolized.key?(property)
+                @data[property] = symbolized.delete(property)
+              end
+            end
           end
         end
 
@@ -25,17 +29,20 @@ module Kube
         end
       end
 
-      def apiVersion = @data.apiVersion
-      def kind       = @data.kind
-      def spec       = @data.spec
-      def metadata   = @data.metadata
-
       # Gets overridden by the factory in Kube::Schema::Instance
-      def self.schema = nil
+      def self.schema
+        raise "Kube::Schema::Resource should NOT be instanciated directly"
+      end
+
+      def self.schema_properties
+        raise "Kube::Schema::Resource should NOT be instanciated directly"
+      end
 
       # Gets overridden by the factory in Kube::Schema::Instance.
       # Returns a frozen Hash like { "apiVersion" => "apps/v1", "kind" => "Deployment" }
-      def self.defaults = nil
+      def self.defaults
+        raise "Kube::Schema::Resource should NOT be instanciated directly"
+      end
 
       def valid?
         if self.class.schema.nil?
@@ -69,7 +76,8 @@ module Kube
       # they are facts derived from the GVK metadata.
       def to_h
         defaults = self.class.defaults
-        data = @data.reject { |_, v| v.is_a?(Hash) && v.empty? }
+        data = deep_compact(@data)
+        data = data.reject { |_, v| v.is_a?(Hash) && v.empty? }
 
         if defaults
           symbolized = deep_symbolize_keys(defaults)
@@ -95,6 +103,20 @@ module Kube
 
       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

data/lib/kube/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Schema
-    VERSION = "1.3.1"
+    VERSION = "1.3.4"
   end
 end

data/lib/kube/schema.rb

@@ -16,6 +16,7 @@ module Kube
 
     @schema_version = nil
     @instances = {}
+    @custom_schemas = {}
 
     GEM_ROOT = File.expand_path("../..", __dir__).freeze
     SCHEMAS_DIR = File.join(GEM_ROOT, "schemas").freeze
@@ -26,6 +27,71 @@ module Kube
       # When nil, the DEFAULT_VERSION is used.
       attr_accessor :schema_version
 
+      # Custom schemas registered via Kube::Schema.register.
+      # Keys are kind strings, values are { schema:, defaults: } hashes.
+      attr_reader :custom_schemas
+
+      # Register a standalone JSON Schema for a custom resource kind.
+      #
+      # This lets users add CRD schemas from any source — for example,
+      # the datreeio/CRDs-catalog, operator repos, or their own CRDs.
+      # Registered kinds take precedence over built-in definitions.
+      #
+      # @param kind [String] The Kubernetes Kind (e.g. "Certificate")
+      # @param schema [Hash, String, Pathname] JSON Schema as a Hash,
+      #   a JSON string, or a file path to a .json file
+      # @param api_version [String] The apiVersion (e.g. "cert-manager.io/v1")
+      #
+      # @example Register from a local file
+      #   Kube::Schema.register("Certificate",
+      #     schema: "schemas/cert-manager.io/certificate_v1.json",
+      #     api_version: "cert-manager.io/v1"
+      #   )
+      #
+      # @example Register from Chart#crds
+      #   chart.crds.each do |crd|
+      #     s = crd.to_json_schema
+      #     Kube::Schema.register(s[:kind], schema: s[:schema], api_version: s[:api_version])
+      #   end
+      #
+      def register(kind, schema:, api_version:)
+        require "json"
+        require "json_schemer"
+
+        parsed = case schema
+          when Hash
+            schema
+          when String, Pathname
+            path = schema.to_s
+            if File.exist?(path)
+              JSON.parse(File.read(path))
+            else
+              JSON.parse(path)
+            end
+          else
+            raise ArgumentError,
+              "schema must be a Hash, a JSON string, or a file path — got #{schema.class}"
+          end
+
+        @custom_schemas[kind] = {
+          schema: JSONSchemer.schema(parsed),
+          defaults: { "apiVersion" => api_version, "kind" => kind }.freeze
+        }
+
+        # Invalidate cached resource classes on all instances so the
+        # new registration takes effect immediately.
+        @instances.each_value { |inst| inst.send(:clear_resource_cache!) }
+
+        kind
+      end
+
+      # Remove all custom schema registrations.
+      # Useful for test teardown or resetting state.
+      def reset_custom_schemas!
+        @custom_schemas.clear
+        @instances.each_value { |inst| inst.send(:clear_resource_cache!) }
+      end
+
       # Kube::Schema["1.34"]           => cached Instance (supports ["Deployment"] chaining)
       # Kube::Schema["Deployment"]     => Resource via the default version
       def [](key)
@@ -51,10 +117,26 @@ module Kube
         end
       end
 
-      # Build a Resource from a hash.
-      #   Kube::Schema.parse(Kube::Schema["Deployment"].to_h) == Kube::Schema["Deployment"]
+      # Build a typed Resource from a raw hash.
+      #
+      # Looks up the "kind" key in the hash and resolves it to the
+      # correct Resource subclass via the schema registry. The hash
+      # may use string or symbol keys.
+      #
+      #   Kube::Schema.parse("kind" => "Deployment", "apiVersion" => "apps/v1")
+      #   Kube::Schema.parse(kind: "Pod", apiVersion: "v1", metadata: { name: "web" })
+      #
+      # @param hash [Hash] a Kubernetes resource hash with at least a "kind" key
+      # @return [Resource] a schema-validated Resource instance
+      # @raise [ArgumentError] if the hash is nil, not a Hash, or missing "kind"
       def parse(hash)
-        raise NotImplementedError
+        raise ArgumentError, "Expected a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+        kind = hash["kind"] || hash[:kind]
+        raise ArgumentError, "Hash must contain a \"kind\" key" if kind.nil?
+
+        resource_class = self[kind]
+        resource_class.new(hash)
       end
 
       # Available Kubernetes versions, read from the local schemas directory.