matsuri 0.1.0 → 0.3.0

data/tests/bin/probe-ssa.sh

@@ -0,0 +1,206 @@
+#!/bin/bash
+set -euo pipefail
+
+# Probes the creation protocol the seeds+SSA posture rests on, before any
+# SSA code lands. Hard expectations (FAIL) pin the invariants the design
+# assumes; REPORT legs are open questions whose answers shape the design.
+#
+# The seed that matters is the IMAGE: the ongoing declaration omits it
+# (the container entry rides on its name key alone) and another writer
+# delivers it. Replicas is the second seed; a declared env var is the
+# ongoing manager's own changeable field.
+#
+#   F. seed via create under the seed owner (a disposable manager derived
+#      from the ongoing one), then the ordinary declared SSA apply, then
+#      remove the seed owner's managedFields entry with an atomic
+#      test+remove JSON patch.
+#      managedFields is never empty when an apply arrives (so the server
+#      never invents before-first-apply), the seeds end unowned, and the
+#      ongoing applier ends sole owner of the declared fields.
+#      F1  EXPECT  create --field-manager=<seed owner> lands both seeds
+#      F2  EXPECT  the declared apply is accepted with the image absent
+#                  from the container entry (keyed-list partial), seeds
+#                  untouched, and the ongoing manager never owns image
+#      F3  EXPECT  test+remove of the seed owner's entry applies (<=3
+#                  attempts; the test op makes a stale index a loud
+#                  retry, not a wrong removal)
+#      F4  EXPECT  values intact; seed owner entry gone; image AND replicas
+#                  unowned; raw managedFields dumped for verification
+#      F5  EXPECT  changing a declared value is clean -- the leg every
+#                  refuted path failed -- and both seeds are untouched
+#      F6  EXPECT  image delivery via kubectl set image (update-family)
+#                  is clean, and the next omitting apply leaves the
+#                  delivered image alone
+#      F7  EXPECT  after kubectl scale, an omitting apply leaves
+#                  replicas alone
+#      F8  EXPECT  a different manager changing an owned field conflicts
+#      F9  REPORT  diff --server-side surfaces that conflict (exit 2)
+#      F10 EXPECT  re-running the seeded create is loud (AlreadyExists)
+#      F11 REPORT  last-applied state; EXPECT it never carries a seed
+#                  (the CSA prune trap)
+#
+# Ownership claims are live reads: owners() runs a fresh get
+# --show-managed-fields per call and scans every entry's fieldsV1 for
+# the field's path; the raw dumps in F4/F6/F7 print the entries
+# verbatim (status/metadata pruned) so "unowned" is checkable against
+# the record, not the filter.
+#
+# Refuted alternatives, pruned from the probe after earlier runs:
+#   - create then SSA directly: the create manager's Update entry co-owns every
+#     seeded field and never relinquishes; the first changed-value apply
+#     conflicts permanently.
+#   - create under the SAME name the applies use: an Update entry and an
+#     Apply entry are distinct managers; the conflict remains.
+#   - seed on the first SSA apply: the next apply that omits the seed
+#     relinquishes the field and the server resets it.
+#   - wipe managedFields BEFORE the first apply (patch or embedded in the
+#     create body): an apply against empty managedFields attributes every
+#     existing field to the synthetic manager before-first-apply, which
+#     never relinquishes; the same dead end under another name.
+#
+# Start the cluster with bin/minikube-start.sh first. kubectl dials the
+# VM: on macOS run from a Local Network-granted context (not tmux).
+
+TESTS_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+CONTEXT="${CONTEXT:-matsuri}"
+MANAGER="${MANAGER:-matsuri}"
+OTHER_MANAGER="${OTHER_MANAGER:-other}"
+# Disposable but deliberate: the F3 removal predicate keys on this name,
+# and a converge that dies before F3 strands an object whose managedFields
+# should read as ours. The seed owner is derived from the ongoing manager
+# (<manager>-seed), matching Tasks::Stacks::Seed.
+CREATE_MANAGER="${CREATE_MANAGER:-${MANAGER}-seed}"
+K8S="${TESTS_DIR}/k8s/ssa"
+KUBECTL=(kubectl --context "${CONTEXT}" --namespace matsuri-probes)
+
+fail()   { echo "FAIL: $*" >&2; exit 1; }
+report() { echo "REPORT $*"; }
+
+ssa() { "${KUBECTL[@]}" apply --server-side --field-manager="${MANAGER}" -f "$1"; }
+
+replicas() { "${KUBECTL[@]}" get deployment "$1" -o jsonpath='{.spec.replicas}'; }
+image()    { "${KUBECTL[@]}" get deployment "$1" -o jsonpath='{.spec.template.spec.containers[0].image}'; }
+declared() { "${KUBECTL[@]}" get deployment "$1" -o jsonpath='{.spec.template.spec.containers[0].env[?(@.name=="DECLARED")].value}'; }
+
+# every manager/operation pair on the object
+managers() { # managers <deployment>
+  "${KUBECTL[@]}" get deployment "$1" --show-managed-fields -o json |
+    jq -r '[.metadata.managedFields[]? | "\(.manager)/\(.operation)"] | join(" ")'
+}
+
+# manager/operation pairs owning the given field, from a fresh read
+owners() { # owners <deployment> replicas|image|env
+  local path
+  case "$2" in
+    replicas) path='["fieldsV1","f:spec","f:replicas"]' ;;
+    image)    path='["fieldsV1","f:spec","f:template","f:spec","f:containers","k:{\"name\":\"pause\"}","f:image"]' ;;
+    env)      path='["fieldsV1","f:spec","f:template","f:spec","f:containers","k:{\"name\":\"pause\"}","f:env","k:{\"name\":\"DECLARED\"}"]' ;;
+  esac
+  "${KUBECTL[@]}" get deployment "$1" --show-managed-fields -o json |
+    jq -r --argjson p "${path}" '.metadata.managedFields[] | select(getpath($p) != null) | "\(.manager)/\(.operation)"' |
+    paste -sd ' ' -
+}
+
+# the managedFields entries verbatim, status/metadata pruned for reading
+managed_fields_raw() { # managed_fields_raw <deployment>
+  "${KUBECTL[@]}" get deployment "$1" --show-managed-fields -o json |
+    jq -c '.metadata.managedFields[]? | {manager, operation, subresource, fieldsV1: (.fieldsV1 | del(."f:status", ."f:metadata"))}' |
+    sed 's/^/    /'
+}
+
+report "versions: $(kubectl --context "${CONTEXT}" version -o json 2>/dev/null | jq -r '"client \(.clientVersion.gitVersion) / server \(.serverVersion.gitVersion)"')"
+
+kubectl --context "${CONTEXT}" apply -f "${K8S}/namespace.yaml"
+"${KUBECTL[@]}" delete deployment seed-via-create --ignore-not-found --wait
+
+echo '--- Path F: seed via create, declared apply, then remove the seed owner entry ---'
+
+"${KUBECTL[@]}" create --field-manager="${CREATE_MANAGER}" -f "${K8S}/seed-via-create.yaml"
+[ "$(replicas seed-via-create)" = "3" ] || fail "F1 create did not land the seeded replicas (replicas=$(replicas seed-via-create))"
+[ "$(image seed-via-create)" = "registry.k8s.io/pause:3.9" ] || fail "F1 create did not land the seeded image (image=$(image seed-via-create))"
+report "F1 managers at birth: [$(managers seed-via-create)]"
+
+ssa "${K8S}/declared.yaml" || fail "F2 the declared apply was rejected -- a container entry cannot omit its image"
+[ "$(replicas seed-via-create)" = "3" ] || fail "F2 declared apply disturbed the seeded replicas (replicas=$(replicas seed-via-create))"
+[ "$(image seed-via-create)" = "registry.k8s.io/pause:3.9" ] || fail "F2 declared apply disturbed the seeded image (image=$(image seed-via-create))"
+case " $(owners seed-via-create image) " in
+  *" ${MANAGER}/"*) fail "F2 the ongoing manager owns the image it never sent" ;;
+esac
+report "F2 after declared apply: image owned by [$(owners seed-via-create image)], env owned by [$(owners seed-via-create env)]"
+
+patched=""
+for attempt in 1 2 3; do
+  idx="$("${KUBECTL[@]}" get deployment seed-via-create --show-managed-fields -o json |
+    jq --arg m "${CREATE_MANAGER}" '[.metadata.managedFields[].manager] | index($m)')"
+  [ "${idx}" != "null" ] || fail "F3 no ${CREATE_MANAGER} entry to remove"
+  if "${KUBECTL[@]}" patch deployment seed-via-create --type=json -p "[
+      {\"op\":\"test\",\"path\":\"/metadata/managedFields/${idx}/manager\",\"value\":\"${CREATE_MANAGER}\"},
+      {\"op\":\"remove\",\"path\":\"/metadata/managedFields/${idx}\"}
+    ]"; then
+    patched="yes"
+    [ "${attempt}" = "1" ] || report "F3 removal needed ${attempt} attempts (object changed under the read)"
+    break
+  fi
+done
+[ -n "${patched}" ] || fail "F3 test+remove lost the race 3 times"
+report "F3 managers after removal: [$(managers seed-via-create)]"
+
+[ "$(replicas seed-via-create)" = "3" ] || fail "F4 the removal disturbed the seeded replicas (replicas=$(replicas seed-via-create))"
+[ "$(image seed-via-create)" = "registry.k8s.io/pause:3.9" ] || fail "F4 the removal disturbed the seeded image (image=$(image seed-via-create))"
+case " $(managers seed-via-create) " in
+  *" ${CREATE_MANAGER}/"*) fail "F4 the ${CREATE_MANAGER} entry survived the removal" ;;
+esac
+[ -z "$(owners seed-via-create image)" ] || fail "F4 image still owned by [$(owners seed-via-create image)] -- expected unowned"
+[ -z "$(owners seed-via-create replicas)" ] || fail "F4 replicas still owned by [$(owners seed-via-create replicas)] -- expected unowned"
+report "F4 seeds unowned, env owned by [$(owners seed-via-create env)]; managedFields verbatim:"
+managed_fields_raw seed-via-create
+
+ssa "${K8S}/declared-bumped.yaml" || fail "F5 changing a declared value conflicted -- the dead-end survives the seed-owner removal"
+[ "$(declared seed-via-create)" = "two" ] || fail "F5 the declared change did not land (DECLARED=$(declared seed-via-create))"
+[ "$(replicas seed-via-create)" = "3" ] || fail "F5 the declared change disturbed the unowned replicas (replicas=$(replicas seed-via-create)) -- a ghost manager came back"
+[ "$(image seed-via-create)" = "registry.k8s.io/pause:3.9" ] || fail "F5 the declared change disturbed the unowned image (image=$(image seed-via-create)) -- a ghost manager came back"
+echo "F5 changed-declared apply clean -- the ongoing-delivery dead-end is gone"
+report "F5 env owned by [$(owners seed-via-create env)]"
+
+"${KUBECTL[@]}" set image deployment/seed-via-create pause=registry.k8s.io/pause:3.10
+[ "$(image seed-via-create)" = "registry.k8s.io/pause:3.10" ] || fail "F6 image delivery did not land (image=$(image seed-via-create))"
+ssa "${K8S}/declared-bumped.yaml"
+[ "$(image seed-via-create)" = "registry.k8s.io/pause:3.10" ] || fail "F6 omitting apply disturbed the delivered image (image=$(image seed-via-create))"
+report "F6 delivered image stands; image owned by [$(owners seed-via-create image)]; managedFields verbatim:"
+managed_fields_raw seed-via-create
+
+"${KUBECTL[@]}" scale deployment seed-via-create --replicas=5
+ssa "${K8S}/declared-bumped.yaml"
+[ "$(replicas seed-via-create)" = "5" ] || fail "F7 omitting apply disturbed scaled replicas (replicas=$(replicas seed-via-create))"
+report "F7 after scale: replicas owned by [$(owners seed-via-create replicas)]; managedFields verbatim:"
+managed_fields_raw seed-via-create
+
+if out="$("${KUBECTL[@]}" apply --server-side --field-manager="${OTHER_MANAGER}" -f "${K8S}/declared.yaml" 2>&1)"; then
+  fail "F8 a different manager changed an owned field without conflict"
+fi
+echo "F8 cross-manager change conflicts (frontier intact)"
+
+set +e
+out="$("${KUBECTL[@]}" diff --server-side --field-manager="${OTHER_MANAGER}" -f "${K8S}/declared.yaml" 2>&1)"
+rc=$?
+set -e
+report "F9 diff --server-side of the conflicting payload: exit=${rc} (2 = conflict surfaced)"
+echo "${out}" | head -5 | sed 's/^/    /'
+
+if out="$("${KUBECTL[@]}" create --field-manager="${CREATE_MANAGER}" -f "${K8S}/seed-via-create.yaml" 2>&1)"; then
+  fail "F10 re-running the seeded create silently succeeded"
+fi
+echo "F10 re-running the seeded create is loud:"
+echo "${out}" | sed 's/^/    /'
+
+if la="$("${KUBECTL[@]}" apply view-last-applied deployment seed-via-create 2>/dev/null)"; then
+  report "F11 last-applied content:"
+  echo "${la}" | sed 's/^/    /'
+  if echo "${la}" | grep -Eq 'replicas|image'; then
+    fail "F11 last-applied carries a seed -- the CSA prune trap is loaded"
+  fi
+else
+  report "F11 no last-applied annotation"
+fi
+
+echo "PASS: the creation protocol held; read the REPORT lines for ownership detail"

data/tests/example/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/tests/example/Gemfile

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# A real platform repo pins a version: gem 'matsuri', '~> 0.3'
+# This example runs against the working tree.
+gem 'matsuri', path: '../..'

data/tests/example/README.md

@@ -0,0 +1,91 @@
+# Example Matsuri Repo
+
+A working Matsuri platform repo. It boots against the minikube test
+cluster, and it showcases the layout a real repo follows (see
+docs/setup.md in the matsuri repo): a Gemfile pinning the matsuri
+version, a `bin/matsuri` wrapper, config, an org extension library
+(`lib/acme`), and resource definitions under `platform/`.
+
+Two stacks demonstrate the two delivery modes:
+
+- **billing** — classic client-side delivery. Matsuri owns every
+  field: replicas are declared, the image tracks the converge
+  positional.
+- **checkout** — server-side delivery. The deployment applies by field
+  ownership; matsuri omits the image, replicas, and resources, seeds
+  them at creation, and cedes them to the operators that will own them
+  (deployment operator, HPA, in-place autoscaler).
+
+## Prerequisites
+
+The minikube test cluster must be running under the `matsuri` profile:
+
+```bash
+# from the matsuri repo root
+tests/bin/minikube-start.sh
+```
+
+The script also applies `platform/namespaces/` — raw manifests, outside
+matsuri, because namespaces precede anything matsuri converges.
+
+**macOS gotcha:** kubectl and minikube dial the VM over the local
+network, which macOS gates behind a Local Network permission. Run from
+a terminal that has the grant (System Settings → Privacy & Security →
+Local Network). tmux counts as its own responsible process and cannot
+be granted from the CLI — `no route to host` from inside tmux while the
+cluster is fine is this, not the cluster.
+
+Then, from this directory:
+
+```bash
+bundle install
+```
+
+## Creating the Stacks
+
+The first converge creates everything a stack needs:
+
+```bash
+bin/matsuri local_billing_dev converge billing
+bin/matsuri local_checkout_dev converge checkout
+```
+
+Each stack has its own local environment, pointed at the minikube
+cluster with its own namespace (`billing-dev`, `checkout-dev`); see
+`config/platform.rb`. Checkout's first converge routes through the
+seeding protocol: a seeded create completes the boot payload, the
+declared server-side apply takes ownership of matsuri's fields, and the
+seed owner cedes the rest.
+
+## Applying Changes
+
+Edit a definition, preview, then converge the stack:
+
+```bash
+bin/matsuri local_billing_dev diff stack billing     # what would change
+bin/matsuri local_billing_dev converge billing       # apply it
+```
+
+`show stack <name>` renders the full manifests without touching the
+cluster.
+
+For **billing**, a new image rides the converge positional:
+
+```bash
+bin/matsuri local_billing_dev converge billing v1.2.3
+```
+
+For **checkout**, matsuri never carries the image: converge reapplies
+only the declared fields, and the seeded trio stays with whatever
+manager owns it. To play the deployment operator locally:
+
+```bash
+kubectl --context matsuri -n checkout-dev \
+  set image deployment/checkout-web checkout=registry.acme.io/checkout:v2
+bin/matsuri local_checkout_dev converge checkout   # does not claw it back
+```
+
+The staging environments (`billing_staging`, `checkout_staging`) are
+illustrative — they name a cluster that does not exist — and add the
+node-selection vocabulary the local environments leave out (see the
+`case Matsuri.environment` in `platform/pods/`).

data/tests/example/bin/matsuri

@@ -0,0 +1,14 @@
+#!/bin/bash -e
+
+# Pin the bundle to this repo's Gemfile and exec. That is the wrapper's
+# entire job: the Gemfile owns which matsuri runs (see docs/design/boot.md
+# in the matsuri repo). Invoke from the repo base.
+#
+# A per-environment entry point is argument injection, in a sibling script:
+#   exec "$(dirname "$0")/matsuri" staging "$@"
+SCRIPT_DIR="$(dirname "$(realpath "${BASH_SOURCE[0]}")")"
+PLATFORM_DIR="${SCRIPT_DIR}/.."
+
+export BUNDLE_GEMFILE="${PLATFORM_DIR}/Gemfile"
+
+exec bundle exec matsuri "$@"

data/tests/example/config/initializer.rb

@@ -0,0 +1,12 @@
+# Initializer for this repo
+# This is where you load plugins and libraries specific to this repository
+
+# Plugins
+# require 'matsuri/traefik'
+# require 'matsuri/helm'
+
+# Local extensions
+# Add into the local library. You can name it after
+# your organization. Here, we'll use Acme
+
+require 'acme'

data/tests/example/config/matsuri.rb

@@ -0,0 +1,9 @@
+# Overrides Matsuri::Config
+
+# Environment names are not kubectl context names here; each
+# environment names its context in config/platform.rb
+map_env_to_kube_context true
+
+# Should not be storing secrets locally
+# This is for demonstration only
+default(:config_secrets_path) { File.join base_path, 'etc', 'secrets' }

data/tests/example/config/platform.rb

@@ -0,0 +1,39 @@
+# This sets up different Matsuri environments
+#
+# Environment names map to kubectl contexts via kube_context
+# (map_env_to_kube_context is set in config/matsuri.rb). The local
+# environments all point at the minikube "matsuri" profile, one
+# namespace per stack.
+
+config_context :local_app_dev do
+  default(:kube_context) { 'matsuri' }
+  default(:region)       { 'local' }
+  default(:namespace)    { 'app-dev' }
+end
+
+config_context :local_billing_dev do
+  default(:kube_context) { 'matsuri' }
+  default(:region)       { 'local' }
+  default(:namespace)    { 'billing-dev' }
+end
+
+config_context :local_checkout_dev do
+  default(:kube_context) { 'matsuri' }
+  default(:region)       { 'local' }
+  default(:namespace)    { 'checkout-dev' }
+end
+
+# Staging contexts are illustrative: a real repo names the context the
+# provider hands out (for GKE, let gcloud own authentication and
+# naming).
+config_context :billing_staging do
+  default(:kube_context) { 'gke_acme-platform_us-central1_staging' }
+  default(:region)       { 'us-central1' }
+  default(:namespace)    { 'billing' }
+end
+
+config_context :checkout_staging do
+  default(:kube_context) { 'gke_acme-platform_us-central1_staging' }
+  default(:region)       { 'us-central1' }
+  default(:namespace)    { 'checkout' }
+end

data/tests/example/lib/acme/nodes/dedicated.rb

@@ -0,0 +1,26 @@
+# Acme's Elixir workloads can efficiently use up the entire node.
+# This mixins adds helpers for scheduling workloads on nodepools
+# set aside for that
+
+module Acme
+  module Nodes
+    module Dedicated
+      extend Concern
+
+      included do
+        let(:dedicated_key) { fail Matsuri::UndefinedLet, "Must define let(:dedicated_key)" }
+
+        let(:dedicated_node_selector) { { 'dedicated' => dedicated_key } }
+        let(:dedicated_toleration) do
+          tolerate \
+            key:      'dedicated',
+            operator: 'Equal',
+            value:     dedicated_key,
+            effect:    'NoSchedule'
+        end
+      end
+    end
+  end
+end
+
+

data/tests/example/lib/acme/nodes/preemptible.rb

@@ -0,0 +1,17 @@
+# Acme set aside nodegroups that are preemptible
+module Acme
+  module Nodes
+    module Preemptible
+      extend Concern
+
+      included do
+        let(:preemptible_toleration) do
+          tolerate \
+            key:       'preemptible',
+            operator: 'Exists',
+            effect:    'NoSchedule'
+        end
+      end
+    end
+  end
+end

data/tests/example/lib/acme/nodes/required_cores.rb

@@ -0,0 +1,26 @@
+# Acme's Elixir workloads can efficiently use up the entire node.
+# This mixins adds helpers for scheduling workloads on nodepools
+# set aside for that
+
+module Acme
+  module Nodes
+    module RequiredCores
+      extend Concern
+
+      included do
+        let(:required_cores) { fail Matsuri::UndefinedLet, "Must define let(:required_cores)" }
+
+        let(:cores_node_selector) { { 'cores' => required_cores } }
+        let(:cores_toleration) do
+          tolerate \
+            key:       'cores',
+            operator: 'Equal',
+            value:     required_cores,
+            effect:    'NoSchedule'
+        end
+      end
+    end
+  end
+end
+
+

data/tests/example/lib/acme/nodes/resource_class.rb

@@ -0,0 +1,26 @@
+# Acme's Elixir workloads can efficiently use up the entire node.
+# This mixins adds helpers for scheduling workloads on nodepools
+# set aside for that
+
+module Acme
+  module Nodes
+    module ResourceClass
+      extend Concern
+
+      included do
+        let(:big_disk_toleration) { tolerate_resource_class('big-disk') }
+        let(:stateful)            { tolerate_resource_class('stateful') }
+        let(:autopilot)           { tolerate_resource_class('autopilot') }
+      end
+
+      def tolerate_resource_class(resource_class_key)
+          tolerate \
+            key:      'k8s.acme.io/resource-class',
+            operator: 'Equal',
+            value:     resource_class_key,
+            effect:    'NoSchedule'
+      end
+    end
+  end
+end
+

data/tests/example/lib/acme/pods/cacerts.rb

@@ -0,0 +1,15 @@
+# Acme CACerts
+# Mount CACerts into a well-known directory
+module Acme
+  module Pods
+    module CACerts
+      extend Concern
+
+      included do
+        let(:acme_cacerts_dir)   { '/opt/acme/cacerts' }
+        let(:cacerts_mount)      {  mount('cacerts-volume', acme_cacerts_dir, read_only: true) }
+        let(:cacerts_volume)     { config_map_volume('cacerts-volume', config_map_name: 'cacerts') }
+      end
+    end
+  end
+end

data/tests/example/lib/acme/pods/healthcheck.rb

@@ -0,0 +1,36 @@
+module Acme
+  module Pods
+    # Acme's standardized healthcheck for workloads
+    # Override specific let() for legacy workloads or workloads
+    # whose needs don't fit
+    #
+    # Usage:
+    #   # in a pod definition, add:
+    #   include Acme::Pods::Healthcheck
+    module Healthcheck
+      extend Concern
+
+      included do
+        let(:healthcheck_path) { '/healthcheck' }
+        # Standard Acme port. We can be fancier and read from Acme's standard web port
+        let(:healthcheck_port)                  { 8000 }
+        let(:healthcheck_initial_delay_seconds) { 7 }
+        let(:healthcheck_timeout_seconds)       { 1 }
+
+        let(:readiness_probe) { healthcheck_probe }
+        let(:healthcheck_probe) do
+          {
+            httpGet:             { path: healthcheck_path, port: healthcheck_port },
+            initialDelaySeconds: healthcheck_initial_delay_seconds,
+            timeoutSeconds:      healthcheck_timeout_seconds,
+          }
+        end
+
+        # Acme's Elixir apps don't need liveness probes
+        # However, you can add a command liveness probe to check if it
+        # can still send commands to the running app
+        let(:liveness_probe) { nil }
+      end
+    end
+  end
+end

data/tests/example/lib/acme.rb

@@ -0,0 +1,26 @@
+# Example local library
+# This is the entry point for local concerns and customizations
+# for Matsuri. You can also use this register your own
+# custom resources, such as Istio VirtualService, or
+# CloudNativePG resources
+
+module Acme
+  module Pods
+    # It is better for teams to standardize on healthchecks. These would
+    # be promises (promise theory) that workloads make. The use of let()
+    # allows for overrides for specific workloads
+    autoload :Healthcheck,  'acme/pods/healthcheck'
+    autoload :CACerts,      'acme/pods/cacerts'
+
+  end
+
+  module Nodes
+    # Scheduling
+    autoload :Dedicated,     'acme/nodes/dedicated'
+    autoload :Preemptible,   'acme/nodes/preemptible'
+    autoload :RequiredCores, 'acme/nodes/required_cores'
+    autoload :ResourceClass, 'acme/nodes/resource_class'
+  end
+
+end
+

data/tests/example/platform/config_maps/billing-settings.rb

@@ -0,0 +1,8 @@
+Matsuri.define :config_map, 'billing-settings' do
+  let(:data) do
+    {
+      'LOG_LEVEL'      => 'info',
+      'INVOICE_BUCKET' => 'acme-invoices'
+    }
+  end
+end

data/tests/example/platform/config_maps/cacerts.rb

@@ -0,0 +1,9 @@
+# Acme's internal CA bundle, mounted by Acme::Pods::CACerts. A real
+# repo would source this from the org's certificate distribution.
+Matsuri.define :config_map, 'cacerts' do
+  let(:data) do
+    {
+      'acme-root.pem' => "-----BEGIN CERTIFICATE-----\nEXAMPLE\n-----END CERTIFICATE-----\n"
+    }
+  end
+end

data/tests/example/platform/deployments/billing-web.rb

@@ -0,0 +1,5 @@
+Matsuri.define :deployment, 'billing-web' do
+  let(:replicas)     { 2 }
+  let(:match_labels) { { 'app' => 'billing' } }
+  let(:pod_name)     { 'billing' }
+end

data/tests/example/platform/deployments/checkout-web.rb

@@ -0,0 +1,6 @@
+Matsuri.define :deployment, 'checkout-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' => 'checkout' } }
+  let(:pod_name)     { 'checkout' }
+end

data/tests/example/platform/namespaces/billing-dev.yaml

@@ -0,0 +1,7 @@
+# Raw manifest, outside matsuri: namespaces precede everything matsuri
+# converges, so they are applied directly.
+#   kubectl --context matsuri apply -f platform/namespaces/
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: billing-dev

data/tests/example/platform/namespaces/checkout-dev.yaml

@@ -0,0 +1,7 @@
+# Raw manifest, outside matsuri: namespaces precede everything matsuri
+# converges, so they are applied directly.
+#   kubectl --context matsuri apply -f platform/namespaces/
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: checkout-dev

data/tests/example/platform/pods/billing.rb

@@ -0,0 +1,31 @@
+# Billing is stateless and reschedules cheaply, so it rides the
+# preemptible pool where one exists. The image tracks the converge
+# positional (default: the image_tag acceptor's default).
+Matsuri.define :pod, 'billing' do
+  include Acme::Pods::Healthcheck
+  include Acme::Pods::CACerts
+
+  let(:labels) { { 'app' => 'billing' } }
+
+  # Node selection is per-environment: local clusters have no
+  # preemptible pool, so the scheduling vocabulary stays out entirely.
+  case Matsuri.environment
+  when 'billing_staging'
+    include Acme::Nodes::Preemptible
+    let(:tolerations) { [preemptible_toleration] }
+  end
+
+  let(:cpu_limit) { '500m' }
+  let(:mem_limit) { '512Mi' }
+
+  let(:volumes) { [cacerts_volume] }
+  let(:container) do
+    {
+      name:           'billing',
+      image:          "registry.acme.io/billing:#{image_tag}",
+      readinessProbe: readiness_probe,
+      resources:      resources,
+      volumeMounts:   [cacerts_mount]
+    }
+  end
+end