matsuri 0.1.0 → 0.3.0

data/docs/setup.md

@@ -0,0 +1,97 @@
+# Setup
+
+## A Matsuri Repo
+
+The minimal skeleton:
+
+    Gemfile                 # pins the matsuri version (and plugins)
+    bin/matsuri             # wrapper: pins the bundle, nothing else
+    config/
+      matsuri.rb            # marks the repo base; Config overrides
+      platform.rb           # environment definitions
+      initializer.rb        # loads plugins and your library
+    lib/                    # your organization's extension library
+    platform/               # resource definitions
+
+`config/matsuri.rb` is the marker: matsuri finds the repo by walking up
+from the working directory until it sees one. A working example repo
+lives in [tests/example](../tests/example). How the pieces load — the
+wrapper, the environment argument, the initializer — is covered in
+[Boot](boot.md).
+
+## Environments and kubectl Contexts
+
+Every kubectl command matsuri runs is scoped to a context and a
+namespace:
+
+    kubectl --context=<context> --namespace=<namespace> ...
+
+The namespace comes from the environment's platform config (default
+`default`). The context comes from one of two modes.
+
+## Default Mode: the Environment Name Is the Context Name
+
+By default, matsuri assumes a kubeconfig context exists with the same
+name as the environment: `matsuri staging converge myapp` runs
+`kubectl --context=staging ...`. Cluster tools hand out longer names —
+GKE contexts look like `gke_myproject_us-central1_staging` — so matsuri
+provides a verb that binds the environment's name as an alias:
+
+```bash
+matsuri staging kubectl setup
+```
+
+This runs `kubectl config set-context staging` with the cluster, user,
+and namespace drawn from the environment's platform config:
+
+```ruby
+# config/platform.rb
+require 'map'
+
+staging Map.new(
+  namespace:    'myapp',
+  kube_cluster: 'gke_myproject_us-central1_staging',
+  user:         'gke_myproject_us-central1_staging'
+)
+```
+
+`kube_cluster` and `user` default to the environment name when not
+given; `namespace` defaults to `default`.
+
+Setup is a one-time step per environment, and it only creates the alias:
+the cluster and user entries it points at must already exist in your
+kubeconfig. Get them from your provider first — for example
+`gcloud container clusters get-credentials`, or `minikube start` /
+`k3d cluster create`, which write their own entries. Local tools often
+already name their context something usable (`minikube`,
+`k3d-mycluster`), in which case name your environment to match and skip
+setup entirely.
+
+## Mapped Mode: Point the Environment at an Existing Context
+
+If you would rather not alias — letting `gcloud` own authentication and
+context naming, for instance — set `map_env_to_kube_context` and name
+the real context in platform config:
+
+```ruby
+# config/matsuri.rb
+map_env_to_kube_context true
+```
+
+```ruby
+# config/platform.rb
+staging Map.new(
+  namespace:    'myapp',
+  kube_context: 'gke_myproject_us-central1_staging'
+)
+```
+
+With this set, every environment must define `kube_context`;
+`kubectl setup` is unnecessary in this mode.
+
+## Verifying
+
+```bash
+kubectl config get-contexts     # the environment (or mapped) context exists
+matsuri staging status pods     # matsuri reaches the cluster through it
+```

data/docs/ssa.md

@@ -0,0 +1,149 @@
+# Server-Side Apply
+
+Server-side delivery hands the merge to the apiserver: instead of the
+client's three-way last-applied merge, the server tracks which manager
+owns which field and merges by ownership. Choose it when an object's
+fields are genuinely shared — a deployment operator rolls the image, an
+HPA moves the count, an in-place autoscaler adjusts sizing — and the
+repo should own only what it declares.
+
+The posture: matsuri owns exactly the fields the definition declares and
+cedes everything else. The declaration is the ownership record; matsuri
+never reads live state to decide what to send. The constraints behind
+this are in [docs/design/ssa.md](design/ssa.md).
+
+## Enabling It
+
+Server-side apply is one value of the `apply_via` delivery axis, per
+resource:
+
+```ruby
+Matsuri.define :deployment, 'app-web' do
+  let(:apply_via) { :server_side_apply }
+  # ...
+end
+```
+
+Applies are delivered under the repo's field manager —
+`Matsuri::Platform.field_manager`, default `matsuri` — overridable per
+resource with `let(:field_manager)`. Delivery mode and presenter
+pipeline are orthogonal: flipping a resource's `apply_via` never changes
+which presenters run, so members of a stack can migrate individually.
+
+## Declare Only What You Manage
+
+The ongoing payload should carry exactly the fields the repo owns.
+Fields another writer rolls are omitted, not read back: a deployment
+whose image is delivered by an operator declares its containers by name
+without an image, and one whose count an HPA moves declares
+`let(:replicas) { nil }` (Deployment's spec compacts, so nil is clean
+omission). Boot values for those fields ride `:on_create` seeds — see
+[Seeds](presenters.md#seeds) — so the seeded create lands the object
+whole and the seeds end owned by no one.
+
+## Persistence Normal Form
+
+The server does not persist empty values — it drops them on storage —
+and inside an atomic struct like `.spec.selector`, a payload carrying an
+empty member no longer equals the persisted value, which turns the
+creation hand-off into a conflict. An empty collection is also an
+ownership claim over a field the definition does not manage.
+
+So a server-side resource's payloads declare in persistence normal form:
+declare `prune_empty` on both intent regimes, after any seeds, on the
+stack (or the resource):
+
+```ruby
+Matsuri.define :stack, 'app' do
+  needs :deployment, 'app-web'
+  needs :service,    'app-web'
+
+  present :on_create, match_deployments(seed_replicas(2))
+  present :on_create, match_deployments(seed_image('registry.example.com/app:boot'))
+
+  present :on_create, prune_empty
+  present :on_apply,  prune_empty
+end
+```
+
+A field that must be held empty against other writers is a genuine
+assertion, not an accident of rendering — carry it in the exception list
+(`prune_empty(except: [...])`). The mechanics and the exception grammar
+are in [Prune Empty](presenters.md#prune-empty).
+
+## The First Converge
+
+Creation under server-side delivery is a protocol, not a single verb,
+and the delivery verbs run it for you: `apply` (and so converge) routes
+a resource that is not yet live through it, `create` brings one into
+existence through it, and `recreate` tears down and reseeds. Three
+steps:
+
+1.  Create the seeded payload as `<field_manager>-seed`.
+2.  Deliver the declared payload with an ordinary server-side apply.
+    Equal values co-own, which is why normal form matters at this step.
+3.  Cede: atomically remove the seed owner's managedFields entry. The
+    declared fields end solely owned by the field manager; the seeds end
+    unowned, free for the first writer that wants them.
+
+A first converge looks like:
+
+```console
+$ bin/matsuri staging converge app
+deployment.apps/app-web created
+deployment.apps/app-web serverside-applied
+service/app-web created
+```
+
+Every later apply is an ordinary server-side apply. `save_config` is
+pinned false under this mode — a seeded last-applied is a prune trap for
+any later client-side apply — so there is nothing to configure.
+
+The protocol and its refuted alternatives are pinned by
+`tests/bin/probe-ssa.sh`.
+
+## Conflicts
+
+A conflict means another manager owns a field this declaration sends:
+
+    error: Apply failed with 1 conflict: conflict with "some-operator"
+    using apps/v1: .spec.template.spec.containers[name="app"].image
+
+Matsuri never passes `--force-conflicts`; forcing transfers ownership
+and overwrites another party's work, which is a human judgment. Two
+resolutions:
+
+- **Cede the field.** If the other manager is its rightful owner, stop
+  declaring it: omit it from the definition (and seed it on create if
+  the object needs it at creation). This is the common case and lands as
+  an ordinary reviewed change.
+- **Take the field.** If the repo is the rightful owner, take it once
+  with raw kubectl under the repo's manager —
+  `kubectl apply --server-side --force-conflicts --field-manager=matsuri -f -`
+  — then the next matsuri apply is ordinary.
+
+`diff` for a server-side resource dry-runs under the same field manager
+apply uses, so a conflict surfaces in the preview as the same loud error
+delivery would hit.
+
+## An Interrupted First Converge
+
+A converge that dies mid-protocol strands an object still owned by
+`<field_manager>-seed` — the cede never ran, so the seed owner holds its
+fields forever and a retry conflicts with it. Recognize it by reading
+ownership:
+
+```console
+$ kubectl get deployment app-web --show-managed-fields -o json \
+    | jq '[.metadata.managedFields[].manager]'
+```
+
+If `matsuri-seed` appears on an object whose converge is not currently
+running, the recovery is to delete the object and reconverge — the
+seeding protocol runs only at creation, so it must restart from a clean
+create:
+
+```console
+$ kubectl delete deployment app-web
+$ bin/matsuri staging converge app
+```

data/docs/stacks.md

@@ -0,0 +1,146 @@
+# Stacks
+
+Stacks are groupings of resources that are managed together.
+
+## Defining Stacks
+
+Stacks are defined in `platform/stacks` with a DSL that defines
+resources that are needed. It takes an argument that references a
+Matsuri definition and type.
+
+```ruby
+# platform/stacks/app.rb
+#
+# One management promise: the app's bulkheads, the service fronting
+# them, and the settings they share converge as one act, in this
+# sequence.
+Matsuri.define :stack, 'app' do
+  needs :config_map, 'app-settings'
+  needs :deployment, 'app-web'
+  needs :deployment, 'app-web-streams'
+  needs :deployment, 'app-worker-general'
+  needs :service,    'app-web'
+end
+```
+
+Each member stays independently addressable through the registry — the
+stack adds sequence and shared bindings, not a new kind of resource.
+
+At this time, there is no way to define dependencies. Applying the
+manifest is performed in sequence.
+
+## Operation
+
+    matsuri <env> converge <stack name>
+
+The converge operation applies changes in sequence as defined by the
+stack.
+
+## Stack Config
+
+We can pass a configuration yaml file into the stack that can be
+referenced by resources. This is intended to parameterize an entire
+stack. The main use-case is to support dynamic environments used within
+software development lifecycle.
+
+```yaml
+# stack-config.yaml
+name: app-feat-checkout
+namespace: feat-checkout
+log_level: debug
+expires_at: "2026-11-15"
+contact: team-checkout
+```
+
+The stack declares which acceptor admits the artifact with
+`accept :config`; the acceptor owns the vocabulary and the defaults (see
+[Acceptors](acceptors.md)):
+
+```ruby
+# platform/acceptors/app.rb
+Matsuri.define :acceptor, 'app' do
+  let(:artifact) { options || {} }
+
+  let(:instance_name) { artifact[:name] }
+  let(:namespace)     { artifact[:namespace] }
+  let(:log_level)     { artifact[:log_level] || 'info' }
+end
+
+# platform/stacks/app.rb
+Matsuri.define :stack, 'app' do
+  accept :config, 'app'
+
+  needs :config_map, 'app-settings'
+  needs :deployment, 'app-web'
+  needs :service,    'app-web'
+end
+```
+
+Every member resource reads the same binding through `stack_config`:
+
+```ruby
+# platform/config_maps/app-settings.rb
+Matsuri.define :config_map, 'app-settings' do
+  let(:data) do
+    { 'LOG_LEVEL' => stack_config.log_level }
+  end
+end
+```
+
+The artifact rides in on the converge:
+
+    matsuri <env> converge app --stack-config stack-config.yaml
+
+Without the flag, every read lands on the acceptor's defaults — the
+unconfigured stack behaves exactly as it did before the config surface
+existed. Stack-config never crosses a stack boundary: a nested stack
+reads only its own declarations.
+
+## Server Side Apply
+
+Stacks and resources can optionally use server side apply, in
+combination with seeds.
+
+We can also define seed presenters for stacks and resources on the
+initial create. When combined with server side apply, Matsuri cedes
+field management of those values. These presenters are not applied when
+applying after resources are created. This allows other operators to
+claim field management, while matsuri retains management over the
+remaining fields.
+
+Examples include seeded images (for deployment operators), replicas
+(horizontal pod autoscaler), and resources (in-place pod autoscaling).
+
+```ruby
+# platform/deployments/app-web.rb
+Matsuri.define :deployment, 'app-web' do
+  let(:apply_via)    { :server_side_apply } # deliver by field ownership
+  let(:replicas)     { nil }                # omitted: the autoscaler owns the count
+  let(:match_labels) { { 'app' => 'web' } }
+  let(:pod_name)     { 'app' }              # pod 'app' carries no image —
+                                            # a deployment operator owns the tag
+end
+
+# platform/stacks/app.rb
+Matsuri.define :stack, 'app' do
+  needs :config_map, 'app-settings'
+  needs :deployment, 'app-web'
+  needs :service,    'app-web'
+
+  present :on_create, match_deployments(seed_replicas(2))
+  present :on_create, match_deployments(seed_image('registry.example.com/app:boot'))
+end
+```
+
+The first converge of a server-side resource routes through the seeding
+protocol (seeded create, declared apply, cede); every later apply is an
+ordinary server-side apply. Converge is sequential, so a member later in
+the stack converges only after an earlier member is fully seeded and
+ceded. The operator walkthrough — declaring only what you manage,
+conflicts, interrupted converges — is [Server-Side Apply](ssa.md); the
+full model of seeds and field managers is in the Seeds section of
+[Presenters](presenters.md).
+
+See also the seed and delivery specs:
+[spec/presenters/seeds_spec.rb](../spec/presenters/seeds_spec.rb) and
+[spec/tasks/stacks/seed_spec.rb](../spec/tasks/stacks/seed_spec.rb).

data/flake.lock

@@ -0,0 +1,61 @@
+{
+  "nodes": {
+    "flake-utils": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1791914995,
+        "narHash": "sha256-Zf/xfQEAasnwnmEfHqW/4hjDE/s44yn2hD4RuVIZRjA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "b7a79d3fea1e214f6d668d521cecec0c01e26544",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1792615934,
+        "narHash": "sha256-MlvRfa1O5Cqc2/a+gG+l9TSuowEoCKCmrJ1d9oAVm0I=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "da6dc0e7b26060f2f71ce3ef7088fb56ee44fa36",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-26.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "flake-utils": "flake-utils",
+        "nixpkgs": "nixpkgs"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/flake.nix

@@ -0,0 +1,35 @@
+{
+  description = "Matsuri dev environment";
+
+  inputs = {
+    nixpkgs = {
+      url = "github:NixOS/nixpkgs/nixos-26.05"; # Or a specific stable channel like "nixos-24.05"
+    };
+    flake-utils = {
+      url = "github:numtide/flake-utils";
+    };
+  };
+
+  outputs = { self, nixpkgs, flake-utils }:
+    flake-utils.lib.eachDefaultSystem(system:
+      let
+        pkgs = import nixpkgs {
+          inherit system;
+          # overlays = [ ];
+        };
+      in
+        with pkgs; {
+          devShell = mkShell {
+            buildInputs = [
+              ruby_4_0
+              pandoc
+
+              # Cluster harness for tests/ (delivery semantics probes)
+              minikube
+              kubectl
+            ] ++ lib.optionals stdenv.isDarwin [
+              vfkit # hypervisor backend for minikube on macOS
+            ];
+          };
+    });
+}

data/lib/matsuri/acceptor.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'rlet'
+require 'rlet/lazy_options'
+
+module Matsuri
+  # An acceptor admits a value whose vocabulary matsuri does not own, such as
+  # a stack-config artifact. The raw value arrives whole as options; the lets
+  # declared here are the accepted surface, and members read the acceptor
+  # instead of the raw value. Fields the acceptor does not declare are
+  # ignored. Reads the acceptor does not declare raise NoMethodError. There
+  # is no fallback to the underlying value.
+  #
+  # The empty value belongs to the acceptor: every declared read is total
+  # over nil, because what nil means is collection-specific. A scalar
+  # surface reads options whole (options || default); a hash-shaped surface
+  # anchors once with let(:artifact) { options || {} } and reads fields off
+  # the anchor.
+  class Acceptor
+    include Let
+    include RLet::LazyOptions
+
+    class << self
+      def load_path
+        Matsuri::Config.acceptors_path
+      end
+
+      def definition_module_name
+        'Acceptors'
+      end
+    end
+  end
+end

data/lib/matsuri/acceptors/image_tag.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require 'matsuri/acceptor'
+
+module Matsuri
+  module Acceptors
+    # Built-in acceptor for the :image_tag collection on stacks. Maps the
+    # converge positional — a scalar, admitted whole — onto the declared
+    # surface. The 'latest' default lives here and nowhere else; a platform
+    # overrides it by re-declaring the collection with its own acceptor.
+    class ImageTag < Matsuri::Acceptor
+      let(:image_tag) { options || 'latest' }
+    end
+  end
+end

data/lib/matsuri/cmd.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'map'
+require 'rlet'
+require 'yaml'
+require 'matsuri/core_ext'
+
+module Matsuri
+  module Cmd
+    extend Concern
+
+    included do
+      private
+
+      def with_config(opts = {})
+        _final_options = final_options(opts)
+
+        Matsuri::Config.apply_configuration(_final_options)
+
+        yield _final_options
+      end
+
+      def final_options(opts = {})
+        options.merge(parent_options || {}).merge(opts).deep_symbolize_keys
+      end
+
+      # The CLI owns the boundary mapping; the built-in ImageTag acceptor
+      # owns the default — the same single owner the stack :image_tag
+      # collection uses. The positional may be nil.
+      def image_tag_for(positional)
+        Matsuri::Acceptors::ImageTag.new(positional).image_tag
+      end
+
+      # The CLI owns the boundary mapping: --stack-config= names a path,
+      # the stack's :config collection expects data. No flag is the empty
+      # value; a flag with a bad path fails loudly, never falls back.
+      def stack_config_data(opt)
+        path = opt[:stack_config]
+        return nil unless path
+
+        Matsuri.log(:fatal, "stack-config not found: #{path}") unless File.file?(path)
+        Map.new(YAML.safe_load_file(path, aliases: true))
+      end
+    end
+  end
+end

data/lib/matsuri/cmds/apply.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require 'matsuri/core_ext'
+
+module Matsuri
+  module Cmds
+    class Apply < Thor
+      include Matsuri::Cmd
+
+      def self.apply_cmd_for(resource_name, image_tag: false)
+        unless image_tag
+          define_method(resource_name) do |name = :not_specified|
+            apply_resource { Matsuri::Registry.fetch_or_load(resource_name, name).new }
+          end
+        else
+          define_method(resource_name) do |name = :not_specified, image_tag = nil|
+            apply_resource { Matsuri::Registry.fetch_or_load(resource_name, name).new(image_tag: image_tag_for(image_tag)) }
+          end
+        end
+      end
+
+      desc 'imported_manifest NAME', 'apply changes to an imported manifest'
+      apply_cmd_for :imported_manifest
+
+      desc 'pod POD_NAME', 'apply changes to a pod'
+      apply_cmd_for :pod, image_tag: true
+
+      desc 'replica-set REPLICA-SET_NAME', 'apply changes to a replica-set'
+      apply_cmd_for :replica_set, image_tag: true
+      map replicaset: :replica_set
+      map rs: :replica_set
+
+      desc 'stateful-set STATEFUL_SET_NAME', 'apply changes for stateful_set'
+      apply_cmd_for :stateful_set, image_tag: true
+      map sts: :stateful_set
+
+      desc 'daemon-set DAEMON_SET_NAME', 'apply changes for daemon_set'
+      apply_cmd_for :daemon_set, image_tag: true
+      map ds: :daemon_set
+
+      desc 'deployment DEPLOYMENT_NAME', 'apply changes to a deployment'
+      apply_cmd_for :deployment, image_tag: true
+      map deploy: :deployment
+
+      desc 'cron-job CRONJOB_NAME', 'apply changes to a cronjob'
+      apply_cmd_for :cron_job, image_tag: true
+      map cj: :cron_job
+      map cronjob: :cron_job
+
+      desc 'service SERVICE_NAME', 'apply changes to a service'
+      apply_cmd_for :service
+
+      desc 'ingress INGRESS_NAME', 'apply changes to a ingress'
+      apply_cmd_for :ingress
+
+      desc 'secret SECRET_NAME', 'apply changes to a secret'
+      apply_cmd_for :secret
+
+      desc 'config-map CONFIG_MAP_NAME', 'apply changes to a config map'
+      apply_cmd_for :config_map, image_tag: true
+      map configmap: :config_map
+      map cm: :config_map
+
+      desc 'horizontal_pod_autoscaler HPA_NAME', 'apply changes to a horizontal pod autoscaler'
+      apply_cmd_for :horizontal_pod_autoscaler
+      map hpa: :horizontal_pod_autoscaler
+
+      private
+
+      def apply_resource
+        with_config do |opt|
+          resource = yield
+          Matsuri::Tasks::KubectlOps.apply(resource)
+        end
+      end
+    end
+  end
+end