* lang/funcs: testing of functions through the lang package API
The function-specific unit tests do not cover the HCL conversion that happens when the functions are called in a terraform configuration. For e.g., HCL converts sets to lists before passing it to the function. This means that we could not test passing a set in the function _unit_ tests.
This adds a higher-level acceptance test, plus a check that every (pure) function has a test.
* website/docs: update function documentation
There was some leftover v0.11-style interpolation syntax here.
We prefer to use a "naked" expression in situations like this where the result
isn't a string, because interpolations returning non-strings is a common source
of confusion for new users.
The division operator now always performs floating point division, whereas
before it would choose between float and int division based on the types
of its arguments.
We have a specific error message for when a fractional number is used as
an index in HCL, but this additional upgrade guidance provides a specific
solution to the problem: the floor function.
Sadly we don't have enough context in the current design of the upgrade
tool to make this fix automatic. With some refactoring it may be possible
to apply the fix automatically within list brackets, but since that is
a relatively complex change we'll first try this manual solution prompted
by an error message, because in practice so far we've seen this reported
only in the context of list indexing and our error check will catch that
and make the user aware of the need for a fix there.
* funcs/coalesce: return the first non-null, non-empty element from a
sequence.
The go-cty coalesce function, which was originally used here, returns the
first non-null element from a sequence. Terraform 0.11's coalesce,
however, returns the first non-empty string from a list of strings.
This new coalesce function aims to preserve terraform's documented
functionality while adding support for additional argument types. The
tests include those in go-cty and adapted tests from the 0.11 version of
coalesce.
* website/docs: update coalesce function document
The re-introduction of some of the ambiguity between argument and nested
block syntax (for compatibility with existing provider patterns)
unfortunately leads to some interesting consequences for attributes using
this mode.
While the behavior is generally as before in straightforward cases, this
page aims to spell out some of the different usage patterns explicitly
for the benefit of those writing more complex configurations, such as
generic re-usable modules where using argument vs. block syntax leads to
some real differences.
This page is intentionally not linked from anywhere in the part of the
website maintained in the Terraform repository. Instead, it can be linked
from the provider documentation for any argument where this pattern is
used, to help users understand the ways in which that argument might
deviate from the usual behaviors of arguments vs. nested blocks.
Some users are not accustomed to thinking of IP addresses in a bitwise
fashion, so the hope here is to give enough of an introduction to that way
of thinking for the reader to understand what the "newbits" and "netnum"
arguments represent.
The definition of split was referring the built-in function join. However, join is just one of the ways a string might have been created, and this could cause confusion.
In the terraform state documentation the verb "map" is widely used to
describe the relationship between an item in the state and in the real world
whereas the verb "attach" is not used anywhere.
For 0.11 I just specified the naming rules; for 0.12, I added some info about
referencing values and tightened up the layout of the optional arguments.
This commit also syncs up descriptions of `depends_on`.
'legacy' doesn't seem to be a thing anymore, and we were missing some
of the other values for -type. Also -no-color doesn't seem to be
relevant to this command.
1. The double "$" in the template confuses readers
2. As far as I can tell the variable "count" is not used either in this example
(it is in the next example though)
* docs: elaborate on supported remote backend versions
This PR adds a few lines to the docs to indicate which commands are
supported by what version of the remote backend and it makes a
recommendation about which version to use.
* Clarify remote state storage w/ TFE [skip ci]
Specifically, that this is the backend to use with remote state (all
tiers) and Free-Tier vs. Enterprise tiers differ in remote operations
* website: Arrange remote backend info differently
We have released the v0.12-oriented content to the website early in order
to support the beta process, but in some places we neglected to explicitly
mark features or content as being v0.12-only.
Here we add explicit markers to the main cases we've seen where readers
have reported confusion, along with some other tweaks in similar vein.
Terraform is way bigger than the core CLI tools and the language
now, and the docs have grown accordingly. So we're adding a
global index page to help users get around the many sections of the
docs site, and bumping the CLI/core docs down so they're no longer at the
top of the hierarchy.
The "right" (as in, conceptually pure) way to do this would be to actually
create a new level of directory hierarchy in between. But that would be real
expensive and annoying — the amount of 301s and links to edit would be
monumental, and it wouldn't gain us much beyond a certain picture-straightening
satisfaction, so I'm resisting the temptation.
As part of this, I'm copying the entire text of the 0.12
docs/configuration/modules.html page into docs/configuration-0-11/modules.html —
some of the 0.11 pages needed to be able to link to the moved content, I
didn't want to jump versions jarringly, and a close reading didn't reveal
anything in there that's inaccurate for 0.11.
The "terraform fmt" command produces a different canonical form than we
were showing in our examples here. Our examples should always reflect the
conventions applied by "terraform fmt" to avoid confusion.
(This particular decision is a pragmatic one because the formatter design
needs to use the same rules for the colon in the ? : conditional operator
as for the colon in "for" expressions.)
Since references to attributes of resources are by far the most common
reference type, and the mapping of resource type config to the attributes
is not always obvious, here we give some real examples of patterns for
accessing different configuration constructs within resource blocks along
with the resource type's exported attributes.
Since we don't have any real examples of labelled nested blocks yet (the
current SDK doesn't support them) I've included a hypothetical example for
now just to establish the patterns around them in preparation for
beginning to introduce them as we roll out this feature in the SDK.
As well as some general consolidation and reorganizing, this also includes
some updated advice for making the best use of new Terraform v0.12
features to create infrastructure building-blocks.
In particular, the "Module Usage" documentation is now consolidated into
the configuration section in order to bring all of our general language
documentation together, and the top-level "Modules" section is now
primarily focused on module _authors_ as an audience, covering topics such
as publishing modules and designing them for reuse.
* docs: update plan command documentation. Fixes#19235
* docs: added a missing reserved variable name. Fixes#19159.
* website: add note that resource names cannot start with a number
* website: add some notes to the 0.12 upgrade guide
The announcement post contains the information about the temporary
situation where not all of the providers are compatible yet. Linking there
rather than duplicating the information in the upgrade guide means we'll
be able to update in one place as the situation changes.
The upgrade guide had its last major upgrade while we were preparing for
the alpha releases. Now that the upgrade tool is more complete we can
describe the required changes in terms of that tool, and also add
additional information about provider upgrades.
We will revise this at least one more time before v0.12.0 final, but this
is an interim copy of the upgrade guide intended to help those who are
testing the beta releases.
Although /intro/getting-started includes docs content, those pages currently
redirect to the Learn platform, and so shouldn't be affected by the large unfurl
image.
The go-getter library that is used by the module loader validates S3 URLs in the parseURL function. That function assumes path-style URLs and fails on virtual-hosted-style URLs.
In 0.12, the outputs for a data source of terraform_remote_state are
nested under the 'outputs' attribute [1]. This updates the docs
to make this change clearer.
Worked with @radeksimko at Terraform hackday, who has submitted a
related upgrade guide [2]
[1] 1f4d2f4c50/builtin/providers/terraform/data_source_state.go (L16-L43)
[2] d8e00191b7
cgriggs01