There are a few situations that we've seen arise quite commonly for folks
upgrading from Terraform 0.11 to 0.12. These particular problems are not
things that Terraform 0.12 can fix automatically during upgrading, but
we can at least give some better feedback to users that they ought to be
addressed _before_ upgrading.
The provider address problem is already detected and flagged by the
"terraform 0.11checklist" command that folks should run as part of their
upgrade process, but the module address problem is not something we
noticed was lacking validation in 0.11 and so the checklist tool doesn't
cover it. Due to the lack of coverage in the checklist tool, this commit
also includes an additional section in the upgrade guide that mentions
the problem and gives instructions on how to address it.
I've seen folks ask about how to express this in resource address syntax
a number of times now, so adding this example here to illustrate how it
looks when there are multiple levels of module to traverse through.
This is redundant with other information further up the page, but having
it as an entirely separate example gives an opportunity to include more
introductory text to explain what the example is showing.
There are some differences between the Terraform CLI and Terraform Cloud ideas of workspaces.
This documentation aims to explain those differences and show different patterns for configuring the remote backend and the implications of different approaches.
As mentioned in #17871 the current example can hide the fact that the module
path plays an important role. The example's explanation is expanded.
Moreover, the verb "attach" is replaced with "map" to make the vocabulary
consistent with the wording in the documentation of the terraform state.
A very common question since we launched the two repetition constructs
is how to deal with situations where the input data structure doesn't
match one-to-one with the desired configuration.
This adds some full worked examples of two common situations that have
come up in questions. To avoid adding a lot of extra content to the
already-large "expressions" and "resources" pages, the main bulk of this
new content lives with the relevant functions themselves as a full example
of one thing they are good for, and then we'll link to them from the two
general documentation sections where folks are likely to be reading when
they encounter the problem.
* upstream/master: (66 commits)
lang/eval: more evalContext fixups
Update CHANGELOG.md
Cleanup after v0.12.10 release
v0.12.10
website / help: reconcile 'validate' command docs
website: Document behavior of `self` object for provisioners
vendor: switch to HCL 2.0 in the HCL repository
Update communicator/ssh/communicator.go
copy client pointer for keep-alive loop
Update CHANGELOG.md
slow down tfce polling to 1s
typos. some code, some text.
Remove -check-variables flag from the docs
Merge cleanup, remove `license` parameter in favor of bool `accept_license`, adjust how license acceptance is done, update hab provisioner doc.
vendor latest go-tfe
clean up go mod for go-tfe
tfce test additions
update to go-tfe 0.3.23
cost estimation status polling
go-tfe dep update to 0.3.22
...
Previously we were using the experimental HCL 2 repository, but now we'll
shift over to the v2 import path within the main HCL repository as part of
actually releasing HCL 2.0 as stable.
This is a mechanical search/replace to the new import paths. It also
switches to the v2.0.0 release of HCL, which includes some new code that
Terraform didn't previously have but should not change any behavior that
matters for Terraform's purposes.
For the moment the experimental HCL2 repository is still an indirect
dependency via terraform-config-inspect, so it remains in our go.sum and
vendor directories for the moment. Because terraform-config-inspect uses
a much smaller subset of the HCL2 functionality, this does still manage
to prune the vendor directory a little. A subsequent release of
terraform-config-inspect should allow us to completely remove that old
repository in a future commit.
The cidrsubnets function signature is intentionally very low-level and
focused on the core requirement of generating addresses. This registry
module then wraps it with some additional functionality to make it more
convenient to generate and use subnet address ranges.
This is a companion to cidrsubnet that allows bulk-allocation of multiple
subnet addresses at once, with automatic numbering.
Unlike cidrsubnet, cidrsubnets allows each of the allocations to have a
different prefix length, and will pack the networks consecutively into the
given address space. cidrsubnets can potentially create more complicated
addressing schemes than cidrsubnet alone can, because it's able to take
into account the full set of requested prefix lengths rather than just
one at a time.
* command/import: properly use `-provider` supplied on the command line
The import command now attaches the provider configuration in the resource
instance, if set. That config is attached to the NodeAbstractResource
during the import graph building. This prevents errors when the implied
provider is not actually in the configuration at all, which may happen
when a configuration is using the `-beta` version of a provider (and
only that `-beta` version).
* command/import: fix variable reassignment and update docs
Fixes#22564
For a long time now we've been advising against the use of provisioners,
but our documentation for them is pretty prominent on the website in
comparision to the better alternatives, and so it's little surprise that
many users end up making significant use of them.
Although in the longer term a change to our information architecture would
probably address this even better, this is an attempt to be explicit about
the downsides of using provisioners and to prominently describe the
alternatives that are available for common use-cases, along with some
reasons why we consider them to be better.
I took the unusual step here of directly linking to specific provider
documentation pages about the alternatives, even though we normally try
to keep the core documentation provider-agnostic, because otherwise that
information tends to be rather buried in the provider documentation and
thus the reader would be reasonable to use provisioners just because we're
not giving specific enough alternative recommendations.
* website/formatdate: update example
The given example was showing HOUR:MONTH instead of HOUR:MINUTE
Fixes#22598
* website/import: remove reference to no-longer-working option
Users can no longer supply `-config=""` to tell Terraform not to load
configuration for import.
Fixes#22294
* website/provisioners: `host` is required in connection blocks
Fixes#21877
* website/variables: clarify variable definition precedence
It was not entirely obvious that a variable could not be assigned
multiples times in a single source.
Fixes#21682
* website/backend/local: add `workspace_dir` attribute
Fixes#21391
* website/output: `sensitive` outputs are redacted in output
Fixes#21502
* website/backends: sidebar order tweak
It makes sense for backend 'configuration' to appear before 'init'.
Fixes#13796
* Revert "website/formatdate: update example"
This reverts commit ccd93c86ddd15a21625c0767702ee1cc62e77254.
Reference: https://github.com/hashicorp/terraform/issues/16697
Enumerates a set of regular file names from a given glob pattern. Implemented via the Go stdlib `path/filepath.Glob()` functionality. Notably, stdlib does not support `**` or `{}` extended patterns. See also: https://github.com/golang/go/issues/11862
To support the extended glob patterns, it will require adding a dependency on a third party library or adding our own matching code.
The Terraform Enterprise brand has now been split into two parts:
- Terraform Cloud is the application that helps teams use Terraform together,
with remote state storage, a shared run environment, etc.
- Terraform Enterprise is the on-premise distribution that lets enterprises run
a private instance of the Terraform Cloud application.
The former TFE docs have been split accordingly.
- Make these descriptions more similar, since they do basically the same thing.
- Add some subheaders to break up the wall of text and make it more skimmable.
- Nudge people more firmly toward `for_each` if they need to actually
incorporate data from a variable into their instances.
- Add version note so you know whether you can use this yet.
These existing upstream cty functions allow matching strings against
regular expression patterns, which can be useful if you need to consume
a non-standard string format that Terraform doesn't (and can't) have a
built-in function for.
We added the csvdecode function originally with the intent of it being
used with for_each, but because csvdecode was released first we had a
section in its documentation warning about the downsides of using it with
"count", since that seemed like something people would be likely to try.
With resource "for_each" now merged, we can replace that scary section
with a more positive example of using these two features together.
We still include a paragraph noting that "count" _could_ be used here, but
with a caution against doing so. This is in the hope of helping users
understand the difference between these two patterns and why for_each is
the superior choice for most situations.
Ran into an issue requiring `-var='foo=bar'` over `-var 'foo=bar'`.
Without the `=` the generic response came back:
```
Usage: terraform plan [options] [DIR]
Generates an execution plan for Terraform.
This execution plan can be reviewed...
```
Terraform `0.12.2`
Team tokens never worked with the `atlas` backend, but the `remote` backend
uses them as intended; they can perform plans and applies on workspaces where
the associated team has at least plan or write permissions, respectively.
The search "terraform leading zero" does not find the `format()`
function, which is perfectly capable of adding leading zeros.
Thus I have added this one word to help people find `format()`.
The correct environment variable corresponding to the `ca_file` variable is `CONSUL_CACERT` and not `CONSUL_CAFILE`.
See `backend/remote-state/consul/backend.go` line 77.
This also includes a previously-missing test that verifies the behavior
described here, implemented as a planning context test for consistency
with how the other ignore_changes tests are handled.
* Correct fmt -check
With `-check=false` the exit status is always zero.
With `-check=true` the exit status is zero when all files are properly formatted and non-zero otherwise.
* update fmt documentation to use short form for -diff and -check
We previously had some notes about handling configuration variants just
tacked on to the "dependency inversion" section as an afterthought, but
this idea is a major use-case for dependency inversion so it deserves its
own section and a specific example.
There have been a few questions about this so far which indicated that the
previous docs for this feature were very lacking. This is an attempt to
describe more completely what "any" means, and in particular that it isn't
actually a type at all but rather a placeholder for a type to be selected
dynamically.
Based on some common questions and feedback since the v0.12.0 release,
here we add some small additional content to the documentation for
"dynamic" blocks, covering how to access the keys of the collection being
iterated over and how to fold multiple collections into a single one to
achieve the effect of a nested iteration.
These follow the same principle as jsondecode and jsonencode, but use
YAML instead of JSON.
YAML has a much more complex information model than JSON, so we can only
support a subset of it during decoding, but hopefully the subset supported
here is a useful one.
Because there are many different ways to _generate_ YAML, the yamlencode
function is forced to make some decisions, and those decisions are likely
to affect compatibility with other real-world YAML parsers. Although the
format here is intended to be generic and compatible, we may find that
there are problems with it that'll we'll want to adjust for in a future
release, so yamlencode is therefore marked as experimental for now until
the underlying library is ready to commit to ongoing byte-for-byte
compatibility in serialization.
The main use-case here is met by yamldecode, which will allow reading in
files written in YAML format by humans for use in Terraform modules, in
situations where a higher-level input format than direct Terraform
language declarations is helpful.
This is similar to the function of the same name in Python, generating a
sequence of numbers as a list that can then be used in other
sequence-oriented operations.
The primary use-case for it is to turn a count expressed as a number into
a list of that length, which can then be iterated over or passed to a
collection function to produce that number of something else, as shown
in the example at the end of its documentation page.
Using az login and then terraform init from the command line I got `Error: Either an Access Key / SAS Token or the Resource Group for the Storage Account must be specified`
A longer-form guide will follow in the Sentinel section of the Terraform
Enterprise documentation, once it's ready. For now, this section isn't
saying anything useful since it was always just a stub for a guide we
planned to write later.
The upgrade tool is assuming that a type of "list" means list(string) and
a type of "map" means map(string), because that was what we documented
those as meaning.
In practice, Terraform 0.11 was lacking some validation which allowed
more complex nested structures in some cases even though they were pretty
inconvenient to use due to other language limitations.
The upgrade tool doesn't have enough context to make a reliable decision
on this, so instead we'll rely on the upgrade guide for this. We don't
need a TF-UPGRADE-TODO comment in this case because we reserve those for
things where a subsequent operation might cause the configuration to be
misinterpred, rather than just causing an error. Instead, we'll show an
example of the comment in the upgrade guide so the reader can easily
match it, and give some advice in the guide on how to address it.
We've seen in the past that some users try to use this form with the
ssh:// URL prefix, so we'll mention explicitly that this is invalid and
show a working example of how to use it without the URL scheme prefix.
Our original upgrade guide was drafted while some things were still in
flux and not all of our upgrade tooling was in place yet.
This redraft now attempts to be more specific and direct, showing exact
commands to run and (where relevant) exact error messages that Terraform
might return.
I also took this opportunity for some general copy-editing, though we'll
probably want to do one more pass of that alone (without changing any
content at the same time) before final release.
This new content presumes the existence of a Terraform v0.11.14 release,
which isn't published yet at the time of writing but should be published
before v0.12.0 final, once we've done final verification and review of
the upgrade path including it.
- Note that we intentionally omitted it from the sidebar, to reduce confusion.
- Write a summary up top so you can stop reading sooner if you don't actually need this.
* 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
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.
In the heirarchy, both "Terraform Language" and "Functions" are "up" from
the individual function reference pages, so we'll class them as such to
use the back-facing arrow instead of the forward-facing arrow.
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.
These revisions reflect this sub-section's new earlier placement in the
sub-section list, leading to a more guide-like style for the initial
sections.
Also includes some minor copy-editing to align terminology with that
introduced in the prior commit for the "Resources" docs page.
This is now the leading subsection of the Configuration section of the
docs, and so this rewrite intends to make it more "guide-like" and as
accessible as possible to those who are not yet familiar with other
Terraform concepts.
This rewrite also attempts to introduce some consistency into our
vocabulary, which should eventually be reflected throughout our
documentation. In particular:
- "Resource" refers to the block the user writes in configuration, while
"Resource _Type_" refers to what the provider defines. We previously
used "resource" for both of these interchangeably.
- "Resource" is no longer used to refer to what gets created and managed
in remote APIs as a result of a resource block in configuration. Lacking
a good distinct name for these, this guide uses the word "object",
qualifying it as "infrastructure object" or "remote object" where
necessary to retain clarity. This distinction is important to enable
a clear description of resource lifecycle.
- "Argument" refers to an element (attribute or block) within a resource
block. This terminology was already being used in some places, so we
embrace it here as a way to distinguish from "attribute", which is
what a resource _exports_ for use in expressions.
- Since interpolation is no longer needed to use expressions in the
language, the word "expression" is used to describe the definition of
a value that might involve some computation. Where necessary, this is
used with a modifier "arbitrary expression" to contrast with situations
where the set of allowed expression constructs is constrained.
The prior content on this page was little more than an instruction to
begin navigating the sub-sections of this section.
The new content aims to give a broad overview of some of the language
concepts and a syntax example, in order to create some context to help
the user navigate the subsections more easily.
This also introduces for the first time usage of the term "the Terraform
language". This was previously left un-named, leading to some awkward
sentence constructions elsewhere in the docs. This new name gives us
some specific terminology to use in order to contrast the language that
exists at Terraform's level of abstraction, defining the semantics, from
the underlying grammar provided by HCL.
With the additional configuration language features coming in Terraform
v0.12, our existing documentation structure is beginning to strain.
Here we reorganize the navigation slightly in order to introduce the
concepts in a more appropriate order so that we can reveal complexity
more gradually. Subsequent commits will revise the content of these
pages to better reflect the new sequencing.
The "Environment Variables" page is moved from the Configuration section
into the "Commands" section, since it is not considered a part of the
configuration language and thus more appropriate in the CLI documentation.
The old placement is reflective of the broader purpose that the
"Configuration" section had originally, but its new focus will be on
the Terraform language (.tf files) in particular, with other aspects of
customizing Terraforms behavior covered in other sections.
website: Reconcile docs about plugin discovery and downloading
I'm attempting to keep things simple for normal users while making sure we've
got the full behavior written down somewhere for plugin developers.
This commit doesn't stand alone; it's paired with a commit in the
terraform-website repo, to deal with some related content in the "extend"
section.
It's been a while since we made any significant updates to this page.
The main theme of this revamp is to ensure that we highlight how to
provide "ambient credentials" for each of the module sources using the
standard mechanisms for each source type.
While there, I also attempted a general cleanup to highlight the main
cases and make this less like a detailed description of all of
go-getter's esoteric features, and did some general copy-editing to write
it in our usual documentation "voice".
Based on some feedback on the initial draft, make some minor updates to
how information is presented in the preview upgrade guide for v0.12.
This also includes some minor copy-editing work to try to make the "voice"
more consistent between different sections of the guide.
After some discussion with "iamakulov" on Twitter it seems that the use
of the word "conflicts" and "merge conflicts" here was sounding like us
implicitly condoning the use of version control as a mechanism for
distributing local state files, which hasn't been recommended for quite
some time since remote state now provides a much more robust solution.
While here, I also tweaked some other language on this page for style and
for use of terminology we more commonly use in our more recent
documentation.
Following the examples as they were previously would cause errors
accessing demo.consul.io. Now we consistently set the scheme to https for
all examples that use demo.consul.io.
This also includes some other updates to the URLs, since the Consul demo
has been rebuilt with a different based configuration, and some general
formatting and copyediting changes in the Consul example.
Create-before-destroy dependencies are automatically ordered correctly
by terraform. Remove the old notice about requiring all dependencies to
have the same setting for create_before_destroy.
In an earlier commit we added the "Best Practices" situation to try to
clarify the intended uses of named workspaces and to warn against using
them as an alternative to system decomposition.
However, the prior statement was cautious in its recommendations in the
interests of being pragmatic, and as a result we've seen that users have
in some cases misunderstood or disregarded these recommendations.
The new "When to use Multiple Workspaces" section aims to be more explicit
that having multiple separate Terraform configurations is the preferred
solution for many use-cases, and that workspaces are intended for a
more limited set of use-cases around convenient development and testing.
It also emphasizes the analogy to version control branches that was just
a footnote in the prior text, to help the reader become familiar with the
concept by relating it to a concept and workflow they are hopefully
already familiar with.
This new section also attempts to provide a more elaborate description of
the proposed alternative when the goal is system decomposition. In the
long run some of this content would probably be better placed elsewhere
since it is useful advice even for users who never discover named
workspaces, but it can live here for the time being to limit the scope of
this change until we are ready to make more comprehensive revisions to
the docs in this area.
Finally, the introductory documentation here is adjusted slightly in
preparation for the intended future expansion of workspaces to include
stored variable values and, for more tailored backends like Terraform
Enterprise, a full log of prior operations. More revisions will be
required to cover the specifics of this later, but this new framing will
hopefully help users form a mental model of named workspaces that has
room for these future enhancements and the corresponding concept in
Terraform Enterprise, rather than our previous framing that workspaces
are fundamentally just named states.
Also:
- In the getting started guide, the TFE content was all tailored to the older
run-locally workflow. I've replaced it with some brief explanation and a link
to the dedicated TFE getting started guide.
- Fixed a sidebar link glitch in the configuration section. (Both "Terraform"
and "Terraform Enterprise" were marked as active if you were on the TFE page.)
- Renamed the "Terraform Enterprise" page "Terraform Push." (Some people have
gotten confused and landed on this page when trying to set up the `atlas`
remote backend.)
provisioner. Also fixes an issue where channels and URLs are
not honored in the initial package install.
Signed-off-by: Rob Campbell <rcampbell@chef.io>
This new argument allows overriding of the working directory of the child process, with the default still being the working directory of Terraform itself.
This change allows the Habitat supervisor service name to be
configurable. Currently it is hard coded to `hab-supervisor`.
Signed-off-by: Nolan Davidson <ndavidson@chef.io>
Since an early version of Terraform, the `destroy` command has always
had the `-force` flag to allow an auto approval of the interactive
prompt. 0.11 introduced `-auto-approve` as default to `false` when using
the `apply` command.
The `-auto-approve` flag was introduced to reduce ambiguity of it's
function, but the `-force` flag was never updated for a destroy.
People often use wrappers when automating commands in Terraform, and the
inconsistency between `apply` and `destroy` means that additional logic
must be added to the wrappers to do similar functions. Both commands are
more or less able to run with similar syntax, and also heavily share
their code.
This commit updates the command in `destroy` to use the `-auto-approve` flag
making working with the Terraform CLI a more consistent experience.
We leave in `-force` in `destroy` for the time-being and flag it as
deprecated to ensure a safe switchover period.
When writing an example for a submodule, the example should be placed in
`examples/{example name}` instead of
`modules/{module name}/examples/{example name}`.
We have outgrown the single flat list presentation of providers due to the shear number now present, so we'll move here to a model where the providers are split into a number of categories that each contain a smaller list.
The full list is still included in the body of the main index page for quick access via search, but the categories make for a more accessible navbar for those who are just browsing.
Triton Manta allows an account other than the main triton account to be used via RBAC.
Here we expose the SDC_USER / TRITON_USER options to the backend so that a user can be specified.
Our prevailing writing style is to place punctuation outside of quotes, since in many contexts Terraform itself treats punctuation within quotes as significant and so it can be confusing to use punctuation in quotes in our prose.
* add catagory files
* try new source path
* cleaning up formatting
* fixin
* add all providers to providers index page
* add descriptions
* add link to form and first two providers
* small edits
* small edits
* small changes
* add community providers and decription edit from marketing
* add some lines to improve design
* fix typos
First successful run with private origin and HAB_AUTH_TOKEN set
Update struct, schema, and decodeConfig names to more sensible versions
Cleaned up formatting
Update habitat provisioner docs
Remove unused unitstring
Users commonly ask how the S3 backend can be used in an organization that
splits its infrastructure across many AWS accounts.
We've traditionally shied away from making specific recommendations here
because we can't possibly anticipate the different standards and
regulations that constrain each user. This new section attempts to
describe one possible approach that works well with Terraform's workflow,
with the goal that users make adjustments to it taking into account their
unique needs.
Since we are intentionally not being prescriptive here -- instead
considering this just one of many approaches -- it deviates from our usual
active writing style in several places to avoid giving the impression that
these are instructions to be followed exactly, which in some cases
requires the use of passive voice even though that is contrary to our
documentation style guide. For similar reasons, this section is also
light on specific code examples, since we do not wish to encourage users
to just copy-paste the examples without thinking through the consequences.
* Verify discovery works without trailing slash on discovery URL
* Update registry API docs with browse and search endpoints
* Add sample request/responses
* Add comment to test to indicate expecations
* Fix typo
* Remove trailing slash weirdness
It's important to match the version of local Terraform with the remote Terraform version in Terraform Enterprise when using the "terraform push" command, or else the uploaded configuration package may not be compatible.
This is a genre of invalid output expression that we've seen quite
commonly while testing with 0.11.0-rc1, so we'll call it out specifically
in the upgrade guide and suggest how to fix it.
The differences between the implicit and explicit modes of passing
provider configurations between modules are significant enough to warrant
giving these approaches different names and describing them separately.
This also includes documentation of the current limitation discussed in
#16612, where explicit passing requires a proxy configuration block even
for a _default_ provider configuration, because that limitation is being
accepted for the 0.11.0 release to limit scope.
We are recommending that as of 0.11 all provider configurations be placed
in the root module and, where necessary, be explicitly passed down via
a providers map to customize which configurations are seen by each
child module.
This new section attempts to guide users through such refactoring in the
common case where a child module defines its own provider configuration
based on a value passed in an input variable, and then uses that as
some context to link to the more detailed docs to help those who have
more complex configurations.
The initial pass of this section had some remaining ambiguities, so this
is a second revision that attempts to use terminology more consistently
and to not some additional behaviors that were not described in the
initial version.
We've historically been somewhat inconsistent in how we refer to the
type of object defined by "variable" blocks in configuration. Parts of
our documentation refer to them as "input variables" or just "variables",
while our implementation refers to them as "user variables".
Since Terraform Registry is now also referring to these as "Inputs", here
we standardize on "Input Variable" as the fully-qualified name for this
concept, with "variable" being a shorthand for this where context is
obvious. Outside of this context, anything that can be referred to in
an interpolation expression is generically known as a "variable", with
Input Variables being just one kind, specified by the "var." prefix.
While this terminology shift is not critical yet, it will become more
important as we start to document the new version of the configuration
language so we can use the generic meaning of "variable" there.
The bulk of the text on this page hasn't been revised for some time and
so parts of it were using non-idiomatic terminology or not defining terms
at all.
The main goal of this revision is to standardize on the following terms:
- "provider configuration" refers to a specific provider block in config,
as a distinct idea from the provider _itself_, which is a singleton.
- "Default" vs. "additional" provider configurations, distinguishing
those without and with "alias" arguments respectively. These are named
here so that we can use this terminology to describe the different
behaviors of each for the purposes of provider inheritance between
modules.
The "terraform" provider was previously split out into its own repository,
but that turned out to be a mistake due to how tightly it depends on
aspects of Terraform Core.
Here we prepare to bring it back into the core repository by reorganizing
the directory layout to conform with what's expected there.
This allows the user to customize the location where Terraform stores
the files normally placed in the ".terraform" subdirectory, if e.g. the
current working directory is not writable.
This is a significant rework of the Modules getting started guide to be
in terms of the Consul module available via the Terraform Registry. This
allows us to introduce the registry as part of the tutorial, and also
gives us some auto-generated documentation to link to as context for
the tutorial.
This new module is designed pretty differently than the one we formerly
used, and in particular it doesn't expose any server addresses for the
created Consul cluster -- due to using an auto-scaling group -- and thus
we're forced to use the (arguably-less-compelling) auto-scaling group name
for our output example.
Now includes more complete information on usage of private registries and
updates the module registry API documentation to include the new
version-enumeration endpoint along with describing Terraform's discovery
protocol.
The modules mechanism has changed quite a bit for version 0.11 and so
although simple usage remains broadly compatible there are some
significant changes in the behavior of more complex modules.
Since large parts of this were rewritten anyway, I also took the
opportunity to do some copy-editing to make the prose on this page more
consistent with our usual editorial voice and to wrap the long
lines.
In the 0.10 release we added an opt-in mode where Terraform would prompt
interactively for confirmation during apply. We made this opt-in to give
those who wrap Terraform in automation some time to update their scripts
to explicitly opt out of this behavior where appropriate.
Here we switch the default so that a "terraform apply" with no arguments
will -- if it computes a non-empty diff -- display the diff and wait for
the user to type "yes" in similar vein to the "terraform destroy" command.
This makes the commonly-used "terraform apply" a safe workflow for
interactive use, so "terraform plan" is now mainly for use in automation
where a separate planning step is used. The apply command remains
non-interactive when given an explicit plan file.
The previous behavior -- though not recommended -- can be obtained by
explicitly setting the -auto-approve option on the apply command line,
and indeed that is how all of the tests are updated here so that they can
continue to run non-interactively.
This PR changes manta from being a legacy remote state client to a new backend type. This also includes creating a simple lock within manta
This PR also unifies the way the triton client is configured (the schema) and also uses the same env vars to set the backend up
It is important to note that if the remote state path does not exist, then the backend will create that path. This means the user doesn't need to fall into a chicken and egg situation of creating the directory in advance before interacting with it
This resurrects the previously documented but unused "project" option.
This option is required to create buckets (so they are associated with the
right cloud project) but not to access the buckets later on (because their
names are globally unique).
* Remove the (unused) "project" option.
* Mark the "credentials" option as optional; document behavior when
unset.
* Mark the "path" option as deprecated (was: legacy) to match
Terraform's terminology.
Since we don't currently auto-install provisioner plugins this is
currently placed on the providers documentation page and referred to as
the "Provider Plugin Cache". In future this mechanism may also apply to
provisioners, in which case we'll figure out at that point where better
to place this information so it can be referenced from both the provider
and provisioner documentation pages.
This mechanism for configuring plugins is now deprecated, since it's not
capable of declaring plugin versions. Instead, we recommend just placing
plugins into a particular directory, which is now documented on the
main providers documentation page and linked from the more detailed docs
on plugins in general.
Previously we described inline here where to put the .terraformrc file,
but now we have a separate page all about this file that gives us more
room to describe in more detail where the file is placed and what else it
can do.
This function takes a map of lists of strings and inverts it so that
the string values become keys and the keys become items within the
corresponding lists.
In #15884 we adjusted the plan output to give an explicit command to run
to apply a plan, whereas before this command was just alluded to in the
prose.
Since releasing that, we've got good feedback that it's confusing to
include such instructions when Terraform is running in a workflow
automation tool, because such tools usually abstract away exactly what
commands are run and require users to take different actions to
proceed through the workflow.
To accommodate such environments while retaining helpful messages for
normal CLI usage, here we introduce a new environment variable
TF_IN_AUTOMATION which, when set to a non-empty value, is a hint to
Terraform that it isn't being run in an interactive command shell and
it should thus tone down the "next steps" messaging.
The documentation for this setting is included as part of the "...in
automation" guide since it's not generally useful in other cases. We also
intentionally disclaim comprehensive support for this since we want to
avoid creating an extreme number of "if running in automation..."
codepaths that would increase the testing matrix and hurt maintainability.
The focus is specifically on the output of the three commands we give in
the automation guide, which at present means the following two situations:
* "terraform init" does not include the final paragraphs that suggest
running "terraform plan" and tell you in what situations you might need
to re-run "terraform init".
* "terraform plan" does not include the final paragraphs that either
warn about not specifying "-out=..." or instruct to run
"terraform apply" with the generated plan file.
Previously we just assumed the reader was familiar with the idea of a
graph but didn't explain it.
Since graphs are an implementation detail of Terraform, rather than
essential information needed for new users, this revises the introduction
text to talk only about _dependencies_, which we assume the user is
familiar with as a more practical concept.
Additionally, Paul Hinze did a great talk on how Terraform uses graphs
at HashiConf 2016 which is good additional content for our existing
"Graph Internals" page, which includes a concise explanation of the
basics of graph theory.
In #15870 we got good feedback that it'd be more useful to have the
various filename-accepting arguments on this provisioner instead accept
strings that represent the contents of such files, so that they can be
generated from elsewhere in the Terraform config.
This change does not achieve that, but it does make room for doing this
later by renaming "minion_config" to "minion_config_file" so that we
can later add a "minion_config" option alongside that takes the file
content, and deprecate "minion_config_file".
Ideally we'd just implement the requested change immediately, but
unfortunately the release schedule doesn't have time for this so this is
a pragmatic change to allow us to make the full requested change at a
later date without backward incompatibilities.
This change is safe because the salt-masterless provisioner has not yet
been included in a release at the time of this commit.
Previously the -upgrade option was covered only on the "terraform init" usage page. It seems also worth mentioning in the main docs on provider versioning, since we're already explaining here other mechanics of the versioning/constraints system.
Terraform modules encapsulate their resources, and dependencies can only
be expressed through outputs, which wasn't clear to me in the existing
documentation. I'm hoping a small change will make that more explicit.
This escapes all characters that might have a special interpretation when embedded into a portion of a URL, including slashes, equals signs and ampersands.
Since Terraform's internals are not 8-bit clean (it assumes UTF-8
strings), we can't implement raw gzip directly. We're going to add
support where it makes sense for passing data to attributes as
base64 so that the result of this function can be used.
* update plugin/provider to make clear this section isn't needed for regular use
* add some links and notes about getting started
* remove the mention of binaries... I 'm not sure it's needed yet
* 'Installing Terraform Providers' section
* sometimes I can't words good
* move the 'installing providers' block
* cleanup of terms
* copy that update to plugins/provider too
The backend has been renamed. Using the old name in the config will
trigger a deprecation warning, but the implementation and the
documentation is the same.
Added locking support via blob leasing (requires that an empty state is
created before any lock can be acquired.
Added support for "environments" in much the same way as the S3 backend.
Fix the -state and -state-out wording to be consistent with other
commands. Remove the erroneous reference to remote state in the website
version of the flag description.
The docs did not mention that it is possible to provide overrides for specific
plugins by placing them into a `terraform.d/plugins/os_arch/` directory inside
the working dir.
Closes#15727.
This restores the earlier behavior of the first positional argument to
terraform init in 0.9, but as a command line option.
The positional argument was removed to improve consistency with other
commands that take a working directory as their first positional argument.
It was originally intended that this functionality would return in a
later release along with some other general improvements to Terraform's
module handling, but we're introducing here an interim solution that
uses the existing module source concept, to allow for easier porting of
workflows that previously depended on the automatic copy behavior.
In a future release this feature may change again as the module
improvements design firms up, but we expect it to be broadly compatible
with this temporary state.
The "terraform init" command has a lot of different functionality now,
making it hard to follow all of the options in the previous presentation.
Instead, here we describe each of the steps and its associated options
separately, hopefully making it easier to understand what each option
relates to.
In addition, much of the detail around backend partial configuration is
factored out into the backend configuration page, where it seems more
"at home"; previously it felt hard to follow exactly how partial
configuration would be used, due to the information on it being split over
two different pages.
This is documented for all other Hashicorp products using this service but
was missed for Terraform. This serves as a disclosure of the fact that
Terraform reaches out to a Hashicorp service, an explanation of the
purpose of that request, and instructions on how to disable it in
environments where it is inappropriate or cannot be supported due to a
firewall or other connectivity restrictions.
Based on feedback from #15569 that the previous example was too abstract
and did not give enough context about what each of the different arguments
mean and how they generalize to other resource types.
The intent here is just to introduce some initial docs on our recommended
way to develop plugins in the same GOPATH as Terraform itself. The
documentation in this area needs some more fundamental rework as it is
rather outdated and mis-organized, but that's outside the scope of what
this change is trying to achieve.
This changed close to the release of beta1 to use underscores as the
separator and to use a lower-case "v" to avoid any issues on
case-insensitive filesystems.
A common reason to want to use `terraform plan` is to have a chance to
review and confirm a plan before running it. If in fact that is the
only reason you are running plan, this new `terraform apply -auto-approve=false`
flag provides an easier alternative to
P=$(mktemp -t plan)
terraform refresh
terraform plan -refresh=false -out=$P
terraform apply $P
rm $P
The flag defaults to true for now, but in a future version of Terraform it will
default to false.
Error loading Terraform: Error downloading modules: error downloading 'ssh://git@bitbucket.org/acme/foo.git?bar': /usr/bin/git exited with 128: Cloning into '.terraform/modules/yadayada'...
invalid command syntax.
fatal: Could not read from remote repository.
Please make sure you have the correct access rights
and the repository exists.
This guide covers assorted best practices and caveats for running
Terraform within orchestration tools and other automation. It provides
general examples and guidance, with the intent that this advice can be
adapted by the reader to a concrete implementation within a selected
orchestration tool.
This guide is based both on our in-house experience with Terraform
Enterprise and on in-house solutions we are aware of in certain
organizations.
Previously the behavior for -target when given a module address was to
target only resources directly within that module, ignoring any resources
defined in child modules.
This behavior turned out to be counter-intuitive, since users expected
the -target address to be interpreted hierarchically.
We'll now use the new "Contains" function for addresses, which provides
a hierarchical "containment" concept that is more consistent with user
expectations. In particular, it allows module.foo to match
module.foo.module.bar.aws_instance.baz, where before that would not have
been true.
Since Contains isn't commutative (unlike Equals) this requires some
special handling for targeting specific indices. When given an argument
like -target=aws_instance.foo[0], the initial graph construction (for
both plan and refresh) is for the resource nodes from configuration, which
have not yet been expanded to separate indexed instances. Thus we need
to do the first pass of TargetsTransformer in mode where indices are
ignored, with the work then completed by the DynamicExpand method which
re-applies the TargetsTransformer in index-sensitive mode.
This is a breaking change for anyone depending on the previous behavior
of -target, since it will now select more resources than before. There is
no way provided to obtain the previous behavior. Eventually we may support
negative targeting, which could then combine with positive targets to
regain the previous behavior as an explicit choice.
We are replacing this terminology. The old command continues to work for
compatibility, but is deprecated. The docs should reflect the
currently-recommended form.
We are moving away from using the term "environment" to describe separate
named states for a single config, using "workspace" instead. The old
attribute name remains supported for backward compatibility, but is
marked as deprecated.
"environment" is a very overloaded term, so here we prefer to use the
term "working directory" to talk about a local directory where operations
are executed on a given Terraform configuration.
This form of "terraform init" is vestigial at this point and being phased
out in 0.10. Something similar may return in a later version for
installing modules from a more formal module library, but for now we are
advising to use git manually to simplify the UX for "terraform init".
Previously we encouraged users to import a resource and _then_ write the
configuration block for it. This ordering creates lots of risk, since
for various reasons users can end up subsequently running Terraform
without any configuration in place, which then causes Terraform to want
to destroy the resource that was imported.
Now we invert this and require a minimal configuration block be written
first. This helps ensure that the user ends up with a correlated resource
config and state, protecting against any inconsistency caused by typos.
This addresses #11835.
This will be fleshed out later as part of more holistic documentation for
the new provider plugin separation, but this is some minimal documentation
for just this subcommand.
* Data Source support for Resource Group
* Better message for mismatching locations.
* Reuse existing read code
* Adds documentation
* Adds test
* Adds a function for composing ID strings
* Change location to computed.
* Move to v2 client in vendor directory
* Move to v2 api and project IDs for environments
* add host label support to registration command
* Update go-rancher/catalog
* Allow go-rancher to handle URL versioning
This is a separate resource that serves a similar purpose to the
propagating_vgws argument on aws_route_table, but allows route
propagations to be created independently of the route table, which in
turn allows the VPN gateway to be created after the route table it will
contribute to, possibly in a separate Terraform module.
To make this work, propagating_vgws on aws_route_table is now marked
as Computed, meaning that it won't try to delete any existing propagation
edges if there is no setting for it in configuration at all. This allows
the user to choose whether to use the argument or the separate resource,
though using both together will not work, as explained in the docs.
* Update overview/API links for storage_bucket_objects, and acls for both buckets and objects.
* Minor formatting changes to google_storage_bucket and acl docs.
* Updated outdated custom ACL information and fixed grammar.
* Added support for public IP data source. Tested manually.
* WIP: Update to implementation, basic test added.
* WIP: Updates to implementation, basic test added.
* WIP: Added support for idle timeout
* Completed implementation and basic test
* Added documentation.
* Updated the example so it makes a little more sense.
* Add task_parameters support to aws_ssm_maintenance_window_task
task_parameters weren't supported yet. This adds support for them. It
also corrects a documentation typo in the maintenance_window resource.
* Respond to internal feedback
* New SSM Parameter resource
Can be used for creating parameters in AWS' SSM Parameter Store that can then be used by other applications that have access to AWS and necessary IAM permissions.
* Add docs for new SSM Parameter resource
* Code Review and Bug Hunt and KMS Key
- Addressed all issues in #14043
- Added ForceNew directive to type
- Added the ability to specify a KMS key for encryption and decryption
* Add SSM Parameter Data Source
* Fix bad merge
* Fix SSM Parameter Integration Tests
* docs/aws: Fix typo in SSM sidebar link
* Make os_profile optional #11147
* Test for optional os_profile and fix resourceArmVirtualMachineRead
* Updating to match other optionally-required fields
Datadog does not explicitly document which graph types are available, but when you use the GUI to generate the graph and select the JSON tab to inspect said graph, you will see that the available timeboard graph type names are singular, not plural.
* provider/aws: Update Lightsail supported regions
This commit complements (#14621)[https://github.com/hashicorp/terraform/pull/14621] and (#14685)[https://github.com/hashicorp/terraform/pull/14685].
* Revert "provider/aws: Update Lightsail supported regions"
This reverts commit 545c3d6e6e7a9b665542ecc3b5e4d857faac749b.
* This commit complements #14621 and #14685.
* Link to AWS docs instead of listing regions
Instead of explicitly listing supported Lightsail regions in the docs,
we now link to the Lightsail docs.
* Updating the Sku field to be optional
* Making the Sku optional
* Ensuring we check for a 404 to mark a successful deletion
* Upping the size of the internal data disk
* Randomizing the Local Network Gateway tests
* Fixing a bug in Local Network Gateway's where the deletion wouldn't be detected
This fixes the missing `id` attribute on the documentation. The attribute exists if called via `"${aws_elastic_beanstalk_environment.myapp-environment.id}"`, but is just not documented.
Should not be cherry-picked to the `stable-website` branch. The next Terraform deploy will include the latest changes to the OPC provider, and this updated documentation for the next point release.
* vendor: Add gophercloud/routerinsertion package and update
gophercloud/firewall to support router insertion
* provider/openstack: Add support for associating
`openstack_fw_firewall_v1` resources with router(s).
Added `associated_routers` and `no_routers` arguments.
* website: Add documentation for `associated_routers`and `no_routers` arguments on `openstack_fw_firewall_v1` resource.
* provider/openstack: Add `AddValueSpecs` function and refactor existing
uses.
* fix gitlab naming
seems like some github stuff was not renamed
* gitlab is using group or user instead of organisations
* add namespace_id to gitlab_project documentation
* it's not possible to manage group members
* Fix doc bug. Spell `collation` like `lc_collate`.
* Whitespace nit in error message
* Use %q as the format verb for error messages in postgresql_database resource messages.
* REVOKE the `GRANT` given to the connection user when creating a database.
For `ROLE`s who have been delegated `CREATEDB` privileges and are not a
superuser, in order for them to `CREATE DATABASE` they need to be a member
of the `ROLE` who will be `OWNER` for the new database. Once the
`CREATE DATABASE` is complete, `REVOKE` the `GRANT` that was given to role
so that the user who ran the `CREATE DATABASE` looses all privileges to the
target database (unless of course they're a superuser).
Fixes a regression introduced in #11452
* Delegated DBA ROLEs can now fix OWNER drift for PostgreSQL databases.
Uses the helper functions introduced in #11452
* provider/aws: Add data source for aws_elasticache_cluster
Fixes: #11445
* provider/aws: Add acceptance tests for aws_elasticache_cluster data source
* provider/aws: Add documentation for the aws_elasticache_cluster datasource
Add dynamodb_table and deprecation notice on lock_table. Add missing
parameters for the S3 backends: assume_role_policy, external_id,
and session_name.
* provider:openstack Add support provider network
* revert vendor file changes
* vendor: Updating Gophercloud for OpenStack Provider
* create provider network if parameter has segments
* segments is not computed resource
* extract to generate []provider.Segment
* change segmentstion id type
* provider/gitlab: Fix documentation copypasta
The original provider and docs were copied from the github provider, one
bit of copy paste slipped unmissed.
* provider/gitlab: Document `gitlab_project#id`
* provider/gitlab: Document `gitlab_project#namespace_id`
* provider/gitlab: Add fuller demonstration to the provider page
Following in the style of other provider pages, add a worked example
showing off all of the available resources offered by the gitlab
provider.
* provider/gitlab: Correct sample for gitlab_project
* The resource name should be consistent.
The HCL declares the terraform_remote_state with a resource name of foo. But the example invocation uses network which is incorrect.
* Foo > Network so this is a proper example.
A while back `atlas_artifact` was switched from being a `resource` to a `data` provider. When you use the examples suggested in the Terraform Enterprise docs, the Terraform cli shows a deprecation warning and provides an old url to the new data provider docs.
There are some complimentary doc updates in the Terraform Enterprise/Atlas repo.
* vendor: Updating Gophercloud for OpenStack Provider
* provider/openstack: Enable Security Group Updates
This commit enables security group names and descriptions to
be updated without causing a recreate.
* Update news section with April 4 webinar video
* Use YAML data file for news; add webinar registration CTA
* Update news section with Google Cloud webinar post-event info
* Exposing moid value from vm resource
moid value is needed by NSX resources, like security tag, when we attached security tags to a VMs, so needed before we commit NSX provider.
* fixing gofmt issue
* Updating docs regarding new exported moid attribute.
* vendor: Update go-gitlab to master@e6c11e
Update go-gitlab to master@e6c11e. This brings in UpdateGroup in
addition to fuller management of other attributes.
* provider/gitlab: Add `gitlab_group` resource
This adds a gitlab_group resource.
This combined with #14483 will allow you to create projects in a
group.
* Update sources.html.markdown
Moduels not updating was really annoying, should add this documentation in to increase usability of the feature.
* Update sources.html.markdown
* provider/gitlab: add `gitlab_deploy_key`
Here we extend the gitlab provider further by adding a `gitlab_deploy_key`
resource. This resource allows management of a projects deploy
keys.
* provider/gitlab: Do not test `gitlab_deploy_key` `can_push`
Here we remove the testing of the `can_push` attribute. This makes the
tests less comprehensive, but will allow them to work with the current
release of gitlab-ce.
This change is staged as a distinct commit so it can be easily
dropped/reverted once gitlab MR !11607 has reached a released state.
https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11607
* provider/gitlab: Update docs for gitlab_deploy_key/can_push
Note that the can_push attribute of gitlab_deploy_key doesn't currently
work. This note can be removed once
https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11607 is merged
and in general circulation.
system volumes on scaleway can't easily be modified - instead one has to create
a new image with the desired system volume size. This is way out of scope of
terraform - see https://community.online.net/t/expanding-lssd/907/2 for steps on
how to build a new image.
the `scaleway_server` `volume` attribute should only be used if you want to
attach additional volumes to a server which will share the lifetime of the
server, e.g. they will be destroyed once the server is shut down.
To have volumes which outlive the attached server one should use
`scaleway_volume` and `scaleway_volume_attachement` instead.
Prior to Terraform 0.7, lists in Terraform were just a shallow abstraction
on top of strings with a magic delimiter between items. Wrapping a single
string in brackets in the configuration was Terraform's prompt that it
needed to split the string on that delimiter during interpolation.
In 0.7, when first-class lists were added, this convention was preserved
by flattening lists-of-lists by one level when they were encountered in
configuration. However, there was an oversight in that change where it
did not correctly handle the case where the inner list was unknown.
In #14135 we removed some code that was flattening partially-unknown lists
into fully-unknown (untyped) values. This inadvertently exposed the missed
case from the previous paragraph, causing issues for list-wrapped splat
expressions with unknown members. While this worked fine for resources,
due to some fixup done inside helper/schema, this did not work for other
interpolation contexts such as module blocks.
Various attempts to fix this up and restore the flattening behavior
selectively were unsuccessful, due to a proliferation of assumptions all
over the core code that would be too risky to change just to fix this bug.
This change, then, takes the different approach of removing the
requirement that splats be presented inside list brackets. This
requirement didn't make much sense anymore anyway, since no other
list-returning expression had this constraint and so the rest of Terraform
was already successfully dealing with both cases.
This leaves us with two different scenarios:
- For resource arguments, existing normalization code in helper/schema
does its own flattening that preserves compatibility with the common
practice of using bracketed splats. This change proves this with a test
within the "test" provider that exercises the whole Terraform core and
helper/schema stack that assigns bracketed splats to list and set
attributes.
- For arguments in other blocks, such as in module callsites, the
interpolator's own flattening behavior applies to known lists,
preserving compatibility with configurations from before
partially-computed splats were possible, but those wishing to use
partially-computed splats are required to drop the surrounding brackets.
This is less concerning because this scenario was introduced only in
0.9.5, so the scope for breakage is limited to those who adopted this
new feature quickly after upgrading.
As of this commit, the recommendation is to stop using brackets around
splats but the old form continues to be supported for backward
compatibility. In a future _major_ version of Terraform we will probably
phase out this legacy form to improve consistency, but for now both
forms are acceptable at the expense of some (pre-existing) weird behavior
when _actual_ lists-of-lists are used.
This addresses #14521 by officially adopting the suggested workaround of
dropping the brackets around the splat. However, it doesn't yet allow
passing of a partially-unknown list between modules: that still violates
assumptions in Terraform's core, so for the moment partially-unknown lists
work only within a _single_ interpolation expression, and cannot be
passed around between expressions. Until more holistic work is done to
improve Terraform's type handling, passing a partially-unknown splat
through to a module will result in a fully-unknown list emerging on
the other side, just as was the case before #14135; this change just
addresses the fact that this was failing with an error in 0.9.5.
* Support importing google_sql_user
* Updated documentation to reflect that passwords are not retrieved.
* Added additional documentation detailing use.
* Removed unneeded d.setId() line from GoogleSqlUser Read method.
* Changed an errors.New() call to fmt.Errorf().
* Migrate schemas of existing GoogleSqlUser resources.
* Remove explicitly setting 'id' property
* Added google_sql_user to importability page.
* Changed separator to '/' from '.' and updated tests + debug messages.
* Add Network Alias configuration with network options
* Handle case where there's no network option
* Handle use case where network option is not available
* Handle use case where network option is not available
* Network alias only on user defined network
* Update documentation for docker provider on network aliases
* Remove unused variable
* Update documentation
* add unit test for docker container network
* fix unit test for docker container network
The tests did pass, but that was because they only tested part of the changes. By using the `schema.TestResourceDataRaw` function the schema and config are better tested and so they pointed out a problem with the schema of the Chef provisioner.
The `Elem` fields did not have a `*schema.Schema` but a `schema.Schema` and in an `Elem` schema only the `Type` field may (and must) be set. Any other fields like `Optional` are not allowed here.
Next to fixing that problem I also did a little refactoring and cleaning up. Mainly making the `ProvisionerS` private (`provisioner`) and removing the deprecated fields.
* Document source block for archive_file data source.
* Add example for archive_file source block.
* Capitalize Optional/Required for consistency with majority of provider docs.
Kyle MacDonald