FAQ

Data Values ¶

Data values doc

Is it possible to add a new key to my values via the --data-value command line argument? ¶

No. As with all data values, those passed through --data-value must be overrides, not new values. Instead, overlays are the intended way to provide new keys. See the data values vs overlays doc for more information.

How can I dynamically set or replace map key as a data value in my template? ¶

You can use data.values value as a key in a map by using Text Templating feature. That way, you can dynamically set keys in a map using data values.

#@yaml/text-templated-strings
(@= data.values.some_key @): some-value

Additionally, see this playground example which illustrates the use of text templating to set key of a map item.

How do I load json for use as a data value? ¶

An important note here is that json is valid yaml. yaml syntax is a superset of json syntax.
ytt can naturally parse json by passing it through --data-value-yaml, or json can be loaded by passing the file as a --data-value-file.

Additional resources: json is valid yaml, loading by file

How do I check if a key is set? ¶

You can check for the existence of a key by using hasattr.
For example, to check if struct foo has attribute bar, use hasattr(foo, "bar").

How do I provide a default for a data value when it may not be defined? ¶

When a value may be null, you can use or to specify a default.

#@ data.values.foo or "bar"

How do I error if a data value is not provided? ¶

ytt library’s assert package is useful for such situations. It can be used like so:

password: #@ data.values.env.mysql_password if data.values.env.mysql_password else assert.fail("missing env.mysql_password")

or even more compactly,

password: #@ data.values.env.mysql_password or assert.fail("missing env.mysql_password")

Note that empty strings are falsy in Starlark.

Overlays ¶

Overlays doc

How do I remove a document subset? ¶

#@overlay/remove in conjunction with #@overlay/match by=overlay.subset() annotations are useful for removing a subset of a document.

Additional resources: overlay remove docs, overlay subset docs

How do I add items to an existing array?   ¶

Using v0.32.0 or later, the default behavior of overlays is to append array items. Simply put your array item in an overlay.

Prior to v0.32.0, To add an item, either provide the matching annotation (eg. #@overlay/match by="field_name"), or use the #@overlay/append annotation to add to the end of the list. Note that the append annotation must be applied to each item you want to insert.

Additional resources: overlay append docs, example gist on playground, replace-list gist, edit-list gist

Why am I getting an exception when trying to append to an array? ¶

A common append issue is incorrectly setting the #@overlay/match missing_ok=True annotation on the key which gets replaced by new key-values. Instead, it should be applied to each child (made convenient with the #@overlay/match-child-defaults missing_ok=True annotation). See this illustrative gist for an example.

How do I rename a key without changing the value? ¶

An #@overlay/replace annotation with a lambda via. For example, to replace the key bad_name with better_name while retaining the value, you can use:

#@overlay/replace via=lambda a,b: {"better_name": a["bad_name"]}

See this gist for the full example.

How do I add or replace a value in a dictionary? ¶

A #@ template.replace() annotation can be used for these purposes. See this example. You can also use overlays to edit a dictionary, an example can be found on this gist playground.

How do I match a field.name that starts with a string? ¶

overlay/match by=lambda a,_: a["field"]["name"].startswith("string")

How do I match a struct based on the presence of a key? ¶

To match a dictionary from a list of dictionaries if the foo key is present, you can use #@overlay/match by=lambda idx,old,new: "foo" in old, expects="1+".

How do I modify only part of a multi-line string? ¶

An #@overlay/replace annotation with a lambda via function can modify part of a string. See this modify-string gist for an example.

How can I match a regex pattern in the subset matcher? ¶

The subset matcher does not directly support regex patterns. Instead, a custom matcher can be written. See this playground gist for an example.

When should I include a space in my ytt comment? Does it matter? Is it #@load or #@ load? #@overlay/match or #@ overlay/match ¶

The space is subtly meaningful, and directly, load needs a space, while overlay/match does not – but why?

ytt wraps two concepts in its comment syntax:

1. Annotations on a node
2. Directives for ytt

Annotations do not have a space, and they refer to a given node in the tree. These comments attach metadata to the annotated node, which can be used during templating. Some examples of annotations are:

• When inserting a node via an overlay, we would annotate that node with #@overlay/insert.
• When we want to mark a document as containing data values, we annotate the document start marker with #@data/values.

Directives, on the other hand, do include a space, and are used to direct ytt to execute the arguments. Some examples of directives are:

• Loading a library, we add the #@ load directive to the doc, unattached to any particular node.
• To begin and end a for loop or conditional, we use the #@ for, #@ if, and #@ end directives.

For further exploration, investigate what happens when you move an annotation comment and compare it with moving a directive comment!

Why is ytt complaining about “Unknown comment syntax”; can’t I write standard YAML comments (#)? ¶

You can, but it is discouraged to avoid tricky errors that can go unchecked.

The recommended approach is when writing ytt templated files, use ytt comments:

#! this is a ytt comment; it's like she-bang!

If for some reason you need to disable this “linting” check (e.g. you’re gradually migrating an existing YAML file to become a ytt template and it’s onerous to convert all those comments at once), include the --ignore-unknown-comments flag.

For a detailed explanation of how ytt detects and processes YAML files, see File Marks > type detection for YAML files.

Why is my anchor reference null despite my anchor’s successful template? ¶

This is a known limitation of ytt.

Can I generate random strings with ytt? ¶

No. A design goal of ytt is determinism, which keeps randomness out of scope.

If you want to generate secrets, see the injecting secrets doc or the kubernetes secretgen-controller

Can I load multiple functions without having to name each one? ¶

Yes! Functions can be stored in a struct which can be imported all together. You can then call individual functions from within that struct. Note that because Starlark does not provide forward references, you must declare the struct that collects the functions to export at the end of the file.

Storing functions in struct:

#@ load("@ytt:struct", "struct")
#@ mod = struct.make(func1=func1, func2=func2)

Loading and calling functions in template:

#@ load("helpers.lib.yml", "mod")
something: #@ mod.func1()

Additional resources: Load Statement doc

How do I inject secrets? ¶

See the injecting secrets doc.

How do I template values within text? ¶

See the text templating doc. Additionally, see this playground example which illustrates some ways text templating can be done.

How can I use files that are symlinks? ¶

ytt takes a secure by default approach to symlinks. It disables use of symlinks to avoid the risk of malicious template code loading symlinked file contents from sensitive locations.

If you would like to override this behavior, use --allow-symlink-destination flag for allowing symlinks in specific directories or files, or --dangerous-allow-all-symlink-destinations to allow all symlinks.

What templating language does ytt use? ¶

ytt uses a fork of Starlark, with a few changes. See the Language reference for more information.