website: more-elaborate "terraform init" docs
The "terraform init" command has a lot of different functionality now, making it hard to follow all of the options in the previous presentation. Instead, here we describe each of the steps and its associated options separately, hopefully making it easier to understand what each option relates to. In addition, much of the detail around backend partial configuration is factored out into the backend configuration page, where it seems more "at home"; previously it felt hard to follow exactly how partial configuration would be used, due to the information on it being split over two different pages.
This commit is contained in:
Martin Atkins
parent
539f0db74e
commit
23ef0e3247
|
|
@ -18,7 +18,7 @@ Below, we show a complete example configuring the "consul" backend:
|
|||
terraform {
|
||||
backend "consul" {
|
||||
address = "demo.consul.io"
|
||||
path = "tfdocs"
|
||||
path = "example_app/terraform_state"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
|
@ -48,35 +48,46 @@ a configuration in the future: create the new configuration and run
|
|||
|
||||
## Partial Configuration
|
||||
|
||||
You do not need to specify every required attribute in the configuration.
|
||||
This may be desirable to avoid storing secrets (such as access keys) within
|
||||
the configuration itself. We call this specifying only a _partial_ configuration.
|
||||
You do not need to specify every required argument in the backend configuration.
|
||||
Omitting certain arguments may be desirable to avoid storing secrets, such as
|
||||
access keys, within the main configuration. When some or all of the arguments
|
||||
are ommitted, we call this a _partial configuration_.
|
||||
|
||||
With a partial configuration, the remaining configuration is expected as
|
||||
part of the [initialization](/docs/backends/init.html) process. There are
|
||||
a few ways to supply the remaining configuration:
|
||||
With a partial configuration, the remaining configuration arguments must be
|
||||
provided as part of
|
||||
[the initialization process](/docs/backends/init.html#backend-initialization).
|
||||
There are several ways to supply the remaining arguments:
|
||||
|
||||
* **Interactively**: Terraform will interactively ask you for the required
|
||||
values. Terraform will not ask you for optional values.
|
||||
values, unless interactive input is disabled. Terraform will not prompt for
|
||||
optional values.
|
||||
|
||||
* **File**: A configuration file may be specified via the command line.
|
||||
This file can then be sourced via some secure means (such as
|
||||
[Vault](https://www.vaultproject.io)).
|
||||
* **File**: A configuration file may be specified via the `init` command line.
|
||||
To specify a file, use the `-backend-config=PATH` option when running
|
||||
`terraform init`. If the file contains secrets it may be kept in
|
||||
a secure data store, such as
|
||||
[Vault](https://www.vaultproject.io/), in which case it must be downloaded
|
||||
to the local disk before running Terraform.
|
||||
|
||||
* **Command-line key/value pairs**: Key/value pairs in the format of
|
||||
`key=value` can be specified as part of the init command. Note that
|
||||
many shells retain command-line flags in a history file, so this isn't
|
||||
recommended for secrets.
|
||||
* **Command-line key/value pairs**: Key/value pairs can be specified via the
|
||||
`init` command line. Note that many shells retain command-line flags in a
|
||||
history file, so this isn't recommended for secrets. To specify a single
|
||||
key/value pair, use the `-backend-config="KEY=VALUE"` option when running
|
||||
`terraform init`.
|
||||
|
||||
In all cases, the final configuration is stored on disk in the
|
||||
".terraform" directory, which should be ignored from version control.
|
||||
If backend settings are provided in multiple locations, the top-level
|
||||
settings are merged such that any command-line options override the settings
|
||||
in the main configuration and then the command-line options are processed
|
||||
in order, with later options overriding values set by earlier options.
|
||||
|
||||
This means that sensitive information can be omitted from version control
|
||||
but it ultimately still lives on disk. In the future, Terraform may provide
|
||||
basic encryption on disk so that values are at least not plaintext.
|
||||
The final, merged configuration is stored on disk in the `.terraform`
|
||||
directory, which should be ignored from version control. This means that
|
||||
sensitive information can be omitted from version control, but it will be
|
||||
present in plain text on local disk when running Terraform.
|
||||
|
||||
When using partial configuration, Terraform requires at a minimum that
|
||||
an empty backend configuration is in the Terraform files. For example:
|
||||
an empty backend configuration is specified in one of the root Terraform
|
||||
configuration files, to specify the backend type. For example:
|
||||
|
||||
```hcl
|
||||
terraform {
|
||||
|
|
@ -84,10 +95,23 @@ terraform {
|
|||
}
|
||||
```
|
||||
|
||||
This minimal requirement allows Terraform to detect _unsetting_ backends.
|
||||
We cannot accept the backend type on the command-line because while it is
|
||||
technically possible, Terraform would then be unable to detect if you
|
||||
want to unset your backend (and move back to local state).
|
||||
A backend configuration file has the contents of the `backend` block as
|
||||
top-level attributes, without the need to wrap it in another `terraform`
|
||||
or `backend` block:
|
||||
|
||||
```hcl
|
||||
address = "demo.consul.io"
|
||||
path = "example_app/terraform_state"
|
||||
```
|
||||
|
||||
The same settings can alternatively be specified on the command line as
|
||||
follows:
|
||||
|
||||
```
|
||||
$ terraform init \
|
||||
-backend-config="address=demo.consul.io" \
|
||||
-backend-config="path=example_app/terraform_state"
|
||||
```
|
||||
|
||||
## Changing Configuration
|
||||
|
||||
|
|
@ -101,9 +125,9 @@ the reinitialization process, Terraform will ask if you'd like to migrate
|
|||
your existing state to the new configuration. This allows you to easily
|
||||
switch from one backend to another.
|
||||
|
||||
If you're using [state environments](/docs/state/environments.html),
|
||||
Terraform is able to copy all environments to the destination. If Terraform
|
||||
detects you have multiple states, it will ask if this is what you want to do.
|
||||
If you're using multiple [workspaces](/docs/state/workspaces.html),
|
||||
Terraform can copy all workspaces to the destination. If Terraform detects
|
||||
you have multiple workspaces, it will ask if this is what you want to do.
|
||||
|
||||
If you're just reconfiguring the same backend, Terraform will still ask if you
|
||||
want to migrate your state. You can respond "no" in this scenario.
|
||||
|
|
|
|||
|
|
@ -17,90 +17,113 @@ from version control. It is safe to run this command multiple times.
|
|||
|
||||
Usage: `terraform init [options] [DIR]`
|
||||
|
||||
Initialize a new or existing Terraform working directory by creating
|
||||
initial files, loading any remote state, downloading modules, etc.
|
||||
This command performs several different initialization steps in order to
|
||||
prepare a working directory for use. More details on these are in the
|
||||
sections below, but in most cases it is not necessary to worry about these
|
||||
individual steps.
|
||||
|
||||
This is the first command that should be run for any new or existing
|
||||
Terraform configuration per machine. This sets up all the local data
|
||||
necessary to run Terraform that is typically not committed to version
|
||||
control.
|
||||
This command is always safe to run multiple times, to bring the working
|
||||
directory up to date with changes in the configuration. Though subsequent runs
|
||||
may give errors, this command will never delete your existing configuration or
|
||||
state.
|
||||
|
||||
This command is always safe to run multiple times. Though subsequent runs
|
||||
may give errors, this command will never delete your configuration or
|
||||
state. Even so, if you have important information, please back it up prior
|
||||
to running this command, just in case.
|
||||
If no arguments are given, the configuration in the current working directory
|
||||
is initialized. It is recommended to run Terraform with the current working
|
||||
directory set to the root directory of the configuration, and omit the `DIR`
|
||||
argument.
|
||||
|
||||
If no arguments are given, the configuration in this working directory
|
||||
is initialized.
|
||||
## General Options
|
||||
|
||||
The command-line flags are all optional. The list of available flags are:
|
||||
The following options apply to all of (or several of) the initialization steps:
|
||||
|
||||
* `-backend=true` - Initialize the [backend](/docs/backends) for this configuration.
|
||||
|
||||
* `-backend-config=path` This can be either a path to an HCL file with key/value
|
||||
assignments (same format as terraform.tfvars) or a 'key=value' format. This is
|
||||
merged with what is in the configuration file. This can be specified multiple
|
||||
times. The backend type must be in the configuration itself.
|
||||
|
||||
* `-force-copy` Suppress prompts about copying state data. This is
|
||||
equivalent to providing a "yes" to all confirmation prompts.
|
||||
|
||||
* `-get=true` Download any modules for this configuration.
|
||||
|
||||
* `-get-plugins=true` Download any missing plugins for this configuration.
|
||||
|
||||
* `-input=true` Ask for input if necessary. If false, will error if
|
||||
* `-input=true` Ask for input if necessary. If false, will error if
|
||||
input was required.
|
||||
|
||||
* `-lock=true` Lock the state file when locking is supported.
|
||||
* `-lock=false` Disable locking of state files during state-related operations.
|
||||
|
||||
* `-lock-timeout=0s` Duration to retry a state lock.
|
||||
* `-lock-timeout=<duration>` Override the time Terraform will wait to acquire
|
||||
a state lock. The default is `0s` (zero seconds), which causes immediate
|
||||
failure if the lock is already held by another process.
|
||||
|
||||
* `-no-color` If specified, output won't contain any color.
|
||||
* `-no-color` Disable color codes in the command output.
|
||||
|
||||
* `-plugin-dir` Directory containing plugin binaries. This overrides all
|
||||
default search paths for plugins, and prevents the automatic installation of
|
||||
plugins. This flag can be used multiple times.
|
||||
* `-upgrade` Opt to upgrade modules and plugins as part of their respective
|
||||
installation steps. See the seconds below for more details.
|
||||
|
||||
* `-reconfigure` Reconfigure the backend, ignoring any saved configuration.
|
||||
## Backend Initialization
|
||||
|
||||
* `-upgrade=false` If installing modules (-get) or plugins (-get-plugins),
|
||||
ignore previously-downloaded objects and install the latest version allowed
|
||||
within configured constraints.
|
||||
During init, the root configuration directory is consulted for
|
||||
[backend configuration](/docs/backends/config.html) and the chosen backend
|
||||
is initialized using the given configuration settings.
|
||||
|
||||
* `-verify-plugins=true` Verify the authenticity and integrity of automatically
|
||||
downloaded plugins.
|
||||
Re-running init with an already-initalized backend will update the working
|
||||
directory to use the new backend settings. Depending on what changed, this
|
||||
may result in interactive prompts to confirm migration of workspace states.
|
||||
The `-force-copy` option suppresses these prompts and answers "yes" to the
|
||||
migration questions. The `-reconfigure` option disregards any existing
|
||||
configuration, preventing migration of any existing state.
|
||||
|
||||
## Backend Config
|
||||
To skip backend configuration, use `-backend=false`. Note that some other init
|
||||
steps require an initialized backend, so it's recommended to use this flag only
|
||||
when the working directory was already previously initialized for a particular
|
||||
backend.
|
||||
|
||||
The `-backend-config` can take a path or `key=value` pair to specify additional
|
||||
backend configuration when [initializing a backend](/docs/backends/init.html).
|
||||
The `-backend-config=...` option can be used for
|
||||
[partial backend configuration](/docs/backends/config.html#partial-configuration),
|
||||
in situations where the backend settings are dynamic or sensitive and so cannot
|
||||
be statically specified in the configuration file.
|
||||
|
||||
This is particularly useful for
|
||||
[partial configuration of backends](/docs/backends/config.html). Partial
|
||||
configuration lets you keep sensitive information out of your Terraform
|
||||
configuration.
|
||||
## Child Module Installation
|
||||
|
||||
For path values, the backend configuration file is a basic HCL file with key/value pairs.
|
||||
The keys are configuration keys for your backend. You do not need to wrap it
|
||||
in a `terraform` block. For example, the following file is a valid backend
|
||||
configuration file for the Consul backend type:
|
||||
During init, the configuration is searched for `module` blocks, and the source
|
||||
code for referenced [modules](/docs/modules/) is retrieved from the locations
|
||||
given in their `source` arguments.
|
||||
|
||||
```hcl
|
||||
address = "demo.consul.io"
|
||||
path = "newpath"
|
||||
```
|
||||
Re-running init with modules already installed will install the sources for
|
||||
any modules that were added to configuration since the last init, but will not
|
||||
change any already-installed modules. Use `-upgrade` to override this behavior,
|
||||
updating all modules to the latest available source code.
|
||||
|
||||
If the value contains an equal sign (`=`), it is parsed as a `key=value` pair.
|
||||
The format of this flag is identical to the `-var` flag for plan, apply,
|
||||
etc. but applies to configuration keys for backends. For example:
|
||||
To skip child module installation, use `-get=false`. Note that some other init
|
||||
steps can complete only when the module tree is complete, so it's recommended
|
||||
to use this flag only when the working directory was already previously
|
||||
initialized with its child modules.
|
||||
|
||||
```shell
|
||||
$ terraform init \
|
||||
-backend-config 'address=demo.consul.io' \
|
||||
-backend-config 'path=newpath'
|
||||
```
|
||||
## Plugin Installation
|
||||
|
||||
These two formats can be mixed. In this case, the values will be merged by
|
||||
key with keys specified later in the command-line overriding conflicting
|
||||
keys specified earlier.
|
||||
During init, the configuration is searched for both direct and indirect
|
||||
references to [providers](/docs/configuration/providers.html), and the plugins
|
||||
for the providers are retrieved from the plugin repository. The downloaded
|
||||
plugins are installed to a subdirectory of the working directory, and are thus
|
||||
local to that working directory.
|
||||
|
||||
Re-running init with plugins already installed will install plugins only for
|
||||
any providers that were added to the configuration since the last init. Use
|
||||
`-upgrade` to additionally update already-installed plugins to the latest
|
||||
versions that comply with the version constraints given in configuration.
|
||||
|
||||
To skip plugin installation, use `-get-plugins=false`.
|
||||
|
||||
The automatic plugin installation behavior can be overridden by extracting
|
||||
the desired providers into a local directory and using the additonal option
|
||||
`-plugin-dir=PATH`. When this option is specified, _only_ the given directory
|
||||
is consulted, which prevents Terraform from making requests to the plugin
|
||||
repository or looking for plugins in other local directories.
|
||||
|
||||
When plugins are automatically downloaded and installed, by default the
|
||||
contents are verified against an official HashiCorp release signature to
|
||||
ensure that they were not corrupted or tampered with during download. It is
|
||||
recommended to allow Terraform to make these checks, but if desired they may
|
||||
be disabled using the option `-verify-plugins=false`.
|
||||
|
||||
## Running `terraform init` in automation
|
||||
|
||||
For teams that use Terraform as a key part of a change management and
|
||||
deployment pipeline, it can be desirable to orchestrate Terraform runs in some
|
||||
sort of automation in order to ensure consistency between runs, and provide
|
||||
other interesting features such as integration with version control hooks.
|
||||
|
||||
There are some special concerns when running `init` in such an environment,
|
||||
including optionally making plugins available locally to avoid repeated
|
||||
re-installation. For more information, see
|
||||
[`Running Terraform in Automation`](/guides/running-terraform-in-automation.html).
|
||||
|
|
|
|||
Loading…
Reference in New Issue