Commit Graph

1315 Commits

Author SHA1 Message Date
Nick Fagerlund 65f3ddec52 website: Make apply's usage of plan options harder to miss
- I'm using distinct subheaders and smaller paragraphs to try and make the info
  about apply's two modes more skimmable.

- I'm also adding a separate "Plan Options" subheader (and keeping the section
  tiny so it stays snugged up right next to the "Apply Options" one) to make it
  extra-clear that Hey, There's More Options, They're Over There.
2021-05-14 13:26:33 -07:00
Alisdair McDiarmid 3e40a9a4eb
Merge pull request #28507 from stevematney/patch-1
Updating sensitive/nonsensitive docs with v0.14 specifics.
2021-05-14 13:46:12 -04:00
Steve Matney e27a927ba4 Updating sensitive and nonsensitive docs with correct v0.15 info. 2021-05-14 10:32:39 -06:00
Martin Atkins 3c8a4e6e05 command+backend/local: -refresh-only and drift detection
This is a light revamp of our plan output to make use of Terraform core's
new ability to report both the previous run state and the refreshed state,
allowing us to explicitly report changes made outside of Terraform.

Because whether a plan has "changes" or not is no longer such a
straightforward matter, this now merges views.Operation.Plan with
views.Operation.PlanNoChanges to produce a single function that knows how
to report all of the various permutations. This was also an opportunity
to fill some holes in our previous logic which caused it to produce some
confusing messages, including a new tailored message for when
"terraform destroy" detects that nothing needs to be destroyed.

This also allows users to request the refresh-only planning mode using a
new -refresh-only command line option. In that case, Terraform _only_
performs drift detection, and so applying a refresh-only plan only
involves writing a new state snapshot, without changing any real
infrastructure objects.
2021-05-13 09:05:06 -07:00
Martin Atkins 42e0985839 command: use -lock=false consistently in -help output
Previously the docs for this were rather confusing because they showed an
option to turn _on_ state locking, even though it's on by default.

Instead, we'll now show -lock=false in all cases and document it as
_disabling_ the default locking.

While working on this I also noticed that the equivalent docs on the
website were differently inconsistent. I've not made them fully consistent
here but at least moreso than they were before.
2021-05-12 09:27:37 -07:00
Martin Atkins ed121321c6 website: Revamp the "terraform state mv" page
My original motivation here was to add the previously-missing -dry-run
option to the list of options

However, while in the area I noticed that this command hasn't had a
documentation refresh for a while and so I took the opportunity to update
it to match with our current writing style and terminology used in other
parts of the documentation, and so I've rewritten prose elsewhere on the
page to hopefully give the same information in a way that fits in better
with concepts discussed elsewhere in the documentation, and also to try
to add some additional context to connect this information with what
we've described in other places.

This rewrite also drops the example of moving from one "state file" to
another, because that's a legacy usage pattern that isn't supported when
using remote backends, and we recommend most folks to use remote backends
so it's strange to show an example that therefore won't work for most
people. Rather than adding additional qualifiers to that example I chose
to just remove it altogether, because we've generally been working to
de-emphasize these legacy local backend command line options elsewhere in
the documentation.
2021-05-12 09:27:37 -07:00
Martin Atkins ea089d06f1 website: Revamp the "terraform state rm" page
My original motivation here was to add the previously-missing -dry-run
option to the list of options

However, while in the area I noticed that this command hasn't had a
documentation refresh for a while and so I took the opportunity to update
it to match with our current writing style and terminology used in other
parts of the documentation, and so I've rewritten prose elsewhere on the
page to hopefully give the same information in a way that fits in better
with concepts discussed elsewhere in the documentation, and also to try
to add some additional context to connect this information with what
we've described in other places.
2021-05-12 09:27:37 -07:00
Martin Atkins 0aa0e00fdc website: Backend docs link to new .gitignore anchor
The Git book seems to be using a different anchor format now, and so this
link was previously effectively linking to the page as a whole rather
than to the specific section we're trying to refer to.
2021-05-12 09:27:37 -07:00
Martin Atkins 874f1abb2b cli+website: -ignore-remote-version docs and other cleanup
We previously had only very short descriptions of what
-ignore-remote-version does due to having the documentation for it inline
on many different command pages and -help output.

Instead, we'll now centralize the documentation about this argument on
the remote backend page, and link to it or refer to it from all other
locations. This then allows us to spend more words on discussing what
Terraform normally does _without_ this option and warning about the
consequences of using it.

This continues earlier precedent for some local-backend-specific options
which we also don't recommend for typical use. While this does make these
options a little more "buried" than before, that feels justified given
that they are all "exceptional use only" sort of options where users ought
to learn about various caveats before using them.

While there I also took this opportunity to fix some earlier omissions
with the local-backend-specific options and a few other minor consistency
tweaks.
2021-05-12 09:27:37 -07:00
Roger Berlind b6885923d0
website: Add link to Modules in Package Sub-directories (#27980)
* Add link to Modules in Package Sub-directories

Add link to "Modules in Package Sub-directories" section at top of page

* Fix broken links

* Update aws link, fixes missing anchor linkcheck

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
2021-05-11 12:15:09 -07:00
Martin Atkins 6f68065326 website: Explicit example of for_each chaining between resources
This pattern follows as a natural consequence of how for_each is defined,
but I've noticed from community forum Q&A that newcomers often don't
immediately notice the connection between what for_each expects as input
and what a for_each resource produces as a result, so my aim here is to
show a short example of that in the hope of helping folks see the link
here and get ideas on how to employ the technique in other situations.
2021-05-10 10:49:04 -07:00
Rachel Sharp 87c9e78666
Merge pull request #28604 from hashicorp/res-lifecycle-tutorial
Add link to lifecycle tutorial
2021-05-07 13:01:25 -05:00
Alisdair McDiarmid a5b7394f9a command/jsonplan: Add replace_paths
The set of paths which caused a resource update to require replacement
has been stored in the plan since 0.15.0 (#28201). This commit adds a
simple JSON representation of these paths, allowing consumers of this
format to determine exactly which paths caused the resource to be
replaced.

This representation is intentionally more loosely encoded than the JSON
state serialization of paths used for sensitive attributes. Instead of a
path step being represented by an object with type and value, we use a
more-JavaScripty heterogenous array of numbers and strings. Any
practical consumer of this format will likely traverse an object tree
using the index operator, which should work more easily with this
format. It also allows easy prefix comparison for consumers which are
tracking paths.

While updating the documentation to include this new field, I noticed
that some others were missing, so added them too.
2021-05-04 16:51:51 -04:00
Rachel Sharp c302fa507f
Add link to lifecycle tutorial 2021-05-04 14:20:22 -04:00
Martin Atkins 1d3e34e35e command: New -replace=... planning option
This allows a similar effect to pre-tainting an object but does the action
within the context of a normal plan and apply, avoiding the need for an
intermediate state where the old object still exists but is marked as
tainted.

The core functionality for this was already present, so this commit is
just the UI-level changes to make that option available for use and to
explain how it contributed to the resulting plan in Terraform's output.
2021-05-03 15:43:23 -07:00
Martin Atkins 6bed3008a5 website: Reworking of the "terraform plan" docs, and related pages
It's been a long time since we gave this page an overhaul, and with our
ongoing efforts to make plan and apply incorporate all of the side-effects
that might need to be done against a configuration it seems like a good
time for some restructuring in that vein.

The starting idea here is to formally split the many "terraform plan"
options into a few different categories:
 - Planning modes
 - Planning options
 - Other options

The planning modes and options are the subset that are also accepted by
"terraform apply" when it's running in its default mode of generating a
plan and then prompting for interactive approval of it. This then allows
us to avoid duplicating all of that information on the "terraform apply"
page, and thus allows us to spend more words discussing each of them.

This set of docs is intended as a fresh start into which we'll be able to
more surgically add in the information about -refresh-only and -replace=...
once we have those implemented. Consequently there are some parts of this
which may seem a little overwraught for what it's currently describing;
that's a result of my having prepared this by just deleting the
-refresh-only and -replace=... content from our initial docs draft and
submitted the result, in anticipation of re-adding the parts I've deleted
here in the very near future in other commits.
2021-04-30 14:27:36 -07:00
Sam Velie 5d04c4ea27
docs: correct spelling of normally (#28508) 2021-04-30 12:24:02 -04:00
Martin Atkins b802237e03 plans: Track an optional extra "reason" for some planned actions
Previously we were repeating some logic in the UI layer in order to
recover relevant additional context about a change to report to a user.
In order to help keep things consistent, and to have a clearer path for
adding more such things in the future, here we capture this user-facing
idea of an "action reason" within the plan model, and then use that
directly in order to decide how to describe the change to the user.

For the moment the "tainted" situation is the only one that gets a special
message, matching what we had before, but we can expand on this in future
in order to give better feedback about the other replace situations too.

This also preemptively includes the "replacing by request" reason, which
is currently not reachable but will be used in the near future as part of
implementing the -replace=... plan command line option to allow forcing
a particular object to be replaced.

So far we don't have any special reasons for anything other than replacing,
which makes sense because replacing is the only one that is in a sense
a special case of another action (Update), but this could expand to
other kinds of reasons in the future, such as explaining which of the
few different reasons a data source read might be deferred until the
apply step.
2021-04-29 17:50:46 -07:00
Kristin Laemmert f6af7b4f7a
lang/funcs: add (console-only) TypeFunction (#28501)
* lang/funcs: add (console-only) TypeFunction

The type() function, which is only available for terraform console,
prints out the type of a given value. This is mainly intended for
debugging - it's nice to be able to print out terraform's understanding
of a complex variable.

This introduces a new field for Scope: ConsoleMode. When ConsoleMode is true, any additional functions intended for use in the console (only) may be added.
2021-04-23 10:29:50 -04:00
Rachel Sharp 98ce186be9
Merge pull request #28443 from hashicorp/res-add-learn-link-debug-1
Add Learn link to Debugging
2021-04-21 22:59:19 -04:00
John Houston fabdf0bea1
Add config_paths and drop KUBECONFIG env variable in kubernetes backend (#26997) 2021-04-20 10:05:45 -04:00
Rachel Sharp 56483d10d2
Update debugging.html.md 2021-04-19 12:18:02 -04:00
Kristin Laemmert 85adad0ec7
docs: small update for provider binary locations (#28413)
* docs: add note that provider binaries need to be placed in appropriate subdirectories under the default locations
2021-04-19 09:04:46 -04:00
Martin Atkins 5f5432e8ea
website: v0.15 upgrade guide for sensitive resource attributes (#28355)
* website: v0.15 upgrade guide for sensitive resource attributes

Our earlier draft of this guide didn't include a section about the
stabilization of the "provider_sensitive_attrs" language experiment. This
new section aims to address the situation where a module might previously
have been returning a sensitive value without having marked it as such,
and thus that module will begin returning an error after upgrading to
Terraform v0.15.

As part of that, I also reviewed the existing documentation about these
features and made some edits aiming to make these four different sections
work well together if users refer to them all at once, as they are likely
to do if they follow the new links from the upgrade guide. I aimed to
retain all of the content we had before, but some of it is now in a new
location.

In particular, I moved the discussion about the v0.14 language experiment
into the upgrade guide, because it seems like a topic only really relevant
to those upgrading from an earlier version and not something folks need to
know about if they are using Terraform for the first time in v0.15 or
later.

* minor fixups

Co-authored-by: Kristin Laemmert <mildwonkey@users.noreply.github.com>
2021-04-14 09:04:40 -04:00
Martin Atkins 140c613ae8 lang/funcs: "one" function
In the Terraform language we typically use lists of zero or one values in
some sense interchangably with single values that might be null, because
various Terraform language constructs are designed to work with
collections rather than with nullable values.

In Terraform v0.12 we made the splat operator [*] have a "special power"
of concisely converting from a possibly-null single value into a
zero-or-one list as a way to make that common operation more concise.

In a sense this "one" function is the opposite operation to that special
power: it goes from a zero-or-one collection (list, set, or tuple) to a
possibly-null single value.

This is a concise alternative to the following clunky conditional
expression, with the additional benefit that the following expression is
also not viable for set values, and it also properly handles the case
where there's unexpectedly more than one value:

    length(var.foo) != 0 ? var.foo[0] : null

Instead, we can write:

    one(var.foo)

As with the splat operator, this is a tricky tradeoff because it could be
argued that it's not something that'd be immediately intuitive to someone
unfamiliar with Terraform. However, I think that's justified given how
often zero-or-one collections arise in typical Terraform configurations.
Unlike the splat operator, it should at least be easier to search for its
name and find its documentation the first time you see it in a
configuration.

My expectation that this will become a common pattern is also my
justification for giving it a short, concise name. Arguably it could be
better named something like "oneornull", but that's a pretty clunky name
and I'm not convinced it really adds any clarity for someone who isn't
already familiar with it.
2021-04-12 15:32:03 -07:00
Víctor Felipe Godoy Hernández a9487c7674
Fix yamldecode example from json to yaml (#28220)
* Fix yamldecode example from json to yaml

* inline yaml example
2021-04-05 13:41:07 -04:00
Martin Atkins f47c4efb1b website: Dynamic blocks can for_each any collection type
We previously added a hint to both resource for_each and dynamic blocks
about using the "flatten" and "setproduct" situations to construct
suitable collections to repeat over.

However, we used the same text in both places which ended up stating that
dynamic blocks can only accept map or set values, which is a constraint
that applies to resource for_each (because we need to assign a unique
identifier to each instance) and not to dynamic blocks (which don't have
any uniqueness enforced by Terraform Core itself).

To remove that contradiction with the text above which talks about what
is valid here, I've just generalized this to say "collection", because
the primary point of this paragraph is the "one element per desired nested
block" part, not specifically what sort of collections are permitted in
this location. (Text further up describes the supported types.)
2021-03-30 09:43:33 -07:00
Robin Norwood e3bd661470
Merge pull request #28164 from hashicorp/rln-add-resource-targeting-tutorial-callout
Add callout to resource targeting tutorial
2021-03-29 09:12:30 -05:00
Matthew Frahry 15779013da
backend/azurerm: Bug fixes and updated dependencies #28181 2021-03-26 14:07:56 -07:00
Judith Malnick 75fbbe8065
clarify version that pull upgrades local state to (#28204) 2021-03-26 13:57:44 -07:00
Martin Atkins 6f35c2847b command: Reorganize docs of the local backend's legacy CLI options
We have these funny extra options that date back to before Terraform even
had remote state, which we've preserved along the way by most recently
incorporating them as special-case overrides for the local backend.

The documentation we had for these has grown less accurate over time as
the details have shifted, and was in many cases missing the requisite
caveats that they are only for the local backend and that backend
configuration is the modern, preferred way to deal with the use-cases they
were intended for.

We always have a bit of a tension with this sort of legacy option because
we want to keep them documented just enough to be useful to someone who
finds an existing script/etc using them and wants to know what they do,
but not to take up so much space that they might distract users from
finding the modern alternative they should consider instead.

As a compromise in that vein here I've created a new section about these
options under the local backend documentation, which then gives us the
space to go into some detail about the various behaviors and interactions
and also to discuss their history and our recommended alternatives. I then
simplified all of the other mentions of these in command documentation
to just link to or refer to the local backend documentation. My hope then
is that folks who need to know what these do can still find the docs, but
that information can be kept out of the direct path of new users so they
can focus on learning about remote backends instead.

This is certainly not the most ideal thing ever, but it seemed like the
best compromise between the competing priorities I described above.
2021-03-25 13:56:48 -07:00
Matthew Frahry 13b41d59f5 Website Test Fix 2021-03-25 13:47:12 -07:00
Matthew Frahry 3546650ac6 backend/azurerm: adding the right role name 2021-03-22 10:51:01 -07:00
Robin Norwood 31323b911b Add callout to resource targeting tutorial 2021-03-22 11:55:41 -05:00
Matthew Frahry a978d4ee99 website: adding the new fields to azurerm 2021-03-22 09:53:52 -07:00
Tej-Singh-Rana 2a49d908b8
fix the typo (#28140) 2021-03-22 10:51:45 -04:00
Pam Selle 683422e54f
Merge pull request #28113 from hashicorp/pselle/provider_sensitive_attrs_docs
Update documentation for provider_sensitive_attrs experiment
2021-03-18 11:24:55 -04:00
James Bardin c6278bbe37
Merge pull request #28042 from jasons42/update-workspaces-docs
Indicate etcdv3 support for multiple workspaces in docs
2021-03-17 14:13:08 -04:00
Alisdair McDiarmid b6ca782993 documentation: Clarify JSON diagnostic traversal
The traversal value is normally a valid HCL string, but can be
simplified if a traversal step has a complex index value (e.g. an
object). This means it is not always parseable HCL, so this commit
updates the documentation to clarify this and explicitly record that we
do not guarantee its contents are stable. The purpose of these values is
purely for building human-readable UI.
2021-03-17 11:46:24 -04:00
Alisdair McDiarmid 53739f0aac
Merge pull request #28108 from hashicorp/alisdair/validate-json-format-version
cli: Add format version to validate -json output
2021-03-17 11:38:21 -04:00
Martin Atkins 89b2405080 lang/funcs: "sensitive" and "nonsensitive" functions
These aim to allow hinting to Terraform about situations where it's not
able to automatically infer value sensitivity.

"nonsensitive" is for situations where Terraform's behavior is too
conservative, such as when a new value is derived from a sensitive value
in such a way that all of the sensitive content is removed.

"sensitive", on the other hand, is for situations where Terraform can't
otherwise infer that a value is sensitive. These situations should be
pretty rare in a module that's making effective use of sensitive input
variables and output values, but the documentation shows one example of
an uncommon situation where a more direct hint via this function would
be needed.

Both of these functions are aimed at only occasional use in unusual
situations. They are here for reasons of pragmatism, not because we
expect them to be used routinely or recommend their use.
2021-03-16 16:26:22 -07:00
Paddy 0b5c4a6a2c
Accept TF_LOG=json to enable TRACE logs in JSON format
This is not currently a supported interface, but we plan to release
tool(s) that consume parts of it that are more dependable later,
separately from Terraform CLI itself.
2021-03-16 14:59:15 -07:00
Pam Selle 81e8167a4c Update documentation for provider_sensitive_attrs experiment
Update documentation to reference that this experiment is now
default in 0.15+
2021-03-16 13:31:43 -04:00
Alisdair McDiarmid 46a29b13ed cli: Add format version to validate -json output
In line with the other complex JSON output formats for plan and provider
schema, here we add an explicit `format_version` field to the JSON
output of terraform validate.
2021-03-16 09:46:36 -04:00
Alisdair McDiarmid 2a85f0483f website: Update validate -json diags documentation
Updated to include details about the new "snippet" object in JSON
diagnostics.
2021-03-12 14:25:11 -05:00
Martin Atkins dc7f2b7314 website: docs for the terraform validate JSON output 2021-03-12 09:39:56 -08:00
Jason Smith 024035114a Fix broken link error
Link to https://consul.io/ is not actually broken but returns a 307
redirect to https://www.consul.io/ which the broken link test counts as a failure.
2021-03-10 15:38:22 -06:00
Jason Smith 8663b2100a Indicate etcdv3 support for multiple workspaces 2021-03-10 15:36:37 -06:00
Antoine Cotten 3442873cdb
docs: Update link to HCL native syntax spec 2021-03-10 17:47:21 +01:00
Masayuki Morita 31a5aa1878
command/init: Add a new flag `-lockfile=readonly` (#27630)
Fixes #27506

Add a new flag `-lockfile=readonly` to `terraform init`.
It would be useful to allow us to suppress dependency lockfile changes
explicitly.

The type of the `-lockfile` flag is string rather than bool, leaving
room for future extensions to other behavior variants.

The readonly mode suppresses lockfile changes, but should verify
checksums against the information already recorded. It should conflict
with the `-upgrade` flag.

Note: In the original use-case described in #27506, I would like to
suppress adding zh hashes, but a test code here suppresses adding h1
hashes because it's easy for testing.

Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com>
2021-03-09 11:12:00 -05:00