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 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
Because of the different possibilities for arranging the nav sidebars, we want
to make sure:
- IDs for the 0.11 and 0.12 language docs have a common prefix.
- That prefix is not the exact string `docs-config`.
Have I mentioned before that I really dislike this prefix matching behavior.
This is a non-working commit, because a bunch of links (including the sidebar
nav) are broken. Using a transition commit like this makes it easier to see the
changes necessary to get this content woven into the site.
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.
This document was previously copied to the "Extending Terraform" section (in the
terraform-website repo), and the old URL was redirected so that the copy in
/guides can no longer be reached on the website. But the old copy of the file
remained, and now it runs the risk of confusing contributors, since the copy in
terraform-website/.../docs/extend is the more up-to-date version.
The AWS Go SDK automatically provides a default request retryer with exponential backoff that is invoked via setting `MaxRetries` or leaving it `nil` will default to 3. The terraform-aws-provider `config.Client()` sets `MaxRetries` to 0 unless explicitly configured above 0. Previously, we were not overriding this behavior by setting the configuration and therefore not invoking the default request retryer.
The default retryer already handles HTTP error codes above 500, including S3's InternalError response, so the extraneous handling can be removed. This will also start automatically retrying many additional cases, such as temporary networking issues or other retryable AWS service responses.
Changes:
* s3/backend: Add `max_retries` argument
* s3/backend: Enhance S3 NoSuchBucket error to include additional information
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.
* Upgrading to 2.0.0 of github.com/hashicorp/go-azure-helpers
* Support for authenticating using Azure CLI
* backend/azurerm: support for authenticating using the Azure CLI
This change enables a few related use cases:
* AWS has partitions outside Commercial, GovCloud (US), and China, which are the only endpoints automatically handled by the AWS Go SDK. DynamoDB locking and credential verification can not currently be enabled in those regions.
* Allows usage of any DynamoDB-compatible API for state locking
* Allows usage of any IAM/STS-compatible API for credential verification
* backend/azurerm: removing the `arm_` prefix from keys
* removing the deprecated fields test because the deprecation makes it fail
* authentication: support for custom resource manager endpoints
* Adding debug prefixes to the log statements
* adding acceptance tests for msi auth
* including the resource group name in the tests
* backend/azurerm: support for authenticating using a SAS Token
* resolving merge conflicts
* moving the defer to prior to the error
* backend/azurerm: support for authenticating via msi
* adding acceptance tests for msi auth
* including the resource group name in the tests
* support for using the test client via msi
* vendor updates
- updating to v21.3.0 of github.com/Azure/azure-sdk-for-go
- updating to v10.15.4 of github.com/Azure/go-autorest
- vendoring github.com/hashicorp/go-azure-helpers @ 0.1.1
* backend/azurerm: refactoring to use the new auth package
- refactoring the backend to use a shared client via the new auth package
- adding tests covering both Service Principal and Access Key auth
- support for authenticating using a proxy
- rewriting the backend documentation to include examples of both authentication types
* switching to use the build-in logging function
* documenting it's also possible to retrieve the access key from an env var
...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.
If the user uses the auto-expire value in the backend/swift settings
then swift will automatically delete their Statefile which is likely
something the user doesn't want given how Terraform works.
Since the index page is long, by the time the reader reaches the end of
it the relevant portion if the navigation is unlikely to be visible. To
compensate for this, we'll link to the first sub-section and thus give
the user an opportunity to notice the navigation structure for the rest
of the pages.
This has been replaced with an "Expressions" page.
Also includes a number of changes to Markdown style to conform to our
usual conventions, applied automatically by my editor while making these
changes.
This has now been superseded by the expressions.html.md file in the same
directory. As part of deploying this, the former URL for this page must
be redirected to the expressions page to retain a target for any
existing links on third-party sites.
This kinda-weird feature was previously quite severely under-documented in
terms of exactly what effect it has. This new documentation for it first
attempts to frame it as something that should be rarely used, and then
explains in more detail exactly how it behaves for different top-level
block types within the configuration.
As part of revamping the "Configuration" portion of the website for the
v0.12 release, here we update the Terraform Settings page to use a similar
"guide-like" writing style as the other updated pages in this section.
Previously we just listed out all of the functions in alphabetical order
inside the "Interpolation Syntax" page, but that format doesn't leave much
room for details and usage examples.
Now we give each function its own page, and categorize them for easier
navigation. While many functions are very simple and don't really warrant
a full page, certain functions do have additional details that are worth
mentioning and this structure scales better for those more complicated
functions.
So far this includes only the numeric and string functions. Other
categories will follow in subsequent commits.
This rewrite of the "Configuration Syntax" page now gives some more detail
on the top-level structural constructs and de-emphasizes the name "HCL"
as subordinate to "the Terraform language".
It also now includes some commentary on valid identifiers and comments,
and issues around character encodings and line endings.
In addition, we now have a new "Expressions" page that replaces the old
"Interpolation Syntax" page, covering the expression language features
we inherit from HCL and how they behave in the context of Terraform.
The "Expressions" page currently links to a page about the built-in
functions which does not yet exist. This will be created in a later
commit.
This adopts a more guide-like writing style, similar to what prior commits
have done to some other subsections of this section.
The data sources page has not got any real attention since the feature
was first added, and our vocabulary for describing them and their
lifecycle hadn't quite settled when the page was originally written. This
new version is consistent in how it uses "data source" to describe the
feature that providers offer and "data resource" to describe what is
created by a "data" block in configuration, which then allows us to
draw on the many shared features between both data and managed resources.
For the moment this waits until "data resource" is defined in order to
first introduce the qualifier "managed resource". We may wish to revise
this again to mention that more specific nomenclature in passing on the
"Resources" page, in case a user encounters it elsewhere and wants to
learn what it means without needing to be familiar with data resources
first.
This adopts a more guide-like writing style, similar to what prior commits
have done to some other subsections of this section.
Since we already have a whole top-level section devoted to modules, there
is no need for full coverage of all of their features here. Instead, this
section focuses on an an initial introduction to what modules are and
the basics of their usage within the Terraform language. We then link
to the main modules section for the full details.
This adopts a more guide-like writing style, similar to what prior commits
have done to some other subsections of this section.
In the process of writing this, I identified some unclear statements in
the "Resources" subsection, and so these are also revised here for
consistency with the output values documentation.
Martin Atkins