kube_cluster 0.2.0 → 0.2.1

data/examples/version2/helpers.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module App
+  module Helpers
+    def match_labels(name:, instance:, component: nil)
+      labels = {
+        "app.kubernetes.io/name":     name,
+        "app.kubernetes.io/instance": instance,
+      }
+      labels[:"app.kubernetes.io/component"] = component if component
+      labels
+    end
+
+    def base64(str)
+      [str].pack("m0")
+    end
+  end
+end

data/examples/version2/my_app.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+class MyApp < Kube::Cluster::Manifest
+  include Helpers
+
+  Middleware = Kube::Cluster::Manifest::Middleware
+
+  stack do
+    # Generative — produce new resources from existing ones
+    use Middleware::ServiceForDeployment
+    use Middleware::IngressForService
+    use Middleware::HPAForDeployment
+
+    # Transforms — apply to everything, including generated resources
+    use Middleware::Labels, managed_by: "kube_cluster"
+    use Middleware::ResourcePreset
+    use Middleware::SecurityContext
+    use Middleware::PodAntiAffinity
+  end
+
+  attr_reader :domain, :db_domain, :rails_domain, :size
+
+  def initialize(domain, size: :small, &block)
+    super()
+    @domain       = domain
+    @db_domain    = "db.#{domain}"
+    @rails_domain = "app.#{domain}"
+    @size         = size
+    block.call(self) if block
+  end
+
+  # Labels that encode the manifest-level abstractions.
+  # Middleware reads these to apply sizing, security, etc.
+  def app_labels(name:, instance:, component: nil)
+    labels = {
+      "app.kubernetes.io/name":     name,
+      "app.kubernetes.io/instance": instance,
+      "app.kubernetes.io/size":     @size.to_s,
+    }
+    labels[:"app.kubernetes.io/component"] = component if component
+    labels
+  end
+end

data/examples/version2/postgresql.rb

@@ -0,0 +1,81 @@
+class Postgresql < Kube::Cluster::Manifest
+
+  def initialize(namespace: nil)
+    super
+    @namespace = namespace
+
+    self << Namespace.new
+    self << StatefulSet.new
+    self << Service.new
+    self << Secret.new
+  end
+
+  class StatefulSet < Kube::Schema["StatefulSet"]
+    metadata.name      = db_name
+    metadata.namespace = db_ns
+    metadata.labels    = db_labels
+    spec.serviceName = "#{db_name}-headless"
+    spec.replicas    = 1
+    spec.selector.matchLabels = db_match
+    spec.template.metadata.labels = db_labels
+    spec.template.spec.containers = [
+      {
+        name:  "postgres",
+        image: "docker.io/postgres:16.4-alpine",
+        ports: [{ name: "tcp-postgresql", containerPort: 5432 }],
+        env: [
+          { name: "POSTGRES_PASSWORD", valueFrom: { secretKeyRef: { name: db_name, key: "postgres-password" } } },
+          { name: "PGDATA", value: "/var/lib/postgresql/data/pgdata" },
+        ],
+        volumeMounts: [{ name: "data", mountPath: "/var/lib/postgresql/data" }],
+        livenessProbe: {
+          exec: { command: ["pg_isready", "-U", "postgres"] },
+          initialDelaySeconds: 30,
+          periodSeconds: 10,
+          timeoutSeconds: 5,
+          failureThreshold: 6,
+        },
+        readinessProbe: {
+          exec: { command: ["pg_isready", "-U", "postgres"] },
+          initialDelaySeconds: 5,
+          periodSeconds: 10,
+          timeoutSeconds: 5,
+          failureThreshold: 6,
+        },
+      },
+    ]
+    spec.volumeClaimTemplates = [
+      {
+        metadata: { name: "data" },
+        spec: {
+          accessModes: ["ReadWriteOnce"],
+          resources: { requests: { storage: "10Gi" } },
+        },
+      },
+    ]
+  end
+
+  class Namespace < Kube::Schema["Namespace"]
+    metadata.name   = db_ns
+    metadata.labels = db_labels.reject { |k, _| k == :"app.kubernetes.io/component" }
+  end
+
+  class Secret < Kube::Schema["Secret"]
+    metadata.name      = db_name
+    metadata.namespace = db_ns
+    metadata.labels    = db_labels
+    self.type = "Opaque"
+    self.data = { "postgres-password": m.base64(pg_password) }
+  end
+
+  # Headless service for StatefulSet DNS — explicit because the
+  # middleware-generated Service is a regular ClusterIP service.
+  class Service < Kube::Schema["Service"]
+    metadata.name      = "#{db_name}-headless"
+    metadata.namespace = db_ns
+    metadata.labels    = db_labels
+    spec.clusterIP = "None"
+    spec.selector  = db_match
+    spec.ports     = [{ name: "tcp-postgresql", port: 5432, targetPort: "tcp-postgresql" }]
+  end
+end

data/examples/version2/ruby_on_rails.rb

@@ -0,0 +1,31 @@
+class RubyOnRails < Kube::Schema["Deployment"]
+  default do
+    metadata.name      = name
+    metadata.namespace = ns
+    metadata.labels    = labels.merge(
+      "app.kubernetes.io/expose":    "app.example.com",
+      "app.kubernetes.io/autoscale": "1-5",
+    )
+    spec.replicas = 1
+    spec.selector.matchLabels = m.match_labels(name: name, instance: name)
+    spec.template.metadata.labels = labels
+    spec.template.spec.containers = [
+      {
+        name:    name,
+        image:   "ghcr.io/acme/rails-app:2.0",
+        ports:   [{ name: "http", containerPort: 3000, protocol: "TCP" }],
+        envFrom: [{ configMapRef: { name: "#{name}-config" } }],
+        livenessProbe: {
+          httpGet: { path: "/healthz", port: "http" },
+          initialDelaySeconds: 15,
+          periodSeconds: 10,
+        },
+        readinessProbe: {
+          httpGet: { path: "/readyz", port: "http" },
+          initialDelaySeconds: 5,
+          periodSeconds: 5,
+        },
+      },
+    ]
+  end
+end

data/examples/web-app/manifest.rb

@@ -0,0 +1,215 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "kube/schema"
+
+MATCH_LABELS = STANDARD_LABELS.slice(
+  :"app.kubernetes.io/name",
+  :"app.kubernetes.io/instance",
+)
+
+REGISTRY   = "docker.io"
+REPOSITORY = "nginx"
+TAG        = "1.27.3-alpine"
+IMAGE      = "#{REGISTRY}/#{REPOSITORY}:#{TAG}"
+
+RESOURCE_PRESETS = {
+  "nano":    { requests: { cpu: "100m",  memory: "128Mi"  }, limits: { cpu: "150m",  memory: "192Mi"  } },
+  "micro":   { requests: { cpu: "250m",  memory: "256Mi"  }, limits: { cpu: "375m",  memory: "384Mi"  } },
+  "small":   { requests: { cpu: "500m",  memory: "512Mi"  }, limits: { cpu: "750m",  memory: "768Mi"  } },
+  "medium":  { requests: { cpu: "500m",  memory: "1024Mi" }, limits: { cpu: "750m",  memory: "1536Mi" } },
+  "large":   { requests: { cpu: "1.0",   memory: "2048Mi" }, limits: { cpu: "1.5",   memory: "3072Mi" } },
+  "xlarge":  { requests: { cpu: "1.0",   memory: "3072Mi" }, limits: { cpu: "3.0",   memory: "6144Mi" } },
+  "2xlarge": { requests: { cpu: "1.0",   memory: "3072Mi" }, limits: { cpu: "6.0",   memory: "12288Mi" } },
+}
+
+module AutoConfig
+end
+
+class MyApp < Kube::Schema::Manifest
+  include Helpers
+  include AutoConfig
+
+  def initialize(namespace: DEFAULT_NAMESPACE, labels: STANDARD_LABELS)
+    @app_name  = "web-app"
+    @fullname  = "#{RELEASE_NAME}-#{APP_NAME}"[0, 63].chomp("-")
+    @namespace = namespace 
+
+    @labels = {
+      "app.kubernetes.io/name": @app_name
+      "app.kubernetes.io/managed-by": "kube_cluster",
+    }
+  end
+
+  stack do
+    use Middleware::Namespace
+    use Middleware::Labels
+  end
+
+  class Namespace < Kube::Schema["Namespace"]
+    def initialize(namespace:)
+      build {
+        metadata.name = namespace
+      }
+    end
+  end
+
+  class ConfigMap < Kube::Schema["ConfigMap"]
+    def initialize(namespace:)
+      build {
+        metadata.name = "#{namespace}-config"
+        spec.data = {
+          RAILS_ENV:     "production",
+          LOG_LEVEL:     "info",
+          WORKERS:       "4",
+          PORT:          "3000",
+        }
+      }
+    end
+  end
+
+  class Deployment < Kube::Schema["Deployment"]
+    def initialize(namespace:)
+      build {
+        metadata.name = namespace
+
+        spec.replicas = 3
+        spec.selector.matchLabels = MATCH_LABELS
+
+        spec.template.metadata.labels = STANDARD_LABELS
+        spec.template.metadata.annotations = {
+          # Checksum pattern from _utils.tpl -- triggers rolling restart on config change
+          "checksum/config": "{{ sha256sum of configmap data }}",
+        }
+
+        spec.template.spec.containers = [
+          {
+            name:  APP_NAME,
+            image: IMAGE,
+            ports: [{ name: "http", containerPort: 3000, protocol: "TCP" }],
+            resources: RESOURCES,
+            env: [
+              { name: "PORT", value: "3000" },
+            ],
+            envFrom: [
+              { configMapRef: { name: "#{FULLNAME}-config" } },
+            ],
+            livenessProbe: {
+              httpGet: { path: "/healthz", port: "http" },
+              initialDelaySeconds: 15,
+              periodSeconds: 10,
+            },
+            readinessProbe: {
+              httpGet: { path: "/readyz", port: "http" },
+              initialDelaySeconds: 5,
+              periodSeconds: 5,
+            },
+          },
+        ]
+
+        # Pod anti-affinity (from _affinities.tpl)
+        # Soft anti-affinity: prefer spreading pods across nodes but don't enforce it
+        spec.template.spec.affinity = {
+          podAntiAffinity: {
+            preferredDuringSchedulingIgnoredDuringExecution: [
+              {
+                weight: 1,
+                podAffinityTerm: {
+                  labelSelector: {
+                    matchLabels: MATCH_LABELS,
+                  },
+                  topologyKey: "kubernetes.io/hostname",
+                },
+              },
+            ],
+          },
+        }
+      }
+    end
+  end
+
+  class Service < Kube::Schema["Service"]
+    def initialize(namespace:)
+      build {
+        metadata.name = namespace
+
+        spec.selector = MATCH_LABELS
+        spec.ports = [
+          { name: "http", port: 80, targetPort: "http", protocol: "TCP" },
+        ]
+      }
+    end
+  end
+
+  class Ingress < Kube::Schema["Ingress"]
+    def initialize(namespace:)
+      build {
+        metadata.name = namespace
+        metadata.annotations = {
+          "cert-manager.io/cluster-issuer": "letsencrypt-prod",
+          "nginx.ingress.kubernetes.io/ssl-redirect": "true",
+        }
+
+        spec.ingressClassName = "nginx"
+        spec.tls = [
+          {
+            hosts: ["app.example.com"],
+            secretName: "#{namespace}-tls",
+          },
+        ]
+        spec.rules = [
+          {
+            host: "app.example.com",
+            http: {
+              paths: [
+                {
+                  path: "/",
+                  pathType: "Prefix",
+                  backend: {
+                    service: {
+                      name: FULLNAME,
+                      port: { name: "http" },
+                    },
+                  },
+                },
+              ],
+            },
+          },
+        ]
+      }
+    end
+  end
+
+  class HorizontalPodAutoscaler < Kube::Schema["HorizontalPodAutoscaler"]
+    def initialize(namespace:)
+      build {
+        metadata.name = namespace
+
+        spec.scaleTargetRef.apiVersion = "apps/v1"
+        spec.scaleTargetRef.kind = "Deployment"
+        spec.scaleTargetRef.name = namespace
+
+        spec.minReplicas = 3
+        spec.maxReplicas = 10
+        spec.metrics = [
+          {
+            type: "Resource",
+            resource: {
+              name: "cpu",
+              target: { type: "Utilization", averageUtilization: 75 },
+            },
+          },
+          {
+            type: "Resource",
+            resource: {
+              name: "memory",
+              target: { type: "Utilization", averageUtilization: 80 },
+            },
+          },
+        ]
+      }
+    end
+  end
+end
+
+puts MyApp.new.to_yaml

data/flake.lock

@@ -2,11 +2,11 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1773821835,
-        "narHash": "sha256-TJ3lSQtW0E2JrznGVm8hOQGVpXjJyXY2guAxku2O9A4=",
+        "lastModified": 1776169885,
+        "narHash": "sha256-l/iNYDZ4bGOAFQY2q8y5OAfBBtrDAaPuRQqWaFHVRXM=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "b40629efe5d6ec48dd1efba650c797ddbd39ace0",
+        "rev": "4bd9165a9165d7b5e33ae57f3eecbcb28fb231c9",
         "type": "github"
       },
       "original": {

data/flake.nix

@@ -10,6 +10,10 @@
       let
         pkgs = nixpkgs.legacyPackages.${system};
         ruby = pkgs.ruby_3_4; # Specify version
+        kubectlWithKubeconfig = pkgs.writeShellScriptBin "kubectl" ''
+          #!${pkgs.bash}/bin/bash
+          KUBECONFIG="$PWD/kubeconfig.yaml" ${pkgs.kubectl}/bin/kubectl "$@"
+        '';
       in
       {
         devShells.default = pkgs.mkShell {
@@ -21,6 +25,7 @@
             ruby
             pkgs.libyaml # psych gem
             pkgs.openssl # openssl gem
+            kubectlWithKubeconfig
           ];
 
           shellHook = ''
@@ -29,6 +34,7 @@
             export PATH="$GEM_HOME/bin:$PATH"
             export BUNDLE_PATH="$GEM_HOME"
             export BUNDLE_BIN="$GEM_HOME/bin"
+            export KUBECONFIG="$PWD/kubeconfig.yaml"
           '';
         };
       }

data/kube_cluster.gemspec

@@ -32,5 +32,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rubocop", "~> 1.21"
 
-  spec.add_dependency "kube_schema", "~> 1.0"
+  spec.add_dependency "kube_schema", "~> 1.2.0"
+  spec.add_dependency "kube_kit", "> 0"
+  spec.add_dependency "kube_kubectl", "~> 2.0.0"
 end

data/lib/kube/cli/cluster.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "kube/cli"
+require "kube/cluster"
+
+Kube::CLI.register "cluster", ->(argv) {
+  subcommand = argv.shift
+
+  case subcommand
+  when "connect", nil
+    kubeconfig = ENV["KUBECONFIG"]
+
+    # Parse --kubeconfig flag
+    if (idx = argv.index("--kubeconfig"))
+      kubeconfig = argv[idx + 1]
+      argv.slice!(idx, 2)
+    elsif (flag = argv.find { |a| a.start_with?("--kubeconfig=") })
+      kubeconfig = flag.split("=", 2).last
+      argv.delete(flag)
+    end
+
+    if kubeconfig.nil?
+      $stderr.puts "kube cluster connect: missing --kubeconfig or KUBECONFIG env var"
+      exit 1
+    end
+
+    instance = Kube::Cluster.connect(kubeconfig: kubeconfig)
+    puts instance.inspect
+
+  when "help", "--help", "-h"
+    puts "Usage: kube cluster <subcommand> [options]"
+    puts
+    puts "Subcommands:"
+    puts "  connect    Connect to a cluster (--kubeconfig=PATH or KUBECONFIG env)"
+    puts
+
+  else
+    $stderr.puts "kube cluster: unknown subcommand '#{subcommand}'"
+    exit 1
+  end
+}, description: "Manage cluster connections"

data/lib/kube/cluster/connection.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Connection
+      attr_reader :kubeconfig, :ctl
+
+      def initialize(kubeconfig:)
+        @kubeconfig = kubeconfig
+        @ctl        = Kube::Ctl::Instance.new(kubeconfig: kubeconfig)
+      end
+
+      def inspect
+        "#<#{self.class.name} kubeconfig=#{@kubeconfig.inspect}>"
+      end
+    end
+  end
+end

data/lib/kube/cluster/instance.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Instance
+      attr_reader :kubeconfig
+
+      def initialize(kubeconfig:)
+        @kubeconfig = kubeconfig
+      end
+
+      def connection
+        @connection ||= Connection.new(kubeconfig: @kubeconfig)
+      end
+
+      def inspect
+        "#<#{self.class.name} kubeconfig=#{@kubeconfig.inspect}>"
+      end
+    end
+  end
+end

data/lib/kube/cluster/manifest/middleware/annotations.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Manifest < Kube::Schema::Manifest
+      class Middleware
+        # Merges annotations into +metadata.annotations+ on every resource.
+        # Existing annotations are preserved; the supplied annotations act
+        # as defaults that can be overridden per-resource.
+        #
+        #   stack do
+        #     use Middleware::Annotations,
+        #       "prometheus.io/scrape": "true",
+        #       "prometheus.io/port":   "9090"
+        #   end
+        #
+        class Annotations < Middleware
+          def initialize(**annotations)
+            @annotations = annotations.transform_keys(&:to_sym).transform_values(&:to_s)
+          end
+
+          def call(resource)
+            h = resource.to_h
+            h[:metadata] ||= {}
+            h[:metadata][:annotations] = @annotations.merge(h[:metadata][:annotations] || {})
+            rebuild(resource, h)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kube/cluster/manifest/middleware/hpa_for_deployment.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Manifest < Kube::Schema::Manifest
+      class Middleware
+        # Generates a HorizontalPodAutoscaler for every pod-bearing
+        # resource that carries the +app.kubernetes.io/autoscale+ label.
+        #
+        # The label value encodes the min and max replicas as "min-max":
+        #
+        #   metadata.labels = { "app.kubernetes.io/autoscale": "1-5" }
+        #
+        # Options:
+        #   cpu:    — target CPU utilization percentage (default: 75)
+        #   memory: — target memory utilization percentage (default: 80)
+        #
+        #   stack do
+        #     use Middleware::HPAForDeployment
+        #     use Middleware::HPAForDeployment, cpu: 60, memory: 70
+        #   end
+        #
+        class HPAForDeployment < Middleware
+          LABEL = :"app.kubernetes.io/autoscale"
+
+          def initialize(cpu: 75, memory: 80)
+            @cpu = cpu
+            @memory = memory
+          end
+
+          def call(resource)
+            return resource unless pod_bearing?(resource)
+
+            value = label(resource, LABEL)
+            return resource unless value
+
+            min, max = parse_range(value)
+
+            h = resource.to_h
+            name      = h.dig(:metadata, :name)
+            namespace = h.dig(:metadata, :namespace)
+            labels    = h.dig(:metadata, :labels) || {}
+            api_version = h[:apiVersion] || "apps/v1"
+            resource_kind = kind(resource)
+
+            # Capture ivars as locals — the block runs via instance_exec
+            # on a BlackHoleStruct, so @ivars would resolve on the BHS.
+            cpu_target    = @cpu
+            memory_target = @memory
+
+            hpa = Kube::Schema["HorizontalPodAutoscaler"].new {
+              metadata.name      = name
+              metadata.namespace = namespace if namespace
+              metadata.labels    = labels.reject { |k, _| k == LABEL }
+
+              spec.scaleTargetRef = {
+                apiVersion: api_version,
+                kind:       resource_kind,
+                name:       name,
+              }
+              spec.minReplicas = min
+              spec.maxReplicas = max
+              spec.metrics = [
+                {
+                  type: "Resource",
+                  resource: {
+                    name: "cpu",
+                    target: { type: "Utilization", averageUtilization: cpu_target },
+                  },
+                },
+                {
+                  type: "Resource",
+                  resource: {
+                    name: "memory",
+                    target: { type: "Utilization", averageUtilization: memory_target },
+                  },
+                },
+              ]
+            }
+
+            [resource, hpa]
+          end
+
+          private
+
+            def parse_range(value)
+              parts = value.to_s.split("-", 2)
+
+              unless parts.length == 2
+                raise ArgumentError,
+                  "Invalid autoscale label: #{value.inspect}. Expected format: \"min-max\" (e.g. \"1-5\")"
+              end
+
+              min = Integer(parts[0])
+              max = Integer(parts[1])
+
+              unless min > 0 && max >= min
+                raise ArgumentError,
+                  "Invalid autoscale range: min=#{min}, max=#{max}. " \
+                  "min must be > 0 and max must be >= min."
+              end
+
+              [min, max]
+            end
+        end
+      end
+    end
+  end
+end