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

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