We typically try to avoid making subjective, boasty claims in our
documentation in recent times, but there remained both some older
documentation that we've not recently revised and also some newer examples
that are, in retrospect, also perhaps more "boasty" than they need to be.
We prefer not to use this sort of boasty language because not everyone
using Terraform has the same background and experience, and so what is
"easy" or "intuitive" to one person may not be so to another person, and
that should not suggest that the second person is in any way wrong or
inadequate.
In reviewing some of our use of the word "easy" here I tried as much as
possible to surgically revise the existing content without getting drawn
into a big rewrite, but in some cases the content was either pretty
unsalvageable (due to talking about obsolete features that were removed
long ago) or required some broader changes to make the result hopefully
still get the same facts across. In those cases I've both removed some
content entirely or adjusted larger paragraphs.
This was not an exhaustive review and so I'm sure there's still plenty of
room for similar improvements elsewhere. I also resisted the urge to
update some pages that contain outdated information about currently-active
features.
We previously had this just stubbed out because it was a stretch goal for
the v0.13.0 release and it ultimately didn't make it in.
Here we fill out the existing stub -- with a minor change to its interface
so it can access credentials -- with a client implementation that is
compatible with the directory structure produced by the
"terraform providers mirror" subcommand, were the result to be published
on a static file server.
* Make sidebar nav in language docs more intuitive
* Minor display fixes for registry docs
* Explain providers in the registry in the providers index
* Revise a bunch of language docs around provider reqs
This is mostly an effort to smooth out some of the explanations, make sure
things are presented in a helpful order, make sure terminology lines up, draw
connections between related concepts, make default behavior more apparent, and
the like. It shouldn't include very much new information, but there might be one
or two things that came out of a conversation somewhere.
Co-authored-by: Judith Malnick <judith@hashicorp.com>
Although this command is removed in Terraform 0.13, our documentation is
for all versions of Terraform that remain in common use and keeping this
documented will be helpful for folks who are still using Terraform 0.11
and planning their upgrades to Terraform 0.12.
Both of the upgrade commands now include notes that they are only
available in their specific major version, along with a link to the
relevant upgrade guide for other background information about the upgrade,
in case the user finds the command documentation first. (The command docs
are, I think, a little more discoverable than the upgrade guides.)
We previously covered everything about using providers on a single page,
but that was getting unwieldy already and we now have a lot more to
discuss with v0.13 introducing a new source address syntax and some other
concepts.
Here we split the provider-related content into two parts: "Provider
Requirements" covers how to find and declare dependencies on providers,
and then "Provider Configuration" (formerly just "Providers") then focuses
primarily on how to write zero or more provider configurations for a
particular provider.
Because "Provider Requirements" is now presented before "Provider
Configuration" in the navigation, I've also moved some of the introductory
content about providers in general onto the "Requirements" page. The
first paragraph of that content is duplicated onto the "Configuration"
page for discoverability, but we now link to the requirements page to get
the full story.
The "Configuration Language" section was becoming rather unweildy, both
by having a lot of pages and by some of the pages being quite large in
themselves.
This is a first step towards breaking things up a little more, starting
with two changes:
- The "Configuration Language" navigation is now split into two
sub-headings "Configuration Blocks" and "Syntax".
- Some of the information about sub-blocks of the "terraform" block are
now given their own pages, because their content is quite complex
in itself.
- "Version Constraints" is now a page in its own right, rather than this
content being duplicated in slightly different forms across multiple
contexts that make use of user-specified version constraints.
Implement a new provider_meta block in the terraform block of modules, allowing provider-keyed metadata to be communicated from HCL to provider binaries.
Bundled in this change for minimal protocol version bumping is the addition of markdown support for attribute descriptions and the ability to indicate when an attribute is deprecated, so this information can be shown in the schema dump.
Co-authored-by: Paul Tyng <paul@paultyng.net>
* 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.
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 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.
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.
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.
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.
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.)
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.
* 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
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.
Martin Atkins