382e1ca821
These follow the same principle as jsondecode and jsonencode, but use YAML instead of JSON. YAML has a much more complex information model than JSON, so we can only support a subset of it during decoding, but hopefully the subset supported here is a useful one. Because there are many different ways to _generate_ YAML, the yamlencode function is forced to make some decisions, and those decisions are likely to affect compatibility with other real-world YAML parsers. Although the format here is intended to be generic and compatible, we may find that there are problems with it that'll we'll want to adjust for in a future release, so yamlencode is therefore marked as experimental for now until the underlying library is ready to commit to ongoing byte-for-byte compatibility in serialization. The main use-case here is met by yamldecode, which will allow reading in files written in YAML format by humans for use in Terraform modules, in situations where a higher-level input format than direct Terraform language declarations is helpful.
3.6 KiB
| layout | page_title | sidebar_current | description |
|---|---|---|---|
| functions | yamldecode - Functions - Configuration Language | docs-funcs-encoding-yamldecode | The yamldecode function decodes a YAML string into a representation of its value. |
yamldecode Function
-> Note: This page is about Terraform 0.12 and later. For Terraform 0.11 and earlier, see 0.11 Configuration Language: Interpolation Syntax.
yamldecode parses a string as a subset of YAML, and produces a representation
of its value.
This function supports a subset of YAML 1.2, as described below.
This function maps YAML values to Terraform language values in the following way:
| YAML type | Terraform type |
|---|---|
!!str |
string |
!!float |
number |
!!int |
number |
!!bool |
bool |
!!map |
object(...) with attribute types determined per this table |
!!seq |
tuple(...) with element types determined per this table |
!!null |
The Terraform language null value |
!!timestamp |
string in RFC 3339 format |
!!binary |
string containing base64-encoded representation |
The Terraform language automatic type conversion rules mean that you don't usually need to worry about exactly what type is produced for a given value, and can just use the result in an intuitive way.
Note though that the mapping above is ambiguous -- several different source
types map to the same target type -- and so round-tripping through yamldecode
and then yamlencode cannot produce an identical result.
YAML is a complex language and it supports a number of possibilities that the Terraform language's type system cannot represent. Therefore this YAML decoder supports only a subset of YAML 1.2, with restrictions including the following:
-
Although aliases to earlier anchors are supported, cyclic data structures (where a reference to a collection appears inside that collection) are not. If
yamldecodedetects such a structure then it will return an error. -
Only the type tags shown in the above table (or equivalent alternative representations of those same tags) are supported. Any other tags will result in an error.
-
Only one YAML document is permitted. If multiple documents are present in the given string then this function will return an error.
Examples
> yamldecode("{\"hello\": \"world\"}")
{
"hello" = "world"
}
> yamldecode("true")
true
> yamldecode("{a: &foo [1, 2, 3], b: *foo}")
{
"a" = [
1,
2,
3,
]
"b" = [
1,
2,
3,
]
}
> yamldecode("{a: &foo [1, *foo, 3]}")
Error: Error in function call
Call to function "yamldecode" failed: cannot refer to anchor "foo" from inside
its own definition.
> yamldecode("{a: !not-supported foo}")
Error: Error in function call
Call to function "yamldecode" failed: unsupported tag "!not-supported".
Related Functions
jsondecodeis a similar operation using JSON instead of YAML.yamlencodeperforms the opposite operation, encoding a value as YAML.