At some point after this documentation was originally written the schema
structure grew to include the possibility of structural attribute types,
represented using "nested_type" instead of "type" in the attribute
definition, but it seems that the documentation was not updated to mention
that.
This is just a minimal extra note about that focused mainly on just
acknowledging that this possibility exists at all, in case anyone is
relying on these docs to build something to parse this format. It would
probably be helpful to expand both this and the existing documentation to
specify the format more precisely, but my focus here is just on quickly
filling in this missing piece so that the documentation is complete, even
if not detailed and precise.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
By design the "-raw" option to "tofu output" writes the literal output
value directly to stdout without any quoting or escaping, and so it's
risky to use it with an output value that could be controlled by an
attacker when stdout is a terminal.
This risk is inherent in the purpose of this option and is part of the
reason why this is not the default behavior (OpenTofu returns a quoted
representation of an output string by default) so here we just make that
risk explicit in the documentation, in the hope that operators will use
this operation mindfully.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
Over time the discussion about "lifecycle" blocks in the documentation
became confusing because the docs originally written for managed resource
lifecycle got partially generalized for resources of other modes and for
module calls, even though each of those has a completely different
lifecycle and thus a different set of lifecycle settings.
This is a first pass at trying to reorganize that so that the "lifecycle"
page is really just an index of all of the different kinds of lifecycle
block that exist in the language, while the main documentation for each
use of that block type now belongs with the documentation of the block
it's nested within.
While working on this I also found that there was some duplication inside
the "data sources" page where the same information was described multiple
times, and a few other cases where things had become inconsistent over
time. This also includes a little extra content to try to clarify the
difference between managed, data, and ephemeral resources and to make it
explicit that the "Resources" section is focused only on managed resources
because that is the primary resource mode.
As usual there's lots more that could be done here -- this documentation
has gradually evolved over time and is full of weird quirks due to that
evolution -- but I decided to draw a line here so that the diff wouldn't
get too large.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
These were previously settable only via environment variables. These are
now handled as part of CLI Configuration and so also settable in a new
"registry_protocols" block in a CLI configuration file, with the
environment variables now treated as if they are an additional virtual
configuration file containing the corresponding settings.
This handles our settings in our modern style where package cliconfig is
responsible for deciding the configuration and then package main reacts
to that configuration without being aware of how it is decided.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
ORAS v1.3.0 introduces some new features that allow directly building an
index manifest in the form that OpenTofu expects, so it's no longer
necessary to edit that index manifest manually.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
We previously added the -config mode for showing the entire assembled
configuration tree, including the content of any descendent modules, but
that mode requires first running "tofu init" to install all of the
provider and module dependencies of the configuration.
This new -module=DIR mode returns a subset of the same JSON representation
for only a single module that can be generated without first installing
any dependencies, making this mode more appropriate for situations like
generating documentation for a single module when importing it into the
OpenTofu Registry. The registry generation process does not want to endure
the overhead of installing other providers and modules when all it actually
needs is metadata about the top-level declarations in the module.
To minimize the risk to the already-working full-config JSON representation
while still reusing most of its code, the implementation details of package
jsonconfig are a little awkward here. Since this code changes relatively
infrequently and is implementing an external interface subject to
compatibility constraints, and since this new behavior is relatively
marginal and intended primarily for our own OpenTofu Registry purposes,
this is a pragmatic tradeoff that is hopefully compensated for well enough
by the code comments that aim to explain what's going on for the benefit
of future maintainers. If we _do_ find ourselves making substantial changes
to this code at a later date then we can consider a more significant
restructure of the code at that point; the weird stuff is intentionally
encapsulated inside package jsonconfig so it can change later without
changing any callers.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
This text was from earlier on in the development period when we hadn't yet
settled on a strategy, but now we are intending to work with the ORAS team
so that ORAS can construct index manifests in the form that OpenTofu
expects, so we'll talk about that instead of making a comment about
prereleases that will become confusing once OpenTofu v1.10.0 final is
released.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
For the v1.10.0-alpha1 release, where we weren't even feature-complete yet,
we included a callout box warning that features were incomplete and details
subject to change.
We're not expecting to issue another alpha before we reach the beta phase
during which we'll be aiming to change the design of these features as
little as possible, so it's time to remove that callout box.
In its place we now have a short statement about which versions of the
OCI Distribution protocol we support. Because some registries allow and
just ignore unrecognized properties in submitted manifests it is possible
that these features will work with older implementations, but such support
is not guaranteed by earlier versions of the specification. In practice,
OCI Distribution v1.1.0 is already quite well-deployed.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
From feedback in alpha testing of the new OCI Distribution features we
learned that on some platforms Docker CLI automatically searches for
platform-specific credential helpers and uses them automatically when
found, but OpenTofu intentionally does not copy that behavior.
We'll now be explicit about that intentional difference in a callout box
in the documentation. This is unfortunately the kind of situation where
an affected person is unlikely to read the documentation to find out what
_isn't_ supported, and so this content is primarily intended to appear
in search results and other similar indirect querying, rather than by the
reader encountering it organically while reading the documentation. It's
therefore placed adjacent to the configuration option that someone might
use to solve the problem once they've learned about it.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
The "tofu show" command has historically been difficult to extend to meet
new use-cases, such as showing the current configuration without creating
a plan, because it was designed to take zero or one arguments and then try
to guess what the one specified argument was intended to mean.
This commit introduces a new style where the type of object to inspect is
specified using command line option syntax, using one of two
mutually-exclusive options:
-state Show the latest state snapshot.
-plan=FILE Show the plan from the given saved plan file.
We expect that a future commit will extend this with a new "-config" option
to inspect the configuration rooted in the current working directory, and
possibly with "-module=DIR" to shallowly inspect a single module without
necessarily having to fully initialize it with all of its dependencies
first. However, both of those use-cases (and any others) are not in scope
for this commit, which is focused only on refactoring to make those future
use-cases possible.
The old mode of specifying neither option and providing zero or one
positional arguments is still supported for backward compatibility.
Notably, the legacy style is the only way to access the legacy behavior of
inspecting a specific state snapshot file from the local filesystem, which
has not often been used since Terraform v0.9 as we've moved away
from manual management of state files to the structure of state backends.
Those who _do_ still need that old behavior can still access it in the
old way, but there will be no new-style equivalent of it unless we learn
of a compelling use case for it.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
This is a first draft of documentation describing our new capability to
treat artifacts in OCI Distribution repositories as a new kind of remote
module package.
This documentation includes both some caller-focused documentation that
extends our existing "Module Sources" page, and some documentation intended
more for the author of a module package describing how they could publish
their package as an OCI artifact that OpenTofu will accept.
As usual, we'll continue to refine this documentation based on feedback
during the prerelease period and beyond.
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
We are currently documenting how to manually edit the index manifest while
we wait for the ORAS CLI support for this to be finalized, but the initial
draft of these instructions missed the step of annotating each manifest
with the platform it's intended for.
(We intend to replace all of this manual setup with a single ORAS CLI
command once the associated functionality is finalized there. At the time
of writing this message, the ORAS project is preparing that functionality
for their forthcoming v1.3.0 release.)
Signed-off-by: Martin Atkins <mart@degeneration.co.uk>
