kube_cluster 0.2.0 → 0.3.0

data/examples/03-app-with-database/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/03-app-with-database/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::Cluster["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::Cluster["Namespace"]
+    metadata.name   = db_ns
+    metadata.labels = db_labels.reject { |k, _| k == :"app.kubernetes.io/component" }
+  end
+
+  class Secret < Kube::Cluster["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::Cluster["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/03-app-with-database/ruby_on_rails.rb

@@ -0,0 +1,31 @@
+class RubyOnRails < Kube::Cluster["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/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.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    # A flat, ordered collection of Kubernetes resources.
+    #
+    # Manifest is a pure resource collection. Middleware is applied
+    # separately via Kube::Cluster::Middleware::Stack.
+    #
+    #   manifest = Kube::Cluster::Manifest.new
+    #   manifest << Kube::Cluster["Deployment"].new { ... }
+    #
+    #   stack = Kube::Cluster::Middleware::Stack.new do
+    #     use Middleware::Namespace, "production"
+    #     use Middleware::Labels, app: "web-app"
+    #   end
+    #
+    #   stack.call(manifest)
+    #   manifest.to_yaml
+    #
+    class Manifest < Kube::Schema::Manifest
+      attr_reader :resources
+    end
+  end
+end

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

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    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(manifest)
+          manifest.resources.map! do |resource|
+            h = resource.to_h
+            h[:metadata] ||= {}
+            h[:metadata][:annotations] = @annotations.merge(h[:metadata][:annotations] || {})
+            resource.rebuild(h)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    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(manifest)
+          generated = []
+
+          manifest.resources.each do |resource|
+            next unless resource.pod_bearing?
+
+            value = resource.label(LABEL)
+            next 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 = resource.kind
+
+            # 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
+
+            generated << Kube::Cluster["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 },
+                  },
+                },
+              ]
+            }
+          end
+
+          manifest.resources.concat(generated)
+        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

data/lib/kube/cluster/middleware/ingress_for_service.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Middleware
+      # Generates an Ingress for every Service whose source resource
+      # carries the +app.kubernetes.io/expose+ label.
+      #
+      # The label value is the hostname:
+      #
+      #   metadata.labels = { "app.kubernetes.io/expose": "app.example.com" }
+      #
+      # Set to +"true"+ to use the resource name as a hostname placeholder
+      # (useful when a later middleware or the manifest class resolves it).
+      #
+      # Options:
+      #   issuer:          — cert-manager ClusterIssuer name (default: "letsencrypt-prod")
+      #   ingress_class:   — IngressClassName (default: "nginx")
+      #
+      #   stack do
+      #     use Middleware::IngressForService
+      #     use Middleware::IngressForService, issuer: "letsencrypt-staging"
+      #   end
+      #
+      class IngressForService < Middleware
+        LABEL = :"app.kubernetes.io/expose"
+
+        def initialize(issuer: "letsencrypt-prod", ingress_class: "nginx")
+          @issuer = issuer
+          @ingress_class = ingress_class
+        end
+
+        def call(manifest)
+          generated = []
+
+          manifest.resources.each do |resource|
+            next unless resource.kind == "Service"
+
+            host = resource.label(LABEL)
+            next unless host
+
+            h = resource.to_h
+            name      = h.dig(:metadata, :name)
+            namespace = h.dig(:metadata, :namespace)
+            labels    = h.dig(:metadata, :labels) || {}
+
+            # Find the first port on the service
+            port_name = Array(h.dig(:spec, :ports)).first&.dig(:name) || "http"
+
+            # Use resource name as hostname fallback if label is just "true"
+            host = "#{name}.local" if host == "true"
+
+            # Capture ivars as locals — the block runs via instance_exec
+            # on a BlackHoleStruct, so @ivars would resolve on the BHS.
+            issuer        = @issuer
+            ingress_class = @ingress_class
+
+            generated << Kube::Cluster["Ingress"].new {
+              metadata.name      = name
+              metadata.namespace = namespace if namespace
+              metadata.labels    = labels.reject { |k, _| k == LABEL }
+              metadata.annotations = {
+                "cert-manager.io/cluster-issuer":           issuer,
+                "nginx.ingress.kubernetes.io/ssl-redirect": "true",
+              }
+
+              spec.ingressClassName = ingress_class
+              spec.tls = [
+                { hosts: [host], secretName: "#{name}-tls" },
+              ]
+              spec.rules = [
+                {
+                  host: host,
+                  http: {
+                    paths: [{
+                      path:     "/",
+                      pathType: "Prefix",
+                      backend:  { service: { name: name, port: { name: port_name } } },
+                    }],
+                  },
+                },
+              ]
+            }
+          end
+
+          manifest.resources.concat(generated)
+        end
+      end
+    end
+  end
+end

data/lib/kube/cluster/middleware/labels.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Middleware
+      # Merges labels into +metadata.labels+ on every resource.
+      # Existing labels are preserved; the supplied labels act as defaults
+      # that can be overridden per-resource.
+      #
+      #   stack do
+      #     use Middleware::Labels, app: "web-app", managed_by: "kube_cluster"
+      #   end
+      #
+      # The keyword arguments are converted to standard label keys:
+      #
+      #   app:        -> "app.kubernetes.io/name"
+      #   instance:   -> "app.kubernetes.io/instance"
+      #   version:    -> "app.kubernetes.io/version"
+      #   component:  -> "app.kubernetes.io/component"
+      #   part_of:    -> "app.kubernetes.io/part-of"
+      #   managed_by: -> "app.kubernetes.io/managed-by"
+      #
+      # Any unrecognized keys are passed through as-is (string or symbol).
+      #
+      class Labels < Middleware
+        STANDARD_KEYS = {
+          app:        :"app.kubernetes.io/name",
+          instance:   :"app.kubernetes.io/instance",
+          version:    :"app.kubernetes.io/version",
+          component:  :"app.kubernetes.io/component",
+          part_of:    :"app.kubernetes.io/part-of",
+          managed_by: :"app.kubernetes.io/managed-by",
+        }.freeze
+
+        def initialize(**labels)
+          @labels = normalize(labels)
+        end
+
+        def call(manifest)
+          manifest.resources.map! do |resource|
+            h = resource.to_h
+            h[:metadata] ||= {}
+            h[:metadata][:labels] = @labels.merge(h[:metadata][:labels] || {})
+            resource.rebuild(h)
+          end
+        end
+
+        private
+
+          def normalize(labels)
+            labels.each_with_object({}) do |(key, value), result|
+              normalized_key = STANDARD_KEYS.fetch(key, key)
+              result[normalized_key] = value.to_s
+            end
+          end
+      end
+    end
+  end
+end

data/lib/kube/cluster/middleware/namespace.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Kube
+  module Cluster
+    class Middleware
+      # Sets +metadata.namespace+ on all namespace-scoped resources.
+      # Cluster-scoped kinds (Namespace, ClusterRole, etc.) are skipped.
+      #
+      #   stack do
+      #     use Middleware::Namespace, "production"
+      #   end
+      #
+      class Namespace < Middleware
+        def initialize(namespace)
+          @namespace = namespace
+        end
+
+        def call(manifest)
+          manifest.resources.map! do |resource|
+            next resource if resource.cluster_scoped?
+
+            h = resource.to_h
+            h[:metadata] ||= {}
+            h[:metadata][:namespace] = @namespace
+            resource.rebuild(h)
+          end
+        end
+      end
+    end
+  end
+end