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.