github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/configuration/functions/yamlencode.html.md (about)

     1  ---
     2  layout: "functions"
     3  page_title: "yamlencode - Functions - Configuration Language"
     4  sidebar_current: "docs-funcs-encoding-yamlencode"
     5  description: |-
     6    The yamlencode function encodes a given value as a YAML string.
     7  ---
     8  
     9  # `yamlencode` Function
    10  
    11  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    12  earlier, see
    13  [0.11 Configuration Language: Interpolation Syntax](../../configuration-0-11/interpolation.html).
    14  
    15  `yamlencode` encodes a given value to a string using
    16  [YAML 1.2](https://yaml.org/spec/1.2/spec.html) block syntax.
    17  
    18  ~> **Warning:** This function is currently **experimental** and its exact
    19  result format may change in future versions of Terraform, based on feedback.
    20  Do not use `yamldecode` to construct a value for any resource argument where
    21  changes to the result would be disruptive. To get a consistent string
    22  representation of a value use [`jsonencode`](./jsonencode.html) instead; its
    23  results are also valid YAML because YAML is a JSON superset.
    24  
    25  <!--
    26      The condition for removing the above warning is that the underlying
    27      go-cty-yaml module makes a stable release with a commitment to guarantee
    28      that the representation of particular input will not change without a
    29      major release. It is not making that commitment at the time of writing to
    30      allow for responding to user feedback about its output format, since YAML
    31      is a very flexible format and its initial decisions may prove to be
    32      sub-optimal when generating YAML intended for specific external consumers.
    33  -->
    34  
    35  This function maps
    36  [Terraform language values](../expressions.html#types-and-values)
    37  to YAML tags in the following way:
    38  
    39  | Terraform type | YAML type            |
    40  | -------------- | -------------------- |
    41  | `string`       | `!!str`              |
    42  | `number`       | `!!float` or `!!int` |
    43  | `bool`         | `!!bool`             |
    44  | `list(...)`    | `!!seq`              |
    45  | `set(...)`     | `!!seq`              |
    46  | `tuple(...)`   | `!!seq`              |
    47  | `map(...)`     | `!!map`              |
    48  | `object(...)`  | `!!map`              |
    49  | Null value     | `!!null`             |
    50  
    51  `yamlencode` uses the implied syntaxes for all of the above types, so it does
    52  not generate explicit YAML tags.
    53  
    54  Because the YAML format cannot fully represent all of the Terraform language
    55  types, passing the `yamlencode` result to `yamldecode` will not produce an
    56  identical value, but the Terraform language automatic type conversion rules
    57  mean that this is rarely a problem in practice.
    58  
    59  ## Examples
    60  
    61  ```
    62  > yamlencode({"a":"b", "c":"d"})
    63  "a": "b"
    64  "c": "d"
    65  
    66  > yamlencode({"foo":[1, 2, 3], "bar": "baz"})
    67  "bar": "baz"
    68  "foo":
    69  - 1
    70  - 2
    71  - 3
    72  
    73  > yamlencode({"foo":[1, {"a":"b","c":"d"}, 3], "bar": "baz"})
    74  "bar": "baz"
    75  "foo":
    76  - 1
    77  - "a": "b"
    78    "c": "d"
    79  - 3
    80  ```
    81  
    82  `yamlencode` always uses YAML's "block style" for mappings and sequences, unless
    83  the mapping or sequence is empty. To generate flow-style YAML, use
    84  [`jsonencode`](./jsonencode.html) instead: YAML flow-style is a superset
    85  of JSON syntax.
    86  
    87  ## Related Functions
    88  
    89  - [`jsonencode`](./jsonencode.html) is a similar operation using JSON instead
    90    of YAML.
    91  - [`yamldecode`](./yamldecode.html) performs the opposite operation, _decoding_
    92    a YAML string to obtain its represented value.