diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx index 42e1eaa60..ed2e5df9e 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.mdx @@ -38,36 +38,36 @@ behavior. For more information on this assumption, see The command-line flags are all optional. The list of available flags are: -* `-config=path` - Path to directory of Terraform configuration files that +- `-config=path` - Path to directory of Terraform configuration files that configure the provider for import. This defaults to your working directory. If this directory contains no Terraform configuration files, the provider must be configured via manual input or environmental variables. -* `-input=true` - Whether to ask for input for provider configuration. +- `-input=true` - Whether to ask for input for provider configuration. -* `-lock=false` - Don't hold a state lock during the operation. This is +- `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. -* `-lock-timeout=0s` - Duration to retry a state lock. +- `-lock-timeout=0s` - Duration to retry a state lock. -* `-no-color` - If specified, output won't contain any color. +- `-no-color` - If specified, output won't contain any color. -* `-parallelism=n` - Limit the number of concurrent operation as Terraform +- `-parallelism=n` - Limit the number of concurrent operation as Terraform [walks the graph](/internals/graph#walking-the-graph). Defaults to 10. -* `-provider=provider` - **Deprecated** Override the provider configuration to +- `-provider=provider` - **Deprecated** Override the provider configuration to use when importing the object. By default, Terraform uses the provider specified in the configuration for the target resource, and that is the best behavior in most cases. -* `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag +- `-var 'foo=bar'` - Set a variable in the Terraform configuration. This flag can be set multiple times. Variable values are interpreted as [literal expressions](/language/expressions/types) in the Terraform language, so list and map values can be specified via this flag. This is only useful with the `-config` flag. -* `-var-file=foo` - Set variables in the Terraform configuration from +- `-var-file=foo` - Set variables in the Terraform configuration from a [variable file](/language/values/variables#variable-definitions-tfvars-files). If a `terraform.tfvars` or any `.auto.tfvars` files are present in the current directory, they will be automatically loaded. `terraform.tfvars` is loaded @@ -76,11 +76,10 @@ The command-line flags are all optional. The list of available flags are: the working directory. This flag can be used multiple times. This is only useful with the `-config` flag. -For configurations using -[the `remote` backend](/language/settings/backends/remote) +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform import` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using [the `local` backend](/language/settings/backends/local) only, diff --git a/website/docs/cli/commands/push.mdx b/website/docs/cli/commands/push.mdx index 7eb66776e..0e15e1590 100644 --- a/website/docs/cli/commands/push.mdx +++ b/website/docs/cli/commands/push.mdx @@ -7,7 +7,7 @@ description: >- # Command: push -!> **Important:** The `terraform push` command is no longer functional. Its functionality was replaced and surpassed by [the `remote` backend](/language/settings/backends/remote), which works with current versions of Terraform Cloud. The `remote` backend allows you to run remote operations directly from the command line, and displays real-time output from the remote run environment. +!> **Important:** The `terraform push` command is no longer functional. We recommend the [Terraform Cloud CLI integration](/cli/cloud) instead, which allows you to run remote operations in Terraform Cloud directly from the command line. The `terraform push` command was an early implementation of remote Terraform runs. It allowed teams to push a configuration to a remote run environment in a discontinued version of Terraform Enterprise. diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.mdx index 72999019e..ed2159b14 100644 --- a/website/docs/cli/commands/state/mv.mdx +++ b/website/docs/cli/commands/state/mv.mdx @@ -54,23 +54,22 @@ address. This command also accepts the following options: -* `-dry-run` - Report all of the resource instances that match the given +- `-dry-run` - Report all of the resource instances that match the given address without actually "forgetting" any of them. -* `-lock=false` - Don't hold a state lock during the operation. This is +- `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. -* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, +- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -For configurations using -[the `remote` backend](/language/settings/backends/remote) +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform state mv` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). The legacy options [`-backup` and `-backup-out`](/language/settings/backends/local#command-line-arguments) operate on a local state file only. Configurations using diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx index 853b53618..f4417b9b0 100644 --- a/website/docs/cli/commands/state/push.mdx +++ b/website/docs/cli/commands/state/push.mdx @@ -40,8 +40,7 @@ Both of these safety checks can be disabled with the `-force` flag. **This is not recommended.** If you disable the safety checks and are pushing state, the destination state will be overwritten. -For configurations using -[the `remote` backend](/language/settings/backends/remote) +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform state push` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). diff --git a/website/docs/cli/commands/state/replace-provider.mdx b/website/docs/cli/commands/state/replace-provider.mdx index 3c74bd6e7..63fc4a75e 100644 --- a/website/docs/cli/commands/state/replace-provider.mdx +++ b/website/docs/cli/commands/state/replace-provider.mdx @@ -24,19 +24,18 @@ of this command, backups are required. This command also accepts the following options: -* `-auto-approve` - Skip interactive approval. +- `-auto-approve` - Skip interactive approval. -* `-lock=false` - Don't hold a state lock during the operation. This is +- `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. -* `-lock-timeout=0s` - Duration to retry a state lock. +- `-lock-timeout=0s` - Duration to retry a state lock. -For configurations using -[the `remote` backend](/language/settings/backends/remote) +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform state replace-provider` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using [the `local` state rm](/language/settings/backends/local) only, diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.mdx index 034265767..e7031865d 100644 --- a/website/docs/cli/commands/state/rm.mdx +++ b/website/docs/cli/commands/state/rm.mdx @@ -37,23 +37,22 @@ the old objects still present. This command also accepts the following options: -* `-dry-run` - Report all of the resource instances that match the given +- `-dry-run` - Report all of the resource instances that match the given address without actually "forgetting" any of them. -* `-lock=false` - Don't hold a state lock during the operation. This is +- `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. -* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, +- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -For configurations using -[the `remote` backend](/language/settings/backends/remote) +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform state rm` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using [the `local` state rm](/language/settings/backends/local) only, diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index 007c6d9c8..b37a34b3e 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -35,31 +35,29 @@ The address is in [the resource address syntax](/cli/state/resource-addressing) syntax, as shown in the output from other commands, such as: -* `aws_instance.foo` -* `aws_instance.bar[1]` -* `aws_instance.baz[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they will not be interpreted by your shell) -* `module.foo.module.bar.aws_instance.qux` +- `aws_instance.foo` +- `aws_instance.bar[1]` +- `aws_instance.baz[\"key\"]` (quotes in resource addresses must be escaped on the command line, so that they will not be interpreted by your shell) +- `module.foo.module.bar.aws_instance.qux` This command accepts the following options: -* `-allow-missing` - If specified, the command will succeed (exit code 0) +- `-allow-missing` - If specified, the command will succeed (exit code 0) even if the resource is missing. The command might still return an error for other situations, such as if there is a problem reading or writing the state. -* `-lock=false` - Disables Terraform's default behavior of attempting to take +- `-lock=false` - Disables Terraform's default behavior of attempting to take a read/write lock on the state for the duration of the operation. -* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, +- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -For configurations using -[the `remote` backend](/language/settings/backends/remote) -only, `terraform taint` +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform taint` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using [the `local` backend](/language/settings/backends/local) only, diff --git a/website/docs/cli/commands/untaint.mdx b/website/docs/cli/commands/untaint.mdx index 85e210a6a..7d247638e 100644 --- a/website/docs/cli/commands/untaint.mdx +++ b/website/docs/cli/commands/untaint.mdx @@ -43,29 +43,28 @@ identifying a particular resource instance which is currently tainted. This command also accepts the following options: -* `-allow-missing` - If specified, the command will succeed (exit code 0) +- `-allow-missing` - If specified, the command will succeed (exit code 0) even if the resource is missing. The command might still return an error for other situations, such as if there is a problem reading or writing the state. -* `-lock=false` - Don't hold a state lock during the operation. This is +- `-lock=false` - Don't hold a state lock during the operation. This is dangerous if others might concurrently run commands against the same workspace. -* `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, +- `-lock-timeout=DURATION` - Unless locking is disabled with `-lock=false`, instructs Terraform to retry acquiring a lock for a period of time before returning an error. The duration syntax is a number followed by a time unit letter, such as "3s" for three seconds. -* `-no-color` - Disables terminal formatting sequences in the output. Use this +- `-no-color` - Disables terminal formatting sequences in the output. Use this if you are running Terraform in a context where its output will be rendered by a system that cannot interpret terminal formatting. -For configurations using -[the `remote` backend](/language/settings/backends/remote) +For configurations using the [Terraform Cloud CLI integration](/cli/cloud) or the [`remote` backend](/language/settings/backends/remote) only, `terraform untaint` also accepts the option -[`-ignore-remote-version`](/language/settings/backends/remote#command-line-arguments). +[`-ignore-remote-version`](/cli/cloud/command-line-arguments#ignore-remote-version). For configurations using [the `local` backend](/language/settings/backends/local) only, diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.mdx index fbbb03971..f662ed624 100644 --- a/website/docs/cli/commands/validate.mdx +++ b/website/docs/cli/commands/validate.mdx @@ -20,9 +20,7 @@ It is safe to run this command automatically, for example as a post-save check in a text editor or as a test step for a re-usable module in a CI system. -Validation requires an initialized working directory with any referenced -plugins and modules installed. To initialize a working directory for -validation without accessing any configured remote backend, use: +Validation requires an initialized working directory with any referenced plugins and modules installed. To initialize a working directory for validation without accessing any configured backend, use: ``` $ terraform init -backend=false @@ -72,26 +70,26 @@ We will introduce new major versions only within the bounds of In the normal case, Terraform will print a JSON object to the standard output stream. The top-level JSON object will have the following properties: -* `valid` (boolean): Summarizes the overall validation result, by indicating +- `valid` (boolean): Summarizes the overall validation result, by indicating `true` if Terraform considers the current configuration to be valid or `false` if it detected any errors. -* `error_count` (number): A zero or positive whole number giving the count +- `error_count` (number): A zero or positive whole number giving the count of errors Terraform detected. If `valid` is `true` then `error_count` will always be zero, because it is the presence of errors that indicates that a configuration is invalid. -* `warning_count` (number): A zero or positive whole number giving the count +- `warning_count` (number): A zero or positive whole number giving the count of warnings Terraform detected. Warnings do not cause Terraform to consider a configuration to be invalid, but they do indicate potential caveats that a user should consider and possibly resolve. -* `diagnostics` (array of objects): A JSON array of nested objects that each +- `diagnostics` (array of objects): A JSON array of nested objects that each describe an error or warning from Terraform. The nested objects in `diagnostics` have the following properties: -* `severity` (string): A string keyword, currently either `"error"` or +- `severity` (string): A string keyword, currently either `"error"` or `"warning"`, indicating the diagnostic severity. The presence of errors causes Terraform to consider a configuration to be @@ -100,7 +98,7 @@ The nested objects in `diagnostics` have the following properties: introduce new severity keywords, so consumers should be prepared to accept and ignore severity values they don't understand. -* `summary` (string): A short description of the nature of the problem that +- `summary` (string): A short description of the nature of the problem that the diagnostic is reporting. In Terraform's usual human-oriented diagnostic messages, the summary serves @@ -113,7 +111,7 @@ The nested objects in `diagnostics` have the following properties: summary. In those cases, the summary might include newline characters which a renderer should honor when presenting the message visually to a user. -* `detail` (string): An optional additional message giving more detail about +- `detail` (string): An optional additional message giving more detail about the problem. In Terraform's usual human-oriented diagnostic messages, the detail provides @@ -135,7 +133,7 @@ The nested objects in `diagnostics` have the following properties: additional rules for processing other text conventions, but will do so within the bounds of the rules above to achieve backward-compatibility. -* `range` (object): An optional object referencing a portion of the configuration +- `range` (object): An optional object referencing a portion of the configuration source code that the diagnostic message relates to. For errors, this will typically indicate the bounds of the specific block header, attribute, or expression which was detected as invalid. @@ -149,36 +147,36 @@ The nested objects in `diagnostics` have the following properties: configuration, so `range` will be omitted or `null` for diagnostic messages where it isn't relevant. -* `snippet` (object): An optional object including an excerpt of the +- `snippet` (object): An optional object including an excerpt of the configuration source code that the diagnostic message relates to. The snippet information includes: - * `context` (string): An optional summary of the root context of the + - `context` (string): An optional summary of the root context of the diagnostic. For example, this might be the resource block containing the expression which triggered the diagnostic. For some diagnostics this information is not available, and then this property will be `null`. - * `code` (string): A snippet of Terraform configuration including the + - `code` (string): A snippet of Terraform configuration including the source of the diagnostic. This can be multiple lines and may include additional configuration source code around the expression which triggered the diagnostic. - * `start_line` (number): A one-based line count representing the position + - `start_line` (number): A one-based line count representing the position in the source file at which the `code` excerpt begins. This is not necessarily the same value as `range.start.line`, as it is possible for `code` to include one or more lines of context before the source of the diagnostic. - * `highlight_start_offset` (number): A zero-based character offset into the + - `highlight_start_offset` (number): A zero-based character offset into the `code` string, pointing at the start of the expression which triggered the diagnostic. - * `highlight_end_offset` (number): A zero-based character offset into the + - `highlight_end_offset` (number): A zero-based character offset into the `code` string, pointing at the end of the expression which triggered the diagnostic. - * `values` (array of objects): Contains zero or more expression values + - `values` (array of objects): Contains zero or more expression values which may be useful in understanding the source of a diagnostic in a complex expression. These expression value objects are described below. @@ -187,12 +185,12 @@ The nested objects in `diagnostics` have the following properties: A source position object, as used in the `range` property of a diagnostic object, has the following properties: -* `byte` (number): A zero-based byte offset into the indicated file. +- `byte` (number): A zero-based byte offset into the indicated file. -* `line` (number): A one-based line count for the line containing the relevant +- `line` (number): A one-based line count for the line containing the relevant position in the indicated file. -* `column` (number): A one-based count of _Unicode characters_ from the start +- `column` (number): A one-based count of _Unicode characters_ from the start of the line indicated in `line`. A `start` position is inclusive while an `end` position is exclusive. The @@ -208,13 +206,13 @@ part of the expression which triggered the diagnostic. This is especially useful when using `for_each` or similar constructs, in order to identify exactly which values are responsible for an error. The object has two properties: -* `traversal` (string): An HCL-like traversal string, such as +- `traversal` (string): An HCL-like traversal string, such as `var.instance_count`. Complex index key values may be elided, so this will not always be valid, parseable HCL. The contents of this string are intended to be human-readable and are subject to change in future versions of Terraform. -* `statement` (string): A short English-language fragment describing the value +- `statement` (string): A short English-language fragment describing the value of the expression when the diagnostic was triggered. The contents of this string are intended to be human-readable and are subject to change in future versions of Terraform. diff --git a/website/docs/cli/config/environment-variables.mdx b/website/docs/cli/config/environment-variables.mdx index ffe749ec6..57f0dd0cd 100644 --- a/website/docs/cli/config/environment-variables.mdx +++ b/website/docs/cli/config/environment-variables.mdx @@ -88,7 +88,7 @@ be separated by spaces otherwise. ## TF_DATA_DIR `TF_DATA_DIR` changes the location where Terraform keeps its -per-working-directory data, such as the current remote backend configuration. +per-working-directory data, such as the current backend configuration. By default this data is written into a `.terraform` subdirectory of the current directory, but the path given in `TF_DATA_DIR` will be used instead diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx index 3ff341749..d9503e0b4 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.mdx @@ -38,13 +38,6 @@ imported object will be mapped. While this may seem tedious, it still gives Terraform users an avenue for importing existing resources. -## Remote Backends +## Terraform Cloud -When using Terraform import on the command line with a [remote -backend](/language/settings/backends/remote), such as Terraform Cloud, the import -command runs locally, unlike commands such as apply, which run inside your -Terraform Cloud environment. Because of this, the import command will not have -access to information from the remote backend, such as workspace variables. - -In order to use Terraform import with a remote state backend, you may need to -set local variables equivalent to the remote workspace variables. +When you use Terraform on the command line with Terraform Cloud, many commands (e.g., `apply`) run inside your Terraform Cloud environment. However, the `import` command runs locally, so it will not have access to information from Terraform Cloud. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in Terraform Cloud. diff --git a/website/docs/language/modules/sources.mdx b/website/docs/language/modules/sources.mdx index d4aa0d35b..0ca91108b 100644 --- a/website/docs/language/modules/sources.mdx +++ b/website/docs/language/modules/sources.mdx @@ -22,23 +22,23 @@ used by other Terraform commands. The module installer supports installation from a number of different source types, as listed below. -* [Local paths](#local-paths) +- [Local paths](#local-paths) -* [Terraform Registry](#terraform-registry) +- [Terraform Registry](#terraform-registry) -* [GitHub](#github) +- [GitHub](#github) -* [Bitbucket](#bitbucket) +- [Bitbucket](#bitbucket) -* Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories +- Generic [Git](#generic-git-repository), [Mercurial](#generic-mercurial-repository) repositories -* [HTTP URLs](#http-urls) +- [HTTP URLs](#http-urls) -* [S3 buckets](#s3-bucket) +- [S3 buckets](#s3-bucket) -* [GCS buckets](#gcs-bucket) +- [GCS buckets](#gcs-bucket) -* [Modules in Package Sub-directories](#modules-in-package-sub-directories) +- [Modules in Package Sub-directories](#modules-in-package-sub-directories) Each of these is described in the following sections. Module source addresses use a _URL-like_ syntax, but with extensions to support unambiguous selection @@ -135,7 +135,7 @@ If you are using the SaaS version of Terraform Cloud, its private registry hostname is `app.terraform.io`. If you use a self-hosted Terraform Enterprise instance, its private registry hostname is the same as the host where you'd access the web UI and the host you'd use when configuring -the `remote` backend. +the [Terraform Cloud CLI integration](/cli/cloud). Registry modules support versioning. You can provide a specific version as shown in the above examples, or use flexible @@ -347,13 +347,12 @@ optionally return a different result when Terraform is requesting it. If the response is successful (`200`-range status code), Terraform looks in the following locations in order for the next address to access: -* The value of a response header field named `X-Terraform-Get`. +- The value of a response header field named `X-Terraform-Get`. -* If the response is an HTML page, a `meta` element with the name `terraform-get`: +- If the response is an HTML page, a `meta` element with the name `terraform-get`: ```html - + ``` In either case, the result is interpreted as another module source address @@ -378,10 +377,10 @@ module "vpc" { The extensions that Terraform recognizes for this special behavior are: -* `zip` -* `tar.bz2` and `tbz2` -* `tar.gz` and `tgz` -* `tar.xz` and `txz` +- `zip` +- `tar.bz2` and `tbz2` +- `tar.gz` and `tgz` +- `tar.xz` and `txz` If your URL _doesn't_ have one of these extensions but refers to an archive anyway, use the `archive` argument to force this interpretation: @@ -423,9 +422,9 @@ Terraform will extract the archive to obtain the module source tree. The module installer looks for AWS credentials in the following locations, preferring those earlier in the list when multiple are available: -* The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. -* The default profile in the `.aws/credentials` file in your home directory. -* If running on an EC2 instance, temporary credentials associated with the +- The `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables. +- The default profile in the `.aws/credentials` file in your home directory. +- If running on an EC2 instance, temporary credentials associated with the instance's IAM Instance Profile. ## GCS Bucket @@ -436,8 +435,8 @@ prefix, followed by For example -* `gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH_TO_MODULE` -* `gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH/TO/module.zip` +- `gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH_TO_MODULE` +- `gcs::https://www.googleapis.com/storage/v1/BUCKET_NAME/PATH/TO/module.zip` ```hcl module "consul" { @@ -463,16 +462,16 @@ A special double-slash syntax is interpreted by Terraform to indicate that the remaining path after that point is a sub-directory within the package. For example: -* `hashicorp/consul/aws//modules/consul-cluster` -* `git::https://example.com/network.git//modules/vpc` -* `https://example.com/network-module.zip//modules/vpc` -* `s3::https://s3-eu-west-1.amazonaws.com/examplecorp-terraform-modules/network.zip//modules/vpc` +- `hashicorp/consul/aws//modules/consul-cluster` +- `git::https://example.com/network.git//modules/vpc` +- `https://example.com/network-module.zip//modules/vpc` +- `s3::https://s3-eu-west-1.amazonaws.com/examplecorp-terraform-modules/network.zip//modules/vpc` If the source address has arguments, such as the `ref` argument supported for the version control sources, the sub-directory portion must be _before_ those arguments: -* `git::https://example.com/network.git//modules/vpc?ref=v1.2.0` +- `git::https://example.com/network.git//modules/vpc?ref=v1.2.0` Terraform will still extract the entire package to local disk, but will read the module from the subdirectory. As a result, it is safe for a module in diff --git a/website/docs/language/state/remote-state-data.mdx b/website/docs/language/state/remote-state-data.mdx index 8dbda8ccb..48ead8ea4 100644 --- a/website/docs/language/state/remote-state-data.mdx +++ b/website/docs/language/state/remote-state-data.mdx @@ -9,17 +9,12 @@ description: >- [backends]: /language/settings/backends -The `terraform_remote_state` data source retrieves the root module output values -from some other Terraform configuration, using the latest state snapshot from -the remote backend. +The `terraform_remote_state` data source uses the latest state snapshot from a specified state backend to retrieve the root module output values +from some other Terraform configuration. -This data source is built into Terraform, and is always available; you do not -need to require or configure a provider in order to use it. +You can use the `terraform_remote_state` data source without requiring or configuring a provider. It is always available through a built-in provider with the [source address](/language/providers/requirements#source-addresses) `terraform.io/builtin/terraform`. That provider does not include any other resources or data sources. --> **Note:** This data source is implemented by a built-in provider, whose -[source address](/language/providers/requirements#source-addresses) -is `terraform.io/builtin/terraform`. That provider does not include any other -resources or data sources. +~> **Important:** We recommend using the [`tfe_outputs` data source](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) in the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) to access remote state outputs in Terraform Cloud or Terraform Enterprise. The `tfe_outputs` data source is more secure because it does not require full access to workspace state to fetch outputs. ## Alternative Ways to Share Data Between Configurations @@ -94,12 +89,6 @@ post-processing such as JSON decoding. You can then change that module later if you switch to a different strategy for sharing data between multiple Terraform configurations. -## Usage with Terraform Cloud/Enterprise - -When trying to access remote state outputs in Terraform Cloud/Enterprise, it is recommended to use the `tfe_outputs` data source in the [Terraform Cloud/Enterprise Provider](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs) instead of relying the `terraform_remote_state` data source. - -See the [full documentation](https://registry.terraform.io/providers/hashicorp/tfe/latest/docs/data-sources/outputs) for the `tfe_outputs` data source for more details. - ## Example Usage (`remote` Backend) ```hcl diff --git a/website/intro/core-workflow.mdx b/website/intro/core-workflow.mdx index 62afc53dc..e73cb326d 100644 --- a/website/intro/core-workflow.mdx +++ b/website/intro/core-workflow.mdx @@ -229,22 +229,23 @@ for a better experience at each step. Terraform Cloud provides a centralized and secure location for storing input variables and state while also bringing back a tight feedback loop for -speculative plans for config authors. Terraform configuration interacts with -Terraform Cloud via the ["remote" backend](/language/settings/backends/remote). +speculative plans for config authors. Terraform configuration can interact with +Terraform Cloud through the [CLI integration](/cli/cloud). ``` terraform { - backend "remote" { + cloud { organization = "my-org" + hostname = "app.terraform.io" # Optional; defaults to app.terraform.io + workspaces { - prefix = "my-app-" + tags = ["networking", "source:cli"] } } } ``` -Once the backend is wired up, a Terraform Cloud API key is all that's -needed by team members to be able to edit config and run speculative plans +After you configure the integration, a Terraform Cloud API key is all your team members need to edit config and run speculative plans against the latest version of the state file using all the remotely stored input variables.