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.