github.com/eliastor/durgaform@v0.0.0-20220816172711-d0ab2d17673e/website/docs/cli/config/config-file.mdx (about) 1 --- 2 page_title: CLI Configuration 3 description: >- 4 Learn to use the CLI configuration file to customize your CLI settings, 5 including credentials, plugin caching, provider installation methods, etc. 6 --- 7 8 # CLI Configuration File (`.terraformrc` or `terraform.rc`) 9 10 The CLI configuration file configures per-user settings for CLI behaviors, 11 which apply across all Terraform working directories. This is separate from 12 [your infrastructure configuration](/language). 13 14 ## Locations 15 16 The configuration can be placed in a single file whose location depends 17 on the host operating system: 18 19 * On Windows, the file must be named `terraform.rc` and placed 20 in the relevant user's `%APPDATA%` directory. The physical location 21 of this directory depends on your Windows version and system configuration; 22 use `$env:APPDATA` in PowerShell to find its location on your system. 23 * On all other systems, the file must be named `.terraformrc` (note 24 the leading period) and placed directly in the home directory 25 of the relevant user. 26 27 On Windows, beware of Windows Explorer's default behavior of hiding filename 28 extensions. Terraform will not recognize a file named `terraform.rc.txt` as a 29 CLI configuration file, even though Windows Explorer may _display_ its name 30 as just `terraform.rc`. Use `dir` from PowerShell or Command Prompt to 31 confirm the filename. 32 33 The location of the Terraform CLI configuration file can also be specified 34 using the `TF_CLI_CONFIG_FILE` [environment variable](/cli/config/environment-variables). 35 Any such file should follow the naming pattern `*.tfrc`. 36 37 ## Configuration File Syntax 38 39 The configuration file uses the same _HCL_ syntax as `.tf` files, but with 40 different attributes and blocks. The following example illustrates the 41 general syntax; see the following section for information on the meaning 42 of each of these settings: 43 44 ```hcl 45 plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" 46 disable_checkpoint = true 47 ``` 48 49 ## Available Settings 50 51 The following settings can be set in the CLI configuration file: 52 53 * `credentials` - configures credentials for use with Terraform Cloud or 54 Terraform Enterprise. See [Credentials](#credentials) below for more 55 information. 56 57 * `credentials_helper` - configures an external helper program for the storage 58 and retrieval of credentials for Terraform Cloud or Terraform Enterprise. 59 See [Credentials Helpers](#credentials-helpers) below for more information. 60 61 * `disable_checkpoint` — when set to `true`, disables 62 [upgrade and security bulletin checks](/cli/commands#upgrade-and-security-bulletin-checks) 63 that require reaching out to HashiCorp-provided network services. 64 65 * `disable_checkpoint_signature` — when set to `true`, allows the upgrade and 66 security bulletin checks described above but disables the use of an anonymous 67 id used to de-duplicate warning messages. 68 69 * `plugin_cache_dir` — enables 70 [plugin caching](#provider-plugin-cache) 71 and specifies, as a string, the location of the plugin cache directory. 72 73 * `provider_installation` - customizes the installation methods used by 74 `terraform init` when installing provider plugins. See 75 [Provider Installation](#provider-installation) below for more information. 76 77 ## Credentials 78 79 [Terraform Cloud](/cloud) provides a number of remote network 80 services for use with Terraform, and 81 [Terraform Enterprise](/enterprise) allows hosting those 82 services inside your own infrastructure. For example, these systems offer both 83 [remote operations](/cloud-docs/run/cli) and a 84 [private module registry](/cloud-docs/registry). 85 86 When interacting with Terraform-specific network services, Terraform expects 87 to find API tokens in CLI configuration files in `credentials` blocks: 88 89 ```hcl 90 credentials "app.terraform.io" { 91 token = "xxxxxx.atlasv1.zzzzzzzzzzzzz" 92 } 93 ``` 94 95 If you are running the Terraform CLI interactively on a computer with a web browser, you can use [the `terraform login` command](/cli/commands/login) 96 to get credentials and automatically save them in the CLI configuration. If 97 not, you can manually write `credentials` blocks. 98 99 You can have multiple `credentials` blocks if you regularly use services from 100 multiple hosts. Many users will configure only one, for either 101 Terraform Cloud (at `app.terraform.io`) or for their organization's own 102 Terraform Enterprise host. Each `credentials` block contains a `token` argument 103 giving the API token to use for that host. 104 105 ~> **Important:** If you are using Terraform Cloud or Terraform Enterprise, 106 the token provided must be either a 107 [user token](/cloud-docs/users-teams-organizations/users#api-tokens) 108 or a 109 [team token](/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens); 110 organization tokens cannot be used for command-line Terraform actions. 111 112 -> **Note:** The credentials hostname must match the hostname in your module 113 sources and/or backend configuration. If your Terraform Enterprise instance 114 is available at multiple hostnames, use only one of them consistently. 115 Terraform Cloud responds to API calls at both its current hostname 116 `app.terraform.io`, and its historical hostname `atlas.hashicorp.com`. 117 118 ### Environment Variable Credentials 119 120 -> **Note:** Environment variable credentials are supported in Terraform v1.2.0 and later. 121 122 If you would prefer not to store your API tokens directly in the CLI configuration, you may use 123 a host-specific environment variable. Environment variable names should have the prefix 124 `TF_TOKEN_` added to the domain name, with periods encoded as underscores. For example, the 125 value of a variable named `TF_TOKEN_app_terraform_io` will be used as a bearer authorization 126 token when the CLI makes service requests to the hostname `app.terraform.io`. 127 128 You must convert domain names containing non-ASCII characters to their [punycode equivalent](https://www.charset.org/punycode) 129 with an ACE prefix. For example, token credentials for 例えば.com must be set in a variable 130 called `TF_TOKEN_xn--r8j3dr99h_com`. 131 132 Hyphens are also valid within host names but usually invalid as variable names and 133 may be encoded as double underscores. For example, you can set a token for the domain name 134 `café.fr` as `TF_TOKEN_xn--caf-dma.fr`, `TF_TOKEN_xn--caf-dma_fr`, or `TF_TOKEN_xn____caf__dma_fr`. 135 If multiple variables evaluate to the same hostname, Terraform will choose the one defined last 136 in the operating system's variable table. 137 138 ### Credentials Helpers 139 140 You can configure a `credentials_helper` to instruct Terraform to use a different credentials storage mechanism. 141 142 ```hcl 143 credentials_helper "example" { 144 args = [] 145 } 146 ``` 147 148 `credentials_helper` is a configuration block that can appear at most once 149 in the CLI configuration. Its label (`"example"` above) is the name of the 150 credentials helper to use. The `args` argument is optional and allows passing 151 additional arguments to the helper program, for example if it needs to be 152 configured with the address of a remote host to access for credentials. 153 154 A configured credentials helper will be consulted only to retrieve credentials 155 for hosts that are _not_ explicitly configured in a `credentials` block as 156 described in the previous section. 157 Conversely, this means you can override the credentials returned by the helper 158 for a specific hostname by writing a `credentials` block alongside the 159 `credentials_helper` block. 160 161 Terraform does not include any credentials helpers in the main distribution. 162 To learn how to write and install your own credentials helpers to integrate 163 with existing in-house credentials management systems, see 164 [the guide to Credentials Helper internals](/internals/credentials-helpers). 165 166 ### Credentials Source Priority Order 167 168 Credentials found in an environment variable for a particular service host 169 as described above will be preferred over those in CLI config as set by `terraform login`. 170 If neither are set, any configured credentials helper will be consulted. 171 172 ~> **Note:** For users of [terraform-credentials-helper](https://github.com/apparentlymart/terraform-credentials-env), this priority has been effectively reversed following the 173 release of Terraform 1.2. Previously, credentials found within CLI config or set by 174 `terraform login` were preferred to `TF_TOKEN_*` variables. 175 176 ## Provider Installation 177 178 The default way to install provider plugins is from a provider registry. The 179 origin registry for a provider is encoded in the provider's source address, 180 like `registry.terraform.io/hashicorp/aws`. For convenience in the common case, 181 Terraform allows omitting the hostname portion for providers on 182 `registry.terraform.io`, so you can write shorter public provider addresses like 183 `hashicorp/aws`. 184 185 Downloading a plugin directly from its origin registry is not always 186 appropriate, though. For example, the system where you are running Terraform 187 may not be able to access an origin registry due to firewall restrictions 188 within your organization or your locality. 189 190 To allow using Terraform providers in these situations, there are some 191 alternative options for making provider plugins available to Terraform which 192 we'll describe in the following sections. 193 194 ### Explicit Installation Method Configuration 195 196 A `provider_installation` block in the CLI configuration allows overriding 197 Terraform's default installation behaviors, so you can force Terraform to use 198 a local mirror for some or all of the providers you intend to use. 199 200 The general structure of a `provider_installation` block is as follows: 201 202 ```hcl 203 provider_installation { 204 filesystem_mirror { 205 path = "/usr/share/terraform/providers" 206 include = ["example.com/*/*"] 207 } 208 direct { 209 exclude = ["example.com/*/*"] 210 } 211 } 212 ``` 213 214 Each of the nested blocks inside the `provider_installation` block specifies 215 one installation method. Each installation method can take both `include` 216 and `exclude` patterns that specify which providers a particular installation 217 method can be used for. In the example above, we specify that any provider 218 whose origin registry is at `example.com` can be installed only from the 219 filesystem mirror at `/usr/share/terraform/providers`, while all other 220 providers can be installed only directly from their origin registries. 221 222 If you set both `include` and `exclude` for a particular installation 223 method, the exclusion patterns take priority. For example, including 224 `registry.terraform.io/hashicorp/*` but also excluding 225 `registry.terraform.io/hashicorp/dns` will make that installation method apply 226 to everything in the `hashicorp` namespace with the exception of 227 `hashicorp/dns`. 228 229 As with provider source addresses in the main configuration, you can omit 230 the `registry.terraform.io/` prefix for providers distributed through the 231 public Terraform registry, even when using wildcards. For example, 232 `registry.terraform.io/hashicorp/*` and `hashicorp/*` are equivalent. 233 `*/*` is a shorthand for `registry.terraform.io/*/*`, not for 234 `*/*/*`. 235 236 The following are the two supported installation method types: 237 238 * `direct`: request information about the provider directly from its origin 239 registry and download over the network from the location that registry 240 indicates. This method expects no additional arguments. 241 242 * `filesystem_mirror`: consult a directory on the local disk for copies of 243 providers. This method requires the additional argument `path` to indicate 244 which directory to look in. 245 246 Terraform expects the given directory to contain a nested directory structure 247 where the path segments together provide metadata about the available 248 providers. The following two directory structures are supported: 249 250 * Packed layout: `HOSTNAME/NAMESPACE/TYPE/terraform-provider-TYPE_VERSION_TARGET.zip` 251 is the distribution zip file obtained from the provider's origin registry. 252 * Unpacked layout: `HOSTNAME/NAMESPACE/TYPE/VERSION/TARGET` is a directory 253 containing the result of extracting the provider's distribution zip file. 254 255 In both layouts, the `VERSION` is a string like `2.0.0` and the `TARGET` 256 specifies a particular target platform using a format like `darwin_amd64`, 257 `linux_arm`, `windows_amd64`, etc. 258 259 If you use the unpacked layout, Terraform will attempt to create a symbolic 260 link to the mirror directory when installing the provider, rather than 261 creating a deep copy of the directory. The packed layout prevents this 262 because Terraform must extract the zip file during installation. 263 264 You can include multiple `filesystem_mirror` blocks in order to specify 265 several different directories to search. 266 267 * `network_mirror`: consult a particular HTTPS server for copies of providers, 268 regardless of which registry host they belong to. This method requires the 269 additional argument `url` to indicate the mirror base URL, which should 270 use the `https:` scheme and end with a trailing slash. 271 272 Terraform expects the given URL to be a base URL for an implementation of 273 [the provider network mirror protocol](/internals/provider-network-mirror-protocol), 274 which is designed to be relatively easy to implement using typical static 275 website hosting mechanisms. 276 277 ~> **Warning:** Don't configure `network_mirror` URLs that you do not trust. 278 Provider mirror servers are subject to TLS certificate checks to verify 279 identity, but a network mirror with a TLS certificate can potentially serve 280 modified copies of upstream providers with malicious content. 281 282 Terraform will try all of the specified methods whose include and exclude 283 patterns match a given provider, and select the newest version available across 284 all of those methods that matches the version constraint given in each 285 Terraform configuration. If you have a local mirror of a particular provider 286 and intend Terraform to use that local mirror exclusively, you must either 287 remove the `direct` installation method altogether or use its `exclude` 288 argument to disable its use for specific providers. 289 290 ### Implied Local Mirror Directories 291 292 If your CLI configuration does not include a `provider_installation` block at 293 all, Terraform produces an _implied_ configuration. The implied configuration 294 includes a selection of `filesystem_mirror` methods and then the `direct` 295 method. 296 297 The set of directories Terraform can select as filesystem mirrors depends on 298 the operating system where you are running Terraform: 299 300 * **Windows:** `%APPDATA%/terraform.d/plugins` and `%APPDATA%/HashiCorp/Terraform/plugins` 301 * **Mac OS X:** `$HOME/.terraform.d/plugins`, 302 `~/Library/Application Support/io.terraform/plugins`, and 303 `/Library/Application Support/io.terraform/plugins` 304 * **Linux and other Unix-like systems**:`$HOME/.terraform.d/plugins` and 305 `terraform/plugins` located within a valid 306 [XDG Base Directory](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html) 307 data directory such as `$XDG_DATA_HOME/terraform/plugins`. 308 Without any XDG environment variables set, Terraform will use 309 `~/.local/share/terraform/plugins`, 310 `/usr/local/share/terraform/plugins`, and `/usr/share/terraform/plugins`. 311 312 If a `terraform.d/plugins` directory exists in the current working directory 313 then Terraform will also include that directory, regardless of your operating 314 system. This behavior changes when you use the `-chdir` option with the `init` command. In that case, Terraform checks for the `terraform.d/plugins` directory in the launch directory and not in the directory you specified with `-chdir`. 315 316 Terraform will check each of the paths above to see if it exists, and if so 317 treat it as a filesystem mirror. The directory structure inside each one must 318 therefore match one of the two structures described for `filesystem_mirror` 319 blocks in [Explicit Installation Method Configuration](#explicit-installation-method-configuration). 320 321 In addition to the zero or more implied `filesystem_mirror` blocks, Terraform 322 also creates an implied `direct` block. Terraform will scan all of the 323 filesystem mirror directories to see which providers are placed there and 324 automatically exclude all of those providers from the implied `direct` block. 325 (This automatic `exclude` behavior applies only to _implicit_ `direct` blocks; 326 if you use explicit `provider_installation` you will need to write the intended 327 exclusions out yourself.) 328 329 ### Provider Plugin Cache 330 331 By default, `terraform init` downloads plugins into a subdirectory of the 332 working directory so that each working directory is self-contained. As a 333 consequence, if you have multiple configurations that use the same provider 334 then a separate copy of its plugin will be downloaded for each configuration. 335 336 Given that provider plugins can be quite large (on the order of hundreds of 337 megabytes), this default behavior can be inconvenient for those with slow 338 or metered Internet connections. Therefore Terraform optionally allows the 339 use of a local directory as a shared plugin cache, which then allows each 340 distinct plugin binary to be downloaded only once. 341 342 To enable the plugin cache, use the `plugin_cache_dir` setting in 343 the CLI configuration file. For example: 344 345 ```hcl 346 plugin_cache_dir = "$HOME/.terraform.d/plugin-cache" 347 ``` 348 349 This directory must already exist before Terraform will cache plugins; 350 Terraform will not create the directory itself. 351 352 Please note that on Windows it is necessary to use forward slash separators 353 (`/`) rather than the conventional backslash (`\`) since the configuration 354 file parser considers a backslash to begin an escape sequence. 355 356 Setting this in the configuration file is the recommended approach for a 357 persistent setting. Alternatively, the `TF_PLUGIN_CACHE_DIR` environment 358 variable can be used to enable caching or to override an existing cache 359 directory within a particular shell session: 360 361 ```bash 362 export TF_PLUGIN_CACHE_DIR="$HOME/.terraform.d/plugin-cache" 363 ``` 364 365 When a plugin cache directory is enabled, the `terraform init` command will 366 still use the configured or implied installation methods to obtain metadata 367 about which plugins are available, but once a suitable version has been 368 selected it will first check to see if the chosen plugin is already available 369 in the cache directory. If so, Terraform will use the previously-downloaded 370 copy. 371 372 If the selected plugin is not already in the cache, Terraform will download 373 it into the cache first and then copy it from there into the correct location 374 under your current working directory. When possible Terraform will use 375 symbolic links to avoid storing a separate copy of a cached plugin in multiple 376 directories. 377 378 The plugin cache directory _must not_ also be one of the configured or implied 379 filesystem mirror directories, since the cache management logic conflicts with 380 the filesystem mirror logic when operating on the same directory. 381 382 Terraform will never itself delete a plugin from the plugin cache once it has 383 been placed there. Over time, as plugins are upgraded, the cache directory may 384 grow to contain several unused versions which you must delete manually. 385 386 -> **Note:** The plugin cache directory is not guaranteed to be concurrency 387 safe. The provider installer's behavior in environments with multiple `terraform 388 init` calls is undefined. 389 390 ### Development Overrides for Provider Developers 391 392 -> **Note:** Development overrides work only in Terraform v0.14 and later. 393 Using a `dev_overrides` block in your CLI configuration will cause Terraform 394 v0.13 to reject the configuration as invalid. 395 396 Normally Terraform verifies version selections and checksums for providers 397 in order to help ensure that all operations are made with the intended version 398 of a provider, and that authors can gradually upgrade to newer provider versions 399 in a controlled manner. 400 401 These version and checksum rules are inconvenient when developing a provider 402 though, because we often want to try a test configuration against a development 403 build of a provider that doesn't even have an associated version number yet, 404 and doesn't have an official set of checksums listed in a provider registry. 405 406 As a convenience for provider development, Terraform supports a special 407 additional block `dev_overrides` in `provider_installation` blocks. The contents 408 of this block effectively override all of the other configured installation 409 methods, so a block of this type must always appear first in the sequence: 410 411 ```hcl 412 provider_installation { 413 414 # Use /home/developer/tmp/terraform-null as an overridden package directory 415 # for the hashicorp/null provider. This disables the version and checksum 416 # verifications for this provider and forces Terraform to look for the 417 # null provider plugin in the given directory. 418 dev_overrides { 419 "hashicorp/null" = "/home/developer/tmp/terraform-null" 420 } 421 422 # For all other providers, install them directly from their origin provider 423 # registries as normal. If you omit this, Terraform will _only_ use 424 # the dev_overrides block, and so no other providers will be available. 425 direct {} 426 } 427 ``` 428 429 With development overrides in effect, the `terraform init` command will still 430 attempt to select a suitable published version of your provider to install and 431 record in 432 [the dependency lock file](/language/files/dependency-lock) 433 for future use, but other commands like 434 `terraform apply` will disregard the lock file's entry for `hashicorp/null` and 435 will use the given directory instead. Once your new changes are included in a 436 published release of the provider, you can use `terraform init -upgrade` to 437 select the new version in the dependency lock file and remove your development 438 override. 439 440 The override path for a particular provider should be a directory similar to 441 what would be included in a `.zip` file when distributing the provider. At 442 minimum that includes an executable file named with a prefix like 443 `terraform-provider-null`, where `null` is the provider type. If your provider 444 makes use of other files in its distribution package then you can copy those 445 files into the override directory too. 446 447 You may wish to enable a development override only for shell sessions where 448 you are actively working on provider development. If so, you can write a 449 local CLI configuration file with content like the above in your development 450 directory, perhaps called `dev.tfrc` for the sake of example, and then use the 451 `TF_CLI_CONFIG_FILE` environment variable to instruct Terraform to use that 452 localized CLI configuration instead of the default one: 453 454 ``` 455 export TF_CLI_CONFIG_FILE=/home/developer/tmp/dev.tfrc 456 ``` 457 458 Development overrides are not intended for general use as a way to have 459 Terraform look for providers on the local filesystem. If you wish to put 460 copies of _released_ providers in your local filesystem, see 461 [Implied Local Mirror Directories](#implied-local-mirror-directories) 462 or 463 [Explicit Installation Method Configuration](#explicit-installation-method-configuration) 464 instead. 465 466 This development overrides mechanism is intended as a pragmatic way to enable 467 smoother provider development. The details of how it behaves, how to 468 configure it, and how it interacts with the dependency lock file may all evolve 469 in future Terraform releases, including possible breaking changes. We therefore 470 recommend using development overrides only temporarily during provider 471 development work. 472 473 ## Removed Settings 474 475 The following settings are supported in Terraform 0.12 and earlier but are 476 no longer recommended for use: 477 478 * `providers` - a configuration block that allows specifying the locations of 479 specific plugins for each named provider. This mechanism is deprecated 480 because it is unable to specify a version number and source for each provider. 481 See [Provider Installation](#provider-installation) above for the replacement 482 of this setting in Terraform 0.13 and later.