mirror of
https://github.com/opentffoundation/opentf.git
synced 2026-02-17 01:00:39 -05:00
f260ed1177
We originally included this warning because the go-cty-yaml module wasn't yet stable and it was also not extensively tested so it wasn't yet clear if its behavior would need to change in some less common cases we hadn't tested so far. However, go-cty-yaml had its v1.0.0 release some time ago and is now committed to preserving its current Marshal output unless it is found to be non-compliant with the YAML 1.2 specification. This doc change means that Terraform's yamlencode is now adopting a similar posture: - The exact style details produced by the function for a particular input are now frozen. It'll change only if we find that the function is producing output that isn't valid per the YAML spec. - If someone finds a YAML parser that cannot parse what yamlencode produces but what it produces is valid per the YAML 1.2 spec, we'll expect the parser to be corrected to better support the spec rather than changing the yamlencode output. There may be pragmatic exceptions if we encounter a situation we cannot anticipate yet, but the above will be our general rule. This is really just a specialization of the spirit of the v1.x Compatibility Promises, tailored specifically to this function.
78 lines
2.5 KiB
Plaintext
78 lines
2.5 KiB
Plaintext
---
|
|
page_title: yamlencode - Functions - Configuration Language
|
|
description: The yamlencode function encodes a given value as a YAML string.
|
|
---
|
|
|
|
# `yamlencode` Function
|
|
|
|
`yamlencode` encodes a given value to a string using
|
|
[YAML 1.2](https://yaml.org/spec/1.2/spec.html) block syntax.
|
|
|
|
This function maps
|
|
[Terraform language values](/language/expressions/types)
|
|
to YAML tags in the following way:
|
|
|
|
| Terraform type | YAML type |
|
|
| -------------- | -------------------- |
|
|
| `string` | `!!str` |
|
|
| `number` | `!!float` or `!!int` |
|
|
| `bool` | `!!bool` |
|
|
| `list(...)` | `!!seq` |
|
|
| `set(...)` | `!!seq` |
|
|
| `tuple(...)` | `!!seq` |
|
|
| `map(...)` | `!!map` |
|
|
| `object(...)` | `!!map` |
|
|
| Null value | `!!null` |
|
|
|
|
`yamlencode` uses the implied syntaxes for all of the above types, so it does
|
|
not generate explicit YAML tags.
|
|
|
|
Because the YAML format cannot fully represent all of the Terraform language
|
|
types, passing the `yamlencode` result to `yamldecode` will not produce an
|
|
identical value, but the Terraform language automatic type conversion rules
|
|
mean that this is rarely a problem in practice.
|
|
|
|
YAML is a superset of JSON, and so where possible we recommend generating
|
|
JSON using [`jsonencode`](/language/functions/jsonencode) instead, even if
|
|
a remote system supports YAML. JSON syntax is equivalent to flow-style YAML
|
|
and Terraform can present detailed structural change information for JSON
|
|
values in plans, whereas Terraform will treat block-style YAML just as a normal
|
|
multi-line string. However, generating YAML may improve readability if the
|
|
resulting value will be directly read or modified in the remote system by
|
|
humans.
|
|
|
|
## Examples
|
|
|
|
```
|
|
> yamlencode({"a":"b", "c":"d"})
|
|
"a": "b"
|
|
"c": "d"
|
|
|
|
> yamlencode({"foo":[1, 2, 3], "bar": "baz"})
|
|
"bar": "baz"
|
|
"foo":
|
|
- 1
|
|
- 2
|
|
- 3
|
|
|
|
> yamlencode({"foo":[1, {"a":"b","c":"d"}, 3], "bar": "baz"})
|
|
"bar": "baz"
|
|
"foo":
|
|
- 1
|
|
- "a": "b"
|
|
"c": "d"
|
|
- 3
|
|
```
|
|
|
|
`yamlencode` always uses YAML's "block style" for mappings and sequences, unless
|
|
the mapping or sequence is empty. To generate flow-style YAML, use
|
|
[`jsonencode`](/language/functions/jsonencode) instead: YAML flow-style is a superset
|
|
of JSON syntax.
|
|
|
|
## Related Functions
|
|
|
|
- [`jsonencode`](/language/functions/jsonencode) is a similar operation using JSON instead
|
|
of YAML.
|
|
- [`yamldecode`](/language/functions/yamldecode) performs the opposite operation, _decoding_
|
|
a YAML string to obtain its represented value.
|