IntenseWebs/opentofu
3
0
Fork 0
mirror of https://github.com/opentofu/opentofu.git synced 2025-02-25 18:45:20 -06:00
Code Issues Packages Projects Releases Wiki Activity

Replace legacy admonition syntax (#432)

Browse Source
This commit is contained in:
Damian Stasik 2023-09-18 13:56:28 +02:00 committed by GitHub
parent 4950f16756
commit 4cab6e72b4
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
75 changed files with 360 additions and 124 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
website/docs/cli/cloud/migrating.mdx
View File

@ -81,4 +81,6 @@ terraform {
}
```
~> **Warning**: Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the OpenTF CLI. For example, rather than `opentf workspace select prod`, you must run the command `opentf workspace select my-app-prod`.
:::warning
Because the `cloud` block does not support the `prefix` argument, once you migrate, you must refer to workspaces by their full name when using the OpenTF CLI. For example, rather than `opentf workspace select prod`, you must run the command `opentf workspace select my-app-prod`.
:::

8
website/docs/cli/cloud/settings.mdx
View File

@ -88,7 +88,9 @@ The `cloud` block supports the following configuration arguments:
You can use environment variables to configure one or more `cloud` block attributes. This is helpful when you want to configure OpenTF as part of a Continuous Integration (CI) pipeline. OpenTF only reads these variables if the corresponding attribute is omitted from your configuration file. If you choose to configure the `cloud` block entirely through environment variables, you must still add an empty `cloud` block in your configuration file.
~> **Warning:** Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline.
:::warning
Remote execution with non-interactive workflows requires auto-approved deployments. Minimize risk of unpredictable infrastructure changes and configuration drift by making sure that no one can change your infrastructure outside of your automated build pipeline.
:::
Use the following environment variables to configure the `cloud` block:
@ -118,4 +120,6 @@ The rules in `.terraformignore` file resemble the rules allowed in a
- End a pattern with a forward slash `/` to specify a directory.
- Negate a pattern by starting it with an exclamation point `!`.
-> **Note:** Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.
:::note
Unlike `.gitignore`, only the `.terraformignore` at the root of the configuration directory is considered.
:::

4
website/docs/cli/commands/apply.mdx
View File

@ -22,7 +22,9 @@ When you run `opentf apply` without passing a saved plan file, OpenTF automatica
You can pass the `-auto-approve` option to instruct OpenTF to apply the plan without asking for confirmation.
!> **Warning:** If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your OpenTF workflow. This minimizes the risk of unpredictable changes and configuration drift.
:::danger Warning
If you use `-auto-approve`, we recommend making sure that no one can change your infrastructure outside of your OpenTF workflow. This minimizes the risk of unpredictable changes and configuration drift.
:::
### Saved Plan Mode

4
website/docs/cli/commands/import.mdx
View File

@ -24,13 +24,15 @@ it is the zone ID (`Z12ABC4UGMOZ2N`). Please reference the provider documentatio
on the ID format. If you're unsure, feel free to just try an ID. If the ID
is invalid, you'll just receive an error message.
~> Warning: OpenTF expects that each remote object it is managing will be
:::warning
OpenTF expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by OpenTF
itself having created all objects. If you import existing objects into OpenTF,
be careful to import each remote object to only one OpenTF resource address.
If you import the same object multiple times, OpenTF may exhibit unwanted
behavior. For more information on this assumption, see
[the State section](/docs/language/state).
:::
The command-line flags are all optional. The following flags are available:

4
website/docs/cli/commands/login.mdx
View File

@ -9,11 +9,13 @@ description: >-
The `opentf login` command can be used to automatically obtain and save an
API token for any host that offers OpenTF-compatible services.
-> **Note:** This command is suitable only for use in interactive scenarios
:::note
This command is suitable only for use in interactive scenarios
where it is possible to launch a web browser on the same host where OpenTF
is running. If you are running OpenTF in an unattended automation scenario,
you can
[configure credentials manually in the CLI configuration](/docs/cli/config/config-file#credentials).
:::
## Usage

4
website/docs/cli/commands/logout.mdx
View File

@ -13,8 +13,10 @@ The `opentf logout` command is used to remove credentials stored by
Usage: `opentf logout [hostname]`
-> **Note:** the API token is only removed from local storage, not destroyed on
:::note
The API token is only removed from local storage, not destroyed on
the remote server, so it will remain valid until manually revoked.
:::
## Credentials Storage

4
website/docs/cli/commands/output.mdx
View File

@ -31,9 +31,11 @@ The command-line flags are all optional. The following flags are available:
* `-state=path` - Path to the state file. Defaults to "opentf.tfstate".
Ignored when [remote state](/docs/language/state/remote) is used.
-> **Note:** When using the `-json` or `-raw` command-line flag, any sensitive
:::note
When using the `-json` or `-raw` command-line flag, any sensitive
values in OpenTF state will be displayed in plain text. For more information,
see [Sensitive Data in State](/docs/language/state/sensitive-data).
:::
## Examples

8
website/docs/cli/commands/plan.mdx
View File

@ -119,7 +119,9 @@ In addition to alternate [planning modes](#planning-modes), there are several op
on resource instances which match the given address and on any objects that
those instances depend on.
-> **Note:** Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around OpenTF limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
:::note
Use `-target=ADDRESS` in exceptional circumstances only, such as recovering from mistakes or working around OpenTF limitations. Refer to [Resource Targeting](#resource-targeting) for more details.
:::
- `-var 'NAME=VALUE'` - Sets a value for a single
[input variable](/docs/language/values/variables) declared in the
@ -150,7 +152,9 @@ we recommend using the `-var-file` option instead, and write your actual values
in a separate file so that OpenTF can parse them directly, rather than
interpreting the result of your shell's parsing.
~> **Warning:** OpenTF will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`).
:::warning
OpenTF will error if you include a space before or after the equals sign (e.g., `-var "length = 2"`).
:::
To use `-var` on a Unix-style shell on a system like Linux or macOS we
recommend writing the option argument in single quotes `'` to ensure the

4
website/docs/cli/commands/providers/lock.mdx
View File

@ -48,13 +48,15 @@ providers from their origin registries and then update
include a selected version for each provider and all of the package checksums
that are covered by the provider developer's cryptographic signature.
~> **Warning:** The `opentf providers lock` command prints information
:::warning
The `opentf providers lock` command prints information
about what it has fetched and whether each package was signed using a
cryptographic signature, but it cannot automatically verify that the
providers are trustworthy and that they comply with your local system
policies or relevant regulations. Review the signing key information
in the output to confirm that you trust all of the signers before committing
the updated lock file to your version control system.
:::
If you list one or more provider source addresses on the command line then
`opentf providers lock` will restrict its work only to those providers,

4
website/docs/cli/commands/refresh.mdx
View File

@ -9,9 +9,11 @@ description: |-
The `opentf refresh` command reads the current settings from all managed
remote objects and updates the OpenTF state to match.
~> _Warning:_ This command is deprecated, because its default behavior is
:::warning
This command is deprecated, because its default behavior is
unsafe if you have misconfigured credentials for any of your providers.
See below for more information and recommended alternatives.
:::
This won't modify your real remote objects, but it will modify the
[OpenTF state](/docs/language/state).

4
website/docs/cli/commands/show.mdx
View File

@ -16,9 +16,11 @@ as OpenTF sees it.
Machine-readable output is generated by adding the `-json` command-line
flag.
-> **Note:** When using the `-json` command-line flag, any sensitive values in
:::note
When using the `-json` command-line flag, any sensitive values in
OpenTF state will be displayed in plain text. For more information, see
[Sensitive Data in State](/docs/language/state/sensitive-data).
:::
## JSON Output

4
website/docs/cli/commands/state/mv.mdx
View File

@ -43,13 +43,15 @@ object and create a new object at the new address, and so `opentf state mv`
allows you to override that interpretation by pre-emptively attaching the
existing object to the new address in OpenTF.
~> _Warning:_ If you are using OpenTF in a collaborative environment, you
:::warning
If you are using OpenTF in a collaborative environment, you
must ensure that when you are using `opentf state mv` for a code refactoring
purpose you communicate carefully with your coworkers to ensure that nobody
makes any other changes between your configuration change and your
`opentf state mv` command, because otherwise they might inadvertently create
a plan that will destroy the old object and create a new object at the new
address.
:::
This command also accepts the following options:

4
website/docs/cli/commands/state/pull.mdx
View File

@ -26,4 +26,6 @@ You cannot use this command to inspect the OpenTF version of
the remote state, as it will always be converted to the current OpenTF
version before output.
-> **Note:** OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state pull | sc opentf.tfstate`.
:::note
OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state pull | sc opentf.tfstate`.
:::

4
website/docs/cli/commands/state/push.mdx
View File

@ -22,7 +22,9 @@ If PATH is "-" then the state data to push is read from stdin. This data
is loaded completely into memory and verified prior to being written to
the destination state.
-> **Note:** OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state push | sc opentf.tfstate`.
:::note
OpenTF state files must be in UTF-8 format without a byte order mark (BOM). For PowerShell on Windows, use `Set-Content` to automatically encode files in UTF-8 format. For example, run `opentf state push | sc opentf.tfstate`.
:::
OpenTF will perform a number of safety checks to prevent you from
making changes that appear to be unsafe:

4
website/docs/cli/commands/taint.mdx
View File

@ -11,7 +11,9 @@ become degraded or damaged. OpenTF represents this by marking the
object as "tainted" in the OpenTF state, and OpenTF will
propose to replace it in the next plan you create.
~> **Warning:** This command is deprecated, we recommend using the `-replace` option with `opentf apply` instead (details below).
:::warning
This command is deprecated, we recommend using the `-replace` option with `opentf apply` instead (details below).
:::
## Recommended Alternative

20
website/docs/cli/config/config-file.mdx
View File

@ -87,8 +87,10 @@ You can have multiple `credentials` blocks if you regularly use services from
multiple hosts. Each `credentials` block contains a `token` argument
giving the API token to use for that host.
-> **Note:** The credentials hostname must match the hostname in your module
:::note
The credentials hostname must match the hostname in your module
sources and/or backend configuration.
:::
### Environment Variable Credentials
@ -243,10 +245,12 @@ The following are the two supported installation method types:
which is designed to be relatively easy to implement using typical static
website hosting mechanisms.
~> **Warning:** Don't configure `network_mirror` URLs that you do not trust.
:::warning
Don't configure `network_mirror` URLs that you do not trust.
Provider mirror servers are subject to TLS certificate checks to verify
identity, but a network mirror with a TLS certificate can potentially serve
modified copies of upstream providers with malicious content.
:::
OpenTF will try all of the specified methods whose include and exclude
patterns match a given provider, and select the newest version available across
@ -352,15 +356,19 @@ OpenTF will never itself delete a plugin from the plugin cache once it has
been placed there. Over time, as plugins are upgraded, the cache directory may
grow to contain several unused versions which you must delete manually.
-> **Note:** The plugin cache directory is not guaranteed to be concurrency
:::note
The plugin cache directory is not guaranteed to be concurrency
safe. The provider installer's behavior in environments with multiple `opentf
init` calls is undefined.
:::
### Allowing the Provider Plugin Cache to break the dependency lock file
~> **Note:** The option described in is for unusual and exceptional situations
:::warning Note
The option described in is for unusual and exceptional situations
only. Do not set this option unless you are sure you need it and you fully
understand the consequences of enabling it.
:::
By default OpenTF will use packages from the global cache directory only
if they match at least one of the checksums recorded in the
@ -400,12 +408,14 @@ will always install a provider from upstream the first time you use it with
a particular configuration, but can then re-use the cache entry on later runs
once the dependency lock file records valid checksums for the provider package.
~> **Note:** The OpenTF team intends to improve the dependency lock file
:::warning Note
The OpenTF team intends to improve the dependency lock file
mechanism in future versions so that it will be usable in more situations. At
that time this option will become silently ignored. If your workflow relies on
the use of this option, please open a GitHub issue to share details about your
situation so that we can consider how to support it without breaking the
dependency lock file.
:::
### Development Overrides for Provider Developers

8
website/docs/cli/import/index.mdx
View File

@ -8,11 +8,15 @@ description: >-
OpenTF can import existing infrastructure resources. This functionality lets you bring existing resources under OpenTF management.
-> **Note:** OpenTF supports `import` blocks. Unlike the `opentf import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/docs/language/import).
:::note
OpenTF supports `import` blocks. Unlike the `opentf import` command, you can use `import` blocks to import more than one resource at a time, and you can review imports as part of your normal plan and apply workflow. [Learn more about `import` blocks](/docs/language/import).
:::
## State Only
~> **Warning:** OpenTF expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. See [State](/docs/language/state) for more details.
:::warning
OpenTF expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ OpenTF resource address. If you import the same object multiple times, OpenTF may exhibit unwanted behavior. See [State](/docs/language/state) for more details.
:::
The `opentf import` CLI command can only import resources into the [state](/docs/language/state). Importing via the CLI does _not_ generate configuration. If you want to generate the accompanying configuration for imported resources, [use the `import` block instead](/docs/language/import).

4
website/docs/cli/import/usage.mdx
View File

@ -8,13 +8,15 @@ Use the `opentf import` command to import existing infrastructure to OpenTF stat
The `opentf import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC.
~> Warning: OpenTF expects that each remote object it is managing will be
:::warning
OpenTF expects that each remote object it is managing will be
bound to only one resource address, which is normally guaranteed by OpenTF
itself having created all objects. If you import existing objects into OpenTF,
be careful to import each remote object to only one OpenTF resource address.
If you import the same object multiple times, OpenTF may exhibit unwanted
behavior. For more information on this assumption, see
[the State section](/docs/language/state).
:::
To import a resource, first write a resource block for it in your
configuration, establishing the name by which it will be known to OpenTF:

4
website/docs/cli/plugins/index.mdx
View File

@ -11,8 +11,10 @@ of resources. (For more information about providers, see
[Providers](/docs/language/providers) in the OpenTF
language docs.)
-> **Note:** Providers are the only plugin type most OpenTF users interact with. OpenTF also supports third-party provisioner plugins, but
:::note
Providers are the only plugin type most OpenTF users interact with. OpenTF also supports third-party provisioner plugins, but
we discourage their use.
:::
OpenTF downloads and/or installs any providers
[required](/docs/language/providers/requirements) by a configuration

8
website/docs/cli/plugins/signing.mdx
View File

@ -4,11 +4,13 @@ description: >-
Registry.
---
<!-- THIS PAGED IS LINKED TO IN THE CLI -->
# Plugin Signing
~> **Note** OpenTF only authenticates provider plugins fetched from a registry.
<!-- THIS PAGED IS LINKED TO IN THE CLI -->
:::warning Note
OpenTF only authenticates provider plugins fetched from a registry.
:::
OpenTF providers installed from the Registry are cryptographically signed, and the signature is verified at time of installation. There are three types of provider signatures, each with different trust implications:

4
website/docs/cli/state/index.mdx
View File

@ -25,7 +25,9 @@ OpenTF CLI supports several workflows for interacting with state:
[Importing Infrastructure](/docs/cli/import) section)
- [Disaster Recovery](/docs/cli/state/recover)
~> **Important:** Modifying state data outside a normal plan or apply can cause
:::warning Important
Modifying state data outside a normal plan or apply can cause
OpenTF to lose track of managed resources, which might waste money, annoy
your colleagues, or even compromise the security of your operations. Make sure
to keep backups of your state data when modifying state out-of-band.
:::

4
website/docs/internals/debugging.mdx
View File

@ -13,7 +13,9 @@ You can set `TF_LOG` to one of the log levels (in order of decreasing verbosity)
Setting `TF_LOG` to `JSON` outputs logs at the `TRACE` level or higher, and uses a parseable JSON encoding as the formatting.
~> **Warning:** The JSON encoding of log files is not considered a stable interface. It may change at any time, without warning. It is meant to support tooling that will be forthcoming, and that tooling is the only supported way to interact with JSON formatted logs.
:::warning
The JSON encoding of log files is not considered a stable interface. It may change at any time, without warning. It is meant to support tooling that will be forthcoming, and that tooling is the only supported way to interact with JSON formatted logs.
:::
Logging can be enabled separately for opentf itself and the provider plugins
using the `TF_LOG_CORE` or `TF_LOG_PROVIDER` environment variables. These take

4
website/docs/internals/graph.mdx
View File

@ -15,11 +15,13 @@ generate plans, refresh state, and more. This page documents
the details of what are contained in this graph, what types
of nodes there are, and how the edges of the graph are determined.
~> **Advanced Topic!** This page covers technical details
:::warning Advanced Topic!
This page covers technical details
of OpenTF. You don't need to understand these details to
effectively use OpenTF. The details are documented here for
those who wish to learn about them without having to go
spelunking through the source code.
:::
For some background on graph theory, and a summary of how
OpenTF applies it, see the HashiCorp 2016 presentation

4
website/docs/internals/index.mdx
View File

@ -12,6 +12,8 @@ of this section is to remove any notion of "magic" from OpenTF.
We want you to be able to trust and understand what OpenTF is
doing to function.
-> **Note:** Knowledge of OpenTF internals is not
:::note
Knowledge of OpenTF internals is not
required to use OpenTF. If you aren't interested in the internals
of OpenTF, you may safely skip this section.
:::

8
website/docs/internals/json-format.mdx
View File

@ -523,7 +523,9 @@ Each unevaluated expression in the configuration is represented with an `<expres
}
```
-> **Note:** Expressions in `dynamic` blocks are not included in the configuration representation.
:::note
Expressions in `dynamic` blocks are not included in the configuration representation.
:::
### Block Expressions Representation
@ -614,9 +616,11 @@ A `<change-representation>` describes the change to the indicated object.
## Checks Representation
~> **Warning:** The JSON representation of checks is experimental
:::warning
The JSON representation of checks is experimental
and some details may change in future OpenTF versions based on feedback,
even in minor releases of OpenTF CLI.
:::
A `<checks-representation>` describes the current state of a checkable object in the configuration. For example, a resource with one or more preconditions or postconditions is an example of a checkable object, and its check state represents the results of those conditions.

4
website/docs/internals/login-protocol.mdx
View File

@ -6,10 +6,12 @@ description: >-
# Server-side Login Protocol
~> **Note:** You don't need to read these docs to _use_
:::warning Note
You don't need to read these docs to _use_
[`opentf login`](/docs/cli/commands/login). The information below is for
anyone intending to implement the server side of `opentf login` in order to
offer OpenTF-native services in a third-party system.
:::
The `opentf login` command supports performing an OAuth 2.0 authorization
request using configuration provided by the target host. You may wish to

8
website/docs/internals/provider-meta.mdx
View File

@ -22,17 +22,21 @@ statistics for each module via the provider. For that reason, this
documentation is presented from the perspective of the provider developer
rather than the module developer.
~> **Advanced Topic!** This page covers technical details
:::warning Advanced Topic!
This page covers technical details
of OpenTF. You don't need to understand these details to
effectively use OpenTF. The details are documented here for
module authors and provider developers working on advanced
functionality.
:::
~> **Experimental Feature!** This functionality is still considered
:::warning Experimental Feature!
This functionality is still considered
experimental, and anyone taking advantage of it should [coordinate
with the OpenTF team](https://github.com/placeholderplaceholderplaceholder/opentf/issues/new)
to help the team understand how the feature is being used and to make
sure their use case is taken into account as the feature develops.
:::
## Defining the Schema

7
website/docs/intro/index.mdx
View File

@ -1,8 +1,9 @@
---
sidebar_position: 1
description: |-
OpenTF is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently.
OpenTF is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently.
---
# What is OpenTF?
OpenTF is an infrastructure as code tool that lets you define both cloud and on-prem resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to provision and manage all of your infrastructure throughout its lifecycle. OpenTF can manage low-level components like compute, storage, and networking resources, as well as high-level components like DNS entries and SaaS features.
@ -45,7 +46,9 @@ OpenTF supports reusable configuration components called [modules](/docs/languag
Since your configuration is written in a file, you can commit it to a Version Control System (VCS) and use a cloud backend to efficiently manage OpenTF workflows across teams. A cloud backend runs OpenTF in a consistent, reliable environment and provides secure access to shared state and secret data, role-based access controls, a private registry for sharing both modules and providers, and more.
-> **Tip:** Learn more about [OpenTF use cases](/docs/intro/use-cases) and [how OpenTF compares to alternatives](/docs/intro/vs).
:::note Tip
Learn more about [OpenTF use cases](/docs/intro/use-cases) and [how OpenTF compares to alternatives](/docs/intro/vs).
:::
## Community

4
website/docs/language/attr-as-blocks.mdx
View File

@ -8,7 +8,9 @@ description: >-
# Attributes as Blocks
-> **Note:** This page is an appendix to the OpenTF documentation. Most users do not need to know the full details of this behavior.
:::note
This page is an appendix to the OpenTF documentation. Most users do not need to know the full details of this behavior.
:::
## Summary

4
website/docs/language/expressions/references.mdx
View File

@ -177,10 +177,12 @@ where they appear. Some of most common local names are:
* `self`, in [provisioner](/docs/language/resources/provisioners/syntax) and
[connection](/docs/language/resources/provisioners/connection) blocks.
-> **Note:** Local names are often referred to as _variables_ or
:::note
Local names are often referred to as _variables_ or
_temporary variables_ in their documentation. These are not [input
variables](/docs/language/values/variables); they are just arbitrary names
that temporarily represent a value.
:::
The names in this section relate to top-level configuration blocks only.
If you use [`dynamic` blocks](/docs/language/expressions/dynamic-blocks) to dynamically generate

8
website/docs/language/expressions/type-constraints.mdx
View File

@ -95,7 +95,9 @@ The three kinds of collection type in the OpenTF language are:
for single line maps. A newline between key/value pairs is sufficient
in multi-line maps.
-> **Note:** Although colons are valid delimiters between keys and values, `opentf fmt` ignores them. In contrast, `opentf fmt` attempts to vertically align equals signs.
:::note
Although colons are valid delimiters between keys and values, `opentf fmt` ignores them. In contrast, `opentf fmt` attempts to vertically align equals signs.
:::
* `set(...)`: a collection of unique values that do not have any secondary
identifiers or ordering.
@ -207,9 +209,11 @@ will raise a type mismatch error, since a tuple cannot be converted to a string.
## Dynamic Types: The "any" Constraint
~> **Warning:** `any` is very rarely the correct type constraint to use.
:::warning
`any` is very rarely the correct type constraint to use.
**Do not use `any` just to avoid specifying a type constraint**. Always write an
exact type constraint unless you are truly handling dynamic data.
:::
The keyword `any` is a special construct that serves as a placeholder for a
type yet to be decided. `any` is not _itself_ a type: when interpreting a

4
website/docs/language/functions/can.mdx
View File

@ -37,11 +37,13 @@ access to data that isn't known until runtime. It will not catch errors
relating to expressions that can be proven to be invalid for any input, such
as a malformed resource reference.
~> **Warning:** The `can` function is intended only for simple tests in
:::warning
The `can` function is intended only for simple tests in
variable validation rules. Although it can technically accept any sort of
expression and be used elsewhere in the configuration, we recommend against
using it in other contexts. For error handling elsewhere in the configuration,
prefer to use [`try`](/docs/language/functions/try).
:::
## Examples

4
website/docs/language/functions/cidrhost.mdx
View File

@ -32,10 +32,12 @@ situations, such as point-to-point links.
This function accepts both IPv6 and IPv4 prefixes, and the result always uses
the same addressing scheme as the given prefix.
-> **Note:** As a historical accident, this function interprets IPv4 address
:::note
As a historical accident, this function interprets IPv4 address
octets that have leading zeros as decimal numbers, which is contrary to some
other systems which interpret them as octal. We have preserved this behavior
for backward compatibility, but recommend against relying on this behavior.
:::
## Examples

4
website/docs/language/functions/cidrnetmask.mdx
View File

@ -23,10 +23,12 @@ IPv4 address syntax, as expected by some software.
CIDR notation is the only valid notation for IPv6 addresses, so `cidrnetmask`
produces an error if given an IPv6 address.
-> **Note:** As a historical accident, this function interprets IPv4 address
:::note
As a historical accident, this function interprets IPv4 address
octets that have leading zeros as decimal numbers, which is contrary to some
other systems which interpret them as octal. We have preserved this behavior
for backward compatibility, but recommend against relying on this behavior.
:::
## Examples

4
website/docs/language/functions/cidrsubnet.mdx
View File

@ -32,10 +32,12 @@ allows you to give a specific network number to use. `cidrsubnets` can allocate
multiple network addresses at once, but numbers them automatically starting
with zero.
-> **Note:** As a historical accident, this function interprets IPv4 address
:::note
As a historical accident, this function interprets IPv4 address
octets that have leading zeros as decimal numbers, which is contrary to some
other systems which interpret them as octal. We have preserved this behavior
for backward compatibility, but recommend against relying on this behavior.
:::
## Examples

8
website/docs/language/functions/cidrsubnets.mdx
View File

@ -37,16 +37,20 @@ existing calls safely, as long as there is sufficient address space available.
This function accepts both IPv6 and IPv4 prefixes, and the result always uses
the same addressing scheme as the given prefix.
-> **Note:** As a historical accident, this function interprets IPv4 address
:::note
As a historical accident, this function interprets IPv4 address
octets that have leading zeros as decimal numbers, which is contrary to some
other systems which interpret them as octal. We have preserved this behavior
for backward compatibility, but recommend against relying on this behavior.
:::
-> **Note:** [The `hashicorp/subnets/cidr` module](https://registry.terraform.io/modules/hashicorp/subnets/cidr)
:::note
[The `hashicorp/subnets/cidr` module](https://registry.terraform.io/modules/hashicorp/subnets/cidr)
wraps `cidrsubnets` to provide additional functionality for assigning symbolic
names to your networks and skipping prefixes for obsolete allocations. Its
documentation includes usage examples for several popular cloud virtual network
platforms.
:::
## Examples

4
website/docs/language/functions/format.mdx
View File

@ -121,9 +121,11 @@ The following examples demonstrate example use cases for the width modifier.
| `%.2f` | Default width, precision 2. |
| `%9.2f` | Width 9, precision 2. |
-> **Note:** Width and precision modifiers with non-numeric types such as
:::note
Width and precision modifiers with non-numeric types such as
strings (`%s`) are interpreted differently. Setting either width or precision to
zero is the same as not including them at all.
:::
### Additional Format Options

4
website/docs/language/functions/lookup.mdx
View File

@ -12,9 +12,11 @@ If the given key does not exist, the given default value is returned instead.
lookup(map, key, default)
```
-> For historical reasons, the `default` parameter is actually optional. However,
:::note
For historical reasons, the `default` parameter is actually optional. However,
omitting `default` is deprecated since v0.7 because that would then be
equivalent to the native index syntax, `map[key]`.
:::
## Examples

4
website/docs/language/functions/nonsensitive.mdx
View File

@ -10,11 +10,13 @@ description: >-
`nonsensitive` takes a sensitive value and returns a copy of that value with
the sensitive marking removed, thereby exposing the sensitive value.
~> **Warning:** Using this function indiscriminately will cause values that
:::warning
Using this function indiscriminately will cause values that
OpenTF would normally have considered as sensitive to be treated as normal
values and shown clearly in OpenTF's output. Use this function only when
you've derived a new value from a sensitive value in a way that eliminates the
sensitive portions of the value.
:::
Normally OpenTF tracks when you use expressions to derive a new value from
a value that is marked as sensitive, so that the result can also be marked

4
website/docs/language/functions/try.mdx
View File

@ -73,12 +73,14 @@ access to data that isn't known until runtime. It will not catch errors
relating to expressions that can be proven to be invalid for any input, such
as a malformed resource reference.
~> **Warning:** The `try` function is intended only for concise testing of the
:::warning
The `try` function is intended only for concise testing of the
presence of and types of object attributes. Although it can technically accept
any sort of expression, we recommend using it only with simple attribute
references and type conversion functions as shown in the examples above.
Overuse of `try` to suppress errors will lead to a configuration that is hard
to understand and maintain.
:::
## Examples

4
website/docs/language/import/generating-configuration.mdx
View File

@ -5,7 +5,9 @@ description: >-
# Generating configuration
~> **Experimental:** Configuration generation is available in OpenTF v1.6 as an experimental feature. Later minor versions may contain changes to the formatting of generated configuration and behavior of the `opentf plan` command using the `-generate-config-out` flag.
:::warning Experimental
Configuration generation is available in OpenTF v1.6 as an experimental feature. Later minor versions may contain changes to the formatting of generated configuration and behavior of the `opentf plan` command using the `-generate-config-out` flag.
:::
OpenTF can generate code for the resources you define in [`import` blocks](/docs/language/import) that do not already exist in your configuration. OpenTF produces HCL to act as a template that contains OpenTF's best guess at the appropriate value for each resource argument.

4
website/docs/language/import/index.mdx
View File

@ -5,7 +5,9 @@ description: >-
# Import
~> **Experimental:** While we do not expect to make backwards-incompatible changes to syntax, the `-generate-config-out` flag and how OpenTF processes imports during the plan stage and generates configuration may change in future releases.
:::warning Experimental
While we do not expect to make backwards-incompatible changes to syntax, the `-generate-config-out` flag and how OpenTF processes imports during the plan stage and generates configuration may change in future releases.
:::
Use the `import` block to import existing infrastructure resources into OpenTF, bringing them under OpenTF's management. Unlike the `opentf import` command, configuration-driven import using `import` blocks is predictable, works with CICD pipelines, and lets you preview an import operation before modifying state.

8
website/docs/language/meta-arguments/count.mdx
View File

@ -6,7 +6,9 @@ description: >-
# The `count` Meta-Argument
-> **Note:** A given resource or module block cannot use both `count` and `for_each`.
:::note
A given resource or module block cannot use both `count` and `for_each`.
:::
By default, a [resource block](/docs/language/resources/syntax) configures one real
infrastructure object. (Similarly, a
@ -79,9 +81,11 @@ with `module.<NAME>[<KEY>]` when displayed in plan output and elsewhere in the U
For a module without `count` or `for_each`, the address will not contain
the module index as the module's name suffices to reference the module.
-> **Note:** Within nested `provisioner` or `connection` blocks, the special
:::note
Within nested `provisioner` or `connection` blocks, the special
`self` object refers to the current _resource instance,_ not the resource block
as a whole.
:::
## When to Use `for_each` Instead of `count`

8
website/docs/language/meta-arguments/for_each.mdx
View File

@ -19,7 +19,9 @@ If a resource or module block includes a `for_each` argument whose value is a ma
a set of strings, OpenTF creates one instance for each member of
that map or set.
-> **Note:** A given resource or module block cannot use both `count` and `for_each`.
:::note
A given resource or module block cannot use both `count` and `for_each`.
:::
## Basic Syntax
@ -213,9 +215,11 @@ with `module.<NAME>[<KEY>]` when displayed in plan output and elsewhere in the U
For a module without `count` or `for_each`, the address will not contain
the module index as the module's name suffices to reference the module.
-> **Note:** Within nested `provisioner` or `connection` blocks, the special
:::note
Within nested `provisioner` or `connection` blocks, the special
`self` object refers to the current _resource instance,_ not the resource block
as a whole.
:::
## Using Sets

4
website/docs/language/modules/develop/providers.mdx
View File

@ -129,7 +129,9 @@ resource "aws_s3_bucket" "example" {
We recommend using this approach when a single configuration for each provider
is sufficient for an entire configuration.
~> **Note:** Only provider configurations are inherited by child modules, not provider source or version requirements. Each module must [declare its own provider requirements](/docs/language/providers/requirements). This is especially important for non-HashiCorp providers.
:::warning Note
Only provider configurations are inherited by child modules, not provider source or version requirements. Each module must [declare its own provider requirements](/docs/language/providers/requirements). This is especially important for non-HashiCorp providers.
:::
In more complex situations there may be
[multiple provider configurations](/docs/language/providers/configuration#alias-multiple-provider-configurations),

4
website/docs/language/modules/develop/refactoring.mdx
View File

@ -188,11 +188,13 @@ moved {
}
```
-> **Note:** When you add `count` to an existing resource that didn't use it,
:::note
When you add `count` to an existing resource that didn't use it,
OpenTF automatically proposes to move the original object to instance zero,
unless you write an `moved` block explicitly mentioning that resource.
However, we recommend still writing out the corresponding `moved` block
explicitly, to make the change clearer to future readers of the module.
:::
## Renaming a Module Call

8
website/docs/language/modules/sources.mdx
View File

@ -372,10 +372,12 @@ module "vpc" {
}
```
-> **Note:** If the content of the archive file is a directory, you will need to
:::note
If the content of the archive file is a directory, you will need to
include that directory in the module source. Read the section on
[Modules in Package Sub-directories](#modules-in-package-sub-directories) for more
information.
:::
## S3 Bucket
@ -389,7 +391,9 @@ module "consul" {
}
```
-> **Note:** Buckets in AWS's us-east-1 region must use the hostname `s3.amazonaws.com` (instead of `s3-us-east-1.amazonaws.com`).
:::note
Buckets in AWS's us-east-1 region must use the hostname `s3.amazonaws.com` (instead of `s3-us-east-1.amazonaws.com`).
:::
The `s3::` prefix causes OpenTF to use AWS-style authentication when
accessing the given URL. As a result, this scheme may also work for other

4
website/docs/language/providers/configuration.mdx
View File

@ -182,8 +182,8 @@ from their parents.
<a id="provider-versions"></a>
## `version` (Deprecated)
{/* TODO: Figure out the best way to link to this, or remove the deprecated setting documentation completely */}
{/* lint ignore remark-lint-no-undefined-references */}
<!-- TODO: Figure out the best way to link to this, or remove the deprecated setting documentation completely -->
<!-- lint ignore remark-lint-no-undefined-references -->
[inpage-versions]: #provider-versions

4
website/docs/language/providers/requirements.mdx
View File

@ -132,10 +132,12 @@ version is used. This display version omits the source host when it is the
public registry, so you may see the shortened version `"hashicorp/random"` instead
of `"registry.terraform.io/hashicorp/random"`.
-> **Note:** If you omit the `source` argument when requiring a provider,
:::note
If you omit the `source` argument when requiring a provider,
OpenTF uses an implied source address of
`registry.terraform.io/hashicorp/<LOCAL NAME>`.
We recommend using explicit source addresses for all providers.
:::
### Handling Local Name Conflicts

4
website/docs/language/resources/provisioners/connection.mdx
View File

@ -9,8 +9,10 @@ description: >-
Most provisioners require access to the remote resource via SSH or WinRM and
expect a nested `connection` block with details about how to connect.
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
:::warning Important
Use provisioners as a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details.
:::
## Connection Block

8
website/docs/language/resources/provisioners/file.mdx
View File

@ -11,8 +11,10 @@ The `file` provisioner copies files or directories from the machine
running OpenTF to the newly created resource. The `file` provisioner
supports both `ssh` and `winrm` type [connections](/docs/language/resources/provisioners/connection).
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
:::warning Important
Use provisioners as a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details.
:::
## Example usage
@ -46,7 +48,9 @@ resource "aws_instance" "web" {
}
```
-> **Note:** When the `file` provisioner communicates with a Windows system over SSH, you must configure OpenSSH to run the commands with `cmd.exe` and not PowerShell. PowerShell causes file parsing errors because it is incompatible with both Unix shells and the Windows command interpreter.
:::note
When the `file` provisioner communicates with a Windows system over SSH, you must configure OpenSSH to run the commands with `cmd.exe` and not PowerShell. PowerShell causes file parsing errors because it is incompatible with both Unix shells and the Windows command interpreter.
:::
## Argument Reference

4
website/docs/language/resources/provisioners/local-exec.mdx
View File

@ -17,8 +17,10 @@ Note that even though the resource will be fully created when the provisioner is
run, there is no guarantee that it will be in an operable state - for example
system services such as `sshd` may not be started yet on compute resources.
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
:::warning Important
Use provisioners as a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details.
:::
## Example usage

4
website/docs/language/resources/provisioners/null_resource.mdx
View File

@ -17,8 +17,10 @@ and [connection details](/docs/language/resources/provisioners/connection) on a
meta-arguments to control exactly where in the dependency graph its
provisioners will run.
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
:::warning Important
Use provisioners as a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details.
:::
## Example usage

8
website/docs/language/resources/provisioners/remote-exec.mdx
View File

@ -16,8 +16,10 @@ into a cluster, etc. To invoke a local process, see the `local-exec`
provisioner requires a [connection](/docs/language/resources/provisioners/connection)
and supports both `ssh` and `winrm`.
~> **Important:** Use provisioners as a last resort. There are better alternatives for most situations. Refer to
:::warning Important
Use provisioners as a last resort. There are better alternatives for most situations. Refer to
[Declaring Provisioners](/docs/language/resources/provisioners/syntax) for more details.
:::
## Example usage
@ -59,7 +61,9 @@ The following arguments are supported:
that will be copied to the remote resource and then executed. They are executed
in the order they are provided. This cannot be provided with `inline` or `script`.
-> **Note:** Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/docs/language/resources/provisioners/syntax#failure-behavior) applies only to the final command in the list. In particular, with `on_failure = fail` (the default behaviour) earlier commands will be allowed to fail, and later commands will also execute. If this behaviour is not desired, consider using `"set -o errexit"` as the first command.
:::note
Since `inline` is implemented by concatenating commands into a script, [`on_failure`](/docs/language/resources/provisioners/syntax#failure-behavior) applies only to the final command in the list. In particular, with `on_failure = fail` (the default behaviour) earlier commands will be allowed to fail, and later commands will also execute. If this behaviour is not desired, consider using `"set -o errexit"` as the first command.
:::
## Script Arguments

16
website/docs/language/resources/provisioners/syntax.mdx
View File

@ -170,9 +170,11 @@ bootstrap a resource, cleanup before destroy, run configuration management, etc.
## How to use Provisioners
-> **Note:** Provisioners should only be used as a last resort. For most
:::note
Provisioners should only be used as a last resort. For most
common situations there are better alternatives. For more information, see
the sections above.
:::
If you are certain that provisioners are the best way to solve your problem
after considering the advice in the sections above, you can add a
@ -211,9 +213,11 @@ The `self` object represents the provisioner's parent resource, and has all of
that resource's attributes. For example, use `self.public_ip` to reference an
`aws_instance`'s `public_ip` attribute.
-> **Technical note:** Resource references are restricted here because
:::note Technical note
Resource references are restricted here because
references create dependencies. Referring to a resource by name within its own
block would create a dependency cycle.
:::
## Suppressing Provisioner Logs in CLI Output
@ -261,7 +265,9 @@ fail, OpenTF will error and rerun the provisioners again on the next
`opentf apply`. Due to this behavior, care should be taken for destroy
provisioners to be safe to run multiple times.
~> **Note**: Destroy provisioners of this resource do not run if `create_before_destroy` is set to `true`.
:::warning Note
Destroy provisioners of this resource do not run if `create_before_destroy` is set to `true`.
:::
Destroy-time provisioners can only run if they remain in the configuration
at the time a resource is destroyed. If a resource block with a destroy-time
@ -277,7 +283,9 @@ remove a resource with a destroy-time provisioner:
Because of this limitation, you should use destroy-time provisioners sparingly and with care.
~> **NOTE:** A destroy-time provisioner within a resource that is tainted _will not_ run. This includes resources that are marked tainted from a failed creation-time provisioner or tainted manually using `opentf taint`.
:::warning Note
A destroy-time provisioner within a resource that is tainted _will not_ run. This includes resources that are marked tainted from a failed creation-time provisioner or tainted manually using `opentf taint`.
:::
## Multiple Provisioners

8
website/docs/language/resources/syntax.mdx
View File

@ -39,8 +39,10 @@ for the resource itself. Most arguments in this section depend on the
resource type, and indeed in this example both `ami` and `instance_type` are
arguments defined specifically for [the `aws_instance` resource type](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/instance).
-> **Note:** Resource names must start with a letter or underscore, and may
:::note
Resource names must start with a letter or underscore, and may
contain only letters, digits, underscores, and dashes.
:::
## Resource Types
@ -103,9 +105,11 @@ documentation you are viewing.
To browse the publicly available providers and their documentation, see the
[Public Terraform Registry](https://registry.terraform.io/browse/providers).
-> **Note:** Provider documentation previously existed as part of OpenTF's core documentation. Although some provider documentation
:::note
Provider documentation previously existed as part of OpenTF's core documentation. Although some provider documentation
might still be hosted here, the Public Terraform Registry is now the main home for all
public provider docs.
:::
## Resource Behavior

25
website/docs/language/settings/backends/azurerm.mdx
View File

@ -77,7 +77,9 @@ terraform {
}
```
-> **Note:** When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned.
:::note
When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned.
:::
***
@ -115,7 +117,9 @@ terraform {
}
```
-> **NOTE:** When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/docs/language/settings/backends/configuration#partial-configuration) for the credentials.
:::note
When using a Service Principal or an Access Key - we recommend using a [Partial Configuration](/docs/language/settings/backends/configuration#partial-configuration) for the credentials.
:::
## Data Source Configuration
@ -188,7 +192,9 @@ data "terraform_remote_state" "foo" {
}
```
-> **Note:** When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned.
:::note
When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned.
:::
***
@ -230,8 +236,9 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options are supported:
@ -245,7 +252,9 @@ The following configuration options are supported:
* `endpoint` - (Optional) The Custom Endpoint for Azure Resource Manager. This can also be sourced from the `ARM_ENDPOINT` environment variable.
~> **NOTE:** An `endpoint` should only be configured when using Azure Stack.
:::warning Note
An `endpoint` should only be configured when using Azure Stack.
:::
* `metadata_host` - (Optional) The Hostname of the Azure Metadata Service (for example `management.azure.com`), used to obtain the Cloud Environment when using a Custom Azure Environment. This can also be sourced from the `ARM_METADATA_HOSTNAME` Environment Variable.
@ -297,7 +306,9 @@ When authenticating using AzureAD Authentication - the following fields are also
* `use_azuread_auth` - (Optional) Should AzureAD Authentication be used to access the Blob Storage Account. This can also be sourced from the `ARM_USE_AZUREAD` environment variable.
-> **Note:** When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned.
:::note
When using AzureAD for Authentication to Storage you also need to ensure the `Storage Blob Data Owner` role is assigned.
:::
***

8
website/docs/language/settings/backends/configuration.mdx
View File

@ -47,7 +47,9 @@ There are some important limitations on backend configuration:
Backends store state in a remote service, which allows multiple people to access it. Accessing remote state generally requires access credentials, since state data contains extremely sensitive information.
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. This can leak sensitive credentials.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. This can leak sensitive credentials.
:::
OpenTF writes the backend configuration in plain text in two separate files.
- The `.terraform/terraform.tfstate` file contains the backend configuration for the current working directory.
@ -83,8 +85,10 @@ When you change backends, OpenTF gives you the option to migrate
your state to the new backend. This lets you adopt backends without losing
any existing state.
~> **Important:** Before migrating to a new backend, we strongly recommend manually backing up your state by copying your `terraform.tfstate` file
:::warning Important
Before migrating to a new backend, we strongly recommend manually backing up your state by copying your `terraform.tfstate` file
to another location.
:::
## Partial Configuration

4
website/docs/language/settings/backends/consul.mdx
View File

@ -37,7 +37,9 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options / environment variables are supported:

8
website/docs/language/settings/backends/cos.mdx
View File

@ -14,8 +14,10 @@ This backend supports [state locking](/docs/language/state/locking). Storing you
- `CreateTag`, `DeleteTag`, and `DescribeTags` on the tag key `tencentcloud-terraform-lock`
- `Put`, `Get`, and `Delete` files for the specified bucket's prefix
~> **Warning!** It is highly recommended that you enable [Object Versioning](https://intl.cloud.tencent.com/document/product/436/19883)
:::warning
It is highly recommended that you enable [Object Versioning](https://intl.cloud.tencent.com/document/product/436/19883)
on the COS bucket to allow for state recovery in the case of accidental deletions and human error.
:::
## Example Configuration
@ -50,7 +52,9 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options or environment variables are supported:

20
website/docs/language/settings/backends/gcs.mdx
View File

@ -12,9 +12,11 @@ The bucket must exist prior to configuring the backend.
This backend supports [state locking](/docs/language/state/locking).
~> **Warning!** It is highly recommended that you enable
:::warning
It is highly recommended that you enable
[Object Versioning](https://cloud.google.com/storage/docs/object-versioning)
on the GCS bucket to allow for state recovery in the case of accidental deletions and human error.
:::
## Example Configuration
@ -72,7 +74,9 @@ OpenTF can impersonate a Google Service Account as described [here](https://clou
## Encryption
!> **Warning:** Take care of your encryption keys because state data encrypted with a lost or deleted key is not recoverable. If you use customer-supplied encryption keys, you must securely manage your keys and ensure you do not lose them. You must not delete customer-managed encryption keys in Cloud KMS used to encrypt state. However, if you accidentally delete a key, there is a time window where [you can recover it](https://cloud.google.com/kms/docs/destroy-restore#restore).
:::danger Warning
Take care of your encryption keys because state data encrypted with a lost or deleted key is not recoverable. If you use customer-supplied encryption keys, you must securely manage your keys and ensure you do not lose them. You must not delete customer-managed encryption keys in Cloud KMS used to encrypt state. However, if you accidentally delete a key, there is a time window where [you can recover it](https://cloud.google.com/kms/docs/destroy-restore#restore).
:::
### Customer-supplied encryption keys
@ -80,7 +84,9 @@ To get started, follow this guide: [Use customer-supplied encryption keys](https
If you want to remove customer-supplied keys from your backend configuration or change to a different customer-supplied key, OpenTF cannot perform a state migration automatically and manual intervention is necessary instead. This intervention is necessary because Google does not store customer-supplied encryption keys, any requests sent to the Cloud Storage API must supply them instead (see [Customer-supplied Encryption Keys](https://cloud.google.com/storage/docs/encryption/customer-supplied-keys)). At the time of state migration, the backend configuration loses the old key's details and OpenTF cannot use the key during the migration process.
~> **Important:** To migrate your state away from using customer-supplied encryption keys or change the key used by your backend, you need to perform a [rewrite (gsutil CLI)](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) or [cp (gcloud CLI)](https://cloud.google.com/sdk/gcloud/reference/storage/cp#--decryption-keys) operation to remove use of the old customer-supplied encryption key on your state file. Once you remove the encryption, you can successfully run `opentf init -migrate-state` with your new backend configuration.
:::warning Important
To migrate your state away from using customer-supplied encryption keys or change the key used by your backend, you need to perform a [rewrite (gsutil CLI)](https://cloud.google.com/storage/docs/gsutil/commands/rewrite) or [cp (gcloud CLI)](https://cloud.google.com/sdk/gcloud/reference/storage/cp#--decryption-keys) operation to remove use of the old customer-supplied encryption key on your state file. Once you remove the encryption, you can successfully run `opentf init -migrate-state` with your new backend configuration.
:::
### Customer-managed encryption keys (Cloud KMS)
@ -90,11 +96,15 @@ If you want to remove customer-managed keys from your backend configuration or c
Customer-managed keys do not need to be sent in requests to read files from GCS buckets because decryption occurs automatically within GCS. This process means that if you use the `terraform_remote_state` [data source](/docs/language/state/remote-state-data) to access KMS-encrypted state, you do not need to specify the KMS key in the data source's `config` object.
~> **Important:** To use customer-managed encryption keys, you need to create a key and give your project's GCS service agent permission to use it with the Cloud KMS CryptoKey Encrypter/Decrypter predefined role.
:::warning Important
To use customer-managed encryption keys, you need to create a key and give your project's GCS service agent permission to use it with the Cloud KMS CryptoKey Encrypter/Decrypter predefined role.
:::
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF includes these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF includes these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options are supported:

4
website/docs/language/settings/backends/http.mdx
View File

@ -40,7 +40,9 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options / environment variables are supported:

8
website/docs/language/settings/backends/kubernetes.mdx
View File

@ -5,7 +5,9 @@ description: OpenTF can store state remotely in Kubernetes and lock that state.
# Backend Type: kubernetes
-> **Note:** This backend is limited by Kubernetes' maximum Secret size of 1MB. See [Secret restrictions](https://kubernetes.io/docs/concepts/configuration/secret/#restrictions) for details.
:::note
This backend is limited by Kubernetes' maximum Secret size of 1MB. See [Secret restrictions](https://kubernetes.io/docs/concepts/configuration/secret/#restrictions) for details.
:::
Stores the state in a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/).
@ -46,7 +48,9 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options are supported:

4
website/docs/language/settings/backends/local.mdx
View File

@ -44,8 +44,10 @@ The following configuration options are supported:
## Command Line Arguments
~> This section describes legacy features that we've preserved for backward
:::warning Note
This section describes legacy features that we've preserved for backward
compatibility but that we no longer recommend. See below for more details.
:::
For configurations that include a `backend "local"` block or that default to
the local backend by not specifying a backend at all, most commands that either

8
website/docs/language/settings/backends/oss.mdx
View File

@ -69,7 +69,9 @@ data "terraform_remote_state" "network" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options or environment variables are supported:
@ -130,4 +132,6 @@ The following configuration options or environment variables are supported:
* `session_expiration` - (Optional) The time after which the established session for assuming role expires. Valid value range: \[900-3600] seconds. Default to 3600 (in this case Alibaba Cloud uses its own default value). It supports environment variable `ALICLOUD_ASSUME_ROLE_SESSION_EXPIRATION`.
-> **Note:** If you want to store state in the custom OSS endpoint, you can specify an environment variable `OSS_ENDPOINT`, like "oss-cn-beijing-internal.aliyuncs.com"
:::note
If you want to store state in the custom OSS endpoint, you can specify an environment variable `OSS_ENDPOINT`, like "oss-cn-beijing-internal.aliyuncs.com"
:::

4
website/docs/language/settings/backends/pg.mdx
View File

@ -82,7 +82,9 @@ data "terraform_remote_state" "network" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options or environment variables are supported:

16
website/docs/language/settings/backends/remote.mdx
View File

@ -7,7 +7,9 @@ description: >-
# Backend Type: remote
-> **Note:** **We recommend using the [`cloud` built-in integration](/docs/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features.
:::note
**We recommend using the [`cloud` built-in integration](/docs/cli/cloud/settings)** instead of this backend. The `cloud` option includes an improved user experience and more features.
:::
The remote backend is unique among all other OpenTF backends because it can both store state snapshots and execute operations for TACOS (TF Automation and Collaboration Software) [CLI-driven run workflow](/docs/cloud-docs/run/cli). It used to be called an "enhanced" backend.
@ -94,9 +96,11 @@ output "remote_execution_determine" {
## Example Configurations
-> **Note:** We recommend omitting the token from the configuration, and instead using
:::note
We recommend omitting the token from the configuration, and instead using
[`opentf login`](/docs/cli/commands/login) or manually configuring
`credentials` in the [CLI config file](/docs/cli/config/config-file#credentials).
:::
### Basic Configuration
@ -170,7 +174,9 @@ data "terraform_remote_state" "foo" {
## Configuration Variables
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration options are supported:
@ -193,9 +199,11 @@ The following configuration options are supported:
(minus the prefix) are used on the command line for OpenTF CLI workspaces.
If omitted, only the default workspace can be used. This option conflicts with `name`.
-> **Note:** You must use the `name` key when configuring a `terraform_remote_state`
:::note
You must use the `name` key when configuring a `terraform_remote_state`
data source that retrieves state from another remote workspace. The `prefix` key is only
intended for use when configuring an instance of the remote backend.
:::
## Command Line Arguments

12
website/docs/language/settings/backends/s3.mdx
View File

@ -12,9 +12,11 @@ This backend also supports state locking and consistency checking via
the `dynamodb_table` field to an existing DynamoDB table name.
A single DynamoDB table can be used to lock multiple remote state files. OpenTF generates key names that include the values of the `bucket` and `key` variables.
~> **Warning!** It is highly recommended that you enable
:::warning
It is highly recommended that you enable
[Bucket Versioning](https://docs.aws.amazon.com/AmazonS3/latest/userguide/manage-versioning-examples.html)
on the S3 bucket to allow for state recovery in the case of accidental deletions and human error.
:::
## Example Configuration
@ -64,12 +66,14 @@ This is seen in the following AWS IAM Statement:
}
```
-> **Note:** AWS can control access to S3 buckets with either IAM policies
:::note
AWS can control access to S3 buckets with either IAM policies
attached to users/groups/roles (like the example above) or resource policies
attached to bucket objects (which look similar but also require a `Principal` to
indicate which entity has those permissions). For more details, see Amazon's
documentation about
[S3 access control](https://docs.aws.amazon.com/AmazonS3/latest/userguide/s3-access-control.html).
:::
### DynamoDB Table Permissions
@ -143,7 +147,9 @@ This backend requires the configuration of the AWS Region and S3 state storage.
### Credentials and Shared Configuration
!> **Warning:** We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::danger Warning
We recommend using environment variables to supply credentials and other sensitive data. If you use `-backend-config` or hardcode these values directly in your configuration, OpenTF will include these values in both the `.terraform` subdirectory and in plan files. Refer to [Credentials and Sensitive Data](/docs/language/settings/backends/configuration#credentials-and-sensitive-data) for details.
:::
The following configuration is required:

12
website/docs/language/state/remote-state-data.mdx
View File

@ -41,12 +41,14 @@ limited to) the following:
| Kubernetes | [`kubernetes_config_map` resource type](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/resources/config_map) | [`kubernetes_config_map` data source](https://registry.terraform.io/providers/hashicorp/kubernetes/latest/docs/data-sources/config_map) |
| OCI Object Storage | [`oci_objectstorage_bucket` resource type](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/resources/objectstorage_object) | [`oci_objectstorage_bucket` data source](https://registry.terraform.io/providers/hashicorp/oci/latest/docs/data-sources/objectstorage_object) |
-> These are some common options from the Official OpenTF providers, but
:::note
These are some common options from the Official OpenTF providers, but
there are too many configuration storage options for us to list them all
here, including some in partner and community providers.
Any pair of managed resource type and corresponding data source can potentially
be used to share data between OpenTF configurations. See individual provider
documentation to find other possibilities.
:::
A key advantage of using a separate explicit configuration store instead of
`terraform_remote_state` is that the data can potentially also be read by
@ -137,9 +139,11 @@ The following arguments are supported:
[the documentation of your chosen backend](/docs/language/settings/backends/configuration)
for details.
-> **Note:** If the backend configuration requires a nested block, specify
:::note
If the backend configuration requires a nested block, specify
it here as a normal attribute with an object value. (For example,
`workspaces = { ... }` instead of `workspaces { ... }`.)
:::
* `defaults` - (Optional; object) Default values for outputs, in case the state
file is empty or lacks a required output.
@ -177,10 +181,12 @@ available as the `app_value` root module output value. If this configuration
didn't include the `output "app_value"` block then the data would not be
accessible via `terraform_remote_state`.
~> **Warning:** Although `terraform_remote_state` doesn't expose any other
:::warning
Although `terraform_remote_state` doesn't expose any other
state snapshot information for use in configuration, the state snapshot data
is a single object and so any user or server which has enough access to read
the root module output values will also always have access to the full state
snapshot data by direct network requests. Don't use `terraform_remote_state`
if any of the resources in your configuration work with data that you consider
sensitive.
:::

4
website/docs/language/state/workspaces.mdx
View File

@ -29,7 +29,9 @@ You can use multiple workspaces with the following backends:
## Using Workspaces
~> **Important:** Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/docs/cli/workspaces#use-cases) in the OpenTF CLI documentation for details and recommended alternatives.
:::warning Important
Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls. Refer to [Use Cases](/docs/cli/workspaces#use-cases) in the OpenTF CLI documentation for details and recommended alternatives.
:::
OpenTF starts with a single, default workspace named `default` that you cannot delete. If you have not created a new workspace, you are using the default workspace in your OpenTF working directory.

4
website/docs/language/syntax/configuration.mdx
View File

@ -48,7 +48,8 @@ arguments), but many arguments accept arbitrary
[expressions](/docs/language/expressions), which allow the value to
either be specified literally or generated from other values programmatically.
-> **Note:** OpenTF's configuration language is based on a more general
:::note
OpenTF's configuration language is based on a more general
language called HCL, and HCL's documentation usually uses the word "attribute"
instead of "argument." These words are similar enough to be interchangeable in
this context, and experienced OpenTF users might use either term in casual
@ -57,6 +58,7 @@ called "attributes" (in particular, OpenTF resources have attributes like
`id` that can be referenced from expressions but can't be assigned values in
configuration), we've chosen to use "argument" in the OpenTF documentation
when referring to this syntax construct.
:::
### Blocks

4
website/docs/language/syntax/style.mdx
View File

@ -13,7 +13,9 @@ for consistency between files and modules written by different teams.
Automatic source code formatting tools may apply these conventions
automatically.
-> **Note**: You can enforce these conventions automatically by running [`opentf fmt`](/docs/cli/commands/fmt).
:::note
You can enforce these conventions automatically by running [`opentf fmt`](/docs/cli/commands/fmt).
:::
* Indent two spaces for each nesting level.

8
website/docs/language/values/locals.mdx
View File

@ -17,8 +17,10 @@ compare modules to function definitions:
- [Output values](/docs/language/values/outputs) are like function return values.
- Local values are like a function's temporary local variables.
-> **Note:** For brevity, local values are often referred to as just "locals"
:::note
For brevity, local values are often referred to as just "locals"
when the meaning is clear from context.
:::
## Declaring a Local Value
@ -56,9 +58,11 @@ locals {
Once a local value is declared, you can reference it in
[expressions](/docs/language/expressions) as `local.<NAME>`.
-> **Note:** Local values are _created_ by a `locals` block (plural), but you
:::note
Local values are _created_ by a `locals` block (plural), but you
_reference_ them as attributes on an object named `local` (singular). Make sure
to leave off the "s" when referencing a local value!
:::
```
resource "aws_instance" "example" {

8
website/docs/language/values/outputs.mdx
View File

@ -22,8 +22,10 @@ Resource instances managed by OpenTF each export attributes whose values
can be used elsewhere in configuration. Output values are a way to expose some
of that information to the user of your module.
-> **Note:** For brevity, output values are often referred to as just "outputs"
:::note
For brevity, output values are often referred to as just "outputs"
when the meaning is clear from context.
:::
## Declaring an Output Value
@ -47,8 +49,10 @@ refers to the `private_ip` attribute exposed by an `aws_instance` resource
defined elsewhere in this module (not shown). Any valid expression is allowed
as an output value.
-> **Note:** Outputs are only rendered when OpenTF applies your plan. Running
:::note
Outputs are only rendered when OpenTF applies your plan. Running
`opentf plan` will not render outputs.
:::
## Accessing Child Module Outputs

12
website/docs/language/values/variables.mdx
View File

@ -22,12 +22,14 @@ compare modules to function definitions:
* [Output values](/docs/language/values/outputs) are like function return values.
* [Local values](/docs/language/values/locals) are like a function's temporary local variables.
-> **Note:** For brevity, input variables are often referred to as just
:::note
For brevity, input variables are often referred to as just
"variables" or "OpenTF variables" when it is clear from context what sort of
variable is being discussed. Other kinds of variables in OpenTF include
_environment variables_ (set by the shell where OpenTF runs) and _expression
variables_ (used to indirectly represent a value in an
[expression](/docs/language/expressions)).
:::
## Declaring an Input Variable
@ -299,8 +301,10 @@ Within the module that declared a variable, its value can be accessed from
within [expressions](/docs/language/expressions) as `var.<NAME>`,
where `<NAME>` matches the label given in the declaration block:
-> **Note:** Input variables are _created_ by a `variable` block, but you
:::note
Input variables are _created_ by a `variable` block, but you
_reference_ them as attributes on an object named `var`.
:::
```hcl
resource "aws_instance" "example" {
@ -495,7 +499,9 @@ precedence over earlier ones:
* Any `-var` and `-var-file` options on the command line, in the order they
are provided.
~> **Important:** Variables with map and object
:::warning Important
Variables with map and object
values behave the same way as other variables: the last value found overrides
the previous values. This is a change from previous versions of OpenTF, which
would _merge_ map values instead of overriding them.
:::