kube_schema 1.2.1 → 1.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7644c3e6649df4772ab947bafb8987c14a77fff9e473ffcd860391b6cb48387
-  data.tar.gz: 660f1b1e495bb5f677768c8ed3b312d5af50776bcc9ef1f627d7e29ba7a22e32
+  metadata.gz: d4d0fd333c3834e4593b60c9c57ada0fa0fd275175f55ffcfcc0616cd64fef1d
+  data.tar.gz: c427e577b4d92bc9241c21da35ae7f863f9ac0c1e354696a31e5292c8f818089
 SHA512:
-  metadata.gz: 07f0a77370aeee2cc79d603b64b75f403baff2054f982d6aec1ef1ebfc3f9b3b5a8b863d2d9686fddf8ac5b0fadf236d1be409ba5579df8130d955eace09dc8f
-  data.tar.gz: 905dad3ab418d1d3e6d311f4719484c2056948ecab18020b82676df8b5eea3aaaf584298e9c49e0b98126c355ff24f79fefac0a322a4c0f5892b8fb100035c4b
+  metadata.gz: 752d0e5bae651ce4734e46ac9a886f06253dacd5193861729509c92e39bdfca81a543ad3267440b1499725147466783e1aca904312a1184e9c6ce77d311d1282
+  data.tar.gz: 893b866464d3f4f8565d7e73c840c1f2cfaf4421dcfeeb867374a606d1b7b34b89118a4ccecbba47f58c767f33c4d2969deaa427b4ad3e38117f987c8af76db7

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kube_schema (1.1.1)
+    kube_schema (1.2.1)
       black_hole_struct (~> 0.1)
       json_schemer (~> 2.5)
       rubyshell (~> 1.5)
@@ -10,7 +10,7 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
-    bigdecimal (4.1.1)
+    bigdecimal (4.1.2)
     black_hole_struct (0.1.3)
     diff-lcs (1.6.2)
     hana (1.3.7)

data/README.md

@@ -1,36 +1,259 @@
-# Kube::Schema
+# kube_schema
 
-Ruby objects for Kubernetes OpenAPI schemas.
+Ruby objects for every Kubernetes resource. Validated against the real OpenAPI spec.
 
-## Installation
+```ruby
+Kube::Schema["Deployment"].new {
+  metadata.name = "web"
+  metadata.namespace = "prod"
+  spec.replicas = 3
+  spec.template.spec.containers = [
+    { name: "app", image: "nginx:1.27", ports: [{ containerPort: 80 }] }
+  ]
+}
+```
+
+No YAML. No hash literals. Just Ruby blocks that know their schema.
+
+## Contents
+
+- [Install](#install)
+- [Resources](#resources)
+- [The block DSL](#the-block-dsl)
+- [Subclassing](#subclassing)
+- [Validation](#validation)
+- [Error messages](#error-messages)
+- [Manifests](#manifests)
+  - [File I/O](#file-io)
+  - [Composition](#composition)
+  - [Enumerable](#enumerable)
+- [Schema versions](#schema-versions)
+- [Related projects](#related-projects)
+- [Built with](#built-with)
+
+## Install
+
+```
+gem install kube_schema
+```
+
+## Resources
+
+Every Kubernetes kind is a class. Fetch it by name.
 
 ```ruby
-gem "kube_schema"
+Kube::Schema["Deployment"]     # => Class < Kube::Schema::Resource
+Kube::Schema["Service"]
+Kube::Schema["ConfigMap"]
+Kube::Schema["NetworkPolicy"]
 ```
 
-## Usage
+Specific versions:
 
 ```ruby
-Deployment = Kube::Schema["1.33.6"]["Deployment"]
+Kube::Schema["1.34"]["Deployment"]
+Kube::Schema["1.31"]["Pod"]
+```
 
-app = Deployment.new do
-  self.description = "My app"
-  self.type = "custom"
-end
+Discovery:
+
+```ruby
+Kube::Schema.schema_versions    # => ["1.19", "1.20", ..., "1.35"]
+Kube::Schema.latest_version     # => "1.35"
+
+Kube::Schema["1.34"].list_resources
+# => ["Binding", "CSIDriver", "ConfigMap", "Deployment", ...]
+```
+
+## The block DSL
+
+Nested attributes just work. No intermediate hashes, no string keys.
+
+```ruby
+deploy = Kube::Schema["Deployment"].new {
+  metadata.name = "web"
+  metadata.namespace = "prod"
+  metadata.labels = { app: "web" }
+
+  spec.replicas = 3
+  spec.selector.matchLabels = { app: "web" }
+
+  spec.template.metadata.labels = { app: "web" }
+  spec.template.spec.containers = [
+    { name: "app", image: "nginx:1.27", ports: [{ containerPort: 80 }] }
+  ]
+}
+```
+
+`apiVersion` and `kind` are derived from the schema automatically:
 
-app.description   # => "My app"
-app.type          # => "custom"
-app.properties    # => {"apiVersion" => ..., "kind" => ..., ...}
+```ruby
+deploy.to_h[:apiVersion]  # => "apps/v1"
+deploy.to_h[:kind]        # => "Deployment"
 ```
 
+## Subclassing
+
 ```ruby
-class RailsApp < Kube::Schema["1.33.6"]["Deployment"]
-  def is_the_best?
-    true
+class RailsApp < Kube::Schema["Deployment"]
+  def default_image
+    "ruby:3.4"
   end
 end
 
-app = RailsApp.new
-app.is_the_best?  # => true
-app.description   # => "Deployment enables declarative updates for Pods and ReplicaSets."
+app = RailsApp.new {
+  metadata.name = "rails"
+  spec.template.spec.containers = [
+    { name: "web", image: "myapp:latest" }
+  ]
+}
+
+app.default_image  # => "ruby:3.4"
+app.valid?         # => true
+```
+
+## Validation
+
+Every resource validates against the full Kubernetes OpenAPI spec.
+
+```ruby
+deploy.valid?   # => true
+
+bad = Kube::Schema["Deployment"].new {
+  self.apiVersion = 12345
+}
+
+bad.valid?   # => false
+
+bad.valid!
+# Kube::ValidationError: Schema validation failed for Deployment:
+#   - apiVersion = 12345 — expected string, got Integer
+```
+
+`to_yaml` refuses to serialize invalid resources:
+
+```ruby
+bad.to_yaml  # raises Kube::ValidationError
 ```
+
+## Error messages
+
+Validation errors render annotated YAML with color-coded diagnostics. Error lines are highlighted in red, missing required keys are injected inline, and each problem gets a clear explanation:
+
+![Validation error output](assets/validation-error.png)
+
+## Manifests
+
+Group resources into multi-document YAML.
+
+```ruby
+manifest = Kube::Schema::Manifest.new
+
+manifest << Kube::Schema["Namespace"].new {
+  metadata.name = "prod"
+}
+
+manifest << Kube::Schema["Deployment"].new {
+  metadata.name = "web"
+  metadata.namespace = "prod"
+  spec.replicas = 3
+  spec.template.spec.containers = [
+    { name: "app", image: "nginx:1.27" }
+  ]
+}
+
+manifest << Kube::Schema["Service"].new {
+  metadata.name = "web"
+  metadata.namespace = "prod"
+  spec.selector = { app: "web" }
+  spec.ports = [{ port: 80, targetPort: 8080 }]
+}
+
+puts manifest.to_yaml
+```
+
+```yaml
+---
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: prod
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web
+  namespace: prod
+spec:
+  replicas: 3
+  ...
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: web
+  namespace: prod
+spec:
+  selector:
+    app: web
+  ports:
+  - port: 80
+    targetPort: 8080
+```
+
+### File I/O
+
+```ruby
+# Write
+manifest.write("cluster.yaml")
+
+# Read
+loaded = Kube::Schema::Manifest.open("cluster.yaml")
+
+# Modify and write back
+loaded << new_resource
+loaded.write
+```
+
+### Composition
+
+Manifests flatten into each other. No nesting.
+
+```ruby
+infra = Kube::Schema::Manifest.new(namespace, configmap, secret)
+app   = Kube::Schema::Manifest.new(deployment, service)
+
+combined = Kube::Schema::Manifest.new
+combined << infra
+combined << app
+combined.size  # => 5
+```
+
+### Enumerable
+
+```ruby
+manifest.map { |r| r.to_h[:kind] }
+manifest.select { |r| r.to_h[:kind] == "Service" }
+manifest.any? { |r| r.to_h[:kind] == "Pod" }
+manifest.count
+```
+
+## Schema versions
+
+Bundled schemas ship with the gem for Kubernetes 1.19 through 1.35. Updated automatically via CI.
+
+```ruby
+Kube::Schema.schema_version = "1.31"
+Kube::Schema["Deployment"]  # uses 1.31
+```
+
+## Related projects
+
+- [kube_cluster](https://github.com/general-intelligence-systems/kube_cluster) -- OOP resource management with dirty tracking and persistence
+- [kube_kubectl](https://github.com/general-intelligence-systems/kube_ctl) -- Ruby DSL that compiles to kubectl and helm commands
+- [kube_kit](https://github.com/general-intelligence-systems/kube_kit) -- Generators for kube_cluster projects
+- [kube_engine](https://github.com/general-intelligence-systems/kube_engine) -- Kubernetes engine
+
+## Built with
+
+[black_hole_struct](https://github.com/aanand/black_hole_struct) -- the dynamic nested struct that powers the block DSL. [json_schemer](https://github.com/davishmcclurg/json_schemer) -- JSON Schema validation against the real Kubernetes OpenAPI specs.

data/lib/kube/schema/resource.rb

@@ -6,48 +6,61 @@ module Kube
   module Schema
     class Resource
 
-      # Subclasses generated by Instance#[] have a class-level .schema
-      # which is a JSONSchemer::Schema object, and .defaults which
-      # provides apiVersion and kind derived from the GVK metadata.
       def initialize(hash = {}, &block)
-        hash = deep_stringify_keys(hash)
+        deep_symbolize_keys(self.class.defaults.to_h).then do |defaults|
 
-        @data = BlackHoleStruct.new(hash)
-        @data.instance_exec(&block) if block
+          deep_symbolize_keys(hash).then do |symbolized|
+            config = defaults.merge({
+              metadata: symbolized.delete(:metadata),
+              spec: symbolized.delete(:spec),
+            })
+
+            @data = BlackHoleStruct.new(config)
+          end
+        end
+
+        if block_given?
+          @data.instance_exec(&block)
+        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
-      end
+      def self.schema = nil
 
       # Gets overridden by the factory in Kube::Schema::Instance.
       # Returns a frozen Hash like { "apiVersion" => "apps/v1", "kind" => "Deployment" }
-      def self.defaults
-        nil
-      end
+      def self.defaults = nil
 
       def valid?
-        return true if self.class.schema.nil?
-
-        self.class.schema.valid?(deep_stringify_keys(to_h))
+        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.
       # The error message includes the resource kind and name for context.
       def valid!
-        return true if self.class.schema.nil?
+        if self.class.schema.nil?
+          true
+        else
+          data = deep_stringify_keys(to_h)
+          errors = self.class.schema.validate(data).to_a
 
-        data = deep_stringify_keys(to_h)
-        errors = self.class.schema.validate(data).to_a
+          unless errors.empty?
+            kind = self.class.defaults&.dig("kind")
+            name = data.dig("metadata", "name")
+            raise Kube::ValidationError.new(errors, kind: kind, name: name, manifest: data)
+          end
 
-        unless errors.empty?
-          kind = self.class.defaults&.dig("kind")
-          name = data.dig("metadata", "name")
-          raise Kube::ValidationError.new(errors, kind: kind, name: name, manifest: data)
+          true
         end
-
-        true
       end
 
       # Returns the resource data as a Hash. Defaults (apiVersion, kind)
@@ -70,8 +83,9 @@ module Kube
       # Serializes to clean Kubernetes YAML.
       # Raises Kube::ValidationError if the resource is not valid.
       def to_yaml
-        valid!
-        deep_stringify_keys(to_h).to_yaml
+        if valid!
+          deep_stringify_keys(to_h).to_yaml
+        end
       end
 
       def ==(other)

data/lib/kube/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Schema
-    VERSION = "1.2.1"
+    VERSION = "1.2.3"
   end
 end

data/lib/kube/schema.rb

@@ -75,3 +75,51 @@ module Kube
     end
   end
 end
+
+# Patch BlackHoleStruct to handle arrays consistently.
+#
+# The upstream gem does not recurse into arrays — hashes inside arrays
+# are not converted to BlackHoleStruct on construction, and are not
+# converted back to plain Hash on #to_h.  This causes key-type
+# inconsistencies after a Resource round-trip (symbol keys become
+# string keys inside arrays).
+#
+# These two patches fix both directions:
+#   initialize — converts hashes inside arrays to BlackHoleStruct
+#   to_h       — converts BlackHoleStruct/arrays back to plain objects
+class BlackHoleStruct
+  def initialize(hash = {})
+    raise ArgumentError, "Argument should be a Hash" unless hash.is_a?(Hash)
+
+    @table = {}
+    hash.each do |key, value|
+      @table[key.to_sym] = deep_wrap(value)
+    end
+  end
+
+  def to_h
+    hash = {}
+    @table.each do |key, value|
+      hash[key] = deep_unwrap(value)
+    end
+    hash
+  end
+
+  private
+
+  def deep_wrap(value)
+    case value
+    when Hash  then self.class.new(value)
+    when Array then value.map { |v| deep_wrap(v) }
+    else       value
+    end
+  end
+
+  def deep_unwrap(value)
+    case value
+    when self.class then value.to_h
+    when Array      then value.map { |v| deep_unwrap(v) }
+    else            value
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kube_schema
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.3
 platform: ruby
 authors:
 - Nathan K
@@ -115,6 +115,7 @@ files:
 - Gemfile.lock
 - README.md
 - Rakefile
+- assets/validation-error.png
 - bin/console
 - bin/copy-schemas-over
 - bin/increment-version