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 apiVersion: apps/v1
kind: Deployment
metadata:
name: api
spec:
replicas: 8NOVA: the change @patch sha256:91cf16db
@scope services[id=api]
replicas: 5 -> 8
? enabled: trueIf 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
| Topic | Kustomize | NOVA | Spec |
|---|---|---|---|
| Preconditions | None; the overlay value wins | old -> new replaces only the expected value; ? tests without changing | §7.5 |
| Base drift | The overlay applies to whatever the base is now | An optional base revision; a changed base is a conflict | §7.5 |
| Scope | A target by kind and name | @scope limits every operation to one subtree | §7.4 |
| List items | Merge keys per resource type, or JSON Patch indexes | Keyed selectors like services[id=api], unique with @key | §6.2 |
| Validation | Later, by kubectl or the API server | Against the schema, before the result is accepted | §7.5 |
| Writing overlays | By hand | By 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.novsSomeone 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 6Or let NOVA write the overlay nvf diff base.nova prod.nova > prod.nova-patchOverlays 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.