* docs: update plan command documentation. Fixes#19235
* docs: added a missing reserved variable name. Fixes#19159.
* website: add note that resource names cannot start with a number
* website: add some notes to the 0.12 upgrade guide
...and one other reference to the application data directory.
Context:
https://docs.microsoft.com/en-us/windows/desktop/shell/knownfolderid#folderid_roamingappdata
In newer Windows versions, the folder accessible as `%APPDATA%` (and via various
APIs) is actually at something like "documents and settings\user\application
data\roaming", while earlier versions omit the "\roaming" part of the path. This
means you can confuse people by referring to the "application data" directory by
its human name, because "roaming" is the real application data directory, but it
looks like a subdirectory of "application data".
Thus, it's less confusing to just use the `%APPDATA%` variable, with the added
benefit that you can copy and paste the path and it'll just work in most places.
This has been replaced with an "Expressions" page.
Also includes a number of changes to Markdown style to conform to our
usual conventions, applied automatically by my editor while making these
changes.
With the additional configuration language features coming in Terraform
v0.12, our existing documentation structure is beginning to strain.
Here we reorganize the navigation slightly in order to introduce the
concepts in a more appropriate order so that we can reveal complexity
more gradually. Subsequent commits will revise the content of these
pages to better reflect the new sequencing.
The "Environment Variables" page is moved from the Configuration section
into the "Commands" section, since it is not considered a part of the
configuration language and thus more appropriate in the CLI documentation.
The old placement is reflective of the broader purpose that the
"Configuration" section had originally, but its new focus will be on
the Terraform language (.tf files) in particular, with other aspects of
customizing Terraforms behavior covered in other sections.
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.
Also:
- In the getting started guide, the TFE content was all tailored to the older
run-locally workflow. I've replaced it with some brief explanation and a link
to the dedicated TFE getting started guide.
- Fixed a sidebar link glitch in the configuration section. (Both "Terraform"
and "Terraform Enterprise" were marked as active if you were on the TFE page.)
- Renamed the "Terraform Enterprise" page "Terraform Push." (Some people have
gotten confused and landed on this page when trying to set up the `atlas`
remote backend.)
Since an early version of Terraform, the `destroy` command has always
had the `-force` flag to allow an auto approval of the interactive
prompt. 0.11 introduced `-auto-approve` as default to `false` when using
the `apply` command.
The `-auto-approve` flag was introduced to reduce ambiguity of it's
function, but the `-force` flag was never updated for a destroy.
People often use wrappers when automating commands in Terraform, and the
inconsistency between `apply` and `destroy` means that additional logic
must be added to the wrappers to do similar functions. Both commands are
more or less able to run with similar syntax, and also heavily share
their code.
This commit updates the command in `destroy` to use the `-auto-approve` flag
making working with the Terraform CLI a more consistent experience.
We leave in `-force` in `destroy` for the time-being and flag it as
deprecated to ensure a safe switchover period.
It's important to match the version of local Terraform with the remote Terraform version in Terraform Enterprise when using the "terraform push" command, or else the uploaded configuration package may not be compatible.
In the 0.10 release we added an opt-in mode where Terraform would prompt
interactively for confirmation during apply. We made this opt-in to give
those who wrap Terraform in automation some time to update their scripts
to explicitly opt out of this behavior where appropriate.
Here we switch the default so that a "terraform apply" with no arguments
will -- if it computes a non-empty diff -- display the diff and wait for
the user to type "yes" in similar vein to the "terraform destroy" command.
This makes the commonly-used "terraform apply" a safe workflow for
interactive use, so "terraform plan" is now mainly for use in automation
where a separate planning step is used. The apply command remains
non-interactive when given an explicit plan file.
The previous behavior -- though not recommended -- can be obtained by
explicitly setting the -auto-approve option on the apply command line,
and indeed that is how all of the tests are updated here so that they can
continue to run non-interactively.
Previously we described inline here where to put the .terraformrc file,
but now we have a separate page all about this file that gives us more
room to describe in more detail where the file is placed and what else it
can do.
Fix the -state and -state-out wording to be consistent with other
commands. Remove the erroneous reference to remote state in the website
version of the flag description.
The docs did not mention that it is possible to provide overrides for specific
plugins by placing them into a `terraform.d/plugins/os_arch/` directory inside
the working dir.
Closes#15727.
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.
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 is documented for all other Hashicorp products using this service but
was missed for Terraform. This serves as a disclosure of the fact that
Terraform reaches out to a Hashicorp service, an explanation of the
purpose of that request, and instructions on how to disable it in
environments where it is inappropriate or cannot be supported due to a
firewall or other connectivity restrictions.
A common reason to want to use `terraform plan` is to have a chance to
review and confirm a plan before running it. If in fact that is the
only reason you are running plan, this new `terraform apply -auto-approve=false`
flag provides an easier alternative to
P=$(mktemp -t plan)
terraform refresh
terraform plan -refresh=false -out=$P
terraform apply $P
rm $P
The flag defaults to true for now, but in a future version of Terraform it will
default to false.
Previously the behavior for -target when given a module address was to
target only resources directly within that module, ignoring any resources
defined in child modules.
This behavior turned out to be counter-intuitive, since users expected
the -target address to be interpreted hierarchically.
We'll now use the new "Contains" function for addresses, which provides
a hierarchical "containment" concept that is more consistent with user
expectations. In particular, it allows module.foo to match
module.foo.module.bar.aws_instance.baz, where before that would not have
been true.
Since Contains isn't commutative (unlike Equals) this requires some
special handling for targeting specific indices. When given an argument
like -target=aws_instance.foo[0], the initial graph construction (for
both plan and refresh) is for the resource nodes from configuration, which
have not yet been expanded to separate indexed instances. Thus we need
to do the first pass of TargetsTransformer in mode where indices are
ignored, with the work then completed by the DynamicExpand method which
re-applies the TargetsTransformer in index-sensitive mode.
This is a breaking change for anyone depending on the previous behavior
of -target, since it will now select more resources than before. There is
no way provided to obtain the previous behavior. Eventually we may support
negative targeting, which could then combine with positive targets to
regain the previous behavior as an explicit choice.
Kristin Laemmert