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

     1  ---
     2  layout: "docs"
     3  page_title: "Syntax - Configuration Language"
     4  sidebar_current: "docs-config-syntax"
     5  description: |-
     6    The Terraform language has its own syntax, intended to combine declarative
     7    structure with expressions in a way that is easy for humans to read and
     8    understand.
     9  ---
    10  
    11  # Configuration Syntax
    12  
    13  -> **Note:** This page is about Terraform 0.12 and later. For Terraform 0.11 and
    14  earlier, see
    15  [0.11 Configuration Language: Syntax](../configuration-0-11/syntax.html).
    16  
    17  Other pages in this section have described various configuration constructs
    18  that can appear in the Terraform language. This page describes the lower-level
    19  syntax of the language in more detail, revealing the building blocks that
    20  those constructs are built from.
    21  
    22  This page describes the _native syntax_ of the Terraform language, which is
    23  a rich language designed to be easy for humans to read and write. The
    24  constructs in the Terraform language can also be expressed in
    25  [JSON syntax](./syntax-json.html), which is harder for humans
    26  to read and edit but easier to generate and parse programmatically.
    27  
    28  This low-level syntax of the Terraform language is defined in terms of a
    29  syntax called _HCL_, which is also used by configuration languages in
    30  other applications, and in particular other HashiCorp products.
    31  It is not necessary to know all of the details of HCL syntax in
    32  order to use Terraform, and so this page summarizes the most important
    33  details. If you are interested, you can find a full definition of HCL
    34  syntax in
    35  [the HCL native syntax specification](https://github.com/hashicorp/hcl/blob/hcl2/hclsyntax/spec.md).
    36  
    37  ## Arguments and Blocks
    38  
    39  The Terraform language syntax is built around two key syntax constructs:
    40  arguments and blocks.
    41  
    42  ### Arguments
    43  
    44  An _argument_ assigns a value to a particular name:
    45  
    46  ```hcl
    47  image_id = "abc123"
    48  ```
    49  
    50  The identifier before the equals sign is the _argument name_, and the expression
    51  after the equals sign is the argument's value.
    52  
    53  The context where the argument appears determines what value types are valid
    54  (for example, each resource type has a schema that defines the types of its
    55  arguments), but many arguments accept arbitrary
    56  [expressions](./expressions.html), which allow the value to
    57  either be specified literally or generated from other values programmatically.
    58  
    59  -> **Note:** Terraform's configuration language is based on a more general
    60  language called HCL, and HCL's documentation usually uses the word "attribute"
    61  instead of "argument." These words are similar enough to be interchangeable in
    62  this context, and experienced Terraform users might use either term in casual
    63  conversation. But because Terraform also interacts with several _other_ things
    64  called "attributes" (in particular, Terraform resources have attributes like
    65  `id` that can be referenced from expressions but can't be assigned values in
    66  configuration), we've chosen to use "argument" in the Terraform documentation
    67  when referring to this syntax construct.
    68  
    69  ### Blocks
    70  
    71  A _block_ is a container for other content:
    72  
    73  ```hcl
    74  resource "aws_instance" "example" {
    75    ami = "abc123"
    76  
    77    network_interface {
    78      # ...
    79    }
    80  }
    81  ```
    82  
    83  A block has a _type_ (`resource` in this example). Each block type defines
    84  how many _labels_ must follow the type keyword. The `resource` block type
    85  expects two labels, which are `aws_instance` and `example` in the example above.
    86  A particular block type may have any number of required labels, or it may
    87  require none as with the nested `network_interface` block type.
    88  
    89  After the block type keyword and any labels, the block _body_ is delimited
    90  by the `{` and `}` characters. Within the block body, further arguments
    91  and blocks may be nested, creating a hierarchy of blocks and their associated
    92  arguments.
    93  
    94  The Terraform language uses a limited number of _top-level block types,_ which
    95  are blocks that can appear outside of any other block in a configuration file.
    96  Most of Terraform's features (including resources, input variables, output
    97  values, data sources, etc.) are implemented as top-level blocks.
    98  
    99  ## Identifiers
   100  
   101  Argument names, block type names, and the names of most Terraform-specific
   102  constructs like resources, input variables, etc. are all _identifiers_.
   103  
   104  Identifiers can contain letters, digits, underscores (`_`), and hyphens (`-`).
   105  The first character of an identifier must not be a digit, to avoid ambiguity
   106  with literal numbers.
   107  
   108  For complete identifier rules, Terraform implements
   109  [the Unicode identifier syntax](http://unicode.org/reports/tr31/), extended to
   110  include the ASCII hyphen character `-`.
   111  
   112  ## Comments
   113  
   114  The Terraform language supports three different syntaxes for comments:
   115  
   116  * `#` begins a single-line comment, ending at the end of the line.
   117  * `//` also begins a single-line comment, as an alternative to `#`.
   118  * `/*` and `*/` are start and end delimiters for a comment that might span
   119    over multiple lines.
   120  
   121  The `#` single-line comment style is the default comment style and should be
   122  used in most cases. Automatic configuration formatting tools may automatically
   123  transform `//` comments into `#` comments, since the double-slash style is
   124  not idiomatic.
   125  
   126  ## Character Encoding and Line Endings
   127  
   128  Terraform configuration files must always be UTF-8 encoded. While the
   129  delimiters of the language are all ASCII characters, Terraform accepts
   130  non-ASCII characters in identifiers, comments, and string values.
   131  
   132  Terraform accepts configuration files with either Unix-style line endings
   133  (LF only) or Windows-style line endings (CR then LF), but the idiomatic style
   134  is to use the Unix convention, and so automatic configuration formatting tools
   135  may automatically transform CRLF endings to LF.