v1.111.0
Introduce Atmos YAML functions @aknysh (#810)
what
- Introduce Atmos YAML functions
- Update docs
why
Atmos YAML Functions are a crucial part of Atmos stack manifests. They allow you to manipulate data and perform operations on the data to customize the stack configurations.
Atmos YAML functions are based on YAML Explicit typing and user-defined Explicit Tags (local data types). Explicit tags are denoted by the exclamation point ("!") symbol. Atmos detects the tags in the stack manifests and executes the corresponding functions.
NOTE: YAML data types can be divided into three categories: core, defined, and user-defined. Core are ones expected to exist in any parser (e.g. floats, ints, strings, lists, maps). Many more advanced data types, such as binary data, are defined in the YAML specification but not supported in all implementations. Finally, YAML defines a way to extend the data type definitions locally to accommodate user-defined classes, structures, primitives, and functions.
Atmos YAML functions
-
The
!template
YAML function can be used to handle template outputs containing maps or lists returned from theatmos.Component
template function -
The
!exec
YAML function is used to execute shell scripts and assign the results to the sections in Atmos stack manifests -
The
!terraform.output
YAML function is used to read the outputs (remote state) of components directly in Atmos stack manifests
NOTE: You can use Atmos Stack Manifest Templating and Atmos YAML functions in the same stack configurations at the same time. Atmos processes the templates first, and then executes the YAML functions, allowing you to provide the parameters to the YAML functions dynamically.
Examples
components:
terraform:
component2:
vars:
# Handle the output of type list from the `atmos.Component` template function
test_1: !template '{{ toJson (atmos.Component "component1" "plat-ue2-dev").outputs.test_list }}'
# Handle the output of type map from the `atmos.Component` template function
test_2: !template '{{ toJson (atmos.Component "component1" .stack).outputs.test_map }}'
# Execute the shell script and assign the result to the `test_3` variable
test_3: !exec echo 42
# Execute the shell script to get the `test_label_id` output from the `component1` component in the stack `plat-ue2-dev`
test_4: !exec atmos terraform output component1 -s plat-ue2-dev --skip-init -- -json test_label_id
# Execute the shell script to get the `test_map` output from the `component1` component in the current stack
test_5: !exec atmos terraform output component1 -s {{ .stack }} --skip-init -- -json test_map
# Execute the shell script to get the `test_list` output from the `component1` component in the current stack
test_6: !exec atmos terraform output component1 -s {{ .stack }} --skip-init -- -json test_list
# Get the `test_label_id` output of type string from the `component1` component in the stack `plat-ue2-dev`
test_7: !terraform.output component1 plat-ue2-dev test_label_id
# Get the `test_label_id` output of type string from the `component1` component in the current stack
test_8: !terraform.output component1 {{ .stack }} test_label_id
# Get the `test_list` output of type list from the `component1` component in the current stack
test_9: !terraform.output component1 {{ .stack }} test_list
# Get the `test_map` output of type map from the `component1` component in the current stack
test_10: !terraform.output component1 {{ .stack }} test_map