YTT transform

This topic tells you about the Application Accelerator YTT transform in Tanzu Application Platform (commonly known as TAP).

The YTT transform starts the YTT template engine as an external process.

Syntax reference

type: YTT
extraArgs: # optional
  - <SPEL-EXPRESSION-1>
  - <SPEL-EXPRESSION-2>
  - ...

The YTT transform’s YAML notation does not require any parameters. When invoked without parameters, which is the typical use case, the YTT transform’s input is determined entirely by two things only:

1. The input files fed into the transform.
2. The current values for options and derived symbols.

Execution

YTT is invoked as an external process with the following command line:

ytt -f <input-folder> \
    --data-values-file <symbols.json> \
    --output-files <output-folder> \
    <extra-args>

The <input-folder> is a temporary directory into which the input files are “materialized.” That is, the set of files passed to the YTT transform as input is written out into this directory to allow the YTT process to read them.

The <symbols.json> file is a temporary JSON file, which the current option values and derived symbols are materialized in the form of a JSON map. This allows YTT templates in the <input-folder> to make use of these symbols during processing.

The <output-folder> is a fresh temporary directory that is empty at the time of invocation. In a typical scenario, upon completion, the output directory contains files generated by YTT.

The <extra-args> are additional command line arguments obtained by evaluating the SPEL expressions from the extraArgs attribute.

When the ytt process completes with a 0 exit code, this is considered a successful execution and the contents of the output directory is taken to be the result of the YTT transform.

When the ytt process completes with a non 0 exit code, the execution of the YTT transform is considered to have failed and an exception is raised.

Examples

See the following examples using the YTT transform.

Basic invocation

When you want to execute ytt on the contents of the entire accelerator repository, use the YTT transform as your only transform in the engine declaration.

accelerator:
  ...
engine:
  type: YTT

To do anything beyond calling YTT, compose YTT into your accelerator flow using merge or chain combinators. This is exactly the same as composing any other type of transform.

For example, when you want to define some derived symbols as well as merge the results from YTT with results from other parts of your accelerator transform, you can reference this example:

engine:
  let: # Define derived symbols visible to all transforms (including YTT)
  - name: theAnswer
    expression: "41 + 1"
  merge:
  - include: ["deploy/**.yml"] # select some yaml files to process with YTT
    chain: # Chain selected yaml files to YTT
    - type: YTT
  - ... include/generate other stuff to be merged alongside yaml generated by YTT...

The preceding example uses a combination of Chain and Merge. You can use either Merge or Chain or both to compose YTT into your accelerator flow. Which one you choose depends on how you want to use YTT as part of your larger accelerator.

Using extraArgs

The extraArgs passes additional command line arguments to YTT. This adds file marks. See File Marks in the Carvel documentation.

For example, the following runs YTT and renames the foo/demo.yml file in its output to bar/demo.yml.

engine:
  type: YTT
  extraArgs: ["'--file-mark'",  "'foo/demo.yml:path=bar/demo.yml'"]

The extraArgs attribute expects SPEL expressions. Take care to use proper escaping of literal strings using double and single quotes (that is, `“‘LITERAL-STRING’”).