kube_schema 1.4.2 → 1.4.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6a4b8d1ba60da4a1f90ea62beeeff8e5e11ca767ee58762123aa4fa707d123b6
-  data.tar.gz: 2a5cf867a63dd56683d5a944b6fa03d6b30c1ae3a6d6e4f5d30c248615171c6a
+  metadata.gz: e9695974cb2703c11c69c41aa624cd96cf6ac5f8bcf9859ebce423be49146250
+  data.tar.gz: 23210ffab5ca166dacfa3f1ba2ce2d24742a36127d95fa1a1b0d896c464ef1ed
 SHA512:
-  metadata.gz: 4cdd9bf6146cfead65ca01128db452226f48d006e13f4f2e6be901a99d0578678c72174e6daedd1314bc29e182f6c6ba4b31b78237b53c99949527d0bf3092b9
-  data.tar.gz: c2c21e6fc784b7ae4c7cd2fbcea1a8ddd23f31a8d31264d7b46cd83c7b2b7a1a5a19c4ae8f527b0816bd3177a43363d8b432832fcb7b4ffff2308d5185827729
+  metadata.gz: aac9d217ba2235bda3206de3391ece4da353a938b40e0ae58c98932bf03c9deee679e4c2072bbbdf5566e4663b0551b75ff700573481893bd44127e01de0f30e
+  data.tar.gz: 1fc8fc7a0fd40fb47168c48b194f1c51522479652d391d3aa372928d91c08c348595c3e451db2f9ff53187fa4eabaed709f65e63a1e1e119588cc31426b77c65

data/.github/workflows/gh-pages.yml

@@ -0,0 +1,57 @@
+name: Github Pages
+
+on:
+  push:
+    branches:
+      - trench
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages:
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow one concurrent deployment:
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+env:
+  BUNDLE_WITH: maintenance
+
+jobs:
+  generate:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v6
+
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ruby
+        bundler-cache: true
+    
+    - name: Installing packages
+      run: sudo apt-get install wget
+    
+    - name: Generate documentation
+      timeout-minutes: 5
+      run: bundle exec bake utopia:project:static --force no
+    
+    - name: Upload documentation artifact
+      uses: actions/upload-pages-artifact@v4
+      with:
+        path: docs
+  
+  deploy:
+    runs-on: ubuntu-latest
+    
+    environment:
+      name: github-pages
+      url: ${{steps.deployment.outputs.page_url}}
+    
+    needs: generate
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

data/Gemfile

@@ -3,3 +3,10 @@
 source "https://rubygems.org"
 
 gemspec
+
+group :maintenance, optional: true do
+	gem "utopia-project"
+	gem "bake-gem"
+	gem "bake-modernize"
+	gem "bake-releases"
+end

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    kube_schema (1.4.2)
+    kube_schema (1.4.4)
       json_schemer (~> 2.5.0)
       rubyshell (~> 1.5.0)
 
@@ -9,9 +9,97 @@ GEM
   remote: https://rubygems.org/
   specs:
     ast (2.4.3)
+    async (2.39.0)
+      console (~> 1.29)
+      fiber-annotation
+      io-event (~> 1.11)
+      metrics (~> 0.12)
+      traces (~> 0.18)
+    async-container (0.34.5)
+      async (~> 2.22)
+    async-http (0.95.0)
+      async (>= 2.10.2)
+      async-pool (~> 0.11)
+      io-endpoint (~> 0.14)
+      io-stream (~> 0.6)
+      metrics (~> 0.12)
+      protocol-http (~> 0.62)
+      protocol-http1 (~> 0.39)
+      protocol-http2 (~> 0.26)
+      protocol-url (~> 0.2)
+      traces (~> 0.10)
+    async-http-cache (0.4.6)
+      async-http (~> 0.56)
+    async-ollama (0.10.3)
+      async
+      async-rest
+    async-pool (0.11.2)
+      async (>= 2.0)
+    async-rest (0.20.0)
+      async-http (~> 0.42)
+      protocol-url (~> 0.2)
+    async-service (0.22.0)
+      async
+      async-container (~> 0.34)
+      string-format (~> 0.2)
+    async-utilization (0.3.2)
+      console (~> 1.0)
+    bake (0.24.1)
+      bigdecimal
+      samovar (~> 2.1)
+    bake-gem (0.13.1)
+      console (~> 1.25)
+    bake-modernize (0.54.1)
+      async-http
+      async-ollama (~> 0.10)
+      bake
+      build-files (~> 1.6)
+      markly (~> 0.13)
+      rugged
+    bake-releases (0.5.4)
+      bake (~> 0.21)
+      markly (~> 0.8)
     bigdecimal (4.1.2)
+    build-files (1.10.2)
+    concurrent-ruby (1.3.6)
+    console (1.34.3)
+      fiber-annotation
+      fiber-local (~> 1.1)
+      json
+    date (3.5.1)
+    decode (0.27.0)
+      prism
+      rbs
     diff-lcs (1.6.2)
+    erb (6.0.4)
+    falcon (0.55.3)
+      async
+      async-container (~> 0.20)
+      async-http (~> 0.75)
+      async-http-cache (~> 0.4)
+      async-service (~> 0.19)
+      async-utilization (~> 0.3)
+      bundler
+      localhost (~> 1.1)
+      openssl (>= 3.0)
+      protocol-http (~> 0.31)
+      protocol-rack (~> 0.7)
+      samovar (~> 2.3)
+    fiber-annotation (0.2.0)
+    fiber-local (1.1.0)
+      fiber-storage
+    fiber-storage (1.0.1)
     hana (1.3.7)
+    http-accept (2.2.1)
+    io-console (0.8.2)
+    io-endpoint (0.17.2)
+    io-event (1.15.1)
+    io-stream (0.13.0)
+    irb (1.18.0)
+      pp (>= 0.6.0)
+      prism (>= 1.3.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
     json (2.19.3)
     json_schemer (2.5.0)
       bigdecimal
@@ -20,15 +108,75 @@ GEM
       simpleidn (~> 0.2)
     language_server-protocol (3.17.0.5)
     lint_roller (1.1.0)
+    localhost (1.7.0)
+    logger (1.7.0)
+    mail (2.9.0)
+      logger
+      mini_mime (>= 0.1.1)
+      net-imap
+      net-pop
+      net-smtp
+    mapping (1.1.3)
+    markly (0.16.0)
+    metrics (0.15.0)
+    mime-types (3.7.0)
+      logger
+      mime-types-data (~> 3.2025, >= 3.2025.0507)
+    mime-types-data (3.2026.0414)
+    mini_mime (1.1.5)
+    msgpack (1.8.0)
+    net-imap (0.6.4)
+      date
+      net-protocol
+    net-pop (0.1.2)
+      net-protocol
+    net-protocol (0.2.2)
+      timeout
+    net-smtp (0.5.1)
+      net-protocol
+    openssl (4.0.1)
     parallel (2.0.1)
     parser (3.3.11.1)
       ast (~> 2.4.1)
       racc
+    pp (0.6.3)
+      prettyprint
+    prettyprint (0.2.0)
     prism (1.9.0)
+    protocol-hpack (1.5.1)
+    protocol-http (0.62.2)
+    protocol-http1 (0.39.0)
+      protocol-http (~> 0.62)
+    protocol-http2 (0.26.0)
+      protocol-hpack (~> 1.4)
+      protocol-http (~> 0.62)
+    protocol-rack (0.22.1)
+      io-stream (>= 0.10)
+      protocol-http (~> 0.58)
+      rack (>= 1.0)
+    protocol-url (0.4.0)
+    psych (5.3.1)
+      date
+      stringio
     racc (1.8.1)
+    rack (3.2.6)
+    rackula (1.4.1)
+      falcon (~> 0.46)
+      samovar (~> 2.1)
+      variant
     rainbow (3.1.1)
     rake (13.4.2)
+    rbs (4.0.2)
+      logger
+      prism (>= 1.6.0)
+      tsort
+    rdoc (7.2.0)
+      erb
+      psych (>= 4.0.0)
+      tsort
     regexp_parser (2.12.0)
+    reline (0.6.3)
+      io-console (~> 0.5)
     rspec (3.13.2)
       rspec-core (~> 3.13.0)
       rspec-expectations (~> 3.13.0)
@@ -58,20 +206,60 @@ GEM
       prism (~> 1.7)
     ruby-progressbar (1.13.0)
     rubyshell (1.5.0)
+    rugged (1.9.0)
+    samovar (2.4.1)
+      console (~> 1.0)
+      mapping (~> 1.0)
     simpleidn (0.2.3)
+    string-format (0.2.0)
+    stringio (3.2.0)
+    thread-local (1.1.0)
+    timeout (0.6.1)
+    traces (0.18.2)
+    tsort (0.2.0)
     unicode-display_width (3.2.0)
       unicode-emoji (~> 4.1)
     unicode-emoji (4.2.0)
+    utopia (2.32.1)
+      bake (~> 0.20)
+      concurrent-ruby (~> 1.2)
+      console (~> 1.24)
+      http-accept (~> 2.1)
+      irb
+      mail (~> 2.6)
+      mime-types (~> 3.0)
+      msgpack
+      net-smtp
+      protocol-url (~> 0.4)
+      rack (~> 3.0)
+      samovar (~> 2.1)
+      traces (~> 0.10)
+      variant (~> 0.1)
+      xrb (~> 0.4)
+    utopia-project (0.40.0)
+      decode (~> 0.26)
+      falcon
+      markly (~> 0.15)
+      rackula (~> 1.3)
+      thread-local
+      utopia (~> 2.32)
+    variant (0.1.1)
+      thread-local
+    xrb (0.11.2)
 
 PLATFORMS
   ruby
   x86_64-linux
 
 DEPENDENCIES
+  bake-gem
+  bake-modernize
+  bake-releases
   kube_schema!
   rake (~> 13.0)
   rspec (~> 3.13)
   rubocop (~> 1.21)
+  utopia-project
 
 BUNDLED WITH
    2.6.9

data/guides/block-dsl/readme.md

@@ -0,0 +1,50 @@
+# The Block DSL
+
+This guide covers the block DSL for defining Kubernetes resources with nested attributes.
+
+## Nested Attributes
+
+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:
+
+```ruby
+deploy.to_h[:apiVersion]  # => "apps/v1"
+deploy.to_h[:kind]        # => "Deployment"
+```
+
+## Subclassing
+
+```ruby
+class RailsApp < Kube::Schema["Deployment"]
+  def default_image
+    "ruby:3.4"
+  end
+end
+
+app = RailsApp.new {
+  metadata.name = "rails"
+  spec.template.spec.containers = [
+    { name: "web", image: "myapp:latest" }
+  ]
+}
+
+app.default_image  # => "ruby:3.4"
+app.valid?         # => true
+```

data/guides/getting-started/readme.md

@@ -0,0 +1,37 @@
+# Getting Started
+
+This guide walks you through installing kube_schema and creating your first Kubernetes resource object.
+
+## Install
+
+```
+gem install kube_schema
+```
+
+## Basic Usage
+
+Every Kubernetes kind is a class. Fetch it by name:
+
+```ruby
+Kube::Schema["Deployment"]     # => Class < Kube::Schema::Resource
+Kube::Schema["Service"]
+Kube::Schema["ConfigMap"]
+Kube::Schema["NetworkPolicy"]
+```
+
+Specific versions:
+
+```ruby
+Kube::Schema["1.34"]["Deployment"]
+Kube::Schema["1.31"]["Pod"]
+```
+
+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", ...]
+```

data/guides/links.yaml

@@ -0,0 +1,10 @@
+getting-started:
+  order: 1
+block-dsl:
+  order: 2
+validation:
+  order: 3
+manifests:
+  order: 4
+schema-versions:
+  order: 5

data/guides/manifests/readme.md

@@ -0,0 +1,68 @@
+# Manifests
+
+This guide covers grouping resources into multi-document YAML manifests.
+
+## Creating a Manifest
+
+```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
+```
+
+## 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
+```

data/guides/schema-versions/readme.md

@@ -0,0 +1,31 @@
+# Schema Versions
+
+This guide covers working with different Kubernetes schema versions.
+
+## Bundled Schemas
+
+Bundled schemas ship with the gem for Kubernetes 1.19 through 1.35. Updated automatically via CI.
+
+## Setting a Version
+
+```ruby
+Kube::Schema.schema_version = "1.31"
+Kube::Schema["Deployment"]  # uses 1.31
+```
+
+## 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", ...]
+```
+
+## Version-Specific Access
+
+```ruby
+Kube::Schema["1.34"]["Deployment"]
+Kube::Schema["1.31"]["Pod"]
+```

data/guides/validation/readme.md

@@ -0,0 +1,31 @@
+# Validation
+
+This guide covers schema validation against the full Kubernetes OpenAPI spec.
+
+## Basic Validation
+
+```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
+```
+
+## Serialization Safety
+
+`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.

data/kube_schema.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["homepage_uri"] = spec.homepage
   spec.metadata["source_code_uri"] = spec.homepage
-  spec.metadata["documentation_uri"] = spec.homepage
+  spec.metadata["documentation_uri"] = "https://general-intelligence-systems.github.io/kube_schema/"
   spec.metadata["rubygems_mfa_required"] = "true"
 
   spec.files = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }

data/lib/kube/monkey_patches.rb

@@ -33,4 +33,22 @@ class Hash
   def self.vivify(&block)
     new.tap { |h| h.instance_exec(&block) }
   end
+
+  # Deep-stringify keys so symbol keys don't leak into YAML as `:key:`.
+  def to_yaml(*)
+    Hash._deep_stringify_keys(self).then { |h| Psych.dump(h) }
+  end
+
+  def self._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
 end

data/lib/kube/schema/version.rb

@@ -2,6 +2,6 @@
 
 module Kube
   module Schema
-    VERSION = "1.4.2"
+    VERSION = "1.4.4"
   end
 end

data/readme.md

@@ -0,0 +1,28 @@
+# kube_schema
+
+Ruby objects for every Kubernetes resource. Validated against the real OpenAPI spec. No YAML. No hash literals. Just Ruby blocks that know their schema.
+
+## Usage
+
+Please see the [project documentation](https://general-intelligence-systems.github.io/kube_schema/) for more details.
+
+  - [Getting Started](https://general-intelligence-systems.github.io/kube_schema/guides/getting-started/index) - This guide walks you through installing kube_schema and creating your first Kubernetes resource object.
+
+  - [The Block DSL](https://general-intelligence-systems.github.io/kube_schema/guides/block-dsl/index) - This guide covers the block DSL for defining Kubernetes resources with nested attributes.
+
+  - [Validation](https://general-intelligence-systems.github.io/kube_schema/guides/validation/index) - This guide covers schema validation against the full Kubernetes OpenAPI spec.
+
+  - [Manifests](https://general-intelligence-systems.github.io/kube_schema/guides/manifests/index) - This guide covers grouping resources into multi-document YAML manifests.
+
+  - [Schema Versions](https://general-intelligence-systems.github.io/kube_schema/guides/schema-versions/index) - This guide covers working with different Kubernetes schema versions.
+
+## 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
+
+## License
+
+Apache-2.0