terraform/website/docs/commands/init.html.markdown

161 lines
7.4 KiB
Markdown
Raw Normal View History

2014-09-27 21:28:07 +02:00
---
layout: "docs"
page_title: "Command: init"
sidebar_current: "docs-commands-init"
2014-10-22 05:21:56 +02:00
description: |-
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.
2014-09-27 21:28:07 +02:00
---
# Command: init
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.
2014-09-27 21:28:07 +02:00
## Usage
2017-06-16 23:27:57 +02:00
Usage: `terraform init [options] [DIR]`
2014-09-27 21:28:07 +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.
2014-09-27 21:28:07 +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.
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.
## General Options
The following options apply to all of (or several of) the initialization steps:
* `-input=true` Ask for input if necessary. If false, will error if
input was required.
* `-lock=false` Disable locking of state files during state-related operations.
2017-06-16 23:27:57 +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.
2017-06-16 23:27:57 +02:00
* `-no-color` Disable color codes in the command output.
2017-06-16 23:27:57 +02:00
* `-upgrade` Opt to upgrade modules and plugins as part of their respective
installation steps. See the seconds below for more details.
## 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
`-with-module=MODULE-SOURCE` option, in which case the given module will be
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.
For routine use it's recommended to check out configuration from version
control separately, using the version control system's own commands. This way
it's possible to pass extra flags to the version control system when necessary,
and to perform other preparation steps (such as configuration generation, or
activating credentials) before running `terraform init`.
## 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.
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=...` 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.
## Child Module Installation
2017-04-04 19:48:59 +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.
2017-04-04 19:48:59 +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.
2017-04-04 19:48:59 +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.
2017-04-04 19:48:59 +02:00
## Plugin Installation
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
2017-08-07 18:47:42 +02:00
the desired providers into a local directory and using the additional 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.
Custom plugins can be used along with automatically installed plugins by
placing them in `terraform.d/plugins/OS_ARCH/` inside the directory being
initialized. Plugins found here will take precedence if they meet the required
constraints in the configuration. The `init` command will continue to
automatically download other plugins as needed.
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).