github.com/kcburge/terraform@v0.11.12-beta1/website/docs/commands/init.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Command: init"
     4  sidebar_current: "docs-commands-init"
     5  description: |-
     6    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.
     7  ---
     8  
     9  # Command: init
    10  
    11  The `terraform init` command is used to initialize a working directory
    12  containing Terraform configuration files. This is the first command that should
    13  be run after writing a new Terraform configuration or cloning an existing one
    14  from version control. It is safe to run this command multiple times.
    15  
    16  ## Usage
    17  
    18  Usage: `terraform init [options] [DIR]`
    19  
    20  This command performs several different initialization steps in order to
    21  prepare a working directory for use. More details on these are in the
    22  sections below, but in most cases it is not necessary to worry about these
    23  individual steps.
    24  
    25  This command is always safe to run multiple times, to bring the working
    26  directory up to date with changes in the configuration. Though subsequent runs
    27  may give errors, this command will never delete your existing configuration or
    28  state.
    29  
    30  If no arguments are given, the configuration in the current working directory
    31  is initialized. It is recommended to run Terraform with the current working
    32  directory set to the root directory of the configuration, and omit the `DIR`
    33  argument.
    34  
    35  ## General Options
    36  
    37  The following options apply to all of (or several of) the initialization steps:
    38  
    39  * `-input=true` Ask for input if necessary. If false, will error if
    40    input was required.
    41  
    42  * `-lock=false` Disable locking of state files during state-related operations.
    43  
    44  * `-lock-timeout=<duration>` Override the time Terraform will wait to acquire
    45    a state lock. The default is `0s` (zero seconds), which causes immediate
    46    failure if the lock is already held by another process.
    47  
    48  * `-no-color` Disable color codes in the command output.
    49  
    50  * `-upgrade` Opt to upgrade modules and plugins as part of their respective
    51    installation steps. See the sections below for more details.
    52  
    53  ## Copy a Source Module
    54  
    55  By default, `terraform init` assumes that the working directory already
    56  contains a configuration and will attempt to initialize that configuration.
    57  
    58  Optionally, init can be run against an empty directory with the
    59  `-from-module=MODULE-SOURCE` option, in which case the given module will be
    60  copied into the target directory before any other initialization steps are
    61  run.
    62  
    63  This special mode of operation supports two use-cases:
    64  
    65  * Given a version control source, it can serve as a shorthand for checking out
    66    a configuration from version control and then initializing the work directory
    67    for it.
    68  
    69  * If the source refers to an _example_ configuration, it can be copied into
    70    a local directory to be used as a basis for a new configuration.
    71  
    72  For routine use it is recommended to check out configuration from version
    73  control separately, using the version control system's own commands. This way
    74  it is possible to pass extra flags to the version control system when necessary,
    75  and to perform other preparation steps (such as configuration generation, or
    76  activating credentials) before running `terraform init`.
    77  
    78  ## Backend Initialization
    79  
    80  During init, the root configuration directory is consulted for
    81  [backend configuration](/docs/backends/config.html) and the chosen backend
    82  is initialized using the given configuration settings.
    83  
    84  Re-running init with an already-initalized backend will update the working
    85  directory to use the new backend settings. Depending on what changed, this
    86  may result in interactive prompts to confirm migration of workspace states.
    87  The `-force-copy` option suppresses these prompts and answers "yes" to the
    88  migration questions. The `-reconfigure` option disregards any existing
    89  configuration, preventing migration of any existing state.
    90  
    91  To skip backend configuration, use `-backend=false`. Note that some other init
    92  steps require an initialized backend, so it is recommended to use this flag only
    93  when the working directory was already previously initialized for a particular
    94  backend.
    95  
    96  The `-backend-config=...` option can be used for
    97  [partial backend configuration](/docs/backends/config.html#partial-configuration),
    98  in situations where the backend settings are dynamic or sensitive and so cannot
    99  be statically specified in the configuration file.
   100  
   101  ## Child Module Installation
   102  
   103  During init, the configuration is searched for `module` blocks, and the source
   104  code for referenced [modules](/docs/modules/) is retrieved from the locations
   105  given in their `source` arguments.
   106  
   107  Re-running init with modules already installed will install the sources for
   108  any modules that were added to configuration since the last init, but will not
   109  change any already-installed modules. Use `-upgrade` to override this behavior,
   110  updating all modules to the latest available source code.
   111  
   112  To skip child module installation, use `-get=false`. Note that some other init
   113  steps can complete only when the module tree is complete, so it's recommended
   114  to use this flag only when the working directory was already previously
   115  initialized with its child modules.
   116  
   117  ## Plugin Installation
   118  
   119  During init, Terraform searches the configuration for both direct and indirect
   120  references to providers and attempts to load the required plugins.
   121  
   122  For [providers distributed by HashiCorp](/docs/providers/index.html),
   123  init will automatically download and install plugins if necessary. Plugins
   124  can also be manually installed in the user plugins directory, located at
   125  `~/.terraform.d/plugins` on most operating systems and
   126  `<APPLICATION DATA>\plugins` on Windows.
   127  
   128  For more information about configuring and installing providers, see
   129  [Configuration: Providers](/docs/configuration/providers.html).
   130  
   131  On subsequent runs, init only installs providers without acceptable versions
   132  installed. (This includes newly added providers, and providers whose installed
   133  versions can't meet the current version constraints.) Use `-upgrade` if you want
   134  to update _all_ providers to the newest acceptable version.
   135  
   136  You can modify `terraform init`'s plugin behavior with the following options:
   137  
   138  - `-upgrade` — Update all previously installed plugins to the newest version
   139    that complies with the configuration's version constraints. This option does
   140    not apply to manually installed plugins.
   141  - `-get-plugins=false` — Skips plugin installation. Terraform will use plugins
   142    installed in the user plugins directory, and any plugins already installed
   143    for the current working directory. If the installed plugins aren't sufficient
   144    for the configuration, init fails.
   145  - `-plugin-dir=PATH` — Skips plugin installation and loads plugins _only_ from
   146    the specified directory. This ignores the user plugins directory and any
   147    plugins already installed in the current working directory. To restore the
   148    default behavior after using this option, run init again and pass an empty
   149    string to `-plugin-dir`.
   150  - `-verify-plugins=false` — Skips release signature validation when
   151    installing downloaded plugins (not recommended). Official plugin releases are
   152    digitally signed by HashiCorp, and Terraform verifies these signatures when
   153    automatically downloading plugins. This option disables that verification.
   154    (Terraform does not check signatures for manually installed plugins.)
   155  
   156  ## Running `terraform init` in automation
   157  
   158  For teams that use Terraform as a key part of a change management and
   159  deployment pipeline, it can be desirable to orchestrate Terraform runs in some
   160  sort of automation in order to ensure consistency between runs, and provide
   161  other interesting features such as integration with version control hooks.
   162  
   163  There are some special concerns when running `init` in such an environment,
   164  including optionally making plugins available locally to avoid repeated
   165  re-installation. For more information, see
   166  [`Running Terraform in Automation`](/guides/running-terraform-in-automation.html).