ResiLien
/
terraform
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
terraform/website/docs/commands/init.html.markdown

167 lines
7.8 KiB
Markdown
Raw Normal View History

website: document init
2014-09-27 21:28:07 +02:00
---
layout: "docs"
page_title: "Command: init"
sidebar_current: "docs-commands-init"
Add meta descriptions to all pages
2014-10-22 05:21:56 +02:00
description: |-
website: document init and new state commands
2017-02-15 22:14:32 +01:00
The `terraform init` command is used to initialize a Terraform configuration. This is the first command that should be run for any new or existing Terraform configuration. It is safe to run this command multiple times.
website: document init
2014-09-27 21:28:07 +02:00
---
# Command: init
command init: remove confusing uses of "environment" in the usage "environment" is a very overloaded term, so here we prefer to use the term "working directory" to talk about a local directory where operations are executed on a given Terraform configuration.
2017-06-03 01:59:52 +02:00
The `terraform init` command is used to initialize a working directory
containing Terraform configuration files. This is the first command that should
be run after writing a new Terraform configuration or cloning an existing one
from version control. It is safe to run this command multiple times.
website: document init
2014-09-27 21:28:07 +02:00
## Usage
update init website docs
2017-06-16 23:27:57 +02:00
Usage: `terraform init [options] [DIR]`
website: document init
2014-09-27 21:28:07 +02:00
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.
2017-07-25 02:04:28 +02:00
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.
website: document init
2014-09-27 21:28:07 +02:00
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.
2017-07-25 02:04:28 +02:00
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.
website: Update CLI flags for existing commands
2014-12-06 00:29:00 +01:00
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.
2017-07-25 02:04:28 +02:00
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.
website: document init and new state commands
2017-02-15 22:14:32 +01:00
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.
2017-07-25 02:04:28 +02:00
## General Options
website: document init and new state commands
2017-02-15 22:14:32 +01:00
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.
2017-07-25 02:04:28 +02:00
The following options apply to all of (or several of) the initialization steps:
website: Update CLI flags for existing commands
2014-12-06 00:29:00 +01:00
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.
2017-07-25 02:04:28 +02:00
* `-input=true` Ask for input if necessary. If false, will error if
input was required.
website: Update CLI flags for existing commands
2014-12-06 00:29:00 +01:00
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.
2017-07-25 02:04:28 +02:00
* `-lock=false` Disable locking of state files during state-related operations.
update init website docs
2017-06-16 23:27:57 +02:00
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.
2017-07-25 02:04:28 +02:00
* `-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.
update init website docs
2017-06-16 23:27:57 +02:00
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.
2017-07-25 02:04:28 +02:00
* `-no-color` Disable color codes in the command output.
update init website docs
2017-06-16 23:27:57 +02:00
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.
2017-07-25 02:04:28 +02:00
* `-upgrade` Opt to upgrade modules and plugins as part of their respective
Update init.html.markdown Fix typo and replace some "it's" with "it is", according to rules for written English.
2018-01-24 18:41:42 +01:00
installation steps. See the sections below for more details.
website: Update CLI flags for existing commands
2014-12-06 00:29:00 +01:00
command: terraform init -from-module=... This restores the earlier behavior of the first positional argument to terraform init in 0.9, but as a command line option. The positional argument was removed to improve consistency with other commands that take a working directory as their first positional argument. It was originally intended that this functionality would return in a later release along with some other general improvements to Terraform's module handling, but we're introducing here an interim solution that uses the existing module source concept, to allow for easier porting of workflows that previously depended on the automatic copy behavior. In a future release this feature may change again as the module improvements design firms up, but we expect it to be broadly compatible with this temporary state.
2017-07-29 00:23:29 +02:00
## Copy a Source Module
By default, `terraform init` assumes that the working directory already
contains a configuration and will attempt to initialize that configuration.
Optionally, init can be run against an empty directory with the
website: correct the spelling of the -from-module arg to "terraform init"
2017-08-11 02:56:11 +02:00
`-from-module=MODULE-SOURCE` option, in which case the given module will be
command: terraform init -from-module=... This restores the earlier behavior of the first positional argument to terraform init in 0.9, but as a command line option. The positional argument was removed to improve consistency with other commands that take a working directory as their first positional argument. It was originally intended that this functionality would return in a later release along with some other general improvements to Terraform's module handling, but we're introducing here an interim solution that uses the existing module source concept, to allow for easier porting of workflows that previously depended on the automatic copy behavior. In a future release this feature may change again as the module improvements design firms up, but we expect it to be broadly compatible with this temporary state.
2017-07-29 00:23:29 +02:00
copied into the target directory before any other initialization steps are
run.
This special mode of operation supports two use-cases:
* Given a version control source, it can serve as a shorthand for checking out
a configuration from version control and then initializing the work directory
for it.
* If the source refers to an _example_ configuration, it can be copied into
a local directory to be used as a basis for a new configuration.
Update init.html.markdown Fix typo and replace some "it's" with "it is", according to rules for written English.
2018-01-24 18:41:42 +01:00
For routine use it is recommended to check out configuration from version
command: terraform init -from-module=... This restores the earlier behavior of the first positional argument to terraform init in 0.9, but as a command line option. The positional argument was removed to improve consistency with other commands that take a working directory as their first positional argument. It was originally intended that this functionality would return in a later release along with some other general improvements to Terraform's module handling, but we're introducing here an interim solution that uses the existing module source concept, to allow for easier porting of workflows that previously depended on the automatic copy behavior. In a future release this feature may change again as the module improvements design firms up, but we expect it to be broadly compatible with this temporary state.
2017-07-29 00:23:29 +02:00
control separately, using the version control system's own commands. This way
Update init.html.markdown Fix typo and replace some "it's" with "it is", according to rules for written English.
2018-01-24 18:41:42 +01:00
it is possible to pass extra flags to the version control system when necessary,
command: terraform init -from-module=... This restores the earlier behavior of the first positional argument to terraform init in 0.9, but as a command line option. The positional argument was removed to improve consistency with other commands that take a working directory as their first positional argument. It was originally intended that this functionality would return in a later release along with some other general improvements to Terraform's module handling, but we're introducing here an interim solution that uses the existing module source concept, to allow for easier porting of workflows that previously depended on the automatic copy behavior. In a future release this feature may change again as the module improvements design firms up, but we expect it to be broadly compatible with this temporary state.
2017-07-29 00:23:29 +02:00
and to perform other preparation steps (such as configuration generation, or
activating credentials) before running `terraform init`.
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.
2017-07-25 02:04:28 +02:00
## Backend Initialization
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.
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.
update init docs add -reconfigure, and fix ordering of the other flags
2017-04-20 23:34:14 +02:00
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.
2017-07-25 02:04:28 +02:00
To skip backend configuration, use `-backend=false`. Note that some other init
Update init.html.markdown Fix typo and replace some "it's" with "it is", according to rules for written English.
2018-01-24 18:41:42 +01:00
steps require an initialized backend, so it is recommended to use this flag only
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.
2017-07-25 02:04:28 +02:00
when the working directory was already previously initialized for a particular
backend.
website: Update CLI flags for existing commands
2014-12-06 00:29:00 +01:00
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.
2017-07-25 02:04:28 +02:00
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.
Update init and remote config command docs * Update init docs to be correct, and provide an example. * Update remote config docs to provide more details about the Consul backend and to provide another example.
2015-10-19 01:23:13 +02:00
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.
2017-07-25 02:04:28 +02:00
## Child Module Installation
update command docs
2017-04-04 19:48:59 +02:00
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.
2017-07-25 02:04:28 +02:00
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.
update command docs
2017-04-04 19:48:59 +02:00
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.
2017-07-25 02:04:28 +02:00
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.
update command docs
2017-04-04 19:48:59 +02:00
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.
2017-07-25 02:04:28 +02:00
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.
update command docs
2017-04-04 19:48:59 +02:00
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.
2017-07-25 02:04:28 +02:00
## Plugin Installation
add init -verify-plugin to website docs
2017-06-20 17:50:31 +02:00
website: Reconcile docs about plugin discovery and downloading (#18973) website: Reconcile docs about plugin discovery and downloading I'm attempting to keep things simple for normal users while making sure we've got the full behavior written down somewhere for plugin developers. This commit doesn't stand alone; it's paired with a commit in the terraform-website repo, to deal with some related content in the "extend" section.
2018-10-03 01:53:29 +02:00
During init, Terraform searches the configuration for both direct and indirect
references to providers and attempts to load the required plugins.
For [providers distributed by HashiCorp](/docs/providers/index.html),
init will automatically download and install plugins if necessary. Plugins
can also be manually installed in the user plugins directory, located at
`~/.terraform.d/plugins` on most operating systems and
`<APPLICATION DATA>\plugins` on Windows.
For more information about configuring and installing providers, see
[Configuration: Providers](/docs/configuration/providers.html).
On subsequent runs, init only installs providers without acceptable versions
installed. (This includes newly added providers, and providers whose installed
versions can't meet the current version constraints.) Use `-upgrade` if you want
to update _all_ providers to the newest acceptable version.
You can modify `terraform init`'s plugin behavior with the following options:
- `-upgrade` — Update all previously installed plugins to the newest version
that complies with the configuration's version constraints. This option does
not apply to manually installed plugins.
- `-get-plugins=false` — Skips plugin installation. Terraform will use plugins
installed in the user plugins directory, and any plugins already installed
for the current working directory. If the installed plugins aren't sufficient
for the configuration, init fails.
- `-plugin-dir=PATH` — Skips plugin installation and loads plugins _only_ from
the specified directory. This ignores the user plugins directory and any
plugins already installed in the current working directory. To restore the
default behavior after using this option, run init again and pass an empty
string to `-plugin-dir`.
- `-verify-plugins=false` — Skips release signature validation when
installing downloaded plugins (not recommended). Official plugin releases are
digitally signed by HashiCorp, and Terraform verifies these signatures when
automatically downloading plugins. This option disables that verification.
(Terraform does not check signatures for manually installed plugins.)
command/init: backend-config accepts key=value pairs This augments backend-config to also accept key=value pairs. This should make Terraform easier to script rather than having to generate a JSON file. You must still specify the backend type as a minimal amount in configurations, example: ``` terraform { backend "consul" {} } ``` This is required because Terraform needs to be able to detect the _absense_ of that value for unsetting, if that is necessary at some point.
2017-03-17 07:27:05 +01:00
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.
2017-07-25 02:04:28 +02:00
## Running `terraform init` in automation
command/init: backend-config accepts key=value pairs This augments backend-config to also accept key=value pairs. This should make Terraform easier to script rather than having to generate a JSON file. You must still specify the backend type as a minimal amount in configurations, example: ``` terraform { backend "consul" {} } ``` This is required because Terraform needs to be able to detect the _absense_ of that value for unsetting, if that is necessary at some point.
2017-03-17 07:27:05 +01:00
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.
2017-07-25 02:04:28 +02:00
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.
command/init: backend-config accepts key=value pairs This augments backend-config to also accept key=value pairs. This should make Terraform easier to script rather than having to generate a JSON file. You must still specify the backend type as a minimal amount in configurations, example: ``` terraform { backend "consul" {} } ``` This is required because Terraform needs to be able to detect the _absense_ of that value for unsetting, if that is necessary at some point.
2017-03-17 07:27:05 +01:00
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.
2017-07-25 02:04:28 +02:00
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).