mirror of
https://github.com/opentffoundation/opentf.git
synced 2025-12-21 02:37:43 -05:00
6a27c82bb4
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>
102 lines
4.5 KiB
Plaintext
102 lines
4.5 KiB
Plaintext
---
|
|
description: >-
|
|
The tofu show command can inspect various OpenTofu artifacts and produce
|
|
either human-readable or machine-readable descriptions.
|
|
---
|
|
|
|
# Command: show
|
|
|
|
The `tofu show` command can inspect various OpenTofu artifacts and produce
|
|
either human-readable or machine-readable descriptions.
|
|
|
|
For example, you can use `tofu show` to inspect a saved plan file to check
|
|
that the planned operations are acceptable, or to inspect the latest state
|
|
snapshot.
|
|
|
|
:::note
|
|
When using the `-json` command-line flag, any sensitive values in
|
|
OpenTofu state will be returned in plain text. For more information, see
|
|
[Sensitive Data in State](../../language/state/sensitive-data.mdx).
|
|
:::
|
|
|
|
## Usage
|
|
|
|
Usage: `tofu show [target-selection-option] [other-options]`
|
|
|
|
Use one of the following target selection options to specify the artifact
|
|
to inspect:
|
|
|
|
- `-state`: Inspect the latest state snapshot, if any.
|
|
- `-plan=FILENAME`: Inspect the plan stored in the given saved plan file.
|
|
- `-config`: Inspect the current full configuration (requires `-json`).
|
|
- `-module=DIR`: Inspect the configuration of just a single module in the given directory, without requiring any dependencies to be installed (requires `-json`).
|
|
|
|
The `-state` option is the default if none of these options are used. The
|
|
target-selection options are mutually-exclusive.
|
|
|
|
This command also accepts the following additional options:
|
|
|
|
- `-no-color`: Disables the use of terminal escape sequences in
|
|
human-oriented output.
|
|
- `-json`: Selects the machine-readable JSON output format, instead
|
|
of the default human-oriented output.
|
|
- `-var` and `-var-file`: Specifies values for any input variables
|
|
used in module source addresses or backend settings in the
|
|
current configuration.
|
|
|
|
Unless using the `-module=DIR` option, this command relies on schema information
|
|
from provider plugins to fully understand the provider-specific data structures
|
|
in state, plan, and configuration artifacts. If you are currently using
|
|
different provider versions than were used when creating the selected artifact
|
|
then you may need to use `tofu apply` (or similar) to allow OpenTofu to
|
|
upgrade the stored data to match the latest provider schemas.
|
|
|
|
## JSON Output
|
|
|
|
When using the `-json` option, the structure of the machine-readable output
|
|
depends on the selected artifact type:
|
|
|
|
- `-state` returns [the JSON state representation](../../internals/json-format.mdx#state-representation).
|
|
- `-plan=FILENAME` returns the [the JSON plan representation](../../internals/json-format.mdx#plan-representation),
|
|
which also includes information about the configuration and
|
|
prior state that the plan was based on.
|
|
- `-config` returns [the JSON configuration representation](../../internals/json-format.mdx#configuration-representation),
|
|
providing exactly the same configuration-related information that the plan representation would include,
|
|
but without requiring a plan to be created first.
|
|
- `-module=DIR` returns a subset of [the JSON configuration representation](../../internals/json-format.mdx#configuration-representation), where:
|
|
- The `"module"` property of each module call is omitted.
|
|
- The `"schema_version"` property of each resource is omitted.
|
|
- All expression-related properties are omitted.
|
|
|
|
These omissions together allow this particular mode to work without first
|
|
executing `tofu init`, and thus without first installing the module's
|
|
dependencies.
|
|
|
|
## Legacy Usage
|
|
|
|
For backward compatibility with older versions of OpenTofu, this
|
|
command also supports a different usage pattern:
|
|
|
|
`tofu show [other-options] <filename>`
|
|
|
|
In this style, none of the explicit target selection options can be used
|
|
and instead OpenTofu inspects the given file and reacts in the following
|
|
ways:
|
|
|
|
- If the file can be loaded as a saved plan file, behaves like `-plan=FILENAME`
|
|
with the same file.
|
|
- If the file can be parsed as a local state snapshot file such as those
|
|
created by `tofu state pull`, inspects the content of that state file
|
|
using the same output format as would normally be used to inspect the
|
|
latest state snapshot.
|
|
|
|
The selected state snapshot file must be one associated with the
|
|
configuration in the current working directory, or else the results
|
|
are unspecified because the available providers might not match
|
|
those that were used to create the data in the state snapshot.
|
|
|
|
Unless you need the legacy behavior of inspecting an arbitrary state
|
|
snapshot file, we recommend using the new explicit target selection
|
|
options to make it clearer to OpenTofu what artifact type you wish to
|
|
inspect.
|