Terraform v0.15 includes the conclusion of the deprecation cycle for some
renamed arguments in the "azure" backend.
We missed this on the first draft of the upgrade guide because this change
arrived along with various other more innocuous updates and so we didn't
spot it during our change review.
Unfortunately it seems that this link got lost in a merge conflict when
we did the big nav refactor earlier in the v0.15 cycle, so here we'll
retoractively add it to the new location for upgrade guide nav, in the
language layout rather than the downloads layout.
* 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>
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.
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.)
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.
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.
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.
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.
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.
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>
As usual, we'll continue to iterate on this based on feedback and
questions during the beta period, but this is a first draft intended to
help those who are trying out the first beta.
Since this is still at an early phase and likely to change significantly
in future iterations, rather than attempting to guess on a suitable final
location for documenting the testing feature I've instead taken the
unusual approach of adding a new page that is explicitly about the
experiment. My expectation is that once we conclude the experiment we'll
replace this new page with a stub that just explains that there was once
an experiment and then links to whatever final feature unfolded from the
research.
The URL for this page is hard-coded into the warning message in the
"terraform test" command, so as we continue to evolve this feature in
future releases we'll need to update the callout note on the page about
which Terraform CLI version it's currently talking about, so users of
older versions can clearly see when they'd need to upgrade in order to
participate in a later incarnation of the experiment.
* Remove deprecation on undeclared variable
Remove deprecation and add docs specific to the behavior around
undeclared variable values
* Limit full warnings to 2 instances, then summary
This way, the third warning is a summary, rather than the fourth
warning being the summary
To make the command arguments easier to understand and extend, we are
moving away from positional arguments. This commit changes the graph
command to take a `-plan` flag instead of an optional trailing path.
During the language/CLI docs reorg, we noticed several pages that were no longer
viable; some were redundant, some useless, and some just very obsolete.
Since we were trying to avoid breaking links at the time, we opted to remove
them from the navs and leave them as "ghost pages" — still accessible, but not
findable.
This commit finally cleans these ghosts up and updates any remaining links to
relevant modern pages. Bustin' makes me feel good. 👻🚫
This variable mechanism was replaced long ago with a explicit `Allow
destroy plans` setting on a Terraform Cloud workspace, and no longer
does anything: https://www.terraform.io/docs/cloud/workspaces/settings.html#destruction-and-deletion
Rather than mention this new mechanism at all though, I've removed the
requisite from here entirely - the reason being that a consideration
like this is no different from other permission concerns (e.g. "You must
have Apply permission on a workspace to `apply`"), and without
enumerating _all_ of these here - which doesn't seem appropriate - we
just remove this concern entirely.
...and also shrink the explanation for alternate sharing approaches, a bit.
Actually, it looks like I already half-adopted it by accident. 😬 But this
commit adds it to the sidebar under "State", so users can browse to it. I'm
leaving the URL alone, because it's not urgent and we'll need to adjust a large
swath of URLs at some point anyway.
This change effectively stops presenting `terraform` as a provider in the normal
sense, and reduces /docs/providers/terraform/index.html to a ghost page in the
language section (to avoid breaking links for the time being). The message a
reader should get is that Terraform has one special built-in data source where
you don't need to think about the provider or its version.
As of December 18, 2020, we've redirected nearly all of the provider
documentation that used to live on terraform.io:
- For providers that got published on the Registry, we redirected each docs page
to the corresponding Registry docs page.
- For providers that never got adopted by a new publisher, we archived the
GitHub repository and redirected each docs page to the corresponding Markdown
source file on github.com. (For an example of these redirects, see
https://www.terraform.io/docs/providers/telefonicaopencloud/r/s3_bucket.html)
There are ten providers left that we haven't redirected. These ones got adopted
by new publishers and _will_ end up on the Registry, but they aren't quite ready
to ship and get their permanent redirects, and we don't want to sabotage their
SEO by 301ing to a temporary destination.
These links largely still go somewhere useful, but they have some kind of issue
revealed by our new link checker:
- Some of them point to a stale URL that redirects, and can be updated to the
new destination.
- Some of them point to anchors that don't exist (anymore?) in the destination.
- Some of them end up redirecting unnecessarily due to how the server handles
directory URLs without trailing slashes. Sorry, I know that's pointless, just,
humor me for the time being so we can get our CI green. 😭
In a couple cases, I've added invisible anchors to destination pages, either to
preserve an old habit or because the current anchors kind of suck due to being
particularly long or meandering.
* Add limitations section to for_each
Move limitations from a note to their own section,
to allow for expansion on disallowing sensitive values
in for_each
This PR updates the documentation of input variable of terraform. It's
mentioned that multiple `-var` is possible, but no example is given.
This PR adds an example of multiple `-var` option
* command/state list: list resources in nested and expaneded modules
A few distinct bugs fixed in here:
There was a bug in the logic checking if a given module was the child of
the targetAddr, now fixed. That resolved the basic issue where resources
in nested submodules were not listed.
The logic around allowMissing needed some tweaking to allow for empty
modules, as long as those modules had submodules with resources. state
list is the only command using allowMissing with false so this felt safe
to do.
Finally I extended the logic so list would included expanded modules,
which is to say giving module.foo would result in resources from
module.foo[1], module.foo[0], etc.
* update state list docs to show that module filtering includes any nested
modules
I missed this earlier because my link checker was collapsing the two links from
this page to that page into a single report.
For posterity's sake, I'm linking directly to the markdown file in GitHub at an
appropriate tag version. I do not expect anyone to ever click this link again,
though.
So far the output command has had a default output format intended for
human consumption and a JSON output format intended for machine
consumption.
However, until Terraform v0.14 the default output format for primitive
types happened to be _almost_ a raw string representation of the value,
and so users started using that as a more convenient way to access
primitive-typed output values from shell scripts, avoiding the need to
also use a tool like "jq" to decode the JSON.
Recognizing that primitive-typed output values are common and that
processing them with shell scripts is common, this commit introduces a new
-raw mode which is explicitly intended for that use-case, guaranteeing
that the result will always be the direct result of a string conversion
of the output value, or an error if no such conversion is possible.
Our policy elsewhere in Terraform is that we always use JSON for
machine-readable output. We adopted that policy because our other
machine-readable output has typically been complex data structures rather
than single primitive values. A special mode seems justified for output
values because it is common for root module output values to be just
strings, and so it's pragmatic to offer access to the raw value directly
rather than requiring a round-trip through JSON.
This is a repeated cause of confusion and questions in the community
forum, because both JSON and YAML valid syntax are hard to generate using
just string concatenation. Terraform has built-in functions for both of
these common serializations to avoid those problems, and so this will
hopefully make these better alternatives more discoverable.
When we did the earlier documentation rework for Terraform v0.12 we still
had one big "Expressions" page talking about the various operators and
constructs, and so we had to be a bit economical with the details about
some more complicated constructs in order to avoid the page becoming even
more overwhelming.
However, we've recently reorganized the language documentation again so
that the expressions section is split across several separate pages, and
that gives some freedom to go into some more detail about and show longer
examples for certain features.
My changes here are not intended to be an exhaustive rewrite but I did
try to focus on some areas I've commonly seen questions about when helping
in the community forum and elsewhere, and also to create a little more
connectivity between the different content so readers can hopefully find
what they are looking for more easily when they're not yet sure what
terminology to look for.
As of Terraform 0.13+, the get-plugins command has been
superceded by new provider installation mechanisms, and
general philosophy (providers are always installed, but
the sources may be customized). Updat the init command
to give users a warning if they are setting this flag,
to encourage them to remove it from their workflow, and
update relevant docs and docstrings as well
I originally drafted these docs in a context where I was relying on
GitHub's Markdown renderer, and carelessly imported them into the
Terraform website without verifying that the website's Markdown renderer
could process it. This particular quirk has bitten us before: the website
Markdown parser expects follow-on paragraphs in a list item to be indented
at least four spaces, and with less than that it ignores the leading
whitespace altogether and just understands a normal paragraph.
This change will cause the follow-on paragraphs to now correctly render
as part of the bullet points they are intended to be attached to.
This is under a heading "Sensitive Resource Attributes" on the assumption
that if we later stabilize this feature then this heading will live on
with some different content that describes the propagation of sensitive
values from resource attributes, rather than describing the experiment.
The resources, expressions, and modules pages were all split into smaller, more
navigable pages, but the old URLs had accumulated a large number of deep links
to their section headers. To help people recover when they click an old link, we
converted those old URLs to landing pages, which preserve all of the old in-page
anchors and point readers to the appropriate new destinations.
However, because the new link-to-new-page sections are so small, it was kind of
hard to tell which section you had clicked into! Especially if you were near the
bottom of the page and the browser wasn't able to position the desired section
at the very top of the window.
This commit aims to improve that by putting one full screen of whitespace in
between every linkable section on these landing pages. Yes, it's a hack, but
you're meant to only view these pages for three seconds or so before moving on
to the place you wanted to be, and this should help dispel any confusion about
which place that is.
This tutorial uses references to local values, conditional expressions,
and splat expressions, so I've added it to those pages as well as the
expressions overview.
We've historically made statements like this in response to requests for
more customization to the "terraform fmt" behavior, but the documentation
itself was somewhat vague about the intended goals of this command.
This is an attempt to be more explicit that consistency between codebases
is the primary goal of this command, and that the examples in the
Terraform documentation are our main guide for what is "idiomatic style"
when adding additional rules over time.
Nothing here is intended to be new policy, but instead as codifying
positions we've taken elsewhere in the past in the hope of allowing users
to decide how (and whether) they wish to make use of this tool.
When using the enhanced remote backend, a subset of all Terraform
operations are supported. Of these, only plan and apply can be executed
on the remote infrastructure (e.g. Terraform Cloud). Other operations
run locally and use the remote backend for state storage.
This causes problems when the local version of Terraform does not match
the configured version from the remote workspace. If the two versions
are incompatible, an `import` or `state mv` operation can cause the
remote workspace to be unusable until a manual fix is applied.
To prevent this from happening accidentally, this commit introduces a
check that the local Terraform version and the configured remote
workspace Terraform version are compatible. This check is skipped for
commands which do not write state, and can also be disabled by the use
of a new command-line flag, `-ignore-remote-version`.
Terraform version compatibility is defined as:
- For all releases before 0.14.0, local must exactly equal remote, as
two different versions cannot share state;
- 0.14.0 to 1.0.x are compatible, as we will not change the state
version number until at least Terraform 1.1.0;
- Versions after 1.1.0 must have the same major and minor versions, as
we will not change the state version number in a patch release.
If the two versions are incompatible, a diagnostic is displayed,
advising that the error can be suppressed with `-ignore-remote-version`.
When this flag is used, the diagnostic is still displayed, but as a
warning instead of an error.
Commands which will not write state can assert this fact by calling the
helper `meta.ignoreRemoteBackendVersionConflict`, which will disable the
checks. Those which can write state should instead call the helper
`meta.remoteBackendVersionCheck`, which will return diagnostics for
display.
In addition to these explicit paths for managing the version check, we
have an implicit check in the remote backend's state manager
initialization method. Both of the above helpers will disable this
check. This fallback is in place to ensure that future code paths which
access state cannot accidentally skip the remote version check.
The Registry is a web service whose behavior isn't directly tied to Terraform
core's release cycle; therefore, its docs should be decoupled from that release
cycle as well.
https://github.com/hashicorp/terraform-website/pull/1517 adopts the registry
docs into hashicorp/terraform-website, which already hosts several other
corpuses of documentation that aren't tied to Terraform core's version (like
Terraform Cloud, Terraform Enterprise, and Extending Terraform). Once that PR is
merged, we should remove the registry docs from this repository to avoid
confusing anyone.
The local-exec provisioner documentation includes an example which refers
to an attribute of the current resource using its full traversal path,
rather than using "self" as we typically expect.
Due to some coincidences in how Terraform builds the dependency graph,
referring to the resource in this way happens to work when the resource
has only a single instance (the graph builder just skips that
self-referential dependency edge), but it fails if the user later tries
to add "count" or "for_each" to the resource, because at that point all
of the instances become dependent on one another, which creates a
dependency cycle.
Using "self" to access the current instance attributes is the usual
approach, so I've updated the documentation to show that.
As written previously this seemed to suggest using "app.terraform.io" (the
"hostname you use to access the Terraform Cloud application) to access a
private registry in Terraform Enterprise, but that isn't true and I assume
isn't what was intended.
Instead, the hostname for a Terraform Enterprise instance is the hostname
where the Terraform Enterprise application is running, which is both the
hostname where users would find its web UI and the hostname they'd use
to configure the "remote" backend for remote operations and state storage.
In order to be able to predict a result type even if arguments are not yet
known, coalesce requires all of its arguments to be of the same type. Our
usual automatic conversion rules mean that in some cases the result is
a silent type conversion rather than an explicit error, so we'll at least
document that so that folks who encounter it can understand what is
causing the likely-surprising behavior.
If we were building this function over again today I expect we'd make it
always return an error under type mismatch, but to do so now would be a
breaking change and the potential cost of that seems too high for
something that doesn't seem to arise incredibly often in practice.
This one is a lot like the previous two commits, but slightly more complex:
- Only adding one new meta-argument page, for `providers`; otherwise, it just
re-uses the dual-purpose pages I made in the resources commit.
- About that `providers` argument: The stuff that was relevant to consumers of a
module went in that meta-argument page, but there was also a huge deep dive on
how the _author_ of a re-usable module should handle provider configurations
in cases where inheriting the default providers isn't sufficient. THAT, I
moved into a new page in the module development section. (For the consumer of
a module, this should all be an implementation detail; the module README
should tell you which aliased providers you need to configure and pass, and
then you just do it, without worrying about proxy configuration blocks etc.)
- The "standard module structure" recommendations in the main module development
page gets a page of its own, to make it more prominent and discoverable.
- Same deal with using the old URL as a landing page, at least for the main
module calls page. It didn't seem necessary for the module development page.
- Resource behavior gets its own page.
- Meta-arguments all get their own pages.
- Stuff about resource syntax itself gets a page.
In the process of breaking the meta-arguments out into their own pages, I
revised them (with the exception of `provider`) so that they apply to both
resources and modules.
Like with Expressions, this commit repurposes the old resources.html URL as a
landing page for old links.
This commit converts the previous URL for this content to a landing page, which
captures all of the previous in-page anchors and directs readers to the new home
for each section.
For some time now we've been recommending explicitly passing data between
configurations using separate resource types and data sources, rather than
always using terraform_remote_state, for reasons including reducing
coupling between subsystems and allowing a configuration's state snapshots
to be under restrictive access controls.
However, those recommendations have so far not appeared directly in the
documentation for terraform_remote_state, and have instead just been
alluded to elsewhere in the documentation when discussing ways to pass
data between configurations.
This change, then, is an attempt to be clear and explicit about the
recommendation and to give a variety of specific examples of how to
implement it. The terraform_remote_state data source page is admittedly
not the most obvious place in the information architecture to put a set
of alternatives to it, but it does appear that this documentation page is
where people most commonly end up when researching options in this area
and so I've put this here in an attempt to "meet people where they are".
Possibly in a future documentation reorganization we might have an
separate page specifically about sharing data between configurations, but
we don't currently have time to do that bigger reorganization. If we do so
later, the content on this page could potentially be replaced with a
summary of the recommendation and a link to another place for the details,
but the goal here is to make this information visible in the existing
location people look for it, rather than blocking until there's a better
place for it to live.
This also includes a small amount of editing of some existing content on
the page to use terminology and style more similar to how our main
configuration language documentation is written,.
Remove chef, habitat, puppet, and salt-masterless provsioners,
which follows their deprecation. Update the documentatin for these
provisioners to clarify that they have been removed from later versions
of Terraform. Adds the fmt Make target back and updates fmtcheck script
for correctness.
Some hasty, incorrect merge conflict fixing caused this page to have a
strange mix of terminology between "system" and "provider". Along with
that, there were also several editorial errors caused by text on this
page having originally been derived from the provider registry
documentation.
This documentation will now consistently talk about being a module
registry protocol rather than a provider registry protocol, and it will
consistently use the term "system" as a generic term for the final part
of the module source address, aside from noting that there is an optional
convention to name it after the "type" part of an official provider when
possible.
This is a new part of the existing module_variable_optional_attrs
experiment, because it's intended to complement the ability to declare
an input variable whose type constraint is an object type with optional
attributes. Module authors can use this to replace null values (that were
either explicitly set or implied by attribute omission) with other
non-null values of the same type.
This function is a bit more type-fussy than our functions typically are
because it's intended for use primarily with input variables that have
fully-specified type constraints, and thus it uses that type information
to help inform how the defaults data structure should be interpreted.
Other uses of this function will probably be harder today because it takes
a lot of extra annotation to build a value of a specific type if it isn't
passing through a variable type constraint. Perhaps later language
features for more general type conversion will make this more applicable,
but for now the more general form of this problem is better solved other
ways.
The new nav structure demanded a few new pages that give context about a feature
or workflow. In a few cases, they take text from an existing page.
Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Co-authored-by: Judith Malnick <judith.patudith@gmail.com>
We're splitting the current Terraform CLI docs into two top-level categories,
and these are the new nav sidebars for those sections.
As of this commit, they refer to some new "glue" pages that don't exist yet.
The HashiCorp engineering services team has set up APT and Yum
repositories as alternative installation methods for various HashiCorp
products, now including Terraform.
We don't really have a great place to talk about these in our current
website structure. There is a longer-term plan to revamp the downloads
page to include other options, but we are already getting lots of
questions about how to use these repositories and so my goal here is to
publish at least a first pass of documentation, linked from the Downloads
page sidebar as a placeholder for now, so we'll have somewhere to refer to
when answering such questions.
My intent is that even once we have a revamped Downloads page that
mentions these options more clearly, we'll still need to link out to
another page to talk about various details, and so the two new URLs this
creates would be the home of that content, even if we rewrite the specific
prose here to work better in the context of the new Downloads page.
The example configuration now uses Terraform 0.12+ syntax, and the
output examples are up to date with the current text UI. We also add an
explicit recommendation to use the `-json` option for a consistent and
stable output format, for use in automation.
Prior to Terraform 0.12 these two functions were the only way to construct
literal lists and maps (respectively) in HIL expressions. Terraform 0.12,
by switching to HCL 2, introduced first-class syntax for constructing
tuple and object values, which can then be converted into list and map
values using the tolist and tomap type conversion functions.
We marked both of these functions as deprecated in the Terraform v0.12
release and have since then mentioned in the docs that they will be
removed in a future Terraform version. The "terraform 0.12upgrade" tool
from Terraform v0.12 also included a rule to automatically rewrite uses
of these functions into equivalent new syntax.
The main motivation for removing these now is just to get this change made
prior to Terraform 1.0. as we'll be doing with various other deprecations.
However, a specific reason for these two functions in particular is that
their existence is what caused us to invent the idea of a "type expression"
as a distinct kind of expression in Terraform v0.12, and so removing them
now would allow potentially unifying type expressions with value
expressions in a future release.
We do not have any current specific plans to make that change, but one
potential motivation for doing so would be to take another attempt at a
generalized "convert" function which takes a type as one of its arguments.
Our previous attempt to implement such a function was foiled by the fact
that Terraform's expression validator doesn't have any way to know to
treat one argument of a particular function as special, and so it was
generating incorrect error messages. We won't necessarily do that, but
having these "list" and "map" functions out of the way leaves the option
open.
The documentation states that an explicit type conversion to set is needed, but it does not say why implicit type conversion does not work.
Co-authored-by: Nick Fagerlund <nick@hashicorp.com>
* The index must be non-negative integer
and added instructions on how to get the last value in the list.
* Typo fix
Co-authored-by: Nick Fagerlund <nick@hashicorp.com>
* Update module-registry-protocol.html.md
1: There is a mismatch in the segment labels for the version query URL (system vs provider)
2: There is a discrepancy between the documentation and the actual generated request for retrieving module source code (URL segments 4 vs 3)
- There is no segment for "provider"
* Update module-registry-protocol.html.md
Changed ```:system``` to ```:provider``` for versions and source API URLs
These pages are thoroughly obsolete. Later, we'll delete and redirect them; for
now, we'll make sure the relevant pages are front-and-center in the sidebar if
someone somehow ends up on here.
Guides was already mostly gone. The two major remaining bits (the "core
workflow" guide and the "recommended practices" guide, which deserves a rename)
make much more sense as highly technical marketing material, and thus have a
natural home in the intro section.
Several `terraform` subcommands include sub-sub-commands; with our old sidebar
system, viewing those took you to an isolated "island" nav sidebar, away from
the main docs. The new navigation will adopt all these pages, so we don't need
to exile the reader to odd places.
As of this commit, that layout doesn't exist yet, but I'm isolating the one-line
changes to their own commit to try and keep your eyes from glazing over.
We typically try to avoid making subjective, boasty claims in our
documentation in recent times, but there remained both some older
documentation that we've not recently revised and also some newer examples
that are, in retrospect, also perhaps more "boasty" than they need to be.
We prefer not to use this sort of boasty language because not everyone
using Terraform has the same background and experience, and so what is
"easy" or "intuitive" to one person may not be so to another person, and
that should not suggest that the second person is in any way wrong or
inadequate.
In reviewing some of our use of the word "easy" here I tried as much as
possible to surgically revise the existing content without getting drawn
into a big rewrite, but in some cases the content was either pretty
unsalvageable (due to talking about obsolete features that were removed
long ago) or required some broader changes to make the result hopefully
still get the same facts across. In those cases I've both removed some
content entirely or adjusted larger paragraphs.
This was not an exhaustive review and so I'm sure there's still plenty of
room for similar improvements elsewhere. I also resisted the urge to
update some pages that contain outdated information about currently-active
features.
My initial motivation here was to update the example output from
Terraform's top-level help list to match recent updates in the layout
and language used.
However, while here I took the opportunity to update some dated language
that was not consistent with our modern documentation writing style,
in particular including a totally unnecessary and potentially-alienating
claim that Terraform is "very easy to use". Our modern writing style
discourages this sort of "boastful" language and encourages us to focus on
the facts at hand.
This is an analog to the "alltrue" function, using OR as the reduce
operator rather than AND.
This also includes some simplification of the "alltrue" implementation
to implement it similarly as a sort of reduce operation with AND
as the reduce operator, but with the same effective behavior.
* Fixes#26684
* Update provider-requirements.html.md
Removing additional/extra newlines
* Update provider-requirements.html.md
And now some trailing spaces. le sigh
* Update config.html.md
When reading this page, I couldn't find the list of the "supported backends to the left". They're actually on a different page, so thought I'd update it so that others wouldn't find it confusing like me.
If this is ok with you, would it be possible to label this PR with 'hacktoberfest-accepted'? I'm still new to this. If not, I'd be alright. Thank you!
* Update config.html.md
Swapped the full URL in the link for a relative path
Co-authored-by: Petros Kolyvas <petros@hashicorp.com>
* ADD CLI option position for force-unlock command
* Update force-unlock.html.markdown
Made a change to also include the missing [DIR]
Co-authored-by: Petros Kolyvas <petros@hashicorp.com>
These were initially introduced as functions with "encode" and "decode"
prefixes, but that doesn't match with our existing convention of putting
the encoding format first so that the encode and decode functions will
group together in a alphabetically-ordered function list.
"text" is not really a defined serialization format, but it's a short word
that hopefully represents well enough what these functions are aiming to
encode and decode, while being consistent with existing functions like
jsonencode/jsondecode, yamlencode/yamldecode, etc.
The "base64" at the end here is less convincing because there is precedent
for that modifier to appear both at the beginning and the end in our
existing function names. I chose to put it at the end here because that
seems to be our emergent convention for situations where the base64
encoding is a sort of secondary modifier alongside the primary purpose
of the function, as we see with "filebase64". (base64gzip is an exception
here, but it seems outvoted by the others.)
* Add note to upgrade guide about provider sensitivity
Now that sensitivity follows attributes providers mark
as sensitive, add this note to the upgrade guide.
Co-authored-by: Alisdair McDiarmid <alisdair@users.noreply.github.com>
For normal provider installation we want to associate each provider with
a selected version number and find a suitable package for that version
that conforms to the official hashes for that release.
Those requirements are very onerous for a provider developer currently
testing a not-yet-released build, though. To allow for that case this new
CLI configuration feature allows overriding specific providers to refer
to give local filesystem directories.
Any provider overridden in this way is not subject to the usual
restrictions about selected versions or checksum conformance, and
activating an override won't cause any changes to the selections recorded
in the lock file because it's intended to be a temporary setting for one
developer only.
This is, in a sense, a spiritual successor of an old capability we had to
override specific plugins in the CLI configuration file. There were
some vestiges of that left in the main package and CLI config package
but nothing has actually been honoring them for several versions now and
so this commit removes them to avoid confusion with the new mechanism.
Terraform v0.10 introduced .terraform/plugins as a cache directory for
automatically-installed plugins, Terraform v0.13 later reorganized the
directory structure inside but retained its purpose as a cache.
The local cache used to also serve as a record of specifically which
packages were selected in a particular working directory, with the intent
that a second run of "terraform init" would always select the same
packages again. That meant that in some sense it behaved a bit like a
local filesystem mirror directory, even though that wasn't its intended
purpose.
Due to some unfortunate miscommunications, somewhere a long the line we
published some documentation that _recommended_ using the cache directory
as if it were a filesystem mirror directory when working with Terraform
Cloud. That was really only working as an accident of implementation
details, and Terraform v0.14 is now going to break that because the source
of record for the currently-selected provider versions is now the
public-facing dependency lock file rather than the contents of an existing
local cache directory on disk.
After some consideration of how to move forward here, this commit
implements a compromise that tries to avoid silently doing anything
surprising while still giving useful guidance to folks who were previously
using the unsupported strategy. Specifically:
- The local cache directory will now be .terraform/providers rather than
.terraform/plugins, because .terraform/plugins is effectively "poisoned"
by the incorrect usage that we can't reliably distinguish from prior
version correct usage.
- The .terraform/plugins directory is now the "legacy cache directory". It
is intentionally _not_ now a filesystem mirror directory, because that
would risk incorrectly interpreting providers automatically installed
by Terraform v0.13 as if they were a local mirror, and thus upgrades
and checksum fetches from the origin registry would be blocked.
- Because of the previous two points, someone who _was_ trying to use the
legacy cache directory as a filesystem mirror would see installation
fail for any providers they manually added to the legacy directory.
To avoid leaving that user stumped as to what went wrong, there's a
heuristic for the case where a non-official provider fails installation
and yet we can see it in the legacy cache directory. If that heuristic
matches then we'll produce a warning message hinting to move the
provider under the terraform.d/plugins directory, which is a _correct_
location for "bundled" provider plugins that belong only to a single
configuration (as opposed to being installed globally on a system).
This does unfortunately mean that anyone who was following the
incorrectly-documented pattern will now encounter an error (and the
aforementioned warning hint) after upgrading to Terraform v0.14. This
seems like the safest compromise because Terraform can't automatically
infer the intent of files it finds in .terraform/plugins in order to
decide automatically how best to handle them.
The internals of the .terraform directory are always considered
implementation detail for a particular Terraform version and so switching
to a new directory for the _actual_ cache directory fits within our usual
set of guarantees, though it's definitely non-ideal in isolation but okay
when taken in the broader context of this problem, where the alternative
would be silent misbehavior when upgrading.
The upgrade requirements for this release are considerably more modest
than for Terraform v0.13, so this time we just have some notes about a
few changes in behavior that may be impactful to some users.
This first pass is intended to be included as part of a forthcoming beta
testers' guide as we begin the v0.14 beta testing period. We will make
further changes to this upgrade guide based on feedback from those who
participate in the beta process.
Note that this upgrade guide is not intended as release marketing material
and so its presentation is focused on addressing concerns users might
encounter while upgrading. We'll share highlights from the release in
other contexts, such as the changelog and in the product blog.
This builds on an experimental feature in the underlying cty library which
allows marking specific attribtues of an object type constraint as
optional, which in turn modifies how the cty conversion package handles
missing attributes in a source value: it will silently substitute a null
value of the appropriate type rather than returning an error.
In order to implement the experiment this commit temporarily forks the
HCL typeexpr extension package into a local internal/typeexpr package,
where I've extended the type constraint syntax to allow annotating object
type attributes as being optional using the HCL function call syntax.
If the experiment is successful -- both at the Terraform layer and in
the underlying cty library -- we'll likely send these modifications to
upstream HCL so that other HCL-based languages can potentially benefit
from this new capability.
Because it's experimental, the optional attribute modifier is allowed only
with an explicit opt-in to the module_variable_optional_attrs experiment.
This includes both the main documentation about the lock file itself and
changes to related documentation about Terraform commands that interact
with the lock file.
We will likely continue to update this first pass of documentation as we
get feedback and questions during the prerelease period.
* website: Update all Learn crosslinks
The URL structure on Learn recently changed, so it's time to update some URLs.
Co-authored-by: Tu Nguyen <im2nguyen@users.noreply.github.com>
Move the information about state from the "caveats" to the main
info section, using similar information to sensitive outputs.
Updates the header of the section from similar inspiration.
We can remove the caveat about changing map elements.
Add a little more text about the intended use case for ignore_changes,
as the common case of fixing erroneous provider behavior should not be
the primary motivation for the maintenance of this feature.
* Put link to tutorial in its own section, call it a tutorial instead of guide, and use new canonical URL.
* Mention limitations of using import with a remote backed
* Typo fix
Co-authored-by: Nick Fagerlund <nick.fagerlund@gmail.com>
This commit adds an `alltrue` function to Terraform configuration. A
reason we might want this function is because it will enable more
powerful custom variable validations. For example:
```hcl
variable "amis" {
type = list(object({
id = string
}))
validation {
condition = (alltrue([
for a in var.amis : length(a.id) > 4 && substr(a.id, 0, 4) == "ami-"
]))
error_message = "The ID of at least one AMI was invalid."
}
}
```
For a credentials helper plugin to be useful with Terraform 0.13+, we
need to cope with the case of having no credentials for a host without
this being an error. This is to allow the public Terraform Registry to
be accessed without supplying a token.
The way to implement this is to respond to queries for credentials for a
host which has no credentials stored with an empty object and a success
exit code. This contradicts the previous documentation, which calls for
an error response in this case.
* Adding not about data-sources and depends-on for 0.12 users
* Bold
* A little more markdown
* A little more markdown for data_sources in 0.12
* Some iteration based on good feedback
In addition to the directories previously listed, Terraform looks in the
CLI config directory ($HOME/.terraform.d/plugins on macOS/Linux/UNIX,
and %APPDATA%/terraform.d/plugins on Windows). List this in the
documentation for clarity.
We also add a note about the working directory relative "vendor"
location, ./terraform.d/plugins.
The version argument is deprecated in Terraform v0.14 in favor of
required_providers and will be removed in a future version of terraform
(expected to be v0.15). The provider configuration documentation already
discourages use of 'version' inside provider configuration blocks, so it
only needed an extra note that it is actively deprecated.
This new option is intended to address the previous inconsistencies where
some older subcommands supported partially changing the target directory
(where Terraform would use the new directory inconsistently) where newer
commands did not support that override at all.
Instead, now Terraform will accept a -chdir command at the start of the
command line (before the subcommand) and will interpret it as a request
to direct all actions that would normally be taken in the current working
directory into the target directory instead. This is similar to options
offered by some other similar tools, such as the -C option in "make".
The new option is only accepted at the start of the command line (before
the subcommand) as a way to reflect that it is a global command (not
specific to a particular subcommand) and that it takes effect _before_
executing the subcommand. This also means it'll be forced to appear before
any other command-specific arguments that take file paths, which hopefully
communicates that those other arguments are interpreted relative to the
overridden path.
As a measure of pragmatism for existing uses, the path.cwd object in
the Terraform language will continue to return the _original_ working
directory (ignoring -chdir), in case that is important in some exceptional
workflows. The path.root object gives the root module directory, which
will always match the overriden working directory unless the user
simultaneously uses one of the legacy directory override arguments, which
is not a pattern we intend to support in the long run.
As a first step down the deprecation path, this commit adjusts the
documentation to de-emphasize the inconsistent old command line arguments,
including specific guidance on what to use instead for the main three
workflow commands, but all of those options remain supported in the same
way as they were before. In a later commit we'll make those arguments
produce a visible deprecation warning in Terraform's output, and then
in an even later commit we'll remove them entirely so that -chdir is the
single supported way to run Terraform from a directory other than the
one containing the root module configuration.
The subtle difference in keywords when creating vs. accessing locals trips
people up, even more than the "variable" vs. "var" distinction. It deserves its
own subheader on the page, plus a nice noisy callout.
I've just wasted an hour to two hours trying to find the problem to finally realize that although I declare a "locals" block, it's referred to as "local". This is pretty weird! So let's be be clear about this.
The error diagnostic shown when legacy state contains resources from
in-house providers has changed, so update references to it in the 0.13
upgrade guide.
We previously had this just stubbed out because it was a stretch goal for
the v0.13.0 release and it ultimately didn't make it in.
Here we fill out the existing stub -- with a minor change to its interface
so it can access credentials -- with a client implementation that is
compatible with the directory structure produced by the
"terraform providers mirror" subcommand, were the result to be published
on a static file server.
- Edits to registry overview
- Add index link as 'overview' (header links are semi-invisible)
- move providers/overview.html to providers/index.html
- Edits to providers overview
- fix filename of os-arch
- edits to provider publishing
Terraform's design assumes that each remote object in Terraform's care is
bound to one resource instance and one alone. If the same object is bound
to multiple instances then confusing behavior will often result, such as
two resource configurations competing to update a single object, or
objects being "left behind" when all existing Terraform deployments are
destroyed.
This assumption was previously only implied, though. This change is an
attempt to be more explicit about it, although these are additions to some
older documentation sections that have not been revised for some time and
so this is just a best effort to make this information discoverable
without getting drawn into a full-on reorganization of these sections.
While revising this there were some particular oddities that I decided to
revise while I was there, but I'll leave a fuller revision of this older
content for a later commit when we have more time to review it in greater
detail.
* Make sidebar nav in language docs more intuitive
* Minor display fixes for registry docs
* Explain providers in the registry in the providers index
* Revise a bunch of language docs around provider reqs
This is mostly an effort to smooth out some of the explanations, make sure
things are presented in a helpful order, make sure terminology lines up, draw
connections between related concepts, make default behavior more apparent, and
the like. It shouldn't include very much new information, but there might be one
or two things that came out of a conversation somewhere.
Co-authored-by: Judith Malnick <judith@hashicorp.com>
As part of documenting the new module for_each capabilities we added a
section noting that shared modules using the legacy pattern of declaring
their own provider configurations would not be compatible with them.
However, that also applies to the new module depends_on and several folks
participating in the beta pointed out that the documentation wasn't
discussing that at all.
In order to generalize the advice, I've moved the old content we had
(since v0.11) recommending against provider configurations in shared
modules out into its own section, now being more explicit that it is
a legacy pattern and not recommended, and then folded the content about
for_each and count, now also including depends_on, into that expanded
section.
As is often the case, that had some knock-on effects on the content on
the rest of this page, so there's some general editing and reorganization
here. In particular, I moved the "Multiple Instances of a Module" section
much further up the page because it's content relevant to users of
shared modules, while the later content on this page is more aimed at
authors of shared modules, including the new section about the legacy
pattern.
Part of the upgrade process happens in the first "terraform apply" after
adding explicit source addresses in the configuration. Previously we just
left that implied under the assumption that everyone would run
"terraform apply" shortly after anyway, but there is a specific tricky
situation where the first change after upgrading is to remove a resource
from the configuration, leaving Terraform unable to complete the upgrade.
Because of that, we'll now explicitly direct users to run
"terraform apply" after upgrading. Along with that, there's a reminder to
make sure that "terraform plan" indicates no changes before upgrading, so
that completing the upgrade doesn't involve also applying changes to
remote objects.
* website: Terraform Registry Provider Publishing
* website: (Registry) remove OS/arch recommendation
Until we have a canonical list to point to
Co-authored-by: Paul Tyng <ptyng@hashicorp.com>
Co-authored-by: Paul Tyng <ptyng@hashicorp.com>
* command/init: return an error with invalid -backend-config files
The -backend-config flag expects a set of key-value pairs or a file
containing key-value pairs. If the file instead contains a full backend
configuration block, it was silently ignored. This commit adds a check
for blocks in the file and returns an error if they are encountered.
Fixes#24845
* emphasize backend configuration file in docs
* Azure backend: support snapshots/versioning
Co-authored-by: Reda Ahdjoudj <reda.ahdjoudj@gmail.com>
Co-authored-by: Patrick F. Marques <patrickfmarques@gmail.com>
* Azure backend: Versioning -> Snapshot
Co-authored-by: Reda Ahdjoudj <reda.ahdjoudj@gmail.com>
Co-authored-by: Patrick F. Marques <patrickfmarques@gmail.com>
Although this command is removed in Terraform 0.13, our documentation is
for all versions of Terraform that remain in common use and keeping this
documented will be helpful for folks who are still using Terraform 0.11
and planning their upgrades to Terraform 0.12.
Both of the upgrade commands now include notes that they are only
available in their specific major version, along with a link to the
relevant upgrade guide for other background information about the upgrade,
in case the user finds the command documentation first. (The command docs
are, I think, a little more discoverable than the upgrade guides.)
We previously covered everything about using providers on a single page,
but that was getting unwieldy already and we now have a lot more to
discuss with v0.13 introducing a new source address syntax and some other
concepts.
Here we split the provider-related content into two parts: "Provider
Requirements" covers how to find and declare dependencies on providers,
and then "Provider Configuration" (formerly just "Providers") then focuses
primarily on how to write zero or more provider configurations for a
particular provider.
Because "Provider Requirements" is now presented before "Provider
Configuration" in the navigation, I've also moved some of the introductory
content about providers in general onto the "Requirements" page. The
first paragraph of that content is duplicated onto the "Configuration"
page for discoverability, but we now link to the requirements page to get
the full story.
The "Configuration Language" section was becoming rather unweildy, both
by having a lot of pages and by some of the pages being quite large in
themselves.
This is a first step towards breaking things up a little more, starting
with two changes:
- The "Configuration Language" navigation is now split into two
sub-headings "Configuration Blocks" and "Syntax".
- Some of the information about sub-blocks of the "terraform" block are
now given their own pages, because their content is quite complex
in itself.
- "Version Constraints" is now a page in its own right, rather than this
content being duplicated in slightly different forms across multiple
contexts that make use of user-specified version constraints.
We previously had the module registry protocol documented only as an
undefined subset of the full API of the official registry implementation.
However, the vast majority of endpoints documented in the official API
docs are not needed for a headless third-party module registry that only
intends to make modules available to Terraform CLI.
To make this clearer to potential third-party implementors, and also for
consistency with how the provider registry protocol is now documented,
here we create a new page to describe the subset required for all
registries, and then explain in the docs for the offical API that
potential third-party implementors should refer to the new page instead.
The longer page describing the full API of the official implementations
remains for those who wish to write clients for that API, because it is
part of the API surface area for Terraform Cloud and Terraform Enterprise.
I also took this opportunity to address the fact that module addresses
don't really contain "provider names" at all, but rather than the fourth
field in the address is _conventionally_ an official provider name but
can really be any string that serves to differentiate multiple
implementations of the same abstraction. The new docs therefore refer to
this field as "system" rather than "provider".
Currently the example config for the Consul backend uses a live Consul demo cluster at `demo.consul.io`. This results in TF state with sensitive information and all being stored on a public site when users just copy and paste the config. This PR changes it so that the config address isn't the public demo cluster.
This new command is intended to make it easy to create or update a mirror
directory containing suitable providers for the current configuration,
producing a layout that is appropriate both for a filesystem mirror or,
if copied into the document root of an HTTP server, a network mirror.
This initial version is not customizable aside from being able to select
multiple platforms to install packages for.
Future iterations of this could include commands to turn the JSON index
generation on and off, or to instruct it to produce the unpacked directory
layout instead of the packed directory layout as it currently does. Both
of those options would make the generated directory unsuitable to be
a network mirror, but it would still work as a filesystem mirror.
In the long run this will hopefully form part of a replacement workflow to
terraform-bundle as a way to put copies of providers somewhere so we don't
need to re-download them every time, but some other changes will be needed
outside of just this command before that'd be true, such as adding support
for network and/or filesystem mirrors in Terraform Enterprise.
When helping folks in the community forum, I commonly see questions around
more complex patterns in transforming deep data structures into different
shapes to work with for_each. We have examples of these patterns in the
docs for the functions that they rely on, but they were not previously
very discoverable in the main configuration language documentation
sections.
Here I've moved the "Using Expressions in for_each" subsection on the
Resources page above some of the other sub-sections to hopefully make it
easier to see, and written out in more detail the two specific patterns
that answer a significant number of for_each-related user questions in
the hope that readers will be more likely to realize that the links are
relevant to what their goals.
I also added some more elaboration about the behavior of converting from
list to set in the "Using Sets" subsection, because this feature is often
a user's first encounter with the set data type and I've inferred from
some of the questions I've answered that a number of Terraform users don't
have prior experience with set data types in other languages to draw
assumptions from.
Finally, I added some similar links to the for_each patterns within the
for expression documentation itself, to try to make those examples more
visible to those who might be discovering the documentation in a different
sequence, e.g. by following a deep link shared in an answer to a question
in the community forum.
The "apply" documentation contained a simple typo, while the "plan"
documentation contained outdated information about using
"terraform plan PLANFILE" to view a plan. The latter is now a separate
command entirely, since Terraform 0.12: "terraform show PLANFILE".
This is a baby-step towards an intended future where all Terraform actions
which have side-effects in either remote objects or the Terraform state
can go through the plan+apply workflow.
This initial change is focused only on allowing plan+apply for changes to
root module output values, so that these can be written into a new state
snapshot (for consumption by terraform_remote_state elsewhere) without
having to go outside of the primary workflow by running
"terraform refresh".
This is also better than "terraform refresh" because it gives an
opportunity to review the proposed changes before applying them, as we're
accustomed to with resource changes.
The downside here is that Terraform Core was not designed to produce
accurate changesets for root module outputs. Although we added a place for
it in the plan model in Terraform 0.12, Terraform Core currently produces
inaccurate changesets there which don't properly track the prior values.
We're planning to rework Terraform Core's evaluation approach in a
forthcoming release so it would itself be able to distinguish between the
prior state and the planned new state to produce an accurate changeset,
but this commit introduces a temporary stop-gap solution of implementing
the logic up in the local backend code, where we can freeze a snapshot of
the prior state before we take any other actions and then use that to
produce an accurate output changeset to decide whether the plan has
externally-visible side-effects and render any changes to output values.
This temporary approach should be replaced by a more appropriately-placed
solution in Terraform Core in a release, which should then allow further
behaviors in similar vein, such as user-visible drift detection for
resource instances.
as with this version of this doc users receives a warning like this if them use quotes with parameters of 'on_failure' setting:
"
on_failure = "continue"
In this context, keywords are expected literally rather than in quotes.
Terraform 0.11 and earlier required quotes, but quoted keywords are now
deprecated and will be removed in a future version of Terraform. Remove the
quotes surrounding this keyword to silence this warning.
"
same with:
when = "destroy"
All of the feedback from the experiment described enhancements that can
potentially be added later without breaking changes, so this change simply
removes the experiment gate from the feature as originally implemented
with no changes to its functionality.
Further enhancements may follow in later releases, but the goal of this
change is just to ship the feature exactly as it was under the experiment.
Most of the changes here are cleaning up the experiment opt-ins from our
test cases. The most important parts are in configs/experiments.go and in
experiments/experiment.go .
Rachel Sharp