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

     1  ---
     2  layout: "language"
     3  page_title: "Override Files - Configuration Language"
     4  sidebar_current: "docs-config-override"
     5  description: |-
     6    How Terraform override files merge additional settings into existing configuration objects.
     7  ---
     8  
     9  # Override Files
    10  
    11  Terraform normally loads all of the `.tf` and `.tf.json` files within a
    12  directory and expects each one to define a distinct set of configuration
    13  objects. If two files attempt to define the same object, Terraform returns
    14  an error.
    15  
    16  In some rare cases, it is convenient to be able to override specific portions
    17  of an existing configuration object in a separate file. For example, a
    18  human-edited configuration file in the Terraform language native syntax
    19  could be partially overridden using a programmatically-generated file
    20  in JSON syntax.
    21  
    22  For these rare situations, Terraform has special handling of any configuration
    23  file whose name ends in `_override.tf` or `_override.tf.json`. This special
    24  handling also applies to a file named literally `override.tf` or
    25  `override.tf.json`.
    26  
    27  Terraform initially skips these _override files_ when loading configuration,
    28  and then afterwards processes each one in turn (in lexicographical order). For
    29  each top-level block defined in an override file, Terraform attempts to find
    30  an already-defined object corresponding to that block and then merges the
    31  override block contents into the existing object.
    32  
    33  Use override files only in special circumstances. Over-use of override files
    34  hurts readability, since a reader looking only at the original files cannot
    35  easily see that some portions of those files have been overridden without
    36  consulting all of the override files that are present. When using override
    37  files, use comments in the original files to warn future readers about which
    38  override files apply changes to each block.
    39  
    40  ## Example
    41  
    42  If you have a Terraform configuration `example.tf` with the following contents:
    43  
    44  ```hcl
    45  resource "aws_instance" "web" {
    46    instance_type = "t2.micro"
    47    ami           = "ami-408c7f28"
    48  }
    49  ```
    50  
    51  ...and you created a file `override.tf` containing the following:
    52  
    53  ```hcl
    54  resource "aws_instance" "web" {
    55    ami = "foo"
    56  }
    57  ```
    58  
    59  Terraform will merge the latter into the former, behaving as if the original
    60  configuration had been as follows:
    61  
    62  ```hcl
    63  resource "aws_instance" "web" {
    64    instance_type = "t2.micro"
    65    ami           = "foo"
    66  }
    67  ```
    68  
    69  ## Merging Behavior
    70  
    71  The merging behavior is slightly different for each block type, and some
    72  special constructs within certain blocks are merged in a special way.
    73  
    74  The general rule, which applies in most cases, is:
    75  
    76  * A top-level block in an override file merges with a block in a normal
    77    configuration file that has the same block header. The block _header_ is the
    78    block type and any quoted labels that follow it.
    79  
    80  * Within a top-level block, an attribute argument within an override block
    81    replaces any argument of the same name in the original block.
    82  
    83  * Within a top-level block, any nested blocks within an override block replace
    84    _all_ blocks of the same type in the original block. Any block types that
    85    do not appear in the override block remain from the original block.
    86  
    87  * The contents of nested configuration blocks are not merged.
    88  
    89  * The resulting _merged block_ must still comply with any validation rules
    90    that apply to the given block type.
    91  
    92  If more than one override file defines the same top-level block, the overriding
    93  effect is compounded, with later blocks taking precedence over earlier blocks.
    94  Overrides are processed in order first by filename (in lexicographical order)
    95  and then by position in each file.
    96  
    97  The following sections describe the special merging behaviors that apply to
    98  specific arguments within certain top-level block types.
    99  
   100  ### Merging `resource` and `data` blocks
   101  
   102  Within a `resource` block, the contents of any `lifecycle` nested block are
   103  merged on an argument-by-argument basis. For example, if an override block
   104  sets only the `create_before_destroy` argument then any `ignore_changes`
   105  argument in the original block will be preserved.
   106  
   107  If an overriding `resource` block contains one or more `provisioner` blocks
   108  then any `provisioner` blocks in the original block are ignored.
   109  
   110  If an overriding `resource` block contains a `connection` block then it
   111  completely overrides any `connection` block present in the original block.
   112  
   113  The `depends_on` meta-argument may not be used in override blocks, and will
   114  produce an error.
   115  
   116  ### Merging `variable` blocks
   117  
   118  The arguments within a `variable` block are merged in the standard way
   119  described above, but some special considerations apply due to the interactions
   120  between the `type` and `default` arguments.
   121  
   122  If the original block defines a `default` value and an override block changes
   123  the variable's `type`, Terraform attempts to convert the default value to
   124  the overridden type, producing an error if this conversion is not possible.
   125  
   126  Conversely, if the original block defines a `type` and an override block changes
   127  the `default`, the overridden default value must be compatible with the
   128  original type specification.
   129  
   130  ### Merging `output` blocks
   131  
   132  The `depends_on` meta-argument may not be used in override blocks, and will
   133  produce an error.
   134  
   135  ### Merging `locals` blocks
   136  
   137  Each `locals` block defines a number of named values. Overrides are applied
   138  on a value-by-value basis, ignoring which `locals` block they are defined in.
   139  
   140  ### Merging `terraform` blocks
   141  
   142  The settings within `terraform` blocks are considered individually when
   143  merging.
   144  
   145  If the `required_providers` argument is set, its value is merged on an
   146  element-by-element basis, which allows an override block to adjust the
   147  constraint for a single provider without affecting the constraints for
   148  other providers.
   149  
   150  In both the `required_version` and `required_providers` settings, each override
   151  constraint entirely replaces the constraints for the same component in the
   152  original block. If both the base block and the override block both set
   153  `required_version` then the constraints in the base block are entirely ignored.