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

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