Commit Graph

1350 Commits

Author SHA1 Message Date
Laura Pacilio 577c3653f2
Merge pull request #28983 from KurtLehnardt/patch-1
fixed typo
2021-06-30 08:54:04 -04:00
Laura Pacilio a7e24c384b
Merge pull request #28842 from iaoiui/patch-1
remove extra "be"
2021-06-30 08:52:51 -04:00
Laura Pacilio f9ec36383d
Merge pull request #29011 from vlad-ro/patch-1
Add back missing closing quote character
2021-06-30 08:51:47 -04:00
Laura Pacilio 4f12b8d917
Merge pull request #28863 from stensonb/patch-1
typo
2021-06-30 08:50:24 -04:00
Laura Pacilio de97a03528
Merge pull request #28908 from kondr57/patch-1
fix typo
2021-06-30 08:43:26 -04:00
Martin Atkins a945b379d8 website: Explicit examples of -var escaping in various shells
The -var command line option comes with the disadvantage that a user must
contend both with Terraform's own parser and with the parser in whichever
shell they've decided to use, and different shells on different platforms
have different rules.

Previously we've largely just assumed that folks know the appropriate
syntax for the shell they chose, but it seems that command lines involving
spaces and other special characters arise rarely enough in other commands
that Terraform is often the first time someone needs to learn the
appropriate syntax for their shell.

We can't possibly capture all of the details of all shells in our docs,
because that's far outside of our own scope, but hopefully this new
section will go some way to give some real examples that will help folks
figure out how to write suitable escape sequences, if they choose to
set complex variable values on the command line rather than in .tfvars
as we recommend elsewhere on this page.
2021-06-22 14:10:04 -07:00
Robin Norwood 50fe980877
Merge pull request #28998 from hashicorp/rln-add-versions-tutorials-links
Add links to terraform versions tutorials
2021-06-22 11:50:18 -05:00
Vlad Romanenko d4d56a96b1
Add back missing closing quote character 2021-06-22 15:20:31 +01:00
Robin Norwood 2c71bb3a2e Add links to terraform versions tutorials 2021-06-21 14:26:43 -05:00
Radek Simko bb868606ea
docs: Document naming conventions for templates & backend configs (#28924)
* docs: Document naming conventions for templates & backend configs

* Update website/docs/cli/config/config-file.html.md

Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com>

* Update website/docs/language/functions/templatefile.html.md

Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com>

Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com>
2021-06-18 17:20:00 +01:00
Kurt Lehnardt 165b2a2509
fixed typo 2021-06-18 09:59:56 -06:00
Kristin Laemmert 583859e510
commands: `terraform add` (#28874)
* command: new command, terraform add, generates resource templates

terraform add ADDRESS generates a resource configuration template with all required (and optionally optional) attributes set to null. This can optionally also pre-populate nonsesitive attributes with values from an existing resource of the same type in state (sensitive vals will be populated with null and a comment indicating sensitivity)

* website: terraform add documentation
2021-06-17 12:08:37 -04:00
Kristin Laemmert ac03d35997
jsonplan and jsonstate: include sensitive_values in state representations (#28889)
* jsonplan and jsonstate: include sensitive_values in state representations

A sensitive_values field has been added to the resource in state and planned values which is a map of all sensitive attributes with the values set to true.

It wasn't entirely clear to me if the values in state would suffice, or if we also need to consult the schema - I believe that this is sufficient for state files written since v0.15, and if that's incorrect or insufficient, I'll add in the provider schema check as well.

I also updated the documentation, and, since we've considered this before, bumped the FormatVersions for both jsonstate and jsonplan.
2021-06-14 09:19:13 -04:00
Kristin Laemmert 9ca3cb4233
website/docs: move type func docs to a useful location (#28940)
* website/docs: move type func docs to a useful location

* docs don't exist if you don't put them in the index (again)
2021-06-14 08:54:27 -04:00
Vladimir Kondratiev 58a5207dc4
fix typo 2021-06-09 13:13:08 +03:00
Martin Atkins f52aec8e3d website: Fix formatting of v1 compatibility promises
Seems like we lost a newline in some of the shuffling it took to get this
into the live website, and so it's formatting oddly in the rendered
website. This restores the intended formatting of this as the start of
a bullet list, rather than as a continuation of the previous paragraph.
2021-06-08 10:35:23 -07:00
Judith Malnick 044c439dbc
Gloss of top docs pages (#28891)
* clarify input variables opening sentence

* adjust variables description

* claraify providers text and add learn callout

* add description to providers page

* add desscription and clarify provider configuration

* add deprecation note to versions in proivder configs

* add hands on callout and clarify next steps in intro

* link to language collection from language docs

* give more context about configurtion language up front

* clarify output top page

* reorganize for each intro to present feature before notes

* move description before link out and remove passive voice

* fix typo

* clarify purpose of plan

* move explanation before learn link and fully spell boolean

* add a syntax heading  to separate intro from details

* add learn callout to module source docs

* clean up intro to provider requirements and add link

* Apply suggestions from code review

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>

Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
2021-06-08 06:58:55 -07:00
Martin Atkins 07aa07f5b9 website: First Draft of Upgrade Guide 2021-06-07 17:23:39 -07:00
Bryan Stenson b487b9f8fb
typo 2021-06-02 12:27:40 -07:00
iaoiui 176cfad1dd
remove extra "be" 2021-05-29 15:51:33 +09:00
Judith Malnick d7f6000118 Revert "mclarify specifying provider versions"
This reverts commit 397494daca.
2021-05-28 14:34:05 -07:00
Judith Malnick 397494daca mclarify specifying provider versions 2021-05-28 13:51:16 -07:00
Martin Atkins 4e74a7a4f1 initwd: Error message for local paths escaping module packages
Our module installer has a somewhat-informal idea of a "module package",
which is some external thing we can go fetch in order to add one or more
modules to the current configuration. Our documentation doesn't talk much
about it because most users seem to have found the distinction between
external and local modules pretty intuitive without us throwing a lot of
funny terminology at them, but there are some situations where the
distinction between a module and a module package are material to the
end-user.

One such situation is when using an absolute rather than relative
filesystem path: we treat that as an external package in order to make the
resulting working directory theoretically "portable" (although users can
do various other things to defeat that), and so Terraform will copy the
directory into .terraform/modules in the same way as it would download and
extract a remote archive package or clone a git repository.

A consequence of this, though, is that any relative paths called from
inside a module loaded from an absolute path will fail if they try to
traverse upward into the parent directory, because at runtime we're
actually running from a copy of the directory that's been taking out of
its original context.

A similar sort of situation can occur in a truly remote module package if
the author accidentally writes a "../" source path that traverses up out
of the package root, and so this commit introduces a special error message
for both situations that tries to be a bit clearer about there being a
package boundary and use that to explain why installation failed.

We would ideally have made escaping local references like that illegal in
the first place, but sadly we did not and so when we rebuilt the module
installer for Terraform v0.12 we ended up keeping the previous behavior of
just trying it and letting it succeed if there happened to somehow be a
matching directory at the given path, in order to remain compatible with
situations that had worked by coincidence rather than intention. For that
same reason, I've implemented this as a replacement error message we will
return only if local module installation was going to fail anyway, and
thus it only modifies the error message for some existing error situations
rather than introducing new error situations.

This also includes some light updates to the documentation to say a little
more about how Terraform treats absolute paths, though aiming not to get
too much into the weeds about module packages since it's something that
most users can get away with never knowing.
2021-05-27 11:00:43 -07:00
Martin Atkins abf7f3416b website: "taint" command is deprecated from v0.15.2, not from v1.0.0
We got the replacement for this in earlier than anticipated, so these docs
were originally more pessimistic about when the alternative would be
available.
2021-05-26 10:16:38 -07:00
Martin Atkins 6d80088f51 website: More accurate release versions for new plan options
While we were working on and documenting these it wasn't clear exactly
what Terraform CLI version they would land in, and so we used
"Terraform v1.0" in the docs as a safe bound that was definitely going to
include all of them.

With everything now landed though, we can be more specific about which
v0.15.x minor release each of these appeared in.
2021-05-26 09:19:33 -07:00
Alisdair McDiarmid f9fc47c22e website: Add documentation for machine readable UI
Terraform 0.15.3 added support for a `-json` flag to the plan, apply,
and refresh commands, which renders the Terraform UI output in a
structured machine readable format. This commit adds documentation for
this interface.
2021-05-25 16:01:32 -04:00
Matthew Sanabria 1c3f4fe80f
Add examples to `terraform console` command (#28773)
These examples showcase come use cases for `terraform console`.
2021-05-25 10:06:23 -04:00
Matthew Sanabria a63ac81d0c
Example plugin location using XDG Base Directory (#28711)
The current documention was unclear about the full path of local mirrors
when using the XDG Base Directory Specification.

Also removed the trailing slashes for the other paths in this section.
2021-05-25 10:06:07 -04:00
James Bardin 65ee33a90d
Merge pull request #28748 from Bredoxon/patch-1
Fix typo in the docs
2021-05-19 12:18:21 -04:00
Bredoxon 06e756eb0c
Fix typo in the docs 2021-05-19 10:51:06 +10:00
James Bardin 760a59b3a7 negative substring 2021-05-18 16:04:47 -04:00
Karol Szczepański f684f91f3f
website/docs(plan): fix minor typos (#28713) 2021-05-18 11:05:42 -04:00
Kyle A. Matheny 3afa08b1bc
Remove duplicate word (#28716) 2021-05-18 11:04:54 -04:00
James Bardin 51a171c7f4 pg requires PostgreSQL 10 2021-05-18 09:39:05 -04:00
James Bardin 1b48636b42 update init docs for -migrate-state 2021-05-17 12:41:54 -04:00
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