kube_cluster 0.2.0 → 0.2.1

data/TREE_PLAN.md

@@ -1,513 +0,0 @@
-How will be now create ActiveRecord::Relatino style command objects?
-
-10:25
-
-Architected chainable, lazy-evaluated kubectl command builder pattern
-Architected chainable, lazy-evaluated kubectl command builder pattern
-Great use case for the tree! The idea is an immutable, chainable builder that only shells out when forced — exactly like ActiveRecord::Relation.
-
-ruby
-class Kubectl
-  TREE = JSON.parse(
-    File.read(File.join(GEM_DIR, 'data', 'kubectl-command-tree-v1-minimal.json')),
-    symbolize_names: true
-  )
-
-  def initialize(commands: [], flags: {}, tree: TREE)
-    @commands = commands
-    @flags    = flags
-    @tree     = tree
-  end
-
-  def method_missing(name, *args)
-    cmd = name.to_s.tr('_', '-')
-    @tree.key?(cmd.to_sym).then do |valid|
-      raise ArgumentError, "Unknown kubectl command: #{cmd}" unless valid
-      self.class.new(
-        commands: @commands + [cmd] + args.map(&:to_s),
-        flags:    @flags,
-        tree:     @tree.dig(cmd.to_sym) || {}
-      )
-    end
-  end
-
-  def respond_to_missing?(name, include_private = false)
-    @tree.key?(name.to_s.tr('_', '-').to_sym) || super
-  end
-
-  def flag(key, value = nil)
-    self.class.new(
-      commands: @commands,
-      flags:    @flags.merge(key.to_s.tr('_', '-') => value),
-      tree:     @tree
-    )
-  end
-
-  def to_a
-    stdout, = Open3.capture2('kubectl', *@commands, *rendered_flags)
-    stdout.lines.map(&:chomp)
-  end
-
-  def to_s
-    ['kubectl', *@commands, *rendered_flags].join(' ')
-  end
-
-  private
-
-  def rendered_flags
-    @flags.flat_map do |k, v|
-      v ? ["--#{k}", v.to_s] : ["--#{k}"]
-    end
-  end
-end
-Which gives you a nice chainable API:
-
-ruby
-Kubectl.new.get('pods')
-  .flag(:namespace, 'production')
-  .flag(:output, 'json')
-  .to_a
-
-Kubectl.new.rollout.status('deployment/my-app')
-  .flag(:namespace, 'staging')
-  .to_a
-
-# Preview without running
-Kubectl.new.get('nodes').flag(:output, 'wide').to_s
-# => "kubectl get nodes --output wide"
-Key design decisions:
-
-Immutable — every chain returns a new instance with merged state, nothing mutates
-method_missing walks the tree — invalid commands raise immediately rather than failing at shell time
-to_a is the forcing function — lazy until you call it, just like ActiveRecord::Relation
-to_s for free previewing — useful for debugging or logging the command before firing it
-If Enumerable would respond to the method missing then make the api call..
-
-10:28
-
-Architected automatic API invocation through Enumerable inclusion
-Architected automatic API invocation through Enumerable inclusion
-Include Enumerable and make each the single forcing function — then all enumerable methods trigger the shell call automatically:
-
-ruby
-include Enumerable
-
-def each(&block)
-  to_a.each(&block)
-end
-
-def method_missing(name, *args, &block)
-  cmd = name.to_s.tr('_', '-')
-
-  if @tree.key?(cmd.to_sym)
-    self.class.new(
-      commands: @commands + [cmd] + args.map(&:to_s),
-      flags:    @flags,
-      tree:     @tree.dig(cmd.to_sym) || {}
-    )
-  elsif Enumerable.method_defined?(name)
-    to_a.public_send(name, *args, &block)
-  else
-    super
-  end
-end
-Now the API call happens naturally:
-
-ruby
-Kubectl.new.get('pods').flag(:namespace, 'production').map { |line| line.split.first }
-Kubectl.new.get('nodes').flag(:output, 'wide').select { |line| line.include?('Ready') }
-Kubectl.new.get('pods').first(3)
-The chain stays lazy until an Enumerable method is hit — at which point each forces to_a which fires the shell command. No explicit .to_a needed.
-
-Okay call this object CommandNode and create an additional object called ResourceNode which handles the deployment.v1.apps pattern... assume we have an array of all supported type.version.group sets.
-
-10:32
-
-Architected nested tree structure for resource type parsing and integration
-Architected nested tree structure for resource type parsing and integration
-ruby
-class ResourceNode
-  # e.g. ["deployments.v1.apps", "pods.v1", "replicasets.v1.apps", ...]
-  TREE = SUPPORTED_TYPES
-    .each_with_object({}) do |type_string, tree|
-      type_string
-        .split('.')
-        .reduce(tree) { |node, segment| node[segment.to_sym] ||= {} }
-    end
-
-  def initialize(path: [], tree: TREE)
-    @path = path
-    @tree = tree
-  end
-
-  def method_missing(name, *args, &block)
-    segment = name.to_s.tr('_', '-')
-
-    @tree.key?(segment.to_sym).then do |valid|
-      raise ArgumentError, "Unknown resource segment: #{segment}" unless valid
-      self.class.new(
-        path: @path + [segment],
-        tree: @tree[segment.to_sym]
-      )
-    end
-  end
-
-  def respond_to_missing?(name, include_private = false)
-    @tree.key?(name.to_s.tr('_', '-').to_sym) || super
-  end
-
-  def to_s
-    @path.join('.')
-  end
-end
-Which then composes naturally with CommandNode:
-
-ruby
-resource = ResourceNode.new.deployments.v1.apps
-
-CommandNode.new
-  .get(resource.to_s)
-  .flag(:namespace, 'production')
-  .map { |line| line.split.first }
-Or you could make CommandNode accept ResourceNode directly by checking in rendered_args:
-
-ruby
-# in CommandNode
-def method_missing(name, *args, &block)
-  cmd = name.to_s.tr('_', '-')
-
-  if @tree.key?(cmd.to_sym)
-    self.class.new(
-      commands: @commands + [cmd] + args.map(&:to_s), # to_s coerces ResourceNode naturally
-      flags:    @flags,
-      tree:     @tree.dig(cmd.to_sym) || {}
-    )
-  elsif Enumerable.method_defined?(name)
-    to_a.public_send(name, *args, &block)
-  else
-    super
-  end
-end
-So the full idiomatic API becomes:
-
-ruby
-CommandNode.new
-  .get(ResourceNode.new.deployments.v1.apps)
-  .flag(:namespace, 'production')
-  .select { |line| line.include?('my-app') }
-The ResourceNode tree is built once at load time from the flat array — segments become nested keys, so method_missing can walk it exactly like CommandNode walks the kubectl command tree.
-
-hmm... this won't work... we need to be able to do Kubectl.get.deployment.v1 etc...
-
-What we need to do it iterate over the schema and create some TreeInstances for each key... so each key turns from a string into a TreeInstance.... then when we're going throuhg our commands we know what the next node should be....
-
-this is not a simple task... there are a lot of moving parts...
-
-**make a plan** to get this right
-
-10:36
-
-Architected tree-node system grafting commands and resources together
-Architected tree-node system grafting commands and resources together
-The Plan
-The core insight: every step in the chain — whether a kubectl command or a resource segment — is the same thing: a node that knows what its valid children are. So we need one universal building block.
-
-1. TreeNode — the universal building block
-TreeNode
-  name:     string
-  children: { name => TreeNode }
-Built at load time. Every key in every tree becomes a TreeNode instance pointing to its children. No method_missing string parsing at runtime — the graph is pre-resolved.
-
-2. Build two trees into TreeNode graphs
-Command tree — from the JSON:
-
-get -> TreeNode(name: "get", children: {})
-rollout -> TreeNode(name: "rollout", children: {
-  status -> TreeNode(...),
-  history -> TreeNode(...)
-})
-Resource tree — from the flat array:
-
-["deployments.v1.apps", "pods.v1", ...]
-  -> deployments -> TreeNode(name: "deployments", children: {
-       v1 -> TreeNode(name: "v1", children: {
-         apps -> TreeNode(name: "apps", children: {})
-       })
-     })
-3. Graft the resource tree onto resource-accepting commands
-Commands like get, delete, describe, edit accept a resource as their next argument. Their children should include the resource tree nodes:
-
-get.children = resource_tree.children  # deployments, pods, nodes...
-This is the key step — it's what lets Kubectl.get.deployments.v1.apps resolve correctly through a single unified method_missing walk.
-
-4. CommandContext — the chainable, lazy evaluator
-CommandContext
-  current_node: TreeNode    # where we are in the graph
-  args:         []          # accumulated path ["get", "deployments.v1.apps"]
-  flags:        {}          # --namespace production etc
-method_missing — looks up name in current_node.children, returns new CommandContext with updated node + args
-flag(key, value) — returns new CommandContext with merged flags
-include Enumerable + each — forces the shell call, the single lazy boundary
-to_s — renders the command without running it
-5. Entry point
-ruby
-module Kubectl
-  def self.method_missing(name, ...)
-    CommandContext.new(current_node: ROOT_COMMAND_NODE, args: [], flags: {})
-      .public_send(name, ...)
-  end
-end
-Load-time sequence
-1. Parse kubectl-command-tree-v1-minimal.json  -> build command TreeNodes
-2. Parse SUPPORTED_TYPES array                 -> build resource TreeNodes  
-3. Graft resource tree onto resource commands  -> stitch the two graphs
-4. Assign root                                 -> ROOT_COMMAND_NODE
-Everything after that is just graph traversal. Sound right before we build it?
-
-Not quite... the tree node has a type... deployment.v1.app is not 3 tree nodes...
-
-10:39
-
-Reconsidered tree structure distinguishing resource nodes from command nodes
-Reconsidered tree structure distinguishing resource nodes from command nodes
-You're right. deployments.v1.apps is one thing — a resource type. The dots are qualifiers on that resource, not tree levels. So:
-
-Revised Plan
-TreeNode has a type:
-
-TreeNode
-  name:     string
-  type:     :command | :resource
-  children: { name => TreeNode }
-The resource tree is flat — one node per resource name:
-
-deployments -> TreeNode(name: "deployments", type: :resource)
-pods        -> TreeNode(name: "pods",        type: :resource)
-Each ResourceNode holds all its possible version.group qualifiers internally:
-
-deployments knows about: ["v1.apps", "v1"]
-pods        knows about: ["v1"]
-So .v1.apps is qualification within the resource node, not tree traversal. The ResourceNode accumulates those segments until it resolves to a known type string.
-
-The chain then looks like:
-
-Kubectl.get          # CommandNode  -> type: :command
-  .deployments       # ResourceNode -> type: :resource, resolved: false
-  .v1                # still ResourceNode, qualifier accumulated
-  .apps              # ResourceNode -> resolved: "deployments.v1.apps"
-  .flag(...)         # back to CommandContext
-  .select { ... }    # forces shell call
-Does that capture what you're thinking?
-
-the Resource nodes don't know anything about any other resource nodes... they only know the command nodes that will come in future... that's how they know they've exited teh resoruce node phase...
-
-what the Kubectl object shuold be ding here at everystep is building a hash datastructure...
-which we end up passing like this...
-
-def to_a
-  QueryBuilder.new(self.command_data).query.to_a
-end
-This means that the primary focus of each stage on method missing is to iterate over the options and return the appropriate node.
-
-Show more
-10:42
-
-Reconciled node architecture with hash-building data flow pattern
-Reconciled node architecture with hash-building data flow pattern
-Ah, now it's much clearer. Each node's only job is:
-
-"given what I know about my valid next steps, what node do I hand back?"
-
-And the whole chain is just accumulating a hash.
-
-Revised Plan
-The data structure being built:
-
-ruby
-{
-  commands:  ["get"],
-  resource:  "deployments.v1.apps",
-  flags:     { namespace: "production" }
-}
-CommandNode — knows its valid subcommands AND the resource names:
-
-method_missing:
-  name in subcommands? -> return CommandNode (append to commands)
-  name in resources?   -> return ResourceNode (start accumulating resource)
-  Enumerable?          -> force shell call
-ResourceNode — knows the supported type strings AND the command nodes:
-
-method_missing:
-  current_accumulation + segment completes a known type? -> stay ResourceNode
-  name in command nodes?  -> exit, return CommandNode
-  Enumerable?             -> force shell call
-The ResourceNode doesn't know other resources — it only knows commands, which is exactly how it detects it's done.
-
-Entry/exit at every step is just:
-
-ruby
-def method_missing(name, ...)
-  next_node(name).new(command_data.merge(...))
-end
-to_a at any point:
-
-ruby
-def to_a
-  QueryBuilder.new(command_data).query.to_a
-end
-Shall we build it?
-
-yes
-
-10:43
-
-Architected Ruby DSL for kubectl command chaining
-Architected Ruby DSL for kubectl command chaining
-ruby
-require 'json'
-require 'open3'
-
-GEM_DIR = File.expand_path('..', __dir__)
-
-COMMAND_TREE = JSON.parse(
-  File.read(File.join(GEM_DIR, 'data', 'kubectl-command-tree-v1-minimal.json')),
-  symbolize_names: true
-)
-
-SUPPORTED_TYPES = %w[
-  deployments.v1.apps
-  pods.v1
-  replicasets.v1.apps
-].freeze
-
-RESOURCE_NAMES = SUPPORTED_TYPES.map { |t| t.split('.').first }.uniq.freeze
-
-class QueryBuilder
-  def initialize(command_data)
-    @commands = command_data[:commands]
-    @resource = command_data[:resource]
-    @flags    = command_data[:flags]
-  end
-
-  def query
-    stdout, = Open3.capture2('kubectl', *@commands, *[@resource].compact, *rendered_flags)
-    stdout.lines.map(&:chomp)
-  end
-
-  private
-
-  def rendered_flags
-    @flags.flat_map { |k, v| v ? ["--#{k}", v.to_s] : ["--#{k}"] }
-  end
-end
-
-class ResourceNode
-  include Enumerable
-
-  COMMAND_NAMES = COMMAND_TREE.keys.map(&:to_s).freeze
-
-  def initialize(command_data:, accumulated:)
-    @command_data = command_data
-    @accumulated  = accumulated
-  end
-
-  def flag(key, value = nil)
-    self.class.new(
-      command_data: @command_data.merge(flags: @command_data[:flags].merge(key => value)),
-      accumulated:  @accumulated
-    )
-  end
-
-  def each(&block)
-    QueryBuilder.new(@command_data.merge(resource: @accumulated)).query.each(&block)
-  end
-
-  def method_missing(name, *args, &block)
-    segment   = name.to_s.tr('_', '-')
-    candidate = [@accumulated, segment].join('.')
-
-    if COMMAND_NAMES.include?(segment)
-      CommandNode.new(
-        command_data: @command_data.merge(resource: @accumulated, commands: @command_data[:commands] + [segment]),
-        tree:         COMMAND_TREE[name]
-      )
-    elsif SUPPORTED_TYPES.any? { |t| t == candidate || t.start_with?("#{candidate}.") }
-      self.class.new(command_data: @command_data, accumulated: candidate)
-    else
-      super
-    end
-  end
-
-  def respond_to_missing?(name, include_private = false)
-    segment   = name.to_s.tr('_', '-')
-    candidate = [@accumulated, segment].join('.')
-
-    COMMAND_NAMES.include?(segment) ||
-      SUPPORTED_TYPES.any? { |t| t == candidate || t.start_with?("#{candidate}.") } ||
-      super
-  end
-end
-
-class CommandNode
-  include Enumerable
-
-  def initialize(command_data: { commands: [], resource: nil, flags: {} }, tree: COMMAND_TREE)
-    @command_data = command_data
-    @tree         = tree
-  end
-
-  def flag(key, value = nil)
-    self.class.new(
-      command_data: @command_data.merge(flags: @command_data[:flags].merge(key => value)),
-      tree:         @tree
-    )
-  end
-
-  def each(&block)
-    QueryBuilder.new(@command_data).query.each(&block)
-  end
-
-  def method_missing(name, *args, &block)
-    segment = name.to_s.tr('_', '-')
-
-    if @tree.key?(name)
-      self.class.new(
-        command_data: @command_data.merge(commands: @command_data[:commands] + [segment]),
-        tree:         @tree[name]
-      )
-    elsif RESOURCE_NAMES.include?(segment)
-      ResourceNode.new(command_data: @command_data, accumulated: segment)
-    else
-      super
-    end
-  end
-
-  def respond_to_missing?(name, include_private = false)
-    segment = name.to_s.tr('_', '-')
-    @tree.key?(name) || RESOURCE_NAMES.include?(segment) || super
-  end
-end
-
-module Kubectl
-  def self.method_missing(name, *args, &block)
-    CommandNode.new.public_send(name, *args, &block)
-  end
-
-  def self.respond_to_missing?(name, include_private = false)
-    CommandNode.new.respond_to?(name) || super
-  end
-end
-The chain then flows like:
-
-ruby
-Kubectl.get.deployments.v1.apps.flag(:namespace, 'production').select { |l| l.include?('my-app') }
-#      ^          ^       ^^^ ResourceNode accumulating
-#      |          |           until Enumerable forces QueryBuilder
-#      |          RESOURCE_NAMES detected -> ResourceNode
-#      CommandNode
-Key things to note:
-
-ResourceNode only exits back to CommandNode if it sees a known command name — that's the only thing it knows about the outside world
-Both nodes accumulate into command_data hash, which is the only thing QueryBuilder ever sees
-each is the single forcing function on both nodes — Enumerable does the rest for free
-

data/bin/generate-command-schema-v1

@@ -1,44 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'json'
-require 'open3'
-
-def extract(args = [])
-  stdout, = Open3.capture2('kubectl', *args, '--help')
-  lines   = stdout.lines
-
-  subcommands = lines
-    .lazy
-    .select { |l| l.match?(/^  \w[\w-]+\s{2,}/) }
-    .map    { |l| l.strip.split(/\s{2,}/).first }
-    .reject { |cmd| cmd == 'help' }
-    .map    { |cmd| [cmd, extract(args + [cmd])] }
-    .to_h
-
-  flags = lines
-    .lazy
-    .select { |l| l.match?(/^\s+--?[\w]/) }
-    .map    { |l| l.strip }
-    .to_a
-
-  { flags:, subcommands: }
-end
-
-def minimize(tree)
-  tree[:subcommands]
-    .transform_values { |v| minimize(v) }
-end
-
-GEM_DIR = File.expand_path('..', __dir__)
-
-extract.then do |tree|
-  File.write(
-    File.join(GEM_DIR, "data", "kubectl-command-tree-v1.json"),
-    JSON.pretty_generate(tree)
-  )
-
-  File.write(
-    File.join(GEM_DIR, "data", "kubectl-command-tree-v1-minimal.json"),
-    JSON.pretty_generate(minimize(tree))
-  )
-end

data/data/kubectl-command-tree-v1-minimal.json

@@ -1,125 +0,0 @@
-{
-  "create": {
-    "clusterrole": {},
-    "clusterrolebinding": {},
-    "configmap": {},
-    "cronjob": {},
-    "deployment": {},
-    "ingress": {},
-    "job": {},
-    "namespace": {},
-    "poddisruptionbudget": {},
-    "priorityclass": {},
-    "quota": {},
-    "role": {},
-    "rolebinding": {},
-    "secret": {
-      "docker-registry": {},
-      "generic": {},
-      "tls": {}
-    },
-    "service": {
-      "clusterip": {},
-      "externalname": {},
-      "loadbalancer": {},
-      "nodeport": {}
-    },
-    "serviceaccount": {},
-    "token": {}
-  },
-  "expose": {},
-  "run": {},
-  "set": {
-    "env": {},
-    "image": {},
-    "resources": {},
-    "selector": {},
-    "serviceaccount": {},
-    "subject": {}
-  },
-  "explain": {},
-  "get": {},
-  "edit": {},
-  "delete": {},
-  "rollout": {
-    "history": {},
-    "pause": {},
-    "restart": {},
-    "resume": {},
-    "status": {},
-    "undo": {}
-  },
-  "scale": {},
-  "autoscale": {},
-  "certificate": {
-    "approve": {},
-    "deny": {}
-  },
-  "cluster-info": {
-    "dump": {}
-  },
-  "top": {
-    "node": {},
-    "pod": {}
-  },
-  "cordon": {},
-  "uncordon": {},
-  "drain": {},
-  "taint": {},
-  "describe": {},
-  "logs": {},
-  "attach": {},
-  "exec": {},
-  "port-forward": {},
-  "proxy": {},
-  "cp": {},
-  "auth": {
-    "can-i": {},
-    "reconcile": {},
-    "whoami": {}
-  },
-  "debug": {},
-  "events": {},
-  "diff": {},
-  "apply": {
-    "edit-last-applied": {},
-    "set-last-applied": {},
-    "view-last-applied": {}
-  },
-  "patch": {},
-  "replace": {},
-  "wait": {},
-  "kustomize": {},
-  "label": {},
-  "annotate": {},
-  "completion": {},
-  "alpha": {
-    "kuberc": {
-      "set": {},
-      "view": {}
-    }
-  },
-  "api-resources": {},
-  "api-versions": {},
-  "config": {
-    "current-context": {},
-    "delete-cluster": {},
-    "delete-context": {},
-    "delete-user": {},
-    "get-clusters": {},
-    "get-contexts": {},
-    "get-users": {},
-    "rename-context": {},
-    "set": {},
-    "set-cluster": {},
-    "set-context": {},
-    "set-credentials": {},
-    "unset": {},
-    "use-context": {},
-    "view": {}
-  },
-  "plugin": {
-    "list": {}
-  },
-  "version": {}
-}