github.com/iaas-resource-provision/iaas-rpc@v1.0.7-0.20211021023331-ed21f798c408/website/docs/language/syntax/configuration.html.md (about)

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