* 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.
* 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.
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`.
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
In prior versions, we recommended using hash functions in conjunction with
the file function as an idiom for detecting changes to upstream blobs
without fetching and comparing the whole blob.
That approach relied on us being able to return raw binary data from
file(...). Since Terraform strings pass through intermediate
representations that are not binary-safe (e.g. the JSON state), there was
a risk of string corruption in prior versions which we have avoided for
0.12 by requiring that file(...) be used only with UTF-8 text files.
The specific case of returning a string and immediately passing it into
another function was not actually subject to that corruption risk, since
the HIL interpreter would just pass the string through verbatim, but this
is still now forbidden as a result of the stricter handling of file(...).
To avoid breaking these use-cases, here we introduce variants of the hash
functions a with "file" prefix that take a filename for a disk file to
hash rather than hashing the given string directly. The configuration
upgrade tool also now includes a rule to detect the documented idiom and
rewrite it into a single function call for one of these new functions.
This does cause a bit of function sprawl, but that seems preferable to
introducing more complex rules for when file(...) can and cannot read
binary files, making the behavior of these various functions easier to
understand in isolation.
It's not normally necessary to make explicit type conversions in Terraform
because the language implicitly converts as necessary, but explicit
conversions are useful in a few specialized cases:
- When defining output values for a reusable module, it may be desirable
to force a "cleaner" output type than would naturally arise from a
computation, such as forcing a string containing digits into a number.
- Our 0.12upgrade mechanism will use some of these to replace use of the
undocumented, hidden type conversion functions in HIL, and force
particular type interpretations in some tricky cases.
- We've found that type conversion functions can be useful as _temporary_
workarounds for bugs in Terraform and in providers where implicit type
conversion isn't working correctly or a type constraint isn't specified
precisely enough for the automatic conversion behavior.
These all follow the same convention of being named "to" followed by a
short type name. Since we've had a long-standing convention of running all
the words together in lowercase in function names, we stick to that here
even though some of these names are quite strange, because these should
be rarely-used functions anyway.
The sethaselement, setintersection, and setunion functions are defined in
the cty stdlib. Making them available in Terraform will make it easier to
work with sets, and complement the currently-Terraform-specific setproduct
function.
In the long run setproduct should probably move into the cty stdlib too,
but since it was submitted as a Terraform function originally we'll leave
it here now for simplicity's sake and reorganize later.
In our new world it produces either a set of a tuple type or a list of a
tuple type, depending on the given argument types.
The resulting collection's element tuple type is decided by the element
types of the given collections, allowing type information to propagate
even if unknown values are present.
We missed this one on a previous pass of bringing in most of the cty
stdlib functions.
This will resolve#17625 by allowing conversion from Terraform's
conventional RFC 3339 timestamps into various other formats.
This function is similar to the template_file data source offered by the
template provider, but having it built in to the language makes it more
convenient to use, allowing templates to be rendered from files anywhere
an inline template would normally be allowed:
user_data = templatefile("${path.module}/userdata.tmpl", {
hostname = format("petserver%02d", count.index)
})
Unlike the template_file data source, this function allows values of any
type in its variables map, passing them through verbatim to the template.
Its tighter integration with Terraform also allows it to return better
error messages with source location information from the template itself.
The template_file data source was originally created to work around the
fact that HIL didn't have any support for map values at the time, and
even once map support was added it wasn't very usable. With HCL2
expressions, there's little reason left to use a data source to render
a template; the only remaining reason left to use template_file is to
render a template that is constructed dynamically during the Terraform
run, which is a very rare need.
This commit is a wide-ranging set of edits to the pages under
/docs/configuration. Among other things, it
- Separates style conventions out into their own page.
- Separates type constraints and conversion info into their own page.
- Conflates similar complex types a little more freely, since the distinction is
only relevant when restricting inputs for a reusable module or resource.
- Clarifies several concepts that confused me during edits.
...and one other reference to the application data directory.
Context:
https://docs.microsoft.com/en-us/windows/desktop/shell/knownfolderid#folderid_roamingappdata
In newer Windows versions, the folder accessible as `%APPDATA%` (and via various
APIs) is actually at something like "documents and settings\user\application
data\roaming", while earlier versions omit the "\roaming" part of the path. This
means you can confuse people by referring to the "application data" directory by
its human name, because "roaming" is the real application data directory, but it
looks like a subdirectory of "application data".
Thus, it's less confusing to just use the `%APPDATA%` variable, with the added
benefit that you can copy and paste the path and it'll just work in most places.
Kristin Laemmert