Forem: Scott Cotton

Wrote a SOTU satire on substack. Enjoy https://scottcotton.substack.com/p/state-of-the-union-address

Scott Cotton — Wed, 25 Feb 2026 13:57:38 +0000

State of the Union Address - Scott Cotton

As Delivered by the President of the Provisional Government of Free America February 25, 2026 — Undisclosed Location (Formerly a Dave & Buster's)

scottcotton.substack.com

Docs are finally live for Tony format: https://signadot.github.io/tony-format/

Scott Cotton — Wed, 18 Feb 2026 11:56:44 +0000

Structured Matching, Patching, and Diffing Done Right

Scott Cotton ・ Jan 29

#automation #devops #kubernetes #tooling

signadot.github.io

ArgoCD makes it surprisingly hard to supply manifests and update images outside Helm/Kustomize. Here's how o build and ORAS cut through the friction.

Scott Cotton — Mon, 09 Feb 2026 13:41:06 +0000

How to Navigate ArgoCD's Manifest Friction with ORAS and `o build`

Scott Cotton ・ Feb 9

#kubernetes #argocd #gitops #devops

How to Navigate ArgoCD's Manifest Friction with ORAS and `o build`

Scott Cotton — Mon, 09 Feb 2026 13:39:05 +0000

ArgoCD's Blind Spot

ArgoCD has one job: take Kubernetes manifests and apply them to a cluster. It does this well. It watches a git repo, detects drift, syncs state, shows you diffs. What it doesn't do well — surprisingly — is accept manifests.

Out of the box, ArgoCD understands three things: plain YAML directories, Helm charts, and Kustomize overlays. Anything else requires a Config Management Plugin (CMP), which means building a container image, writing a plugin spec, and mounting it as a sidecar on the repo-server.

That's already more friction than you'd expect for a tool whose entire purpose is "take YAML, apply it." But the real problem goes deeper.

argocd-image-updater Doesn't Work with Plugins

The most common operation in a deployment pipeline is updating an image tag. ArgoCD's answer to this is argocd-image-updater, a separate controller that watches registries and writes back image tags. It works with Helm (by updating values.yaml parameters) and Kustomize (by updating kustomization.yaml). It does not work with Config Management Plugins.

This means if you use a CMP — whether it's jsonnet, cue, dhall, or anything else — you're on your own for image updates. ArgoCD's manifest pipeline and its image-update pipeline are two systems that don't talk to each other unless you happen to use one of the two blessed tools.

So a tool built to apply manifests makes it hard to supply manifests, and its image updater only works with specific manifest generators. This is the landscape.

What `o build` Does

Tony format is a data format where patches, queries, and schemas are expressed as documents themselves — combining JSON's structure with YAML's readability. (For background on Tony's core operations, see Structured Matching, Patching, and Diffing Done Right.)

Its CLI tool o includes a build system driven by a build.tony file:

build:
  env:
    namespace: default
    replicas: 3

  sources:
  - dir: ./manifests

  patches:
  - match: { kind: Deployment }
    patch:
      metadata:
        namespace: .[namespace]
      spec:
        replicas: .[replicas]

Sources fetch documents from directories, URLs, or command output. Patches are applied conditionally using match patterns. The .[varname] expressions perform typed substitution — not string interpolation, but structural replacement within the IR tree. (The evaluation system covers how these expressions compose with !eval, !exec, !file, and other tags.) Profiles in a profiles/ subdirectory override the environment per deployment target.

The key idea: patches are documents with the same structure as the data they operate on. No templating language. !key(name) lets you merge arrays by a field — something Kustomize can only do for hardcoded Kubernetes merge keys, but Tony lets you do for any array.

o build -y                      # output as YAML
o build -y -p staging           # with a profile
o build -y -e namespace=prod    # override a single variable

If you also need to produce Helm charts from the same source manifests, o build handles that too — see One Source, Two Outputs for how Tony generates both K8s YAML and Helm charts from a single build directory.

Solving Image Updates Without argocd-image-updater

Since argocd-image-updater doesn't work with plugins, we need another way to get per-commit image tags into the build. The approach: store image tags as OCI artifacts using ORAS and pull them at sync time.

CI Pushes Image Tags

After building images, CI publishes a small JSON artifact to the registry:

cat > image-tags.json << 'EOF'
{"env": {"images": {"tags": {"app": "sha-abc123", "worker": "sha-def456"}}}}
EOF

oras push ghcr.io/org/deploy-manifest:$COMMIT_SHA image-tags.json

The env: wrapper makes this a valid o build profile — it merges into the build environment naturally.

The Plugin Pulls at Sync Time

The CMP's generate command pulls the artifact for the current commit and pipes it to o build:

apiVersion: argoproj.io/v1alpha1
kind: ConfigManagementPlugin
metadata:
  name: tony-build
spec:
  version: v1.0
  generate:
    command:
    - sh
    - -c
    - |
      if oras pull ghcr.io/org/deploy-manifest:$ARGOCD_APP_REVISION -o /tmp 2>/dev/null; then
        cat /tmp/image-tags.json | o build -y $ARGOCD_ENV_ARGS .
      else
        echo "manifest not available for $ARGOCD_APP_REVISION, scheduling retry" >&2
        ARGOCD_TOKEN=$(cat /argocd-api-token/token)
        (sleep 60 && wget -qO- \
          --header="Authorization: Bearer $ARGOCD_TOKEN" \
          "http://argocd-server.argocd.svc/api/v1/applications/$ARGOCD_APP_NAME?refresh=hard" \
          > /dev/null 2>&1) &
        exit 1
      fi

The Timing Problem

When a commit is pushed, two things happen in parallel: CI starts building images, and ArgoCD notices the new commit and tries to sync. ArgoCD is usually faster. The oras pull fails because the artifact doesn't exist yet.

ArgoCD will sometimes retry manifest generation errors on its own, but this isn't reliable — the repo-server can cache the error and stop trying. So the plugin handles retries explicitly: on failure, it backgrounds a process that waits 60 seconds and triggers a hard refresh via the ArgoCD API. The hard refresh clears the cached error and ArgoCD re-invokes the plugin. This repeats until the artifact appears.

It's a workaround for another ArgoCD gap — no built-in way for a plugin to say "not ready yet, try again soon." But it works.

What This Gets You

No git commits for image updates — tags live in the registry alongside the images themselves
No argocd-image-updater — the plugin handles everything, for any manifest generator
Atomic deploys — all image tags for a commit ship as one artifact
Decoupled CI — CI just pushes OCI artifacts, needs no ArgoCD access

The Application

Here's what an ArgoCD Application looks like using o build:

apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: my-operator
  namespace: argocd
spec:
  source:
    repoURL: https://github.com/org/repo.git
    targetRevision: HEAD
    path: deploy/operator
    plugin:
      name: tony-build-v1.0
      env:
      - name: ARGS
        value: "-p staging -p -"
  destination:
    server: https://kubernetes.default.svc
  syncPolicy:
    syncOptions:
    - ApplyOutOfSyncOnly=true

plugin.name: tony-build-v1.0 — tells ArgoCD to use our CMP instead of Helm or Kustomize
env.ARGS: "-p staging -p -" — passes flags to o build: apply the staging profile, then overlay image tags from stdin via -p -. We place these args in the Application to be able to customize them without updating the plugin. We may want to add -e serviceMesh=istio for example.

The deploy/operator directory in that repo contains a build.tony file. ArgoCD clones the repo, hands the directory to the plugin, and the plugin runs o build to produce YAML on stdout. Whatever comes out is what ArgoCD applies. Different Applications use different profiles from the same build directory.

Installing the Plugin

A CMP runs as a sidecar on the argocd-repo-server deployment. You need:

A ConfigMap with the plugin spec
A sidecar container with o and oras
Registry credentials for pulling artifacts
An ArgoCD API token for the retry mechanism

The sidecar looks like this:

containers:
- name: tony-build
  image: ghcr.io/signadot/tony-plugin:latest
  command: [/var/run/argocd/argocd-cmp-server]
  securityContext:
    runAsNonRoot: true
    runAsUser: 999
  volumeMounts:
  - name: var-files
    mountPath: /var/run/argocd
  - name: plugins
    mountPath: /home/argocd/cmp-server/plugins
  - name: tony-plugin-config
    mountPath: /home/argocd/cmp-server/config/plugin.yaml
    subPath: plugin.yaml
  - name: tmp
    mountPath: /tmp
  - name: ghcr-creds
    mountPath: /ghcr-creds
  - name: argocd-api-token
    mountPath: /argocd-api-token

Patching ArgoCD with `o build`

Rather than hand-editing the repo-server Deployment, you can use o build itself to do the patching. The tony-format repo includes an example that fetches the live Deployment from the cluster and patches it:

build:
  sources:
  - exec: "kubectl get deployment argocd-repo-server -n .[namespace] -o yaml"
    format: yaml
  - dir: source

  env:
    namespace: argocd
    image: ghcr.io/signadot/tony:latest
    pluginName: tony-build

  patches:
  - file: patches/cleanup.tony
  - file: patches/namespace.tony
  - file: patches/repo-server.tony
  - file: patches/application.tony

The repo-server.tony patch uses !key(name) to merge arrays by field — adding the sidecar container without knowing or caring what else is in the containers array:

- match:
    kind: Deployment
    metadata:
      name: argocd-repo-server
  patch:
    spec:
      template:
        spec:
          containers: !key(name)
          - name: tony-build
            image: .[image]
            command: [/var/run/argocd/argocd-cmp-server]
            securityContext:
              runAsNonRoot: true
              runAsUser: 999
            volumeMounts:
            - name: var-files
              mountPath: /var/run/argocd
            - name: plugins
              mountPath: /home/argocd/cmp-server/plugins
            - name: tony-plugin-config
              mountPath: /home/argocd/cmp-server/config/plugin.yaml
              subPath: plugin.yaml
            - name: tmp
              mountPath: /tmp
          volumes: !key(name)
          - name: tony-plugin-config
            configMap:
              name: tony-build-plugin

One command:

o build examples/build/patch-argocd -y | kubectl apply -f -

Wrapping Up

ArgoCD is good at what it does — reconciling cluster state against a desired state. But it makes assumptions about how that desired state is produced, and those assumptions break down as soon as you step outside Helm or Kustomize. The plugin system exists but is a second-class citizen. The image updater ignores it entirely.

o build as a CMP gives you a manifest generator that works in structured documents rather than templates, with conditional patches, composable evaluation, environment profiles, and multi-source builds. The ORAS pattern gives you per-commit image updates without git-commit noise and without depending on argocd-image-updater.

It shouldn't require this much machinery to give a manifest-applier some manifests. But given ArgoCD's constraints, this is a functionally complete way through without common drawbacks like storing non-source generated manifests in git.

Install o:

go install github.com/signadot/tony-format/go-tony/cmd/o@latest

Full example: examples/build/patch-argocd

Tony format is open source.

The Invisible Asymmetry discusses the impact of agentic/llm explosion. Cross-cutting and well grounded -- Worth a look! https://open.substack.com/pub/scottcotton/p/the-invisble-asymmetry?r=5cjm1c&utm_campaign=post&utm_medium=web

Scott Cotton — Sat, 07 Feb 2026 12:28:19 +0000

The Invisble Asymmetry - Scott Cotton

When you talk to me, I listen.

scottcotton.substack.com

The only article I've seen whose cover image legitimately shows trees running on a track.

Scott Cotton — Wed, 04 Feb 2026 09:00:16 +0000

Evaluation in Tony Format

Scott Cotton ・ Feb 4

#architecture #automation #opensource #tooling

Evaluation in Tony Format

Scott Cotton — Wed, 04 Feb 2026 08:49:32 +0000

A companion article describes how Tony format's matching, patching, and diffing operations all share the same IR and tag system. This article covers a fourth operation---evaluation---which uses the same tag mechanism to expand expressions, load files, execute commands, and thread an environment through a document tree.

The evaluation mechanism isn't fundamentally different from expansion systems in other tools. YAML's tag syntax (! prefix) is already used this way across the industry: CloudFormation's !Ref, !Sub, and !GetAtt wire resources together at deploy time; Home Assistant's !include and !secret split configuration across files; SpeechBrain's HyperPyYAML uses !ref for cross-references and !new to instantiate Python objects at parse time. Outside YAML-specific tools, the same pattern appears in Jinja2's template rendering, Helm's Go templates, and jsonnet's late binding---walk a tree or string, find markers, substitute values.

What makes Tony's version worth writing about is not novelty in the expansion mechanism itself, but how it fits into the same IR and tag system that drives match, patch, and diff. CloudFormation tags only wire resources. HyperPyYAML tags only construct Python objects. Tony's eval tags are symbols in the same registry as !or, !key(name), and !dive, operating on the same ir.Node tree, composing with everything else.

How it works

Evaluation is a post-order tree walk. The engine traverses the ir.Node tree depth-first, processing children before parents. At each node, if the node carries an eval tag (!eval, !file, !exec, !script, etc.), the engine looks up the corresponding symbol in the eval registry, instantiates an operation, and calls its Eval method:

type Op interface {
    Eval(doc *ir.Node, env Env, f EvalFunc) (*ir.Node, error)
}

The Env is a map[string]any threaded through every call. The EvalFunc callback enables recursive delegation back to the engine, same pattern as MatchFunc and PatchFunc in the merge operations. New eval operations are added by registering a symbol---no changes to the engine.

Expression syntax

Tony supports two expression forms in string values:

.[expression] --- replaces the entire node. If the string is exactly .[x], the node is replaced with whatever x evaluates to---a number, an object, an array, null. The result is typed, not stringified.
$[expression] --- string interpolation. The expression result is converted to a string and spliced into the surrounding text. Multiple $[...] expressions can appear in a single string.

Expressions are evaluated with expr-lang, a Go expression evaluator. Variables come from the threaded environment:

!eval
metadata:
  name: .[name]
  namespace: .[namespace]
  labels:
    version: v$[version]

With env = {name: "frontend", namespace: "prod", version: "1.2.3"}, this produces:

metadata:
  name: frontend
  namespace: prod
  labels:
    version: v1.2.3

The distinction between .[...] and $[...] matters. .[replicas] where replicas is the integer 3 produces the number 3, not the string "3". $[replicas] produces the string "3". CloudFormation has a similar two-form split---!Ref for references, !Sub for string interpolation---but both produce strings in the end. Tony's .[...] produces typed IR nodes: objects, arrays, numbers, not just strings. This is what keeps evaluation type-safe---markers expand to structured data, not text.

Script functions

When evaluating expressions, several built-in functions are available that operate on the document tree itself:

whereami() --- returns the path of the current node (e.g. $.metadata.name)
getpath(path) --- navigates to any node in the document by path
listpath(path) --- returns multiple nodes matching a path pattern
getenv(name) --- reads an OS environment variable

These functions give expressions access to the document's own structure. A value can reference another value elsewhere in the same tree:

!eval
config:
  appName: my-app
  database:
    host: postgres.example.com
    port: 5432
deployment:
  name: '.[getpath("$.config.appName").String]'
  dsn: '.[getpath("$.config.database.host").String + ":" + string(getpath("$.config.database.port").Int64)]'

This is self-referential expansion: the document is both the template and the data source. HyperPyYAML's !ref tag does something similar---!ref <key> resolves a value from elsewhere in the same YAML file, with support for dotted paths and simple arithmetic. Tony's getpath navigates arbitrary paths through the typed IR tree, and because it returns an ir.Node, the result composes with further expressions.

The eval tags

The built-in eval operations, all registered as symbols in the same registry:

Tag	What it does
`!eval`	Expand `.[...]` and `$[...]` expressions in the subtree
`!file`	Load content from a local file or HTTP URL
`!exec`	Run a shell command, capture stdout
`!script`	Evaluate an expr-lang program (with output mode: value, string, or any)
`!osenv`	Read OS environment variables
`!tostring`	Convert a node to its string representation
`!toint`	Convert to integer
`!tovalue`	Parse a YAML string into a typed node
`!b64enc`	Base64 encode

!file and !exec are the I/O operations. !file loads a file path or URL that can itself contain .[...] references (expanded before loading). !exec runs a shell command and returns stdout as a string node. Both are simple---there's no caching, no retry logic, no abstraction layer. They do one thing. This is a deliberate trade-off against tools like Carvel's ytt, which is fully sandboxed (no filesystem, no network, no shell). Tony chooses to allow side effects and marks them: !exec and !pipe are flagged as unsafe operations that callers can opt out of.

!script provides full expr-lang evaluation with configurable output. With !script(value), the result string is parsed as YAML back into IR. With !script(string), it stays a string. With !script(any), the raw expr-lang result is converted directly to an IR node.

Tag composition

Tags compose via dot-separation. !tovalue.file chains two operations on a single node: !file loads the file, !tovalue parses the result as YAML. !not.or negates a disjunction. !subtree.type searches depth-first for nodes of a given type. The engine peels off the first tag, executes it, and passes the rest of the chain to the child---a pipeline that reads right to left. Tags also carry arguments inline: !key(name), !script(value), !delete(!mytag). Other tools that use YAML tags---CloudFormation, HyperPyYAML, authentik blueprints---achieve composition by nesting child nodes: variable maps, extra arrays, separate mapping entries. The YAML spec assigns one tag per node, so stacking tags means adding structure. Tony's dot-separated tags put multiple operations on a single node's tag string. The result: document structure preservation. The operations ride on the tag; they don't reshape the data to accommodate themselves.

# Load a YAML file and merge it into the current object
<<: !tovalue.file config/cluster.yaml

# Run a command, parse its stdout as a typed value
from: !tovalue.exec "echo 42"

Composition with `o build`

The build system is where evaluation becomes practical. A build.tony file declares sources, patches, an environment, and output configuration. The environment is where !eval, !exec, and !file do their work:

build:
  env:
    namespace: default
    version: !exec ./version.sh
    debug: true

  sources:
  - dir: ./manifests

  patches:
  - match: { kind: Deployment }
    patch: { metadata: { namespace: .[namespace] } }
  - file: extra-patches.tony
    if: .[debug]

The environment is itself evaluated---!exec ./version.sh runs at build time and its stdout becomes the value of version. Then every .[namespace] and .[debug] reference in patches expands against that resolved environment. Patches are conditional: if: .[debug] means the patch only applies when debug is truthy.

Environment values are set with increasing precedence:

env: field in the build file
-e key=value flags
-- key1=val1 key2=val2 arguments
$TONY_DIRBUILD_ENV OS environment variable

Profiles---override files in a profiles/ subdirectory---patch the base environment before the build runs. o build -p staging applies profiles/staging.{tony,yaml,json} on top of the base env.

Use case: keeping configuration DRY

The typical use case is a user organising their configuration to avoid repetition. A Kubernetes deployment directory might have dozens of manifests that share the same namespace, image registry, and version string. Without evaluation, you either duplicate these values everywhere or reach for a templating engine.

With Tony evaluation, you declare the shared values once in the environment and reference them:

build:
  env:
    registry: us-docker.pkg.dev/myproject/myrepo
    version: !exec "git describe --tags --always"
    namespace: production

  sources:
  - dir: ./k8s

  patches:
  - match: { kind: !or [Deployment, StatefulSet, DaemonSet] }
    patch:
      metadata:
        namespace: .[namespace]
      spec:
        template:
          spec:
            containers: !key(name)
            - name: app
              image: $[registry]/app:$[version]

The version comes from git at build time. The namespace is a plain string in the environment. The image reference is string-interpolated from multiple variables. Switch to staging by running o build -p staging or o build -- namespace=staging.

This is DRY without a template language. The patches are still valid Tony/YAML documents. You can diff them, match against them, or compose them with other patches. A Helm chart is text that happens to produce YAML. A Tony build file is structured data that stays structured data throughout.

Use case: generating config test fixtures

The other direction is a software provider who needs to generate large volumes of configuration examples for testing. Instead of maintaining hundreds of hand-written YAML files, you define a base document and use evaluation to produce variants:

build:
  env:
    test_name: basic
    replicas: 1
    image_tag: latest
    enable_monitoring: false

  sources:
  - dir: ./templates

  patches:
  - match: { kind: Deployment }
    patch:
      metadata:
        name: test-$[test_name]
        labels:
          test-case: $[test_name]
      spec:
        replicas: .[replicas]
  - match: { kind: Deployment }
    patch:
      spec:
        template:
          spec:
            containers: !key(name)
            - name: app
              image: myapp:$[image_tag]
  - match: { kind: ServiceMonitor }
    if: .[enable_monitoring]
    patch:
      metadata:
        name: test-$[test_name]-monitor

Run o build -- test_name=ha replicas=3 enable_monitoring=true to produce an HA variant. Run it in a loop with different parameters to generate a test matrix. Each generated output is valid, diffable, matchable YAML. You can diff two test variants structurally to verify exactly what changed. You can match the output against validation patterns to catch regressions.

Because evaluation composes with the other operations, the test infrastructure is the same tool as the production build infrastructure. Generate a fixture, diff it against a baseline, match it against a schema---all with o.

Not a template engine

It's worth being explicit about what this is not. Tony evaluation is not string interpolation bolted onto YAML. It operates on the IR tree. An expression that evaluates to a number produces a number node, not a string that looks like a number. An expression that evaluates to an object produces an object node with fields and values, not a string containing YAML.

Helm templates YAML as text---a Go template emits characters that happen to form valid YAML, and if your indentation is wrong, you get a parse error at a distance. Jinja2 has the same problem. Carvel's ytt avoids this by operating on YAML structure, but uses comment annotations rather than YAML's own tag mechanism, and its Starlark-based logic lives in a separate layer from the data. jsonnet solves the typing problem---its expressions produce typed values---but it's a separate language, not YAML.

Tony's eval tags are none of these things. They're processed the same way as !or or !key(name)---a symbol in a registry, receiving an IR node, returning an IR node. The engine doesn't know or care whether a tag means "match this pattern" or "expand this expression." Everything stays in the typed IR. Evaluation doesn't break the invariant that makes match, patch, and diff work. It's all tree operations on the same tree.

Structured Matching, Patching, and Diffing Done Right

Scott Cotton — Thu, 29 Jan 2026 20:32:58 +0000

If you work with YAML or JSON configuration---Kubernetes manifests, Helm charts, IaC definitions, anything really in software ---you've probably hit the same wall. You start with a nice declarative format. Then you need to diff two versions, so you reach for diff. You need to patch a field, so you reach for yq or jq. You need to match documents in a stream, so you reach for grep. Before long, your "declarative" pipeline is held together by text munging.

The higher-level tools don't escape this either. Helm templates YAML as strings. You can't diff two YAML documents as YAML---you convert to JSON first. Config-as-data systems like kpt and porch target narrow use cases--- package management, WYSIWYG authoring---because they're built on top of a hodgepodge data format model. They hide the mess rather than fix it. And the mess leaks: sooner or later you're back to grep, sed, and yq to glue things together.

But this article isn't about building a better Helm or kpt. It's about getting the underlying data model right. What happens when matching, patching, and diffing all operate on the same typed tree representation, with the same extension mechanism, producing output that feeds back into each other?

That's what Tony format does. It operates directly on the intermediate representation (IR) of structured data---a typed tree of objects, arrays, strings, numbers, booleans, and nulls. Matching, patching, and diffing are all defined as operations on this tree, not on its serialized text. And because the three operations share the same IR and the same tag-based extension mechanism, they compose in ways that text-based tools never could, and they generalize in ways config management tools never could either.

The IR: One Tree to Rule Them All

At the core of Tony is ir.Node, a uniform representation for structured data:

type Node struct {
    Type    Type      // Null, Bool, Number, String, Object, Array
    Fields  []*Node   // object keys
    Values  []*Node   // object values or array elements
    Tag     string    // operation tag, e.g. "!or", "!key(name)"
    String  string
    Bool    bool
    Int64   *int64
    Float64 *float64
}

This IR can be parsed from YAML, JSON, or Tony's own format, and encoded back to any of them. Every operation---match, patch, diff---works on *ir.Node. No serialization boundaries, no format-specific quirks. A patch written against YAML works identically against JSON.

The Tag field is what makes things interesting. Tags are YAML-compatible annotations (e.g. !or, !dive, !key(name)) that extend nodes with operational semantics. They compose via dot-separation: !all.field.glob chains three operations into one. The same tag mechanism drives matching, patching, and diffing, which means the three operations speak the same language.

Every tag resolves to a registered Symbol that implements the Op interface:

type Op interface {
    Match(doc *ir.Node, ctx *OpContext, f MatchFunc) (bool, error)
    Patch(doc *ir.Node, ctx *OpContext, mf MatchFunc, pf PatchFunc, df DiffFunc) (*ir.Node, error)
}

Both methods are on the same interface. A single operation can define both matching and patching behavior---!if tests a condition and applies a transformation in one step. The MatchFunc and PatchFunc callbacks enable recursive delegation back to the engine, threading context through the entire tree. New operations can be added without modifying the core engine: just register a new symbol.

The Three Operations

Matching

Tony's Match(doc, pattern) answers a simple question: does this document satisfy this pattern? But "pattern" means something much richer than string equality.

A plain match is structural. For objects, every field in the pattern must exist in the document with a matching value. For arrays, elements match positionally. For scalars, values must be equal. Crucially, the pattern is a subset---the document can have fields the pattern doesn't mention.

# Document
apiVersion: apps/v1
kind: Deployment
metadata:
  name: frontend
  namespace: production

# Pattern - matches because all specified fields are present and equal
kind: Deployment
metadata:
  namespace: production

This is already more useful than grep 'kind: Deployment' because it understands nesting. But tags unlock the real power:

# Match any Deployment or StatefulSet in the monitoring namespace
kind: !or [Deployment, StatefulSet]
metadata:
  namespace: !glob 'monitor*'

!or matches if any alternative matches. !glob matches against a glob pattern. !and, !not, !has-path, !type, !field, and !subtree round out the vocabulary. !subtree searches the entire document depth-first. !let binds variables before matching. Each callback delegates sub-matching back to the engine, so compound operations compose naturally.

Patching

Tony's Patch(doc, patch) transforms a document by merging a patch into it. Without tags, this works like a structural merge patch:

Objects merge field-by-field. Patch fields override document fields; document fields not in the patch are preserved.
Arrays merge positionally up to the shorter length, then the patch's remaining elements are appended.
Scalars replace.

# Document
metadata:
  name: frontend
  labels:
    app: web
spec:
  replicas: 1

# Patch
spec:
  replicas: 3
  strategy:
    type: RollingUpdate

# Result
metadata:
  name: frontend
  labels:
    app: web
spec:
  replicas: 3
  strategy:
    type: RollingUpdate

The patch only mentions what changes. Everything else is left alone. This is the same mental model as JSON merge patch (RFC 7396), but extended to arbitrary structured data with tag support.

Tags turn simple patches into a transformation language:

!delete removes a field:

metadata:
  annotations:
    old-annotation: !delete null

!if conditionally applies patches:

!if
  if:
    kind: Deployment
  then:
    spec:
      replicas: 3
  else:
    !pass null

!dive recursively searches the document tree, applying conditional patches to every subtree. This is how you express transformations over arbitrarily nested structures without knowing the depth ahead of time.

A real example: Kubernetes CRDs embed OpenAPI schemas that can be thousands of lines deep. Stripping description fields from podTemplate subtrees to reduce CRD size used to require a shell script. With !dive, it's a patch:

# Match any CRD, then dive into its version schemas
- match:
    kind: CustomResourceDefinition
  patch:
    spec:
      versions: !dive
      - match:
          podTemplate: null
        patch:
          podTemplate:
            description: !delete null
            properties: !dive
            - match: !irtype {}
              patch:
                description: !delete null

!dive walks the tree bottom-up, applying each match/patch pair at every node. The outer dive finds any podTemplate subtree anywhere in the version schema. The inner dive then strips description from every object inside it. No matter how deeply nested the schema is, the patch handles it. The result: you can ship CRDs with pod templates inside without repeating megabytes of repeated descriptions.

!all applies a patch to every element of an array or every value of an object. !pipe shells out to an external command (marked unsafe, can opt out).

Keyed Lists

One of the most practical features is !key(field), which tells Tony to treat an array as a map keyed by a field value. This solves the classic problem of patching Kubernetes arrays like containers or volumes:

# Document
spec:
  containers: !key(name)
  - name: app
    image: myapp:v1
  - name: sidecar
    image: proxy:v1

# Patch
spec:
  containers: !key(name)
  - name: app
    image: myapp:v2

Without !key, array patching is positional---swap the order and your patch breaks. With !key(name), Tony matches elements by their name field and merges them structurally. The sidecar container is untouched because the patch doesn't mention it.

Diffing

Tony's Diff(from, to) computes minimal/small structural difference between two documents. The output is itself a valid Tony document that moreover contains the common ancestors of a fine grained diff, making it easier to read than jsondiff which uses path references.

Diff uses tags to annotate what changed:

!replace when types differ: !replace { from: "old", to: "new" }
!delete for removed fields or elements
!insert for added fields or elements
!strdiff for character-level string changes
!arraydiff for array changes with key matching
!addtag / !rmtag / !retag for tag-only changes

Fields that are identical are omitted entirely. The diff is minimal.

For strings, The Go Tony o tool computes character-level diffs using the diff-match-patch algorithm. But it's pragmatic: if the diff is larger than half the size of the smaller string, it falls back to a simple !replace. No point in a character-level diff that's harder to read than the replacement.

When arrays are tagged with !key(field), diffing matches elements by key value instead of position. Reordering doesn't produce noise---only actual additions, removals, and modifications are reported:

# from
containers: !key(name)
- name: app
  image: v1
- name: sidecar
  image: proxy:v1

# to
containers: !key(name)
- name: sidecar
  image: proxy:v2
- name: app
  image: v1

# diff - only the sidecar image changed, reordering is ignored
- name: sidecar
  image: !replace
    from: proxy:v1
    to: proxy:v2

For plain arrays (without !key), !arraydiff uses an abstracted longest-common-subsequence to produce a positional diff with !insert and !delete entries---and both the result and the per-item differences are valid patches:

# from
items:
- a
- b
- c

# to
items:
- a
- x
- c
- d

# diff
items: !arraydiff
  1: !replace
    from: b
    to: x
  3: !insert d

Diffs are reversible. libdiff.Reverse(diff) produces a diff that, when applied to to, yields from:

diff := Diff(a, b)
reversed, _ := libdiff.Reverse(diff)
// Patch(b, reversed) == a

The reversal logic is straightforward because the tags carry complete information: !delete becomes !insert and vice versa, !replace swaps its from and to fields, !retag(x,y) becomes !retag(y,x).

Composition

The real payoff is that these three operations form a closed loop.

A diff is a valid patch. The same tags that annotate changes (!delete, !insert, !replace) are recognized by the patch engine. Diff(a, b) produces output that you can pass directly to Patch(a, diff) to get b. Reverse the diff and apply it to b to get a.

Matching composes with patching. !if uses match semantics in its condition and patch semantics in its body. !dive matches to find subtrees and patches to transform them. The Op interface makes this explicit---every operation is both a matcher and a patcher, and the engine threads recursive callbacks for both through the entire tree.

Diffs compose with matching. Because a diff is structured Tony data, you can match against it, filter it, or patch it before applying it. A diff isn't an opaque blob you feed to patch---it's a document you can inspect and transform with the same tools you use on any other document.

This isn't three systems bolted together. It's one system and one structure-preserving format with three entry points. Match, patch, and diff are perspectives on the same tree-walking, tag-dispatching engine. The Op interface, the IR, and the tag registry are shared all the way down.

Conclusion

Three operations. One IR. One tag system. Matching, patching, and diffing are the same operation viewed from different angles, and the model makes that explicit. That's the whole idea.

All I have to say is !

Scott Cotton — Thu, 08 Jan 2026 08:44:06 +0000

One Source, Two Outputs: Generating K8s YAML and Helm Charts with Tony Format

Scott Cotton ・ Jan 8

One Source, Two Outputs: Generating K8s YAML and Helm Charts with Tony Format

Scott Cotton — Thu, 08 Jan 2026 08:42:33 +0000

We use controller-gen to generate CRDs and base manifests. These YAML files are our source of truth—used in CI, deployed to dev clusters like minikube, and tested internally. But customers want Helm charts.

This creates an uncomfortable constraint: Helm cannot be our source of truth because controller-gen outputs YAML. We need to generate Helm charts from YAML, not the other way around.

The Impedance Mismatch

Helm has a fundamental problem: you're editing YAML, but you're not.

containers:
- name: manager
  image: {{ .Values.image.repository }}:{{ .Values.image.tag }}
  resources:
    {{- if .Values.resources }}
    {{ .Values.resources | toYaml | nindent 4 }}
    {{- end }}

This isn't valid YAML. Your IDE doesn't understand it. YAML validators reject it. Kustomize can't patch it. Every tool in the Kubernetes ecosystem expects YAML, but Helm templates are a hybrid format that nothing else can process.

This means you can't use kustomize to customize Helm charts. You can't use Helm as a source and generate plain YAML with structural patches. You're stuck maintaining two parallel worlds.

Our Old Workflow: Death by a Thousand Hacks

Our previous solution was a pipeline of custom tools:

kustomize build deploy/operator/overlays/helm \\
  | go run ./hack/fix-cm \\
  | go run ./hack/templatize.go \\
    -charts-dir $(CHARTS_DIR) \\
    -templates-dir templates

Each piece solved a problem that shouldn't exist.

hack/fix-cm.go: Working Around Kustomize's ConfigMap Limitations

Kustomize can't patch individual fields inside ConfigMap data values. Our workaround: store structured data in ConfigMaps as actual YAML structures (invalid for a real ConfigMap), let kustomize patch them, then convert back to strings:

// Input: invalid ConfigMap with structured data field
// data:
//   config:
//     x: xy
//     f: v
//
// Output: valid ConfigMap with string field
// data:
//   config: |
//     x: xy
//     f: v

A 100-line Go program to work around a tool limitation.

hack/templatize.go: 450 Lines of Regex

Since kustomize rejects invalid YAML, we couldn't put Helm templates in our source files. Instead, we invented a shadow language of annotations:

# In kustomize overlay
metadata:
  labels:
    templatize.signadot.com/range-map: .Values.commonLabels
  annotations:
    templatize.signadot.com/include-if: not .Values.disableAgent

Then templatize.go scans the output line-by-line with regex, looking for these annotations and rewriting them into Helm templates:

directiveExp = regexp.MustCompile(`^(\\s*)templatize\\.signadot\\.com/([^:]+):\\s*(.+)$`)
signadotImageExp = regexp.MustCompile(`^(\\s*-?\\s*)(image|value):\\s*signadot/([a-z-]+):(.+)$`)
helmValuesExp = regexp.MustCompile(`^(.*)helm-values.signadot.com/([a-zA-Z.][a-zA-Z0-9_.]*)(\\?(.*))?$`)

Every image reference, every conditional include, every values injection—all handled by pattern matching on text that happens to look like YAML.

This almost worked. Every change required understanding both the kustomize overlay system and the templatize conventions. Adding a new configurable field meant editing multiple files and hoping the regex would match correctly.

But the real killer was what happened when regex couldn't express a transformation. The escape hatch: git unified diffs stored as source code, applied against generated output:

diff --git b/templates/agent-deployment.yaml a/templates/agent-deployment.yaml
@@ -31,6 +35,15 @@ spec:
         {{- range $key, $val := .Values.podAnnotations }}
         {{ $key | quote }}: {{ $val | quote }}
         {{- end }}
+        {{- if $linkerdEnabled }}
+        {{- range $key, $val := .Values.linkerd.operator.podAnnotations }}
+        {{ $key | quote }}: {{ $val | quote }}
+        {{- end }}
+        {{- end }}

These patches target files that don't exist—they're generated mid-pipeline. If templatize output shifts by one line (a new annotation, a reordered field), the patch context no longer matches and the build fails. You're debugging line number mismatches in diffs against fictional files.

Tony's Solution: Valid Documents All the Way Down

Tony format solves this by letting you embed raw text in structurally valid documents using merge keys (<<:):

resources:
  <<: '{{- if .Values.resources }}'
  <<: '{{ .Values.resources | toYaml | nindent 4 }}'
  <<: '{{- else }}'
  limits:
    memory: "512Mi"
  <<: '{{- end }}'

This is valid Tony. It parses. It patches. And when you run o build with the expand merge keys option -x, the merge keys expand to raw text at the correct indentation:

resources:
{{- if .Values.resources }}
{{ .Values.resources | toYaml | nindent 4 }}
{{- else }}
  limits:
    memory: "512Mi"
{{- end }}

For simple value substitution, !literal preserves template syntax:

image: !literal '{{ .Values.image.repository }}:{{ .Values.image.tag }}'

This guarantees that the output ends up like this

image: |-
  {{ .Values.image.repository }}:{{ .Values.image.tag }}

preserving the quoting conventions inside templates which are needed for Helm.

The New Workflow

deploy/
  sdctl-operator/
    build.tony              # Internal deployment build
    source/                 # Deployments, services
    crd/bases/              # controller-gen output
  charts/sdctl-operator/
    build.tony              # Helm chart build
    patches/
      images.tony           # Templatize images
      resources.tony        # Templatize resources

The Helm chart build sources from the internal deployment:

build:
  destDir: ../../../dist/charts/signadot/sdctl-operator/templates

  sources:
  - exec: "o b ../../sdctl-operator"  # Reuse the same base
    format: yaml

  patches:
  - file: patches/images.tony
  - file: patches/resources.tony

The image patch uses !literal and !key(name) for structural merging:

- match:
    kind: Deployment
    metadata:
      name: sdctl-controller-manager
  patch:
    spec:
      template:
        spec:
          containers: !key(name)
          - name: manager
            image: !literal '{{ include "valuesDefault" (list .Values "signadot/sdctl-controller-manager:latest" "controllerManager" "image") }}'

CI becomes straightforward:

# Deploy to minikube
o build deploy/sdctl-operator/ | kubectl apply -f -

# Build Helm chart for customers
o build -x deploy/charts/sdctl-operator/

controller-gen stays the source of truth. No regex. No annotation hacks. No ConfigMap fixups.

Why This Actually Works

Generic Tools Beat Domain-Specific Ones

Kustomize's philosophy is that it understands Kubernetes. It knows that containers merges by name because the upstream Go struct has patchMergeKey:"name". This sounds helpful until you realize:

You can't change merge behavior for fields Kubernetes got wrong
You can't use kustomize on anything that isn't a K8s resource
Every K8s API change potentially changes your patch semantics

Tony takes the opposite approach: it knows nothing about Kubernetes. It's a generic tool for structured data that happens to work beautifully on K8s manifests.

containers: !key(name)  # You declare merge semantics, not upstream Go structs

This works on any array, in any document. Patch your Helm values.yaml. Patch CI configs. Patch Terraform variables. The same tool, the same syntax, the same mental model—without being locked into one ecosystem's idea of how merging should work.

Structural Matching

Kustomize requires you to know resource names upfront. Tony matches by structure:

- match:
    kind: Deployment
    metadata:
      labels:
        app: myapp
  patch:
    spec:
      replicas: 3

Match expressions compose with !or, !and, and !not. Apply a patch to all ConfigMaps and Secrets:

- match:
    kind: !or [ConfigMap, Secret]
  patch:
    metadata:
      labels:
        managed-by: tony

Conditionals Without Directory Explosion

Kustomize needs separate overlay directories for each variant. Tony uses expressions,
over a substitution environment similar to Helm's values.yaml:

- if: '.[ environment == "prod" ]'
  match: { kind: Deployment }
  patch: { spec: { replicas: 5 } }

Moreover Tony has profiles which are patches to the substition environment.

Looking Forward

Migrating to Tony gave us something we didn't have before: a coherent pipeline we actually understand. No more debugging regex transforms or tracing through three layers of kustomize overlays to figure out why an annotation didn't convert properly, or constructing text patches against fictional targets as source code.

But this is just the start. The o build model—declarative builds with sources, patches, and environment overrides—opens up possibilities we're actively exploring:

Remote builds. Today o build runs locally. We're adding support for remote sources and build execution, so your build.tony can reference artifacts from CI, pull base manifests from registries, or execute builds in controlled environments. The same declarative format, but with the dependency resolution happening across network boundaries.

The goal: treat Kubernetes manifests with the same rigor we treat code. Reproducible builds from declared inputs, whether those inputs are local files, controller-gen output, or artifacts from a release pipeline.

If you're fighting similar battles with Helm generation, give Tony a look: github.com/signadot/tony-format

Forem: Scott Cotton

Wrote a SOTU satire on substack. Enjoy https://scottcotton.substack.com/p/state-of-the-union-address

State of the Union Address - Scott Cotton

Docs are finally live for Tony format: https://signadot.github.io/tony-format/

Structured Matching, Patching, and Diffing Done Right

Scott Cotton ・ Jan 29

ArgoCD makes it surprisingly hard to supply manifests and update images outside Helm/Kustomize. Here's how o build and ORAS cut through the friction.

How to Navigate ArgoCD's Manifest Friction with ORAS and `o build`

Scott Cotton ・ Feb 9

How to Navigate ArgoCD's Manifest Friction with ORAS and `o build`

ArgoCD's Blind Spot

argocd-image-updater Doesn't Work with Plugins

What o build Does

Solving Image Updates Without argocd-image-updater

CI Pushes Image Tags

The Plugin Pulls at Sync Time

The Timing Problem

What This Gets You

The Application

Installing the Plugin

Patching ArgoCD with o build

Wrapping Up

The Invisible Asymmetry discusses the impact of agentic/llm explosion. Cross-cutting and well grounded -- Worth a look! https://open.substack.com/pub/scottcotton/p/the-invisble-asymmetry?r=5cjm1c&utm_campaign=post&utm_medium=web

The Invisble Asymmetry - Scott Cotton

The only article I've seen whose cover image legitimately shows trees running on a track.

Evaluation in Tony Format

Scott Cotton ・ Feb 4

Evaluation in Tony Format

How it works

Expression syntax

Script functions

The eval tags

Tag composition

Composition with o build

Use case: keeping configuration DRY

Use case: generating config test fixtures

Not a template engine

Structured Matching, Patching, and Diffing Done Right

The IR: One Tree to Rule Them All

The Three Operations

Matching

Patching

Keyed Lists

Diffing

Composition

Conclusion

All I have to say is !

One Source, Two Outputs: Generating K8s YAML and Helm Charts with Tony Format

Scott Cotton ・ Jan 8

One Source, Two Outputs: Generating K8s YAML and Helm Charts with Tony Format

The Impedance Mismatch

Our Old Workflow: Death by a Thousand Hacks

hack/fix-cm.go: Working Around Kustomize's ConfigMap Limitations

hack/templatize.go: 450 Lines of Regex

Tony's Solution: Valid Documents All the Way Down

The New Workflow

Why This Actually Works

Generic Tools Beat Domain-Specific Ones

Structural Matching

Conditionals Without Directory Explosion

Looking Forward

What `o build` Does

Patching ArgoCD with `o build`

Composition with `o build`