Now that any configuration processing requires schema, we need either a
standalone schema or a provider/provisioner configured with one a lot more
often in tests.
To avoid adding loads of extra boilerplate to the tests, these new helper
functions produce objects pre-configured with a schema that should be
useful for a number of different cases, and can be customized further for
more interesting situations.
A lot of our tests can then just use these pre-defined object and
attribute names in their fixtures in situations where the canned schemas
here are good enough.
Our "Parse..." functions all take hcl.Traversal objects rather than strings,
assuming that in most cases we've already parsed a traversal out of some
larger construct (usually a config file) before interpreting it as an
address.
However, there are some situations -- particularly tests -- where being
able to easily parse a string directly is helpful. These new "Parse...Str"
functions all wrap the function of the same name with no "Str" suffix and
first parse the string with the HCL native syntax traversal parser.
As noted in the function doc comments, this should not be used in "real"
code except in exceptional circumstances, since it creates addresses and
diagnostics that do not have useful source location information for
reporting diagnostics.
The logic under test has intentionally changed here so that setting count
to any value -- even 1 -- causes Terraform to prefer to keep indexed
instances if both non-indexed and indexed are present.
Previously Terraform treated count = 1 as equivalent to count not set at
all, but we now recognize these as two different situations and treat
count = 1 as the same as any other non-zero count, to ensure that if
count is set conditionally it'll always produce indexed instances, even
if the dynamic expression ends up evaluating to 1.
This function was previously checking for a path length greater than one
because the older path format included an always present "root" element
at the start.
We now need to check for a totally-empty list, because otherwise we fail
to add the expected prefix to the front of a path with only one element.
This also includes some adjustments to the related tests and transforms
that do not change behavior but do make the test results easier to
understand and debug.
Due to some disagreement about what representation of provider addresses
we were using, the inherited providers map wasn't matching. Now we'll
consistenly use the "compact" form (just the provider name and optional
alias).
Also includes some other tweaks to make this test better-behaved.
Although the AddModule method now takes a new-style
module address as an argument, internally we're still
shimming it to a []string.
Therefore this test needs to still expect [][]string as
a result, rather tan []addrs.ModuleInstance.
Prior to the refactoring to move provider address parsing/selection up
into the frontend, there was some logic here to just-in-time default a
provider config based on the given resource type.
This is now expected to happen at a higher layer, with ImportTarget
expecting an already-valid provider configuration address.
The normal import codepath was already updated with this in mind, but some
of the provider transform tests are using ImportStateTransformer as a
shortcut for getting some resource nodes added to the graph, and so those
tests now need to include a valid provider address in their ImportTarget
values.
Also includes some adjustments to test output to make the tests easier
to debug.
The zero value of ProviderConfig is not a valid provider config address,
so we'll generate a special string for that in order to make that clear
in case one sneaks in somewhere. This can happen, for example, in the
core flow of resolving provider inheritance during the ProviderTransformer
if a caller attempts to access the resolved provider before that
transformer has run.
The prior implementation of this function (before the rewrite to use
addrs.AbsProviderConfig values) was relying on some implicit behavior of
our provider address normalization to generate an address in the root
module. Since that wasn't explicit, I introduced a bug here when
introducing the new address type, where I generated an address in the
node's own module, rather than in the root as expected.
This new implementation is functionally equivalent to the prior, but is
written to make the intent more obvious: take _just_ the type from the
node's provider address and create an implicit configuration for it
_in the root module_.
Along with the change in approach, this new implementation also has an
updated documentation comment that better describes its current intent
(previously it was outdated) and hopefully clearer trace logging to
better communicate what it's doing.
Previously we were defaulting the provider configuration selection to a
provider in the root module inferred from the resource type name.
This is close, but not quite right: we need to _start_ with a provider
configuration in the same module as we're importing into, and then our
provider resolution steps during import graph construction will use that
as a starting point for a walk up the tree to find the nearest matching
configuration (which might eventually still be in the root, but not
necessarily).
In the change to using addrs types rather than string keys directly here
I incorrectly made this use the _relative_ provider config instead of
the absolute one, causing MissingProviderTransformer to only match
providers defined in the root module (due to ambiguity in the string
representations of these address types).
The rest of this change is improved logging and test output that helped
with debugging this issue.
Some of these tests were using an outdated form to reference a local
directory as a module. While here, I also updated the provider references
to the new unquoted form, which is preferred from v0.12 onwards.
The changes to our GraphNodeReferencable and GraphNodeReferencer
interfaces were not also reflected in our testing structs here, and so
these tests were no longer working.
This updates these implementations to the new required signatures,
adapting the simplified model used in the structs to generate local
variable references, since the reference model no longer uses the
arbitrary strings that this test originally depended on.
We also remove some of the tests here since the functionality they were
testing no longer applies: inter-module dependencies are now handled by
the graph nodes producing extra ReferencableAddrs, and the "backup" form
is no longer used because our new address model is able to distinguish
resources from resource instances without the need for the magical
backup reference forms we previously used.
Resolution of dependencies automatically from expressions now requires
a schema to be available. To avoid the need to provide mock schemas for
all of these different resource types, we instead use the depends_on
argument here to mark the dependencies explicitly.
Previously we had a bug where we'd use the resource type name instead of
the provider name. Now we use the DefaultProviderConfig helper function
to extract the provider name from the resource type name.
The ReferenceTransformer can't do its work here unless our resources have
schema attached, since otherwise it doesn't know which attributes to
search to find references.
Now that a schema is required to decode resource configuration, a lot more
tests than before need access to mock providers in order to get a schema.
These new helpers allow a mock provider with a schema to be constructed
concisely.
This test required some adaptation for the new variable handling model in
the HCL2-oriented codepaths, where more of the handling is now done in the
"command" package.
The initial reorganization of this test was not correct, so this is a
further revision to adapt the original assertions to the new model as much
as possible, removing a few tests that no longer make sense in the new
world.
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.
A number of our test fixtures were previously using the non-idiomatic form
of including a single child attribute all on one line with the block
header and bounding braces.
This non-idiomatic form is an error in HCL2, and hclfmt has always "fixed"
it to the expected form of each attribute being on a line of its own, and
so here we just update all the affected test fixtures to canonical form
(using hclfmt), allowing them to be parsed as intended.
Since the these entire files were processed with hclfmt, there are some
other unrelated style changes included in situations where the file
layouts were non-idiomatic in other ways.
These are all things that ought to be present in normal use but can end up
being nil in incorrect tests. Test debugging is simpler if these things
return errors gracefully, rather than crashing.
While there's no good reason for this to happen in practice, it can arise
in tests if mocks aren't set up quite right, and so we'll catch it and
report it nicely to make test debugging a little easier.
There's actually no good reason for this to happen in the normal case, but
it can happen reasonably easy if a test doesn't properly configure the
MockEvalContext, and so having this check here makes test debugging a
little easier.
Since this test case is using t.Run, it must be sure to pass the nested
*testing.T over to the testDiffs function or else calls to t.Fatal will
crash the whole test process, since they would otherwise be called on the
wrong instance of *testing.T.
The only reason these cases are arising right now is because we have tests
that haven't yet been updated to properly support schema, but it can't
hurt to add some robustness here to reduce the risk of real crashes.
Previously we had a panic in here for invalid resource modes. While that
does always indicate a programming error, it's frustrating to have a
crasher inside a String method since it often impedes our ability to
report an error properly, since the error reporting itself can crash.
Instead we'll just return an invalid string and hope the caller really is
bailing out with an error message.
Martin Atkins