Overlays

Overview ¶

The way to describe patch-like edits in ytt is via “Overlays”.

(For a high-level overview of ytt, see How it works.)

What are they? ¶

Sometimes it makes more sense to patch some YAML rather than template it.

For example, when:

• the file should not be edited directly (e.g. from a third party);
• the edit will apply to most or all documents; or
• the specific variable is less commonly configured.

Given a sample target YAML file:

config.yml

---
id: 1
contents:
- apple
---
id: 2
contents:
- pineapple

… this overlay …

add-content.yml

#@ load("@ytt:overlay", "overlay")

#@overlay/match by=overlay.all, expects="1+"
---
contents:
- pen

Prior to v0.32.0 append array items with #@overlay/append

read as…

1. “match all YAML documents, expecting to match at least one;”
2. “within each document, merge the key named contents;”
3. “append an array item with the content "pen"”

… when processed by ytt …

$ ytt -f config.yml -f add-content.yml

… produces …

config.yml (edited)

id: 1
contents:
- apple
- pen
---
id: 2
contents:
- pineapple
- pen

Next Steps ¶

• Overlay example in the ytt Playground to try it out, yourself.
• ytt Library: Overlay module for reference of all overlay annotations and functions.
• Data Values vs Overlays for when to use one mechanism over the other.