Kustomize-style overlays that say what they expect

A Kustomize overlay states the new value and nothing about the old one, so it applies just as happily to a base that changed underneath it. In NOVA an overlay is a patch: replicas: 5 -> 8 changes the value only if it is still 5.

Kustomize: the new value replicas-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api
spec:
  replicas: 8
was it 5? nobody checks
NOVA: the change prod.nova-patch
@patch sha256:91cf16db
@scope services[id=api]
replicas: 5 -> 8
? enabled: true
only this base
only inside api
only if it is 5
only if enabled

If any line fails, nothing is applied, and the error names the line with the expected and the actual value. Patch semantics, spec §7.5

What changes

TopicKustomizeNOVASpec
PreconditionsNone; the overlay value winsold -> new replaces only the expected value; ? tests without changing§7.5
Base driftThe overlay applies to whatever the base is nowAn optional base revision; a changed base is a conflict§7.5
ScopeA target by kind and name@scope limits every operation to one subtree§7.4
List itemsMerge keys per resource type, or JSON Patch indexesKeyed selectors like services[id=api], unique with @key§6.2
ValidationLater, by kubectl or the API serverAgainst the schema, before the result is accepted§7.5
Writing overlaysBy handBy hand, or nvf diff between two files§7.6

Migrating

An overlay needs no new mechanism: render the base, then apply the patch. Comments and layout survive, because the patch edits the text in place.

nvf render base.tpl.nova --set env=prod > base.nova
nvf patch base.nova prod.nova-patch --schema infra.novs
Someone changed the base to 6
$ nvf patch base.nova prod.nova-patch
  × patch rejected: operation 1 failed; nothing was applied
   ╭─[prod.nova-patch:3:1]
 3 │ replicas: 5 -> 8
   ·         ╰── conflict: expected 5, found 6
Or let NOVA write the overlay
nvf diff base.nova prod.nova > prod.nova-patch

Overlays get the same conditional operations, atomicity and validation as edits by agents. Overlays, spec §9.6

When to stay with Kustomize

  • You need what Kustomize knows about Kubernetes: merge keys for each resource type, ConfigMap and Secret generators, name prefixes and labels. NOVA patches are generic and know none of it.
  • Your pipeline runs kubectl apply -k. Kustomize is built into kubectl; NOVA is a separate tool.
  • You need a format that is stable today. NOVA is a 0.1 draft.

Questions

What happens when an overlay no longer fits the base?

The patch is rejected as a whole and the base is unchanged. The error names the failing operation by index and line, with the expected and the actual value, or reports a stale base revision.

Does nvf diff produce conditional patches?

Yes. Every change it emits is old -> new or - path: old, and the patch carries the base revision. List items are matched by a unique id, key or name field when possible.

Can I patch YAML files?

Convert them first. Patches apply to NOVA documents, and nvf convert reads YAML, JSON and TOML.