github.com/hugorut/terraform@v1.1.3/website/docs/language/syntax/configuration.mdx (about)

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