github.com/rstandt/terraform@v0.12.32-0.20230710220336-b1063613405c/website/docs/commands/plan.html.markdown (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Command: plan"
     4  sidebar_current: "docs-commands-plan"
     5  description: |-
     6    The `terraform plan` command is used to create an execution plan. Terraform performs a refresh, unless explicitly disabled, and then determines what actions are necessary to achieve the desired state specified in the configuration files. The plan can be saved using `-out`, and then provided to `terraform apply` to ensure only the pre-planned actions are executed.
     7  ---
     8  
     9  # Command: plan
    10  
    11  The `terraform plan` command is used to create an execution plan. Terraform
    12  performs a refresh, unless explicitly disabled, and then determines what
    13  actions are necessary to achieve the desired state specified in the
    14  configuration files.
    15  
    16  This command is a convenient way to check whether the execution plan for a
    17  set of changes matches your expectations without making any changes to
    18  real resources or to the state. For example, `terraform plan` might be run
    19  before committing a change to version control, to create confidence that it
    20  will behave as expected.
    21  
    22  The optional `-out` argument can be used to save the generated plan to a file
    23  for later execution with `terraform apply`, which can be useful when
    24  [running Terraform in automation](https://learn.hashicorp.com/terraform/development/running-terraform-in-automation).
    25  
    26  ## Usage
    27  
    28  Usage: `terraform plan [options] [dir]`
    29  
    30  By default, `plan` requires no flags and looks in the current directory
    31  for the configuration and state file to refresh.
    32  
    33  If the command is given an existing saved plan as an argument, the
    34  command will output the contents of the saved plan. In this scenario,
    35  the `plan` command will not modify the given plan. This can be used to
    36  inspect a planfile.
    37  
    38  The command-line flags are all optional. The list of available flags are:
    39  
    40  * `-compact-warnings` - If Terraform produces any warnings that are not
    41    accompanied by errors, show them in a more compact form that includes only
    42    the summary messages.
    43  
    44  * `-destroy` - If set, generates a plan to destroy all the known resources.
    45  
    46  * `-detailed-exitcode` - Return a detailed exit code when the command exits.
    47    When provided, this argument changes the exit codes and their meanings to
    48    provide more granular information about what the resulting plan contains:
    49    * 0 = Succeeded with empty diff (no changes)
    50    * 1 = Error
    51    * 2 = Succeeded with non-empty diff (changes present)
    52  
    53  * `-input=true` - Ask for input for variables if not directly set.
    54  
    55  * `-lock=true` - Lock the state file when locking is supported.
    56  
    57  * `-lock-timeout=0s` - Duration to retry a state lock.
    58  
    59  * `-no-color` - Disables output with coloring.
    60  
    61  * `-out=path` - The path to save the generated execution plan. This plan
    62    can then be used with `terraform apply` to be certain that only the
    63    changes shown in this plan are applied. Read the warning on saved
    64    plans below.
    65  
    66  * `-parallelism=n` - Limit the number of concurrent operation as Terraform
    67    [walks the graph](/docs/internals/graph.html#walking-the-graph). Defaults
    68    to 10.
    69  
    70  * `-refresh=true` - Update the state prior to checking for differences.
    71  
    72  * `-state=path` - Path to the state file. Defaults to "terraform.tfstate".
    73    Ignored when [remote state](/docs/state/remote.html) is used.
    74  
    75  * `-target=resource` - A [Resource
    76    Address](/docs/internals/resource-addressing.html) to target. This flag can
    77    be used multiple times. See below for more information.
    78  
    79  * `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag
    80    can be set multiple times. Variable values are interpreted as
    81    [HCL](/docs/configuration/syntax.html#HCL), so list and map values can be
    82    specified via this flag.
    83  
    84  * `-var-file=foo` - Set variables in the Terraform configuration from
    85    a [variable file](/docs/configuration/variables.html#variable-files). If
    86    a `terraform.tfvars` or any `.auto.tfvars` files are present in the current
    87    directory, they will be automatically loaded. `terraform.tfvars` is loaded
    88    first and the `.auto.tfvars` files after in alphabetical order. Any files
    89    specified by `-var-file` override any values set automatically from files in
    90    the working directory. This flag can be used multiple times.
    91  
    92  ## Resource Targeting
    93  
    94  The `-target` option can be used to focus Terraform's attention on only a
    95  subset of resources.
    96  [Resource Address](/docs/internals/resource-addressing.html) syntax is used
    97  to specify the constraint. The resource address is interpreted as follows:
    98  
    99  * If the given address has a _resource spec_, only the specified resource
   100    is targeted. If the named resource uses `count` and no explicit index
   101    is specified in the address (i.e. aws_instance.example[3]), all of the instances sharing the given
   102    resource name are targeted.
   103  
   104  * If the given address _does not_ have a resource spec, and instead just
   105    specifies a module path, the target applies to all resources in the
   106    specified module _and_ all of the descendent modules of the specified
   107    module.
   108  
   109  This targeting capability is provided for exceptional circumstances, such
   110  as recovering from mistakes or working around Terraform limitations. It
   111  is *not recommended* to use `-target` for routine operations, since this can
   112  lead to undetected configuration drift and confusion about how the true state
   113  of resources relates to configuration.
   114  
   115  Instead of using `-target` as a means to operate on isolated portions of very
   116  large configurations, prefer instead to break large configurations into
   117  several smaller configurations that can each be independently applied.
   118  [Data sources](/docs/configuration/data-sources.html) can be used to access
   119  information about resources created in other configurations, allowing
   120  a complex system architecture to be broken down into more manageable parts
   121  that can be updated independently.
   122  
   123  ## Security Warning
   124  
   125  Saved plan files (with the `-out` flag) encode the configuration,
   126  state, diff, and _variables_. Variables are often used to store secrets.
   127  Therefore, the plan file can potentially store secrets.
   128  
   129  Terraform itself does not encrypt the plan file. It is highly
   130  recommended to encrypt the plan file if you intend to transfer it
   131  or keep it at rest for an extended period of time.
   132  
   133  Future versions of Terraform will make plan files more
   134  secure.