Commit Graph

14 Commits

Author SHA1 Message Date
Kristin Laemmert 9ca3cb4233
website/docs: move type func docs to a useful location (#28940)
* website/docs: move type func docs to a useful location

* docs don't exist if you don't put them in the index (again)
2021-06-14 08:54:27 -04:00
Martin Atkins 07aa07f5b9 website: First Draft of Upgrade Guide 2021-06-07 17:23:39 -07:00
Martin Atkins 035d1648e4 website: Link to the v0.15 upgrade guide
Unfortunately it seems that this link got lost in a merge conflict when
we did the big nav refactor earlier in the v0.15 cycle, so here we'll
retoractively add it to the new location for upgrade guide nav, in the
language layout rather than the downloads layout.
2021-04-15 10:17:02 -07:00
Martin Atkins 140c613ae8 lang/funcs: "one" function
In the Terraform language we typically use lists of zero or one values in
some sense interchangably with single values that might be null, because
various Terraform language constructs are designed to work with
collections rather than with nullable values.

In Terraform v0.12 we made the splat operator [*] have a "special power"
of concisely converting from a possibly-null single value into a
zero-or-one list as a way to make that common operation more concise.

In a sense this "one" function is the opposite operation to that special
power: it goes from a zero-or-one collection (list, set, or tuple) to a
possibly-null single value.

This is a concise alternative to the following clunky conditional
expression, with the additional benefit that the following expression is
also not viable for set values, and it also properly handles the case
where there's unexpectedly more than one value:

    length(var.foo) != 0 ? var.foo[0] : null

Instead, we can write:

    one(var.foo)

As with the splat operator, this is a tricky tradeoff because it could be
argued that it's not something that'd be immediately intuitive to someone
unfamiliar with Terraform. However, I think that's justified given how
often zero-or-one collections arise in typical Terraform configurations.
Unlike the splat operator, it should at least be easier to search for its
name and find its documentation the first time you see it in a
configuration.

My expectation that this will become a common pattern is also my
justification for giving it a short, concise name. Arguably it could be
better named something like "oneornull", but that's a pretty clunky name
and I'm not convinced it really adds any clarity for someone who isn't
already familiar with it.
2021-04-12 15:32:03 -07:00
Martin Atkins 89b2405080 lang/funcs: "sensitive" and "nonsensitive" functions
These aim to allow hinting to Terraform about situations where it's not
able to automatically infer value sensitivity.

"nonsensitive" is for situations where Terraform's behavior is too
conservative, such as when a new value is derived from a sensitive value
in such a way that all of the sensitive content is removed.

"sensitive", on the other hand, is for situations where Terraform can't
otherwise infer that a value is sensitive. These situations should be
pretty rare in a module that's making effective use of sensitive input
variables and output values, but the documentation shows one example of
an uncommon situation where a more direct hint via this function would
be needed.

Both of these functions are aimed at only occasional use in unusual
situations. They are here for reasons of pragmatism, not because we
expect them to be used routinely or recommend their use.
2021-03-16 16:26:22 -07:00
Nick Fagerlund 7a8dd326c6 website: Language: Update links to moved pages 2021-01-22 12:22:21 -08:00
Nick Fagerlund b71786d9de website: Language: Update sidebar nav with new URLs
The files aren't moved as of this commit, but this serves as a map for the
subsequent changes.
2021-01-22 12:22:20 -08:00
Nick Fagerlund 5ceb8b2b98 website: Adopt `terraform_remote_state` into language docs
...and also shrink the explanation for alternate sharing approaches, a bit.

Actually, it looks like I already half-adopted it by accident. 😬 But this
commit adds it to the sidebar under "State", so users can browse to it. I'm
leaving the URL alone, because it's not urgent and we'll need to adjust a large
swath of URLs at some point anyway.

This change effectively stops presenting `terraform` as a provider in the normal
sense, and reduces /docs/providers/terraform/index.html to a ghost page in the
language section (to avoid breaking links for the time being). The message a
reader should get is that Terraform has one special built-in data source where
you don't need to think about the provider or its version.
2021-01-04 12:08:09 -08:00
Nick Fagerlund cc6a226bcf website: Remove provider category indexes, reduce main list
As of December 18, 2020, we've redirected nearly all of the provider
documentation that used to live on terraform.io:

- For providers that got published on the Registry, we redirected each docs page
to the corresponding Registry docs page.

- For providers that never got adopted by a new publisher, we archived the
GitHub repository and redirected each docs page to the corresponding Markdown
source file on github.com. (For an example of these redirects, see
https://www.terraform.io/docs/providers/telefonicaopencloud/r/s3_bucket.html)

There are ten providers left that we haven't redirected. These ones got adopted
by new publishers and _will_ end up on the Registry, but they aren't quite ready
to ship and get their permanent redirects, and we don't want to sabotage their
SEO by 301ing to a temporary destination.
2020-12-18 13:13:45 -08:00
Nick Fagerlund 209541aaf0 website: Break up main Modules and Module Development pages
This one is a lot like the previous two commits, but slightly more complex:

- Only adding one new meta-argument page, for `providers`; otherwise, it just
  re-uses the dual-purpose pages I made in the resources commit.

- About that `providers` argument: The stuff that was relevant to consumers of a
  module went in that meta-argument page, but there was also a huge deep dive on
  how the _author_ of a re-usable module should handle provider configurations
  in cases where inheriting the default providers isn't sufficient. THAT, I
  moved into a new page in the module development section. (For the consumer of
  a module, this should all be an implementation detail; the module README
  should tell you which aliased providers you need to configure and pass, and
  then you just do it, without worrying about proxy configuration blocks etc.)

- The "standard module structure" recommendations in the main module development
  page gets a page of its own, to make it more prominent and discoverable.

- Same deal with using the old URL as a landing page, at least for the main
  module calls page. It didn't seem necessary for the module development page.
2020-11-17 16:30:51 -08:00
Nick Fagerlund 6e2f5eb0be website: Break up Resources page into smaller chunks
- Resource behavior gets its own page.
- Meta-arguments all get their own pages.
- Stuff about resource syntax itself gets a page.

In the process of breaking the meta-arguments out into their own pages, I
revised them (with the exception of `provider`) so that they apply to both
resources and modules.

Like with Expressions, this commit repurposes the old resources.html URL as a
landing page for old links.
2020-11-17 16:30:51 -08:00
Nick Fagerlund a446ecb7b7 website: Break up Expressions page into smaller chunks
This commit converts the previous URL for this content to a landing page, which
captures all of the previous in-page anchors and directs readers to the new home
for each section.
2020-11-17 16:30:51 -08:00
Martin Atkins cec4578005 lang/funcs: Experimental "defaults" function
This is a new part of the existing module_variable_optional_attrs
experiment, because it's intended to complement the ability to declare
an input variable whose type constraint is an object type with optional
attributes. Module authors can use this to replace null values (that were
either explicitly set or implied by attribute omission) with other
non-null values of the same type.

This function is a bit more type-fussy than our functions typically are
because it's intended for use primarily with input variables that have
fully-specified type constraints, and thus it uses that type information
to help inform how the defaults data structure should be interpreted.

Other uses of this function will probably be harder today because it takes
a lot of extra annotation to build a value of a specific type if it isn't
passing through a variable type constraint. Perhaps later language
features for more general type conversion will make this more applicable,
but for now the more general form of this problem is better solved other
ways.
2020-11-13 17:27:20 -08:00
Nick Fagerlund 8b87318b35 website: Add new Language sidebar, repurpose docs.erb as CLI sidebar
We're splitting the current Terraform CLI docs into two top-level categories,
and these are the new nav sidebars for those sections.

As of this commit, they refer to some new "glue" pages that don't exist yet.
2020-11-11 19:11:29 -08:00