Carvel Logo

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