kube_schema 1.2.0 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7ed4bf90e31bdf3629732faf97da315bbd17b091a622eed5ecb7885a6d793f2
-  data.tar.gz: 0b8ef4a4ddc76fa357ede482571db2725393d8725fca4a9523568b2156c8f8d0
+  metadata.gz: 43157c3d38782006f39aa63c3cc0ae83eb4af0ad3f3974dde30d4ce27aa58a0d
+  data.tar.gz: 510e764c90294d6c351c66930b95a056cbdbd7ac0a6f2d88bed0bb7ef374cc76
 SHA512:
-  metadata.gz: 788d5c2670f9f1613947444eea6105c5519a3d5ed0ba38bf6bc3c58cda73cea2dce6c34dec16c60ce7e30be301eac3f856e6d4a991e92c30ffe82c593909a5d0
-  data.tar.gz: 6d3d78dd248b2763cb849af42064baa3ec54ae098b34985a321e21756070de2d62398b6625495af146a2bb977d898e4e174fea81654d71ed41458c68982544c0
+  metadata.gz: d38e9e7e866071935b86fd788f8f52f0c751e5b2e71341f3509999cf0beefb193cfa04c92a03f2434865c6bb7771c8348f816b5bc25fd7506c7eb00759fccba3
+  data.tar.gz: 6bdab5c5a67196f998e0c8e527964c9921f8cdfc931742fe9a924cf82b4e31c5a54236c22a4bd5c8fe261310affc2cba813a56f248ab38ed6903e5e5bd300056

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/kube_schema.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
     Abstractions are God. Let's give praise and build on the shoulders of giants by using objects to represent schemas. It was written and to it became.
   DESC
 
-  spec.homepage = "https://github.com/n-at-han-k/kube_schema"
+  spec.homepage = "https://github.com/general-intelligence-systems/kube_schema"
   spec.license = "Apache-2.0"
   spec.required_ruby_version = ">= 3.2.0"
 

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.0"
+    VERSION = "1.2.2"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kube_schema
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.2.2
 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
@@ -144,13 +145,13 @@ files:
 - schemas/v1.33.json
 - schemas/v1.34.json
 - schemas/v1.35.json
-homepage: https://github.com/n-at-han-k/kube_schema
+homepage: https://github.com/general-intelligence-systems/kube_schema
 licenses:
 - Apache-2.0
 metadata:
-  homepage_uri: https://github.com/n-at-han-k/kube_schema
-  source_code_uri: https://github.com/n-at-han-k/kube_schema
-  documentation_uri: https://github.com/n-at-han-k/kube_schema
+  homepage_uri: https://github.com/general-intelligence-systems/kube_schema
+  source_code_uri: https://github.com/general-intelligence-systems/kube_schema
+  documentation_uri: https://github.com/general-intelligence-systems/kube_schema
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: