From 9e86c518e0e2efda3d906ab90f4d0a8427868328 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 18 Nov 2024 15:03:49 -0800 Subject: [PATCH 01/11] first commit --- website/docs/cli/cloud/command-line-arguments.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx index 8bdfd36f84e8..57518f2433e9 100644 --- a/website/docs/cli/cloud/command-line-arguments.mdx +++ b/website/docs/cli/cloud/command-line-arguments.mdx @@ -1,9 +1,9 @@ --- -page_title: Command Line Arguments -description: Command Line Arguments +page_title: -ignore-remote-version reference +description: Use the -ignore-remote-version flat to override CLI-driven commands for HCP Terraform runs. --- -# Command Line Arguments +# `-ignore-remote-version` reference When your configuration includes a `cloud` block, commands that make local modifications to Terraform state and then push them back up to the remote workspace From 511614e718200d762659adaff2c0111fbb996755 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 22 Nov 2024 16:07:56 -0800 Subject: [PATCH 02/11] first tiny batch of SEO improvements --- website/docs/cli/auth/index.mdx | 34 +++++++++-------- website/docs/cli/code/index.mdx | 14 +++++-- website/docs/cli/config/config-file.mdx | 14 ++++--- .../docs/cli/config/environment-variables.mdx | 17 +++++---- website/docs/cli/config/index.mdx | 15 ++++---- website/docs/cli/index.mdx | 14 +++---- website/docs/cli/init/index.mdx | 15 +++----- website/docs/cli/inspect/index.mdx | 8 ++-- website/docs/cli/install/apt.mdx | 7 ++-- website/docs/cli/install/yum.mdx | 7 ++-- website/docs/cli/plugins/index.mdx | 31 +++++++-------- website/docs/cli/plugins/signing.mdx | 30 ++++++++------- website/docs/cli/test/index.mdx | 38 ++++++++----------- website/docs/intro/core-workflow.mdx | 6 +-- website/docs/intro/index.mdx | 2 +- website/docs/intro/terraform-editions.mdx | 4 +- website/docs/intro/use-cases.mdx | 4 +- website/docs/intro/vs/boto.mdx | 6 +-- website/docs/intro/vs/cloudformation.mdx | 12 +++--- website/docs/intro/vs/custom.mdx | 7 ++-- website/docs/intro/vs/index.mdx | 6 +-- 21 files changed, 145 insertions(+), 146 deletions(-) diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index 7ac27004fc43..dcbb536fddc9 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -1,31 +1,33 @@ --- -page_title: Authentication - Terraform CLI +page_title: et an API token for HCP Terraform and Terraform Enterprise description: >- - Documentation about the login and logout commands that help automate getting - an API token for your HCP Terraform account. + Use the terraform login and terraform logout commands get + an API token for your HCP Terraform or Terraform Enterprise account. --- -# CLI Authentication +# Get an API token for HCP Terraform and Terraform Enterprise + +This topic describes how to use the `terraform login` and `terraform logout` to authenticate with HCP Terraform and Terraform Enterprise. > **Hands-on:** Try the [Authenticate the CLI with HCP Terraform](/terraform/tutorials/cloud/cloud-login?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +## Overview + [HCP Terraform](https://cloud.hashicorp.com/products/terraform) and [Terraform Enterprise](/terraform/enterprise) are platforms that perform Terraform runs to provision infrastructure, offering a collaboration-focused -environment that makes it easier for teams to use Terraform together. (For -expediency, the content below refers to both products as "HCP Terraform.") +environment that makes it easier for teams to use Terraform together. + +You can integrate the Terraform CLI with Terraform web platform in the following ways: + +- Use the Terraform CLI as a front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in HCP Terraform +- Use HCP Terraform or Terraform Enterprise as a state backend and a private module registry. -Terraform CLI integrates with HCP Terraform in several ways — it can be a -front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in HCP Terraform, -and can also use HCP Terraform as a state backend and a private module -registry. All of these integrations require you to authenticate Terraform CLI +These integrations require you to authenticate the Terraform CLI with your HCP Terraform account. -The best way to handle CLI authentication is with the `login` and `logout` -commands, which help automate the process of getting an API token for your -HCP Terraform user account. +## Authentication -For details, see: +Run the `terraform login` command to automate the process of getting an API token for your HCP Terraform user account. Refer to the [`terraform login` command](/terraform/cli/commands/login) reference documentation for details. -- [The `terraform login` command](/terraform/cli/commands/login) -- [The `terraform logout` command](/terraform/cli/commands/logout) +Run the `terrafom logout` coommand to end your HCP Terraform or Terraform Enterprise session. Refer to the [`terraform logout` command](/terraform/cli/commands/logout) reference documentation for details. diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 714f94227e5f..328bffa53349 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -1,16 +1,22 @@ --- -page_title: Writing and Modifying Code - Terraform CLI +page_title: Write and modify Terrafrom configuration from the CLI description: >- - Learn commands that help validate, format, and upgrade code written in the - Terraform Configuration Language. + Learn about the Terraform commands that help validate, format, and upgrade code written in the + Terraform configuration language. --- -# Writing and Modifying Terraform Code +# Write and modify Terrafrom configuration from the CLI + +This topic provides an overview of the Terraform CLI commands you can use to programmatically write and modify Terraform configuration code. + +## Introduction The [Terraform language](/terraform/language) is Terraform's primary user interface, and all of Terraform's workflows rely on configurations written in the Terraform language. +## Workflows + Terraform CLI includes several commands to make Terraform code more convenient to work with. Integrating these commands into your editing workflow can potentially save you time and effort. diff --git a/website/docs/cli/config/config-file.mdx b/website/docs/cli/config/config-file.mdx index 2dec34a76e73..8b2923887d5c 100644 --- a/website/docs/cli/config/config-file.mdx +++ b/website/docs/cli/config/config-file.mdx @@ -1,15 +1,19 @@ --- -page_title: CLI Configuration +page_title: Create a Terraform CLI configuration file description: >- - Learn to use the CLI configuration file to customize your CLI settings, - including credentials, plugin caching, provider installation methods, etc. + Learn how to create a `.terraformrc` or `terraform.rc` file to define Terraform CLI settings, including credentials, plugin caching, and provider installation. --- -# CLI Configuration File (`.terraformrc` or `terraform.rc`) +# Create a Terraform CLI configuration file + +This topic describes how create a configuration file to customize the behavior of the Terraform CLI. + +## Introduction The CLI configuration file configures per-user settings for CLI behaviors, which apply across all Terraform working directories. This is separate from -[your infrastructure configuration](/terraform/language). +[your infrastructure configuration](/terraform/language). +You can define custom configurations in file with the `.terraformrc` extention a file named `terraform.rc`. ## Locations diff --git a/website/docs/cli/config/environment-variables.mdx b/website/docs/cli/config/environment-variables.mdx index d08bf2d1ca51..70144c6fdef8 100644 --- a/website/docs/cli/config/environment-variables.mdx +++ b/website/docs/cli/config/environment-variables.mdx @@ -1,17 +1,20 @@ --- -page_title: Environment Variables +page_title: Terraform CLI environment variables reference description: >- - Learn to use environment variables to change Terraform's default behavior. - Configure log content and output, set variables, and more. + Terraform environment variables let you customize the Terraform CLI's default behavior. + Learn about the Terraform CLI environment variables. --- -# Environment Variables +# Terraform CLI environment variables reference + +This topic contains reference information about the environment variables you can use with the Terraform CLI. + +## Introduction Terraform refers to a number of environment variables to customize various aspects of its behavior. None of these environment variables are required -when using Terraform, but they can be used to change some of Terraform's -default behaviors in unusual situations, or to increase output verbosity -for debugging. +when using Terraform, but you can use them to change some of Terraform's +default behaviors or to increase output verbosity for debugging. ## TF_LOG diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.mdx index 77022d1335ae..fbe40f3a51d3 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.mdx @@ -1,19 +1,18 @@ --- -page_title: CLI Configuration - Terraform CLI +page_title: Terraform CLI configuration overview description: >- - Find documentation about the CLI config file and customizing Terraform - environment variables. + The CLI config-file and supported Terraform environment variables let you customize Terraform CLI behavior. + Learn how Terraform CLI configuration works. --- -# CLI Configuration +# Terraform CLI configuration overview -Terraform CLI can be configured with some global settings, which are separate +You can configure the Terraform CLI in global settings, which are separate from any Terraform configuration and which apply across all working directories. -We've designed Terraform such that an average user running Terraform CLI -interactively will not need to interact with any of these settings. As a result, +The default behavior of the Terraform CLI is suitable in most cases. As a result, most of the global settings relate to advanced or automated workflows, or -unusual environmental conditions like running Terraform on an airgapped +unusual environmental conditions, such as running Terraform on an air-gapped instance. - The [CLI config file](/terraform/cli/config/config-file) configures provider diff --git a/website/docs/cli/index.mdx b/website/docs/cli/index.mdx index 2e26fe971019..18bc09308216 100644 --- a/website/docs/cli/index.mdx +++ b/website/docs/cli/index.mdx @@ -9,11 +9,11 @@ description: >- > **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. -This is the documentation for Terraform CLI. It is relevant to anyone working -with Terraform's CLI-based workflows; this includes people who use Terraform CLI -by itself, as well as those who use Terraform CLI in conjunction with Terraform -Cloud or Terraform Enterprise. +This documentation provides reference information about Terraform CLI commands, +as well as instructions for using commands to provision infrastructure and manage the +infrastructure lifecyle. It is relevant to anyone working with Terraform's CLI-based +workflows, including people who use Terraform CLI by itself, as well as those who +use Terraform CLI in conjunction with HCTP Terraform or Terraform Enterprise. -Notably, this documentation does not cover the syntax and usage of the Terraform -language. For that, see the -[Terraform Language Documentation](/terraform/language). +For information about the Terraform configuration language syntax and coding patters, refer to the +[Terraform configuration language documentation](/terraform/language). diff --git a/website/docs/cli/init/index.mdx b/website/docs/cli/init/index.mdx index 5b763eb9dad4..f91c7c089761 100644 --- a/website/docs/cli/init/index.mdx +++ b/website/docs/cli/init/index.mdx @@ -1,12 +1,10 @@ --- -page_title: Initializing Working Directories - Terraform CLI +page_title: Initialize the Terraform working directory description: >- - Working directories contain configurations, settings, cached plugins and - modules, and state data. Learn how to initialize and manage working - directories. + Learn how to initialize the working directory with the terraform init command, which installs plugins and modules defined in the configuration and retrieves state data. --- -# Initializing Working Directories +# Initialize the Working Directory Terraform expects to be invoked from a working directory that contains configuration files written in @@ -29,10 +27,9 @@ A Terraform working directory typically contains: record the last known backend configuration in case it needs to migrate state on the next run. This directory is automatically managed by Terraform, and is created during initialization. -- State data, if the configuration uses the default `local` backend. This is - managed by Terraform in a `terraform.tfstate` file (if the directory only uses - the default workspace) or a `terraform.tfstate.d` directory (if the directory - uses multiple workspaces). +- State data when the configuration uses the default `local` backend. Terraform manages state in a `terraform.tfstate` file when the directory only uses + the default workspace or a `terraform.tfstate.d` directory when the directory + uses multiple workspaces. ## Initialization diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx index 113594c58a5c..6397de7fbf49 100644 --- a/website/docs/cli/inspect/index.mdx +++ b/website/docs/cli/inspect/index.mdx @@ -1,11 +1,11 @@ --- -page_title: Inspecting Infrastructure - Terraform CLI +page_title: Inspect infrastructure commands overview description: >- - Learn commands to inspect dependency information, outputs, etc. Use them for - integration or to understand your infrastructure. + The terraform inspect commands return dependency information and outputs. Learn how to use terraform inspect commands + to understand your infrastructure. --- -# Inspecting Infrastructure +# Inspect Infrastructure Commands Overview Terraform configurations and state data include some highly structured information about the resources they manage; this includes dependency diff --git a/website/docs/cli/install/apt.mdx b/website/docs/cli/install/apt.mdx index e8ca55f43189..492d238ea2e0 100644 --- a/website/docs/cli/install/apt.mdx +++ b/website/docs/cli/install/apt.mdx @@ -1,11 +1,10 @@ --- -page_title: APT Packages for Debian and Ubuntu +page_title: Install Terraform using APT packages for Debian and Ubuntu description: >- - The HashiCorp APT repositories contain distribution-specific Terraform - packages for both Debian and Ubuntu systems. + Learn how to install Terraform using HashiCorp APT packages for Debian and Ubuntu systems. --- -# APT Packages for Debian and Ubuntu +# Install Terraform Using APT Packages for Debian and Ubuntu The primary distribution packages for Terraform are `.zip` archives containing single executable files that you can extract anywhere on your system. However, diff --git a/website/docs/cli/install/yum.mdx b/website/docs/cli/install/yum.mdx index b6b4b809705d..1df4811e467f 100644 --- a/website/docs/cli/install/yum.mdx +++ b/website/docs/cli/install/yum.mdx @@ -1,11 +1,10 @@ --- -page_title: 'Yum Packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux' +page_title: Install Terraform using yum packages for Linux distributions description: >- - The HashiCorp Yum repositories contain distribution-specific Terraform - packages for Red Hat Enterprise Linux, Fedora, and Amazon Linux systems. + Learn how to install Terraform using HashiCorp yum packages for Red Hat Enterprise Linux (RHEL), Fedora, CentOS, and Amazon Linux systems. --- -# Yum/DNF Packages for RHEL, CentOS, and Fedora +# Install Terraform Using Yum Packages for Linux Distributions The primary distribution packages for Terraform are `.zip` archives containing single executable files that you can extract anywhere on your system. However, diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.mdx index 67f6db2fb4b5..8ff267cb017d 100644 --- a/website/docs/cli/plugins/index.mdx +++ b/website/docs/cli/plugins/index.mdx @@ -1,30 +1,27 @@ --- -page_title: Managing Plugins - Terraform CLI +page_title: Manage Terraform plugins overview description: >- - Commands to install, configure, and show information about providers. Also - commands to reduce install effort in air-gapped environments. + Providers are types of plugins for Terraform that manage infrastructure resources. Learn about managing plugins using the Terraform CLI. --- -# Managing Plugins +# Manage plugins overview -Terraform relies on plugins called providers to manage various types -of resources. For more information about providers, refer to -[Providers](/terraform/language/providers) in the Terraform -language docs. +This topic provides an overview of the how to manage plugins that Terraform relies on to manage various types +of resources. Providers are the only plugin type Terraform users interact with. Refer to [Providers](/terraform/language/providers) in the Terraform +language docs for additional information about providers. --> **Note:** Providers are the only plugin type most Terraform users interact with. Terraform also supports third-party provisioner plugins, but -we discourage their use. +## Workflow -Terraform installs any providers -[required](/terraform/language/providers/requirements) by a configuration -when [initializing](/terraform/cli/init) a working directory. By default, -this works without any additional interaction but requires network access to +When you initialize a working directory, Terraform installs any providers the Terraform configuration requires. Refer to +[Provider Requirements](/terraform/language/providers/requirements) in the Terraform configuration language information about requiring providers. Refer to the [`terraform init` command documentation](/terraform/cli/init) for additional information about how initialize the working directory. + +By default, Terraform initializes the working directory without any additional interaction, but you must have network access to download providers from their source registry. You can configure Terraform's provider installation behavior to limit or skip -network access, and to enable use of providers that aren't available through a -networked source. Terraform also includes some commands to show information -about providers and to reduce the effort of installing providers in air-gapped +network access, and to enable use of providers that are not available through a +networked source. Terraform also includes commands that show information +about providers and commands that reduce the effort of installing providers in air-gapped environments. ## Configuring Plugin Installation diff --git a/website/docs/cli/plugins/signing.mdx b/website/docs/cli/plugins/signing.mdx index 7eac2efd3020..bb2e69e92d5e 100644 --- a/website/docs/cli/plugins/signing.mdx +++ b/website/docs/cli/plugins/signing.mdx @@ -1,27 +1,29 @@ --- -page_title: Plugin Signing +page_title: Plugin signatures description: >- - Learn about the types of signatures providers can have on the Terraform - Registry. + Signatures help you determine the authenticity of the plugins you want to install. Learn about the types of signatures providers can have on the Terraform registry. --- -# Plugin Signing +# Plugin signatures -~> **Note** Terraform only authenticates provider plugins fetched from a registry. +This topic provides information about the types of signatures that can be built into plugins you install. Terraform only authenticates provider plugins fetched from a registry. -Terraform 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: +## Types of plugin signatures -* **Signed by HashiCorp** - are built, signed, and supported by HashiCorp. -* **Signed by Trusted Partners** - are built, signed, and supported by a third party. HashiCorp has - verified the ownership of the private key and we provide a chain of trust to the CLI to verify this - programatically. -* **Self-signed** - are built, signed, and supported by a third party. HashiCorp does not provide a +Terraform providers installed from the registry are cryptographically signed. Terraform verifies the signature during installation. There are three types of signatures: + +* Providers signed by HashiCorp: HashiCorp builds, signs, and supports these providers. +* Providers signed by trusted partners: A third party builds, signs, and supports these providers. HashiCorp verifies the ownership of the private key and provides a chain of trust to the CLI to verify ownership programatically. +* Self-signed providers: A third party builds, signs, and supports these providers. HashiCorp does not provide a verification or chain of trust for the signature. You may obtain and validate fingerprints manually if you want to ensure you are using a binary you can trust. -Terraform does **NOT** support fetching and using unsigned binaries, but you can manually install -unsigned binaries. You should take extreme care when doing so as no programatic authentication is performed. +## Unsigned binaries + +You cannot fetch and use unsigned binaries from the registry, but you can manually install unsigned binaries. We strongly recommend that you thoroughly vetting providers that you manually install so that these providers do not programatically authenticate. + +## Registry terms of use -Usage of plugins from the registry is subject to the Registry's [Terms of Use](https://registry.terraform.io/terms). +Use of plugins from the registry is subject to the registry's [terms of use](https://registry.terraform.io/terms). diff --git a/website/docs/cli/test/index.mdx b/website/docs/cli/test/index.mdx index 19a874aba0a5..7eeebd6c32f2 100644 --- a/website/docs/cli/test/index.mdx +++ b/website/docs/cli/test/index.mdx @@ -1,43 +1,37 @@ --- -page_title: Testing Terraform - Terraform CLI +page_title: Testing features in Terraform overview description: >- - Write structured tests and validations for your configuration to ensure + Learn about the terraform test command, which runs structured tests and validations for your configuration to ensure correctness in your infrastructure. --- -# Testing Terraform +# Testing features in Terraform overview -Terraform provides numerous testing capabilities to validate your infrastructure. +This topic provides an overview of the testing features in Terraform to help you validate your infrastructure. -These testing capabilities fit into two main categories: +## Introduction -1. Validating your configuration and infrastructure as part of your regular Terraform operations. -2. Performing traditional unit and integration testing on your configuration. +Terraform provides the following types of testing capabilities: -Refer to [Custom Conditions](/terraform/language/expressions/custom-conditions) and [Checks](/terraform/language/checks) to learn more about the first testing capability. Terraform's [`test`](/terraform/cli/commands/test) command provides the second capability. +1. Configuration and infrastructure validation as part of your regular Terraform operations. Refer to [Custom Conditions](/terraform/language/expressions/custom-conditions) and [Checks](/terraform/language/checks) to learn more about these types of testing capabilities. +1. Traditional unit and integration testing on your configuration. Refer to the [`terraform test` command](/terraform/cli/commands/test) documentation to learn more about this testing capability. -## A brief history +### Additional testing and validation features -The various testing capabilities were introduced in the following versions: +- [Input Variable Validation](/terraform/language/expressions/custom-conditions#input-variable-validation) +- [Pre and Post-conditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions) +- [Checks](/terraform/language/checks) -- Terraform v0.13.0 introduced [Input Variable Validation](/terraform/language/expressions/custom-conditions#input-variable-validation). -- Terraform v0.15.0 introduced an experimental Terraform [`test`](/terraform/language/v1.5.x/modules/testing-experiment) command. -- Terraform v1.2.0 introduced [Pre and Post-conditions](/terraform/language/expressions/custom-conditions#preconditions-and-postconditions). -- Terraform v1.5.0 introduced [Checks](/terraform/language/checks). -- Terraform v1.6.0 deprecated the experimental Terraform `test` command, and released an updated and finalized Terraform [`test`](/terraform/cli/commands/test) command. +## How the `terraform test` command works -Note the introduction and deprecation of the experimental `test` command, followed by the introduction of the finalized `test` command. Refer to the [v1.6.x Upgrade Guide](/terraform/language/v1.6.x/upgrade-guides) for a summary of the changes between the experimental and finalized command. - -## The `test` command - -The Terraform `test` command: +The `test` command performs the following actions: - Locates Terraform testing files within your configuration directory. - Provisions the infrastructure within your configuration as specified by each testing file. - Runs the assertions from the test file against the provisioned infrastructure. - Destroys the provisioned infrastructure at the end of the test. -The `test` command, along with command-line flags and options, is discussed in detail within [Command: test](/terraform/cli/commands/test). +For details about using the `test` command, refer to the [`test` command reference documentation](/terraform/cli/commands/test). ### Write configuration for tests @@ -49,7 +43,7 @@ Validations allow you to verify aspects of your configuration and infrastructure The Terraform `test` command also executes any validations within your configuration as part of the tests it executes. For more information on the available validation, refer to [Checks](/terraform/language/checks) and [Custom Conditions](/terraform/language/expressions/custom-conditions). -## Tests or Validations +## Tests versus validations You can write many validations as test assertions, but there are specific use cases for both. diff --git a/website/docs/intro/core-workflow.mdx b/website/docs/intro/core-workflow.mdx index de38b00aeaf0..3d49b7db394c 100644 --- a/website/docs/intro/core-workflow.mdx +++ b/website/docs/intro/core-workflow.mdx @@ -1,9 +1,9 @@ --- -page_title: The Core Terraform Workflow - Guides -description: 'An overview of how individuals, teams, and organizations can use Terraform. ' +page_title: Overview of the core Terraform workflow +description: Learn how to provision and manage infrastructure using the core Terraform workflow for individuals, teams, and organizations. --- -# The Core Terraform Workflow +# Core Terraform Workflow Overview The core Terraform workflow has three steps: diff --git a/website/docs/intro/index.mdx b/website/docs/intro/index.mdx index a9e48c790932..8d3172ded3bf 100644 --- a/website/docs/intro/index.mdx +++ b/website/docs/intro/index.mdx @@ -1,6 +1,6 @@ --- layout: "intro" -page_title: "What is Terraform" +page_title: What is Terraform sidebar_current: "what" description: |- Terraform is an infrastructure as code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently. diff --git a/website/docs/intro/terraform-editions.mdx b/website/docs/intro/terraform-editions.mdx index c8c2305ea7c9..0d3962b153af 100644 --- a/website/docs/intro/terraform-editions.mdx +++ b/website/docs/intro/terraform-editions.mdx @@ -3,10 +3,10 @@ layout: "intro" page_title: "Terraform Editions" sidebar_current: "what" description: |- - Terraform Community Edition, HCP Terraform, and Terraform Enterprise solve increasingly complex infrastructure and collaboration challenges. + Learn how Terraform Community Edition, HCP Terraform, and Terraform Enterprise solve increasingly complex infrastructure and collaboration challenges. --- -# Terraform Editions +# Terraform Editions Overview As your organization adopts infrastructure as code (IaC), you will encounter increasingly complex technical and collaboration challenges. We offer three Terraform editions designed to help you solve them. diff --git a/website/docs/intro/use-cases.mdx b/website/docs/intro/use-cases.mdx index a306acef1279..b858238e2e22 100644 --- a/website/docs/intro/use-cases.mdx +++ b/website/docs/intro/use-cases.mdx @@ -3,10 +3,10 @@ layout: "intro" page_title: "Use Cases" sidebar_current: "use-cases" description: |- - Learn how Terraform enables multi-cloud deployments, application management, policy compliance, and self-service infrastructure. + Learn about Terraform use cases, such as enabling multi-cloud deployments, application management, policy compliance, and self-service infrastructure. --- -# Use Cases +# Terraform Use Cases [HashiCorp Terraform](/terraform/intro) is an infrastructure as code tool that lets you define infrastructure resources in human-readable configuration files that you can version, reuse, and share. You can then use a consistent workflow to safely and efficiently provision and manage your infrastructure throughout its lifecycle. diff --git a/website/docs/intro/vs/boto.mdx b/website/docs/intro/vs/boto.mdx index de008b8dced4..588de6f3b02c 100644 --- a/website/docs/intro/vs/boto.mdx +++ b/website/docs/intro/vs/boto.mdx @@ -1,9 +1,9 @@ --- -page_title: 'Terraform vs. Boto, Fog, etc.' -description: 'How Terraform compares to cloud provider client libraries like Boto and Fog. ' +page_title: Terraform versus Boto, Fog, and other cloud provider client libraries +description: Learn how Terraform's high level syntax compares to Boto, Flog, and other cloud provider client libraries. --- -# Terraform vs. Boto, Fog, etc. +# Terraform versus Boto, Fog, and other cloud provider client libraries Libraries like Boto, Fog, etc. are used to provide native access to cloud providers and services by using their APIs. Some diff --git a/website/docs/intro/vs/cloudformation.mdx b/website/docs/intro/vs/cloudformation.mdx index a677ec089a3b..eaa57524da43 100644 --- a/website/docs/intro/vs/cloudformation.mdx +++ b/website/docs/intro/vs/cloudformation.mdx @@ -1,15 +1,13 @@ --- -page_title: 'Terraform vs. CloudFormation, Heat, etc.' +page_title: Terraform versus CloudFormation, Heat, and other infrastructure as code tools description: >- - How Terraform compares to other infrastructure as code tools like - CloudFormation and Heat. Terraform can simultaneously manage multiple cloud - providers (AWS, OpenStack, etc.) and services (Cloudflare, DNSimple, etc.). + Learn how Terraform manages various cloud providers and services, such as AWS, OpenStack, Cloudflare, and DNSimple, versus CloudFormation, Heat, and other tools. --- -# Terraform vs. CloudFormation, Heat, etc. +# Terraform versus CloudFormation, Heat, and other infrastructure as code tools -Tools like CloudFormation, Heat, etc. allow the details of an infrastructure -to be codified into a configuration file. The configuration files allow +CloudFormation, Heat, and other infrastructure as code tools allow you to codify the details of infrastructure +into a configuration file. The configuration files allow the infrastructure to be elastically created, modified and destroyed. Terraform is inspired by the problems they solve. diff --git a/website/docs/intro/vs/custom.mdx b/website/docs/intro/vs/custom.mdx index dbc96e480ad7..32b18d6eb840 100644 --- a/website/docs/intro/vs/custom.mdx +++ b/website/docs/intro/vs/custom.mdx @@ -1,11 +1,10 @@ --- -page_title: Terraform vs. Custom Solutions +page_title: Terraform versus Custom Solutions description: >- - Why Terraform is easier to use and maintain than custom, internal - infrastructure solutions. + Learn how the Terraform syntax enables to Terraform binary to overcome challenges of custom infrastructure as code solutions. --- -# Terraform vs. Custom Solutions +# Terraform versus Custom Solutions Most organizations start by manually managing infrastructure through simple scripts or web-based interfaces. As the infrastructure grows, diff --git a/website/docs/intro/vs/index.mdx b/website/docs/intro/vs/index.mdx index 0a809d77f3d1..3504ffacb41e 100644 --- a/website/docs/intro/vs/index.mdx +++ b/website/docs/intro/vs/index.mdx @@ -1,9 +1,9 @@ --- -page_title: Terraform vs. Alternatives -description: An overview of how Terraform compares to alternative software and tools. +page_title: Terraform versus alternatives overview +description: Terraform lets you define infrastructure as code and automate infrastructure lifecycle management. Learn how Terraform compares to other cloud infrastructure tools. --- -# Terraform vs. Alternatives +# Terraform versus Alternatives Overview Terraform provides a flexible abstraction of resources and providers. This model allows for representing everything from physical hardware, virtual machines, and From 2f45126b5fcacbbc90873ec537456b6f378088b8 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Fri, 29 Nov 2024 13:47:03 -0800 Subject: [PATCH 03/11] Apply suggestions from code review Co-authored-by: Brian McClain --- website/docs/cli/auth/index.mdx | 2 +- website/docs/cli/code/index.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index dcbb536fddc9..2b1f70a3e5ac 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -1,5 +1,5 @@ --- -page_title: et an API token for HCP Terraform and Terraform Enterprise +page_title: Get an API token for HCP Terraform and Terraform Enterprise description: >- Use the terraform login and terraform logout commands get an API token for your HCP Terraform or Terraform Enterprise account. diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 328bffa53349..032e975a6d1e 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Write and modify Terrafrom configuration from the CLI +page_title: Format and validate Terraform configuration from the CLI description: >- Learn about the Terraform commands that help validate, format, and upgrade code written in the Terraform configuration language. From 89e96fa2262f8e167716eba65e40d4df52b88f77 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Tue, 3 Dec 2024 16:10:31 -0800 Subject: [PATCH 04/11] another batch of updates --- website/data/cli-nav-data.json | 4 +- website/docs/cli/cloud/index.mdx | 4 +- website/docs/cli/commands/apply.mdx | 10 ++-- website/docs/cli/commands/env.mdx | 12 ---- website/docs/cli/commands/force-unlock.mdx | 13 ++--- website/docs/cli/commands/get.mdx | 8 +-- website/docs/cli/commands/index.mdx | 11 +++- website/docs/cli/commands/logout.mdx | 16 ++++-- website/docs/cli/commands/providers/lock.mdx | 15 ++--- .../docs/cli/commands/providers/schema.mdx | 34 ++++------- website/docs/cli/commands/show.mdx | 28 ++++----- website/docs/cli/commands/untaint.mdx | 14 +++-- website/docs/cli/state/index.mdx | 52 ++++++++--------- website/docs/cli/state/inspect.mdx | 6 +- website/docs/cli/state/move.mdx | 7 +-- website/docs/cli/state/recover.mdx | 28 ++++----- .../docs/cli/state/resource-addressing.mdx | 12 ++-- website/docs/cli/state/taint.mdx | 57 ++++++++++--------- website/docs/cli/workspaces/index.mdx | 7 +-- 19 files changed, 158 insertions(+), 180 deletions(-) delete mode 100644 website/docs/cli/commands/env.mdx diff --git a/website/data/cli-nav-data.json b/website/data/cli-nav-data.json index 439a5c9896a8..ab5868de76d4 100644 --- a/website/data/cli-nav-data.json +++ b/website/data/cli-nav-data.json @@ -77,7 +77,7 @@ ] }, { - "title": "Manipulating State", + "title": "Manually Update State", "routes": [ { "title": "Overview", "path": "state" }, { @@ -266,7 +266,6 @@ { "title": "apply", "href": "/cli/commands/apply" }, { "title": "console", "href": "/cli/commands/console" }, { "title": "destroy", "href": "/cli/commands/destroy" }, - { "title": "env", "href": "/cli/commands/env" }, { "title": "fmt", "href": "/cli/commands/fmt" }, { "title": "force-unlock", @@ -367,7 +366,6 @@ { "title": "apply", "path": "commands/apply" }, { "title": "console", "path": "commands/console" }, { "title": "destroy", "path": "commands/destroy" }, - { "title": "env", "path": "commands/env" }, { "title": "fmt", "path": "commands/fmt" }, { "title": "force-unlock", "path": "commands/force-unlock" }, { "title": "get", "path": "commands/get" }, diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx index eaf6d3f7b867..e97651d4f452 100644 --- a/website/docs/cli/cloud/index.mdx +++ b/website/docs/cli/cloud/index.mdx @@ -1,10 +1,10 @@ --- -page_title: Using HCP Terraform - Terraform CLI +page_title: Use HCP Terraform and Terraform Enterprise with Terraform CLI overview description: >- Learn how to use HCP Terraform and Terraform Enterprise on the command line with the Terraform CLI. --- -# Using HCP Terraform with Terraform CLI +# Use HCP Terraform with Terraform CLI Overview The Terraform CLI integration with HCP Terraform lets you use HCP Terraform and Terraform Enterprise on the command line. In the documentation HCP Terraform instructions also apply to Terraform Enterprise, except where explicitly stated. diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index ae2a7cc14d12..e903d6a350cd 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -1,11 +1,15 @@ --- -page_title: 'Command: apply' +page_title: terraform apply command reference description: >- The terraform apply command executes the actions proposed in a Terraform plan to create, update, or destroy infrastructure. --- -# Command: apply +# `terraform apply` command + +This topic provides reference information about the `terraform apply` command. + +## Introduction The `terraform apply` command executes the actions proposed in a Terraform plan. @@ -16,8 +20,6 @@ plan. Usage: `terraform apply [options] [plan file]` - - ### Automatic Plan Mode When you run `terraform apply` without passing a saved plan file, Terraform automatically creates a new execution plan as if you had run [`terraform plan`](/terraform/cli/commands/plan), prompts you to approve that plan, and takes the indicated actions. You can use all of the [planning modes](/terraform/cli/commands/plan#planning-modes) and diff --git a/website/docs/cli/commands/env.mdx b/website/docs/cli/commands/env.mdx deleted file mode 100644 index bb98c9fd153f..000000000000 --- a/website/docs/cli/commands/env.mdx +++ /dev/null @@ -1,12 +0,0 @@ ---- -page_title: 'Command: env' -description: >- - The terraform env command is a deprecated form of the terraform workspace - command. ---- - -# Command: env - -The `terraform env` command is deprecated. -[The `terraform workspace` command](/terraform/cli/commands/workspace) -should be used instead. diff --git a/website/docs/cli/commands/force-unlock.mdx b/website/docs/cli/commands/force-unlock.mdx index 705d04427a74..4c169d6becdf 100644 --- a/website/docs/cli/commands/force-unlock.mdx +++ b/website/docs/cli/commands/force-unlock.mdx @@ -1,18 +1,17 @@ --- -page_title: 'Command: force-unlock' +page_title: terraform force-unlock command reference description: >- The terraform force-unlock command unlocks the state for a configuration. It does not modify your infrastructure. --- -# Command: force-unlock +# `terraform force-unlock` command -Manually unlock the state for the defined configuration. +This topic provides reference information about the `terraform force-unlock` command. This command manually unlocks the state for the defined configuration. -This will not modify your infrastructure. This command removes the lock on the -state for the current configuration. The behavior of this lock is dependent +This command removes the lock on the state for the current configuration. The behavior of this lock is dependent on the backend being used. Local state files cannot be unlocked by another -process. +process. The `terraform force-unlock` command does not modify your infrastructure. ## Usage @@ -27,4 +26,4 @@ process. Options: -* `-force` - Don't ask for input for unlock confirmation. +- `-force` - Don't ask for input for unlock confirmation. diff --git a/website/docs/cli/commands/get.mdx b/website/docs/cli/commands/get.mdx index f46b8776b9d3..e43946cddf3c 100644 --- a/website/docs/cli/commands/get.mdx +++ b/website/docs/cli/commands/get.mdx @@ -1,12 +1,12 @@ --- -page_title: 'Command: get' +page_title: terraform get command reference description: The terraform get command downloads and updates modules. --- -# Command: get +# `terraform get` command -The `terraform get` command is used to download and update -[modules](/terraform/language/modules/develop) mentioned in the root module. +Run the `terraform get` command to download and update +[modules](/terraform/language/modules/develop) declared in the root module. ## Usage diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx index 3e3431c5c9d6..d26b5dc293f6 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.mdx @@ -1,12 +1,17 @@ --- -page_title: Basic CLI Features -description: An introduction to the terraform command and its available subcommands. +page_title: Terraform CLI overview +description: The Terrafrom CLI includes commands for provisioning infrastructure as code and managing the infrastructure lifecycle. Learn about Terraform CLI features. --- -# Basic CLI Features +# Terraform CLI Overview + +This topic provides an overview of the Terraform command line. > **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. + +## Introduction + The command line interface to Terraform is the `terraform` command, which accepts a variety of subcommands such as `terraform init` or `terraform plan`. diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.mdx index f0158fa9a7cd..3c4817b4f797 100644 --- a/website/docs/cli/commands/logout.mdx +++ b/website/docs/cli/commands/logout.mdx @@ -1,14 +1,18 @@ --- -page_title: 'Command: logout' +page_title: terraform logout command reference description: >- - The terraform logout command is used to remove credentials stored by terraform - login. + The terraform logout command removes credentials stored after using the terraform + login command. --- -# Command: logout +# `terraform logout` command -The `terraform logout` command is used to remove credentials stored by -`terraform login`. These credentials are API tokens for HCP Terraform, +This topic provides reference information about the `terraform logout` command. + +## Introduction + +Use the `terraform logout` command to remove credentials stored after running the +`terraform login` command. These credentials are API tokens for HCP Terraform, Terraform Enterprise, or any other host that offers Terraform services. ## Usage diff --git a/website/docs/cli/commands/providers/lock.mdx b/website/docs/cli/commands/providers/lock.mdx index 3216618e2d49..4ea85060ab79 100644 --- a/website/docs/cli/commands/providers/lock.mdx +++ b/website/docs/cli/commands/providers/lock.mdx @@ -1,15 +1,18 @@ --- -page_title: 'Command: providers lock' +page_title: terraform providers lock command reference description: |- The `terraform providers lock` command adds new provider selection information to the dependency lock file without initializing the referenced providers. --- -# Command: terraform providers lock +# `terraform providers lock` command -The `terraform providers lock` consults upstream registries (by default) in -order to write provider dependency information into -[the dependency lock file](/terraform/language/files/dependency-lock). +The `terraform providers lock` adds new provider selection information to the dependency lock file without initializing the referenced providers. + +## Introduction + +When you run the command, Terraform consults upstream registries and writes provider dependency information into the +the dependency lock file. Refer to [Dependency Lock File](/terraform/language/files/dependency-lock) in the Terraform configuration language reference documentation for additional information about the lock file. The common way to update the dependency lock file is as a side-effect of normal provider installation during @@ -37,8 +40,6 @@ automatic approach may not be sufficient: You can avoid that by pre-populating hashes for all of the platforms you intend to use, using the `terraform providers lock` command. --> `terraform providers lock` is available only in Terraform v0.14 or later. - ## Usage Usage: `terraform providers lock [options] [providers...]` diff --git a/website/docs/cli/commands/providers/schema.mdx b/website/docs/cli/commands/providers/schema.mdx index 052bb0f45ae7..af0cf6eb3a3d 100644 --- a/website/docs/cli/commands/providers/schema.mdx +++ b/website/docs/cli/commands/providers/schema.mdx @@ -1,40 +1,30 @@ --- -page_title: 'Command: providers schema' +page_title: terraform providers schema command description: >- - The `terraform providers schema` command prints detailed schemas for the - providers used - - in the current configuration. + The `terraform providers schema` command prints detailed schemas for the providers declared in the configuration. --- -# Command: terraform providers schema - -The `terraform providers schema` command is used to print detailed schemas for the providers used in the current configuration. +# `terraform providers schema` command --> `terraform providers schema` requires **Terraform v0.12 or later**. +The `terraform providers schema` command print detailed schemas for the providers used in the current configuration. ## Usage -Usage: `terraform providers schema [options]` +``` +$ terraform providers schema [options] +``` The following flags are available: -- `-json` - Displays the schemas in a machine-readable, JSON format. - -Please note that, at this time, the `-json` flag is a _required_ option. In future releases, this command will be extended to allow for additional options. +- `-json` - Displays the schemas in a machine-readable JSON format. The `-json` flag is required. -The output includes a `format_version` key, which as of Terraform 1.1.0 has -value `"1.0"`. The semantics of this version are: + The output includes a `format_version` key, which has a default value of `"1.0"`. The semantics of this version are: -- We will increment the minor version, e.g. `"1.1"`, for backward-compatible - changes or additions. Ignore any object properties with unrecognized names to + - Versions between `1.0` and `2.0` are backward-compatible. You should ignore any object properties with unrecognized names to remain forward-compatible with future minor versions. -- We will increment the major version, e.g. `"2.0"`, for changes that are not - backward-compatible. Reject any input which reports an unsupported major + - Major versions are not backward-compatible to older versions. You should reject any input that reports an unsupported major version. - -We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). + - Refer to [Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises) for additional information about version support. ## Format Summary diff --git a/website/docs/cli/commands/show.mdx b/website/docs/cli/commands/show.mdx index cbde69f54e58..cee62369cf02 100644 --- a/website/docs/cli/commands/show.mdx +++ b/website/docs/cli/commands/show.mdx @@ -1,21 +1,15 @@ --- -page_title: 'Command: show' -description: >- - The `terraform show` command is used to provide human-readable output from a - state or plan file. This can be used to inspect a plan to ensure that the - planned operations are expected, or to inspect the current state as Terraform - sees it. +page_title: terraform show command reference +description: The `terraform show` command provides human-readable output from a state or plan file. --- -# Command: show +# `terraform show` command -The `terraform show` command is used to provide human-readable output -from a state or plan file. This can be used to inspect a plan to ensure +The `terraform show` command provides human-readable output +from a state or plan file. Use the command to inspect a plan to ensure that the planned operations are expected, or to inspect the current state as Terraform 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 Terraform state will be displayed in plain text. For more information, see @@ -23,14 +17,16 @@ Terraform state will be displayed in plain text. For more information, see ## JSON Output -For Terraform state files (including when no path is provided), -`terraform show -json` will show a JSON representation of the state. +Add the `-json` command-line flag to generate machine-readable output. -For Terraform plan files, `terraform show -json` will show a JSON representation +For Terraform state files, including when no path is provided, +`terraform show -json` shows a JSON representation of the state. + +For Terraform plan files, `terraform show -json` shows a JSON representation of the plan, configuration, and current state. -If you've updated providers which contain new schema versions since the state -was written, the state needs to be upgraded before it can be displayed with +If you updated providers that contain new schema versions since the state +was written, upgrade the state before so that Terraform can display it with `show -json`. If you are viewing a plan, it must be created without `-refresh=false`. If you are viewing a state file, run `terraform refresh` first. diff --git a/website/docs/cli/commands/untaint.mdx b/website/docs/cli/commands/untaint.mdx index 61bb3ee4dae7..bd2163ae39c8 100644 --- a/website/docs/cli/commands/untaint.mdx +++ b/website/docs/cli/commands/untaint.mdx @@ -1,14 +1,16 @@ --- -page_title: 'Command: untaint' +page_title: terraform untaint command reference description: |- - The `terraform untaint` command tells Terraform that an object is functioning - correctly, even though its creation failed or it was previously manually - marked as degraded. + The `terraform untaint` command removes the `tainted` status from infrastructure objects tracked in the Terraform state data. --- -# Command: untaint +# `terraform untaint` command -Terraform has a marker called "tainted" which it uses to track that an object +This topic provides reference information about the `terraform untaint` command. + +## Introduction + +Terraform has a marker called `tainted` which it uses to track that an object might be damaged and so a future Terraform plan ought to replace it. Terraform automatically marks an object as "tainted" if an error occurs during diff --git a/website/docs/cli/state/index.mdx b/website/docs/cli/state/index.mdx index b5d39bd52832..1e419491d8f8 100644 --- a/website/docs/cli/state/index.mdx +++ b/website/docs/cli/state/index.mdx @@ -1,34 +1,32 @@ --- -page_title: Manipulating State - Terraform CLI +page_title: Update Terraform state manually description: >- - State data tracks which real-world object corresponds to each resource. - Inspect state, move or import resources, and more. + State data is the record of how real-world objects map to resources in the Terraform configuration. Learn how to manually update with state data. --- -# Manipulating Terraform State +# Update Terraform state manually overview + +This topic provides overview information about how to manually update state in Terraform. > **Hands-on:** Try the [Manage Resources in Terraform State](/terraform/tutorials/state/state-cli?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. -Terraform uses [state data](/terraform/language/state) to remember which -real-world object corresponds to each resource in the configuration; -this allows it to modify an existing object when its resource declaration -changes. - -Terraform updates state automatically during plans and applies. However, it's -sometimes necessary to make deliberate adjustments to Terraform's state data, -usually to compensate for changes to the configuration or the real managed -infrastructure. - -Terraform CLI supports several workflows for interacting with state: - -- [Inspecting State](/terraform/cli/state/inspect) -- [Forcing Re-creation](/terraform/cli/state/taint) -- [Moving Resources](/terraform/cli/state/move) -- Importing Pre-existing Resources (documented in the - [Importing Infrastructure](/terraform/cli/import) section) -- [Disaster Recovery](/terraform/cli/state/recover) - -~> **Important:** Modifying state data outside a normal plan or apply can cause -Terraform 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. +## Introduction + +Terraform stores information about real-world object that correspond to resources in the configuration as [state data](/terraform/language/state). +Doing so allows Terraform to modify an existing object when its resource declaration changes. + +Terraform automatically updates state when you run the `terraform plan` and `terraform apply` commands, but you may need to manually adjustment state data as a result of changes to the configuration or the real managed infrastructure. + +## Workflow + +Modifying state data outside of normal `terraform plan` or `terraform apply` operations can cause Terraform to lose track of managed resources, leading to increased costs, reduced productivity, or compromised security. Make sure to keep backups of your state data if you choose to manually modify state. + +You can use the Terraform CLI to perform the following state interations: + +- [Inspect state](/terraform/cli/state/inspect) +- [Re-create resources](/terraform/cli/state/taint) +- [Move resources](/terraform/cli/state/move) +- [Import existing resources](/terraform/cli/import) +- [Recover state from backup](/terraform/cli/state/recover) + + diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.mdx index 439a0646f836..dd9accd2d451 100644 --- a/website/docs/cli/state/inspect.mdx +++ b/website/docs/cli/state/inspect.mdx @@ -1,9 +1,9 @@ --- -page_title: Inspecting State - Terraform CLI -description: Commands that allow you to read and update state. +page_title: Inspect Terraform state overview +description: The `terraform state` group of commands help you inspect Terraform state. Learn how inspecting Terraform state can help you read and update state. --- -# Inspecting State +# Inspect Terraform State Overview Terraform includes some commands for reading and updating state without taking any other actions. diff --git a/website/docs/cli/state/move.mdx b/website/docs/cli/state/move.mdx index 326cd9f8fc20..5256be914bd9 100644 --- a/website/docs/cli/state/move.mdx +++ b/website/docs/cli/state/move.mdx @@ -1,11 +1,10 @@ --- -page_title: Moving Resources - Terraform CLI +page_title: Move resources overview description: >- - Commands that allow you to manage the way that resources are tracked in state. - They are helpful when you move or change resources. + Terraform state commands can move and remove resources and transfer existing resources to a different provider. Learn how about changing or moving resources. --- -# Moving Resources +# Move Resources Terraform's state associates each real-world object with a configured resource at a specific [resource address](/terraform/cli/state/resource-addressing). This diff --git a/website/docs/cli/state/recover.mdx b/website/docs/cli/state/recover.mdx index 07675491c033..68155abe8f57 100644 --- a/website/docs/cli/state/recover.mdx +++ b/website/docs/cli/state/recover.mdx @@ -1,25 +1,19 @@ --- -page_title: Recovering from State Disasters - Terraform CLI +page_title: Recover state from backup overview description: >- Learn how to restore state backups and override Terraform state protections to fix state errors with the Terraform CLI. - --- -# Recovering from State Disasters +# Recover state from backup overview + +This topic provides overview information about recovering Terraform state from a backup after a disaster, such as an accident when performing +other state manipulation actions. -If something has gone horribly wrong (possibly due to accidents when performing -other state manipulation actions), you might need to take drastic actions with -your state data. +## Workflow -- [The `terraform force-unlock` command](/terraform/cli/commands/force-unlock) can - override the protections Terraform uses to prevent two processes from - modifying state at the same time. You might need this if a Terraform process - (like a normal apply) is unexpectedly terminated (like by the complete - destruction of the VM it's running in) before it can release its lock on the - state backend. Do not run this until you are completely certain what happened - to the process that caused the lock to get stuck. +1. **Unlock Terraform**: You may need to unlock Terraform when a `terraform apply` or other process unexpectedly terminates before Terraform can release its lock on the state backend. Unlocking Terraform overrides protectionsthat prevent two processes from modifying state at the same time. We do not recommend unlocking until you determine what caused the lock to get stuck. -- [The `terraform state pull` command](/terraform/cli/commands/state/pull) and - [the `terraform state push` command](/terraform/cli/commands/state/push) can - directly read and write entire state files from and to the configured backend. - You might need this for obtaining or restoring a state backup. + Refer to the [`terraform force-unlock` command](/terraform/cli/commands/force-unlock) documentation for additional information. + +1. **Read state data**: Run the [`terraform state pull` command](/terraform/cli/commands/state/pull) to read the state files from the configured backend. +1. **Write state data**: Run the [`terraform state push` command](/terraform/cli/commands/state/push) to write state files to the configured backend. \ No newline at end of file diff --git a/website/docs/cli/state/resource-addressing.mdx b/website/docs/cli/state/resource-addressing.mdx index 48e3609a6539..04e4b756decb 100644 --- a/website/docs/cli/state/resource-addressing.mdx +++ b/website/docs/cli/state/resource-addressing.mdx @@ -1,11 +1,13 @@ --- -page_title: 'Internals: Resource Address' -description: |- - A resource address is a string that identifies zero or more resource - instances in your overall configuration. +page_title: Resource address reference +description: Use the resource address to reference specific instances of resources elsewhere in the configuration. Learn how Terraform creates addresses for resources. --- -# Resource Addressing +# Resource Address Reference + +This topic provides reference information about resource addresses in Terraform. + +## Syntax A _resource address_ is a string that identifies zero or more resource instances in your overall configuration. diff --git a/website/docs/cli/state/taint.mdx b/website/docs/cli/state/taint.mdx index dbf1229b9876..42673141f934 100644 --- a/website/docs/cli/state/taint.mdx +++ b/website/docs/cli/state/taint.mdx @@ -1,25 +1,35 @@ --- -page_title: Forcing Re-creation of Resources - Terraform CLI -description: Commands that allow you to destroy and re-create resources manually. +page_title: Recreate resources overview +description: The -replace flag and taint command help you replace infrastructure objects. Learn how the -replace flag and taint command can help you recreate resources. --- -# Forcing Re-creation of Resources +# Recreate resources overview -During planning, by default Terraform retrieves the latest state of each -existing object and compares it with the current configuration, planning -actions only against objects whose current state does not match the -configuration. +This topic provides an overview of how to recreate resources in Terraform. -However, in some cases a remote object may become damaged or degraded in a -way that Terraform cannot automatically detect. For example, if software -running inside a virtual machine crashes but the virtual machine itself is -still running then Terraform will typically have no way to detect and respond -to the problem, because Terraform only directly manages the machine as a whole. +## Introduction -If you know that an object is damaged, or if you want to force Terraform to -replace it for any other reason, you can override Terraform's default behavior -using [the `-replace=...` planning option](/terraform/cli/commands/plan#replace-address) -when you run either `terraform plan` or `terraform apply`: +By default, Terraform retrieves the latest state of each existing object and compares it with the current configuration when you run the `terraform apply` command. Terraform only takes action on objects that do not match the configuration. + +When remote objects become damaged or degraded, such as when software +running inside a virtual machine crashes but the virtual machine is +still running, Terraform does not have no way to detect and respond +to the problem. This is because Terraform only directly manages the machine as a whole. + +In some cases, Terraform can automatically infer that an object is in an +incomplete or degraded state. For example, when a complex object is partially created in the remote system or +when a provisioner step failed. When this occurs, Terraform automatically flags resources to recreate. + +You can manually replace objects when Terraform is unable to infer that an object should be replaced. + +## Workflows + +When you meed to replace an object, you can use the following methods. + +### Manually replace resources + +Add the [`-replace` flag](/terraform/cli/commands/plan#replace-address) +to your `terraform plan` or `terraform apply` command: ```shellsession $ terraform apply -replace="aws_instance.example" @@ -31,18 +41,9 @@ $ terraform apply -replace="aws_instance.example" } ``` -## The "tainted" status - -Sometimes Terraform is able to infer automatically that an object is in an -incomplete or degraded state. For example, if creation of a complex object -fails in such a way that parts of it already exist in the remote system, or -if object creation succeeded but a provisioner step subsequently failed, -Terraform must remember that the object exists but may not be fully-functional. +### Replace resource in `tainted` state -Terraform represents this situation by marking an object in the state as -"tainted". When an object is marked with this status, the next plan will force -replacing that object in a similar way to if you had specified that object's -address using `-replace=...` as described above. +Terraform applies the `tainted` status to objects in the state data when Terraform is able to infer that the object is in a degraded or damaged state. This status indicates that the object exists but may not be fully-functional. Terraform replaces objects in a `tainted` states during the next `plan` or `apply` operation. ``` # aws_instance.example is tainted, so must be replaced @@ -57,7 +58,7 @@ determination using [the `terraform untaint` command](/terraform/cli/commands/un after which Terraform will consider the object to be ready for use by any downstream resource declarations. -You can also _force_ Terraform to mark a particular object as tainted using +You can force Terraform to mark a particular object as tainted using [the `terraform taint` command](/terraform/cli/commands/taint), but that approach is deprecated in favor of the `-replace=...` option, which avoids the need to create an interim state snapshot with a tainted object. diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx index 77feaba78437..b776fcb45ca8 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -1,11 +1,10 @@ --- -page_title: Managing Workspaces - Terraform CLI +page_title: Manage workspaces overview description: >- - Commands to list, select, create, and output workspaces. Workspaces help - manage different groups of resources with one configuration. + Workspaces are separate instances of Terraform state data. Learn commands for managing workspaces. --- -# Managing Workspaces +# Manage Workspaces Overview Workspaces in the Terraform CLI refer to separate instances of [state data](/terraform/language/state) inside the same Terraform working directory. They are distinctly different from [workspaces in HCP Terraform](/terraform/cloud-docs/workspaces), which each have their own Terraform configuration and function as separate working directories. From 6844a88f89131673ad655b117ce24f77a0f42349 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 9 Dec 2024 11:59:03 -0800 Subject: [PATCH 05/11] completed seo refresh for cli ref --- website/data/cli-nav-data.json | 37 +----- website/docs/cli/commands/0.12upgrade.mdx | 117 ------------------ website/docs/cli/commands/0.13upgrade.mdx | 89 ------------- website/docs/cli/commands/apply.mdx | 4 - website/docs/cli/commands/console.mdx | 8 +- website/docs/cli/commands/destroy.mdx | 9 +- website/docs/cli/commands/fmt.mdx | 29 +++-- website/docs/cli/commands/graph.mdx | 8 +- website/docs/cli/commands/import.mdx | 11 +- website/docs/cli/commands/init.mdx | 12 +- website/docs/cli/commands/login.mdx | 14 +-- website/docs/cli/commands/output.mdx | 10 +- website/docs/cli/commands/plan.mdx | 10 +- .../docs/cli/commands/providers/mirror.mdx | 4 +- website/docs/cli/commands/push.mdx | 14 --- website/docs/cli/commands/refresh.mdx | 24 +--- website/docs/cli/commands/state/index.mdx | 26 ++-- website/docs/cli/commands/state/list.mdx | 8 +- website/docs/cli/commands/state/mv.mdx | 20 ++- website/docs/cli/commands/state/pull.mdx | 11 +- website/docs/cli/commands/state/push.mdx | 13 +- .../cli/commands/state/replace-provider.mdx | 6 +- website/docs/cli/commands/state/rm.mdx | 21 +--- website/docs/cli/commands/state/show.mdx | 8 +- website/docs/cli/commands/taint.mdx | 14 +-- website/docs/cli/commands/test.mdx | 16 +-- website/docs/cli/commands/validate.mdx | 12 +- website/docs/cli/commands/version.mdx | 21 ++-- .../docs/cli/commands/workspace/delete.mdx | 8 +- website/docs/cli/commands/workspace/index.mdx | 9 +- website/docs/cli/commands/workspace/list.mdx | 8 +- website/docs/cli/commands/workspace/new.mdx | 6 +- .../docs/cli/commands/workspace/select.mdx | 9 +- website/docs/cli/commands/workspace/show.mdx | 10 +- website/docs/cli/import/importability.mdx | 16 --- website/docs/cli/import/index.mdx | 38 ++++-- website/docs/cli/import/usage.mdx | 35 +++--- website/docs/cli/run/index.mdx | 33 ++--- 38 files changed, 233 insertions(+), 515 deletions(-) delete mode 100644 website/docs/cli/commands/0.12upgrade.mdx delete mode 100644 website/docs/cli/commands/0.13upgrade.mdx delete mode 100644 website/docs/cli/commands/push.mdx delete mode 100644 website/docs/cli/import/importability.mdx diff --git a/website/data/cli-nav-data.json b/website/data/cli-nav-data.json index ab5868de76d4..6bc6030ed713 100644 --- a/website/data/cli-nav-data.json +++ b/website/data/cli-nav-data.json @@ -33,15 +33,7 @@ { "title": "Overview", "path": "code" }, { "title": "console", "href": "/cli/commands/console" }, { "title": "fmt", "href": "/cli/commands/fmt" }, - { "title": "validate", "href": "/cli/commands/validate" }, - { - "title": "0.13upgrade", - "href": "/cli/commands/0.13upgrade" - }, - { - "title": "0.12upgrade", - "href": "/cli/commands/0.12upgrade" - } + { "title": "validate", "href": "/cli/commands/validate" } ] }, { @@ -62,17 +54,13 @@ ] }, { - "title": "Importing Infrastructure", + "title": "Import Infrastructure", "routes": [ { "title": "Overview", "path": "import" }, + { "title": "Import existing resources", "path": "import/usage" }, { - "title": "import", + "title": "Reference", "href": "/cli/commands/import" - }, - { "title": "Usage Tips", "path": "import/usage" }, - { - "title": "Resource Importability", - "path": "import/importability" } ] }, @@ -293,10 +281,6 @@ "title": "providers schema", "href": "/cli/commands/providers/schema" }, - { - "title": "push (deprecated)", - "href": "/cli/commands/push" - }, { "title": "refresh", "href": "/cli/commands/refresh" }, { "title": "show", "href": "/cli/commands/show" }, { "title": "state", "href": "/cli/commands/state" }, @@ -347,14 +331,6 @@ { "title": "workspace show", "href": "/cli/commands/workspace/show" - }, - { - "title": "0.12upgrade", - "href": "/cli/commands/0.12upgrade" - }, - { - "title": "0.13upgrade", - "href": "/cli/commands/0.13upgrade" } ] }, @@ -386,7 +362,6 @@ { "title": "providers schema", "path": "commands/providers/schema" } ] }, - { "title": "push (deprecated)", "path": "commands/push" }, { "title": "refresh", "path": "commands/refresh" }, { "title": "show", "path": "commands/show" }, { @@ -423,9 +398,7 @@ { "title": "workspace delete", "path": "commands/workspace/delete" }, { "title": "workspace show", "path": "commands/workspace/show" } ] - }, - { "title": "0.12upgrade", "path": "commands/0.12upgrade" }, - { "title": "0.13upgrade", "path": "commands/0.13upgrade" } + } ] }, { diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.mdx deleted file mode 100644 index eb4acc2a2a23..000000000000 --- a/website/docs/cli/commands/0.12upgrade.mdx +++ /dev/null @@ -1,117 +0,0 @@ ---- -page_title: 'Command: 0.12upgrade' -description: >- - The 0.12upgrade subcommand automatically rewrites existing configurations for - Terraform 0.12 compatibility. ---- - -# Command: 0.12upgrade - -The `terraform 0.12upgrade` command applies several automatic upgrade rules to -help prepare a module that was written for Terraform v0.11 to be used -with Terraform v0.12. - --> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12). - -## Usage - -Usage: `terraform 0.12upgrade [options] [dir]` - -By default, `0.12upgrade` changes configuration files in the current working -directory. However, you can provide an explicit path to another directory if -desired, which may be useful for automating migrations of several modules in -the same repository. - -When run with no other options, the command will first explain what it is -going to do and prompt for confirmation: - -``` -$ terraform 0.12upgrade - -This command will rewrite the configuration files in the given directory so -that they use the new syntax features from Terraform v0.12, and will identify -any constructs that may need to be adjusted for correct operation with -Terraform v0.12. - -We recommend using this command in a clean version control work tree, so that -you can easily see the proposed changes as a diff against the latest commit. -If you have uncommitted changes already present, we recommend aborting this -command and dealing with them before running this command again. - -Would you like to upgrade the module in the current directory? - Only 'yes' will be accepted to confirm. - - Enter a value: yes -``` - -The `0.12upgrade` subcommand requires access to providers used in the -configuration in order to analyze their resource types, so it's important to -run `terraform init` first to install these. In some rare cases, a configuration -that worked in v0.11 may have syntax errors in v0.12, in which case -`terraform init` will run in a special mode where it installs only enough to -run the upgrade command, after which you can run `terraform init` again to -complete initialization. - -Many of the rewrite rules are completely automatic, but in some cases the -tool cannot determine enough information from the configuration alone to make -a decision, and so it will instead add a comment to the configuration for -user review. All such comments contain the string `TF-UPGRADE-TODO` to make -them easier to find. - -After upgrading, the configuration will also be reformatted into the standard -Terraform style and expressions rewritten to use the more-readable v0.12 syntax -features. - -We recommend running this command with a clean version control work tree so -that you can use VCS tools to review the proposed changes, including any -`TF-UPGRADE-TODO` comments, and make any revisions required before committing -the change. - -Once upgraded the configuration will no longer be compatible with Terraform -v0.11 and earlier. When upgrading a shared module that is called from multiple -configurations, you may need to -[fix existing configurations to a previous version](/terraform/language/modules/syntax#version) -to allow for a gradual upgrade. If the module is published via -[a Terraform registry](/terraform/registry), assign a new _major_ version number -to the upgraded module source to represent the fact that this is a breaking -change for v0.11 callers. If a module is installed directly from a version -control system such as Git, -[use specific revisions](/terraform/language/modules/sources#selecting-a-revision) -to control which version is used by which caller. - -The command-line options are all optional. The available options are: - -* `-yes` - Skip the initial introduction messages and interactive confirmation. - Use this when running the command in batch from a script. - -* `-force` - Override the heuristic that attempts to detect if a configuration - is already written for v0.12 or later. Some of the transformations made by - this command are not idempotent, so re-running against the same module may - change the meanings of some expressions in the module. - -## Batch Usage - -After you've experimented with the `0.12upgrade` command in some confined -situations, if you have a repository containing multiple modules you may -wish to batch-upgrade them all and review them together. Recursive upgrades -are not supported by the tool itself, but if you are on a Unix-style system -you can achieve this using the `find` command as follows: - -``` -find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes -``` - -On Mac OS X, the `find` included with the system does not support the `-printf` argument. You can install GNU find using Homebrew in order to use that argument: - -``` -brew install findutils -``` - -Once installed, run the above command line using `gfind` instead of `find`. - -Note that the above includes the `-yes` option to override the interactive -prompt, so be sure you have a clean work tree before running it. - -Because upgrading requires access to the configuration's provider plugins, -all of the directories must be initialized with `terraform init` prior to -running the above. diff --git a/website/docs/cli/commands/0.13upgrade.mdx b/website/docs/cli/commands/0.13upgrade.mdx deleted file mode 100644 index 51c5f451503a..000000000000 --- a/website/docs/cli/commands/0.13upgrade.mdx +++ /dev/null @@ -1,89 +0,0 @@ ---- -page_title: 'Command: 0.13upgrade' -description: >- - The 0.13upgrade subcommand updates existing configurations to use the new - provider source features from Terraform 0.13. ---- - -# Command: 0.13upgrade - -The `terraform 0.13upgrade` command updates existing configuration to add an -explicit `source` attribute for each provider used in a given module. The -provider source settings are stored in a `required_providers` block. - --> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-13). - -## Usage - -Usage: `terraform 0.13upgrade [options] [dir]` - -The primary purpose of the `0.13upgrade` command is to determine which -providers are in use for a module, detect the source address for those -providers where possible, and record this information in a -[`required_providers` block][required-providers]. - -[required-providers]: /terraform/language/providers/requirements - -~> Note: the command ignores `.tf.json` files and override files in the module. - -If the module already has a `required_providers` block, the command updates it -in-place. Otherwise, a new block is added to the `versions.tf` file. - -By default, `0.13upgrade` changes configuration files in the current working -directory. However, you can provide an explicit path to another directory if -desired, which may be useful for automating migrations of several modules in -the same repository. - -When run with no other options, the command will first explain what it is -going to do and prompt for confirmation: - -``` -$ terraform 0.13upgrade - -This command will update the configuration files in the given directory to use -the new provider source features from Terraform v0.13. It will also highlight -any providers for which the source cannot be detected, and advise how to -proceed. - -We recommend using this command in a clean version control work tree, so that -you can easily see the proposed changes as a diff against the latest commit. -If you have uncommited changes already present, we recommend aborting this -command and dealing with them before running this command again. - -Would you like to upgrade the module in the current directory? - Only 'yes' will be accepted to confirm. - - Enter a value: yes -``` - -We recommend running this command with a clean version control work tree so -that you can use VCS tools to review the proposed changes, including any -`TF-UPGRADE-TODO` comments, and make any revisions required before committing -the change. - -There is one command-line option: - -* `-yes` - Skip the initial introduction messages and interactive confirmation. - Use this when running the command in batch from a script. - -## Batch Usage - -After you've experimented with the `0.13upgrade` command in some confined -situations, if you have a repository containing multiple modules you may -wish to batch-upgrade them all and review them together. Recursive upgrades -are not supported by the tool itself, but if you are on a Unix-style system -you can achieve this using the `find` command as follows: - -``` -$ find . -name '*.tf' | xargs -n1 dirname | uniq | xargs -n1 terraform 0.13upgrade -yes -``` - -On a Windows system with PowerShell, you can use this command: - -``` -Get-Childitem -Recurse -Include *.tf | Split-Path | ` -Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName } -``` - -Note that the above commands include the `-yes` option to override the -interactive prompt, so be sure you have a clean work tree before running it. diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index e903d6a350cd..026b8e882af7 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -7,10 +7,6 @@ description: >- # `terraform apply` command -This topic provides reference information about the `terraform apply` command. - -## Introduction - The `terraform apply` command executes the actions proposed in a Terraform plan. diff --git a/website/docs/cli/commands/console.mdx b/website/docs/cli/commands/console.mdx index e5ad1e506d09..cc2df57dbaec 100644 --- a/website/docs/cli/commands/console.mdx +++ b/website/docs/cli/commands/console.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: console' +page_title: terraform console command reference description: >- - The terraform console command provides an interactive console for evaluating + The terraform console command opens an interactive console for evaluating expressions. --- -# Command: console +# `terraform console` command -The `terraform console` command provides an interactive console for +The `terraform console` command opens an interactive console for evaluating [expressions](/terraform/language/expressions). ## Usage diff --git a/website/docs/cli/commands/destroy.mdx b/website/docs/cli/commands/destroy.mdx index a7d26ab6c2d1..a1cd4746118d 100644 --- a/website/docs/cli/commands/destroy.mdx +++ b/website/docs/cli/commands/destroy.mdx @@ -1,14 +1,13 @@ --- -page_title: 'Command: destroy' +page_title: terraform destroy command reference description: >- - The terraform destroy command destroys all objects managed by a Terraform + The terraform destroy command deprovisions all objects managed by a Terraform configuration. --- -# Command: destroy +# `terraform destroy` command -The `terraform destroy` command is a convenient way to destroy all remote -objects managed by a particular Terraform configuration. +The `terraform destroy` command deprovisions all objects managed by a Terraform configuration. While you will typically not want to destroy long-lived objects in a production environment, Terraform is sometimes used to manage ephemeral infrastructure diff --git a/website/docs/cli/commands/fmt.mdx b/website/docs/cli/commands/fmt.mdx index 5c5ad2f30403..85bf224b983d 100644 --- a/website/docs/cli/commands/fmt.mdx +++ b/website/docs/cli/commands/fmt.mdx @@ -1,33 +1,32 @@ --- -page_title: 'Command: fmt' +page_title: terraform fmt command reference description: >- - The terraform fmt command rewrites configuration files to a canonical format + The terraform fmt command formats Terraform configuration contents so that it matches the canonical format and style. --- -# Command: fmt +# `terraform fmt` command -The `terraform fmt` command is used to rewrite Terraform configuration files -to a canonical format and style. This command applies a subset of +The `terraform fmt` command formats Terraform configuration file contents so that it matches the canonical format and style. This command applies a subset of the [Terraform language style conventions](/terraform/language/style#code-formatting), along with other minor adjustments for readability. -Other Terraform commands that generate Terraform configuration will produce -configuration files that conform to the style imposed by `terraform fmt`, so -using this style in your own files will ensure consistency. +## Introduction +Terraform commands that generate Terraform configuration produce +configuration files that conform to the style imposed by `terraform fmt`. Follow this style in your files to ensure consistency. The canonical format may change in minor ways between Terraform versions, so after upgrading Terraform we recommend to proactively run `terraform fmt` on your modules along with any other changes you are making to adopt the new version. -We don't consider new formatting rules in `terraform fmt` to be a breaking -change in new versions of Terraform, but we do aim to minimize changes for -configurations that are already following the style examples shown in the -Terraform documentation. When adding new formatting rules, they will usually -aim to apply more of the rules already shown in the configuration examples -in the documentation, and so we recommend following the documented style even -for decisions that `terraform fmt` doesn't yet apply automatically. +We do not consider new formatting rules in `terraform fmt` to be a breaking +change in new versions of Terraform, but we minimize changes for +configurations that already follow the style examples shown in the +Terraform documentation. New formatting rules programmed into the `terraform fmt` +command are usually expansions to include existing rules from the documentation. +We recommend following the documented style even for decisions that `terraform fmt` +does not yet apply automatically. Formatting decisions are always subjective and so you might disagree with the decisions that `terraform fmt` makes. This command is intentionally opinionated diff --git a/website/docs/cli/commands/graph.mdx b/website/docs/cli/commands/graph.mdx index 6ee59236ad88..cd0a3906dbcc 100644 --- a/website/docs/cli/commands/graph.mdx +++ b/website/docs/cli/commands/graph.mdx @@ -1,15 +1,13 @@ --- -page_title: 'Command: graph' +page_title: terraform graph command reference description: >- The terraform graph command generates a visual representation of a configuration or execution plan that you can use to generate charts. --- -# Command: graph +# `terraform graph` command -The `terraform graph` command produces descriptions of the relationships -between objects in a Terraform configuration, using -[the DOT language](https://en.wikipedia.org/wiki/DOT_(graph_description_language)). +The `terraform graph` command generates a visual representation of a configuration or execution plan that you can use to generate charts. This command uses the DOT language generate graphs. Refer to the [GraphViz documentation](https://graphviz.org/doc/info/lang.html) for additional information. ## Usage diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx index 6f26f2d6a571..fae730dfab6e 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.mdx @@ -1,14 +1,15 @@ --- -page_title: 'Command: import' -description: The terraform import command brings existing resources into Terraform state. +page_title: terraform import command reference +description: The terraform import command imports existing resources into Terraform state. --- -# Command: import +# `terraform import` command reference + +The `terraform import` command imports existing resources into Terraform. Refer to [Import](/terraform/cli/import) for additional information. + > **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. -The `terraform import` command [imports existing resources](/terraform/cli/import) -into Terraform. ## Usage diff --git a/website/docs/cli/commands/init.mdx b/website/docs/cli/commands/init.mdx index b139bdfbd4ba..26579347ba2e 100644 --- a/website/docs/cli/commands/init.mdx +++ b/website/docs/cli/commands/init.mdx @@ -1,19 +1,19 @@ --- -page_title: 'Command: init' +page_title: terraform init command reference description: >- The terraform init command initializes a working directory containing configuration files and installs plugins for required providers. --- -# Command: init - -> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. For more in-depth details on the `init` command, check out the [Initialize Terraform Configuration tutorial](/terraform/tutorials/cli/init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). +# `terraform init` command The `terraform init` command initializes a working directory -containing Terraform configuration files. This is the first command that should -be run after writing a new Terraform configuration or cloning an existing one +containing Terraform configuration files. This is the first command you should +run after writing a new Terraform configuration or cloning an existing configuration from version control. It is safe to run this command multiple times. +> **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. For more in-depth details on the `init` command, check out the [Initialize Terraform Configuration tutorial](/terraform/tutorials/cli/init?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS). + ## Usage Usage: `terraform init [options]` diff --git a/website/docs/cli/commands/login.mdx b/website/docs/cli/commands/login.mdx index b2eb5372bbbd..961b8451a977 100644 --- a/website/docs/cli/commands/login.mdx +++ b/website/docs/cli/commands/login.mdx @@ -1,18 +1,16 @@ --- -page_title: 'Command: login' +page_title: terraform login command reference description: >- - The terraform login command can be used to automatically obtain and save an - API token for HCP Terraform, Terraform Enterprise, or any other host that + The terraform login command obtains an API token for HCP Terraform, Terraform Enterprise, or other host that offers Terraform services. --- -# Command: login +# `terraform login` command -The `terraform login` command can be used to automatically obtain and save an -API token for HCP Terraform, Terraform Enterprise, or any other host that offers Terraform services. +The `terraform login` command obtains an API token for HCP Terraform, Terraform Enterprise, or other host that + offers Terraform services. --> **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 Terraform +You can only use this command in interactive scenarios because the command launches a web browser on the same host where Terraform is running. If you are running Terraform in an unattended automation scenario, you can [configure credentials manually in the CLI configuration](/terraform/cli/config/config-file#credentials). diff --git a/website/docs/cli/commands/output.mdx b/website/docs/cli/commands/output.mdx index b86fca55dbc9..fe2d9d104dbf 100644 --- a/website/docs/cli/commands/output.mdx +++ b/website/docs/cli/commands/output.mdx @@ -1,14 +1,12 @@ --- -page_title: 'Command: output' +page_title: terraform output command referenece description: >- - The `terraform output` command is used to extract the value of an output - variable from the state file. + The `terraform output` command extracts the value of an output variable from the state file. --- -# Command: output +# `terraform output` command -The `terraform output` command is used to extract the value of -an output variable from the state file. +The `terraform output` command extracts the value of an output variable from the state file. ## Usage diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index 255175a853da..c4a215bd161a 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -1,15 +1,17 @@ --- -page_title: 'Command: plan' +page_title: terraform plan command reference description: >- The terraform plan command creates an execution plan with a preview of the changes that Terraform will make to your infrastructure. --- -# Command: plan +# `terraform plan` command The `terraform plan` command creates an execution plan, which lets you preview -the changes that Terraform plans to make to your infrastructure. By default, -when Terraform creates a plan it: +the changes that Terraform plans to make to your infrastructure. + +## Introduction +By default, Terraform performs the following operations when it creates a plan: * Reads the current state of any already-existing remote objects to make sure that the Terraform state is up-to-date. diff --git a/website/docs/cli/commands/providers/mirror.mdx b/website/docs/cli/commands/providers/mirror.mdx index fb48ae6797b9..0ef8bc47cbd5 100644 --- a/website/docs/cli/commands/providers/mirror.mdx +++ b/website/docs/cli/commands/providers/mirror.mdx @@ -1,12 +1,12 @@ --- -page_title: 'Command: providers mirror' +page_title: terraform providers mirror command reference description: |- The `terraform providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local filesystem. --- -# Command: terraform providers mirror +# `terraform providers mirror` command The `terraform providers mirror` command downloads the providers required for the current configuration and copies them into a directory in the local diff --git a/website/docs/cli/commands/push.mdx b/website/docs/cli/commands/push.mdx deleted file mode 100644 index 1771d330e0c4..000000000000 --- a/website/docs/cli/commands/push.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -page_title: 'Command: push' -description: >- - DISCONTINUED. HCP Terraform and the modern "remote" backend have replaced - the old `terraform push` command. ---- - -# Command: push - -!> **Important:** The `terraform push` command is no longer functional. We recommend the [HCP Terraform CLI integration](/terraform/cli/cloud) instead, which allows you to run remote operations in HCP Terraform 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. - -The legacy Terraform Enterprise version that supported `terraform push` is no longer available, and there are no remaining instances of that version in operation. Without a service to push to, the command is now completely non-functional. diff --git a/website/docs/cli/commands/refresh.mdx b/website/docs/cli/commands/refresh.mdx index d44f4f1abf39..d58b385f7b1a 100644 --- a/website/docs/cli/commands/refresh.mdx +++ b/website/docs/cli/commands/refresh.mdx @@ -1,33 +1,19 @@ --- -page_title: 'Command: refresh' +page_title: terraform refresh command reference description: |- The `terraform refresh` command reads the current settings from all managed remote objects and updates the Terraform state to match. --- -# Command: refresh - -> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. +# `terraform refresh` command The `terraform refresh` command reads the current settings from all managed -remote objects and updates the Terraform state to match. +remote objects and updates the Terraform state to match. This command is deprecated. Instead, add the `-refresh-only` flag to [`terraform apply`](/terraform/cli/commands/apply) and [`terraform plan`](/terraform/cli/commands/plan) commands. -~> _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 +This does not modify your real remote objects, but it modifies the [Terraform state](/terraform/language/state). -You shouldn't typically need to use this command, because Terraform -automatically performs the same refreshing actions as a part of creating -a plan in both the -[`terraform plan`](/terraform/cli/commands/plan) -and -[`terraform apply`](/terraform/cli/commands/apply) -commands. This command is here primarily for backward compatibility, but -we don't recommend using it because it provides no opportunity to review -the effects of the operation before updating the state. +> **Hands-on:** Try the [Use Refresh-Only Mode to Sync Terraform State](/terraform/tutorials/state/refresh) tutorial. ## Usage diff --git a/website/docs/cli/commands/state/index.mdx b/website/docs/cli/commands/state/index.mdx index 0d5a46be8c9b..0ba25c3bab1c 100644 --- a/website/docs/cli/commands/state/index.mdx +++ b/website/docs/cli/commands/state/index.mdx @@ -1,24 +1,28 @@ --- -page_title: 'Command: state' -description: The `terraform state` command is used for advanced state management. +page_title: terraform state commands reference +description: The `terraform state` group of commands enable advanced Terraform state management. --- -# State Command +# `terraform state` commands -The `terraform state` command is used for advanced state management. -As your Terraform usage becomes more advanced, there are some cases where -you may need to modify the [Terraform state](/terraform/language/state). -Rather than modify the state directly, the `terraform state` commands can -be used in many cases instead. +The `terraform state` commands enable advanced state management. -This command is a nested subcommand, meaning that it has further subcommands. -These subcommands are listed to the left. +## Introduction + +You can use the `terraform state` commands to modify the [Terraform state](/terraform/language/state) instead modifying the state directly. ## Usage Usage: `terraform state [options] [args]` -Please click a subcommand to the left for more information. +Refer to the following subcommands for additional information: + +- [`terraform state list`](/terraform/cli/commands/state/list) +- [`terraform state mv`](/terraform/cli/commands/state/mv) +- [`terraform state pull`](/terraform/cli/commands/state/pull) +- [`terraform state replace-provider`](/terraform/cli/commands/state/replace-provider) +- [`terraform state rm`](/terraform/cli/commands/state/rm) +- [`terraform state show`](/terraform/cli/commands/state/show) ## Remote State diff --git a/website/docs/cli/commands/state/list.mdx b/website/docs/cli/commands/state/list.mdx index f3879ab6b6e8..3da2091d9012 100644 --- a/website/docs/cli/commands/state/list.mdx +++ b/website/docs/cli/commands/state/list.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: state list' +page_title: terraform state list command reference description: >- - The terraform state list command is used to list resources within a Terraform + The terraform state list command lists resources within a Terraform state. --- -# Command: state list +# `terraform state list` command -The `terraform state list` command is used to list resources within a +The `terraform state list` command lists resources within a [Terraform state](/terraform/language/state). ## Usage diff --git a/website/docs/cli/commands/state/mv.mdx b/website/docs/cli/commands/state/mv.mdx index 46ac03e5448a..4c29c0157227 100644 --- a/website/docs/cli/commands/state/mv.mdx +++ b/website/docs/cli/commands/state/mv.mdx @@ -1,22 +1,18 @@ --- -page_title: 'Command: state mv' +page_title: terraform state mv command reference description: >- - The `terraform state mv` command changes bindings in Terraform state, - associating existing remote objects with new resource instances. + The `terraform state mv` command changes bindings in Terraform state so that existing remote objects bind to new resource instances. --- -# Command: state mv +# `terraform state mv` command -The main function of [Terraform state](/terraform/language/state) is -to track the bindings between resource instance addresses in your configuration -and the remote objects they represent. Normally Terraform automatically -updates the state in response to actions taken when applying a plan, such as -removing a binding for an remote object that has now been deleted. +The `terraform state mv` command changes bindings in Terraform state so that existing remote objects bind to new resource instances. -You can use `terraform state mv` in the less common situation where you wish +## Introduction + +Terraform automatically updates the state when you apply a plan, but you can use `terraform state mv` to retain an existing remote object but track it as a different resource -instance address in Terraform, such as if you have renamed a resource block -or you have moved it into a different module in your configuration. +instance address in Terraform. ## Usage diff --git a/website/docs/cli/commands/state/pull.mdx b/website/docs/cli/commands/state/pull.mdx index 115b5c6c3f2e..2d851fbc198a 100644 --- a/website/docs/cli/commands/state/pull.mdx +++ b/website/docs/cli/commands/state/pull.mdx @@ -1,15 +1,12 @@ --- -page_title: 'Command: state pull' +page_title: terraform state pull command reference description: >- - The `terraform state pull` command is used to manually download and output the - state from remote state. + The `terraform state pull` command downloads and outputs state information from a remote state or local state. --- -# Command: state pull +# `terraform state pull` command -The `terraform state pull` command is used to manually download and output -the state from [remote state](/terraform/language/state/remote). This command also -works with local state. +The `terraform state pull` downloads and outputs state information from a [remote state](/terraform/language/state/remote) or local state. ## Usage diff --git a/website/docs/cli/commands/state/push.mdx b/website/docs/cli/commands/state/push.mdx index 3b4f1fee0e95..0f42379cfbf2 100644 --- a/website/docs/cli/commands/state/push.mdx +++ b/website/docs/cli/commands/state/push.mdx @@ -1,16 +1,11 @@ --- -page_title: 'Command: state push' -description: The `terraform state push` command pushes items to the Terraform state. +page_title: terraform state push command reference +description: The `terraform state push` command uploads a state file to the Terraform state. --- -# Command: state push +# `terraform state push` command -The `terraform state push` command is used to manually upload a local -state file to [remote state](/terraform/language/state/remote). This command also -works with local state. - -This command should rarely be used. It is meant only as a utility in case -manual intervention is necessary with the remote state. +The `terraform state push` command uploads a local state file to [remote state](/terraform/language/state/remote) or a local state. We only recommend using this command when you must manually modify the remote state. ## Usage diff --git a/website/docs/cli/commands/state/replace-provider.mdx b/website/docs/cli/commands/state/replace-provider.mdx index a409e9ee2e71..690277a04958 100644 --- a/website/docs/cli/commands/state/replace-provider.mdx +++ b/website/docs/cli/commands/state/replace-provider.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: state replace-provider' +page_title: terraform state replace-provider command reference description: >- The `terraform state replace-provider` command replaces the provider for resources in the Terraform state. --- -# Command: state replace-provider +# `terraform state replace-provider` command -The `terraform state replace-provider` command is used to replace the provider +The `terraform state replace-provider` command replaces the provider for resources in a [Terraform state](/terraform/language/state). ## Usage diff --git a/website/docs/cli/commands/state/rm.mdx b/website/docs/cli/commands/state/rm.mdx index e55a42e6e66f..92cd4ad36c85 100644 --- a/website/docs/cli/commands/state/rm.mdx +++ b/website/docs/cli/commands/state/rm.mdx @@ -1,24 +1,15 @@ --- -page_title: 'Command: state rm' +page_title: terraform state rm command reference description: >- - The `terraform state rm` command removes bindings from the Terraform state, - causing Terraform to "forget about" existing objects. + The `terraform state rm` command removes bindings between resource instances defined in the Terraform configuration and corresponding remote objects. --- -# Command: state rm +# `terraform state rm` command -The main function of [Terraform state](/terraform/language/state) is -to track the bindings between resource instance addresses in your configuration -and the remote objects they represent. Normally Terraform automatically -updates the state in response to actions taken when applying a plan, such as -removing a binding for a remote object that has now been deleted. +The `terraform state rm` command removes the binding to an existing remote object without first destroying it. The remote object continues +to exist but is no longer managed by Terraform. -You can use `terraform state rm` in the less common situation where you wish -to remove a binding to an existing remote object without first destroying it, -which will effectively make Terraform "forget" the object while it continues -to exist in the remote system. - --> **Note:** Terraform v1.7.0 and later supports `removed` blocks. Unlike the `terraform state rm` command, you can use `removed` blocks to remove more than one resource at a time, and you can review removals as part of your normal plan and apply workflow. [Learn more about using `removed` blocks with resources](/terraform/language/resources/syntax#removing-resources) and [using `removed` blocks with modules](/terraform/language/modules/syntax#removing-modules). +Instead of using the `terraform state rm` command, you can use `removed` blocks to remove resources. You can remove more than one resource at a time, and you can review removals as part of your normal plan and apply workflow. [Learn more about using `removed` blocks with resources](/terraform/language/resources/syntax#removing-resources) and [using `removed` blocks with modules](/terraform/language/modules/syntax#removing-modules). ## Usage diff --git a/website/docs/cli/commands/state/show.mdx b/website/docs/cli/commands/state/show.mdx index b64636200321..30c9036d3268 100644 --- a/website/docs/cli/commands/state/show.mdx +++ b/website/docs/cli/commands/state/show.mdx @@ -1,13 +1,13 @@ --- -page_title: 'Command: state show' +page_title: terraform state show command reference description: >- - The `terraform state show` command is used to show the attributes of a single + The `terraform state show` command shows the attributes of a single resource in the Terraform state. --- -# Command: state show +# `terraform state show` command -The `terraform state show` command is used to show the attributes of a +The `terraform state show` command shows the attributes of a single resource in the [Terraform state](/terraform/language/state). diff --git a/website/docs/cli/commands/taint.mdx b/website/docs/cli/commands/taint.mdx index b3b2c296eb59..eede6b8d1818 100644 --- a/website/docs/cli/commands/taint.mdx +++ b/website/docs/cli/commands/taint.mdx @@ -1,18 +1,14 @@ --- -page_title: 'Command: taint' +page_title: terraform taint command reference description: |- - The `terraform taint` command informs Terraform that a particular object - is damaged or degraded. + The `terraform taint` command marks specified objects in the Terraform state as tainted. --- -# Command: taint +# `terraform taint` command -The `terraform taint` command informs Terraform that a particular object has -become degraded or damaged. Terraform represents this by marking the -object as "tainted" in the Terraform state, and Terraform will -propose to replace it in the next plan you create. +The `terraform taint` command marks specified objects in the Terraform state as tainted. Use the `terraform taint` command when objects become degraded or damaged. Terraform prompts you to replace the tainted objects in the next plan you create. -~> **Warning:** This command is deprecated. For Terraform v0.15.2 and later, we recommend using the `-replace` option with `terraform apply` instead (details below). +This command is deprecated. Instead, add the `-replace` option to your [`terraform apply` command](/terraform/cli/commands/apply). ## Recommended Alternative diff --git a/website/docs/cli/commands/test.mdx b/website/docs/cli/commands/test.mdx index 6c6898ba6221..4e33e16b3165 100644 --- a/website/docs/cli/commands/test.mdx +++ b/website/docs/cli/commands/test.mdx @@ -1,20 +1,22 @@ --- -page_title: 'Command: test' +page_title: terraform test command reference description: >- The `terraform test` command loads and executes Terraform testing files. --- -# Command: test +# `terraform test` command -The `terraform test` command reads in Terraform testing files and executes the tests within. +The `terraform test` command loads and exectures Terraform testing files. -The `test` command, and the test file syntax, are particularly helpful for module authors who want to validate and test their shared modules. You can also use the `test` command to validate root modules. +## Introduction + +The `terraform test` command and the test file syntax help module authors validate and test their shared modules. You can also use the `terraform test` command to validate root modules. ## Usage Usage: `terraform test [options]` -This command searches the current directory and the specified testing directory (`tests`, by default) for any Terraform testing files, and executes the specified tests. Refer to [Tests](/terraform/language/tests) for more details on test files. +This command searches the current directory and the specified testing directory for Terraform testing files and executes the specified tests. By default, the directory containing test files is named `tests`. Refer to [Tests](/terraform/language/tests) for more details on test files. Terraform then executes a series of Terraform plan or apply commands according to the test files' specifications, and also validates the relevant plan and state files according to the test files' specifications. @@ -22,7 +24,7 @@ Terraform then executes a series of Terraform plan or apply commands according t ## General Options -The following options apply to the Terraform `test` command: +The following options apply to the Terraform `terraform test` command: * `-cloud-run=` - This test run executes remotely on HCP Terraform within the specified Terraform [private registry](/terraform/language/modules/sources#terraform-registry) module. @@ -40,7 +42,7 @@ Each Terraform test file will maintain all Terraform state it requires within me ### Terraform Test Cleanup -The Terraform `test` command creates _real_ infrastructure. Once Terraform fully executes each test file, Terraform attempts to destroy any remaining infrastructure. If it cannot do this, Terraform reports a list of resources it created but could not destroy. +The Terraform `terraform test` command creates _real_ infrastructure. Once Terraform fully executes each test file, Terraform attempts to destroy any remaining infrastructure. If it cannot do this, Terraform reports a list of resources it created but could not destroy. You should monitor the output of the test command closely to ensure Terraform removes the infrastructure it created or perform manual cleanup if not. We recommend creating dedicated testing accounts within the target providers that you can routinely and safely purge to ensure any accidental and costly resources aren't left behind. diff --git a/website/docs/cli/commands/validate.mdx b/website/docs/cli/commands/validate.mdx index e9e78f685994..962875f0facd 100644 --- a/website/docs/cli/commands/validate.mdx +++ b/website/docs/cli/commands/validate.mdx @@ -1,15 +1,15 @@ --- -page_title: 'Command: validate' +page_title: terraform validate command reference description: >- - The `terraform validate` command is used to validate the syntax of the - terraform files. + The `terraform validate` command validates the syntax of Terraform configuration files in a directory. --- -# Command: validate +# `terraform validate` command The `terraform validate` command validates the configuration files in a -directory, referring only to the configuration and not accessing any remote -services such as remote state, provider APIs, etc. +directory. It does not validate remote services, such as remote state or provider APIs. + +## Introduction Validate runs checks that verify whether a configuration is syntactically valid and internally consistent, regardless of any provided variables or diff --git a/website/docs/cli/commands/version.mdx b/website/docs/cli/commands/version.mdx index 378ec3ae795a..3d776d5b60de 100644 --- a/website/docs/cli/commands/version.mdx +++ b/website/docs/cli/commands/version.mdx @@ -1,29 +1,28 @@ --- -page_title: 'Command: version' +page_title: terraform version command reference description: >- - The terraform version command displays the Terraform version and the version + The terraform version command prints the Terraform version and the version of all installed plugins. --- -# Command: version +# `terraform version` command -The `terraform version` displays the current version of Terraform and all +The `terraform version` command prints the current version of the Terraform binary and all installed plugins. ## Usage Usage: `terraform version [options]` -With no additional arguments, `version` will display the version of Terraform, -the platform it's installed on, installed providers, and the results of upgrade -and security checks [unless disabled](/terraform/cli/commands#upgrade-and-security-bulletin-checks). +With no additional arguments, `version` displays the version of Terraform, +the platform it is installed on, installed providers, and the results of upgrade +and security checks unless disabled. Refer to [Upgrade and Security Bulletin Checks](/terraform/cli/commands#upgrade-and-security-bulletin-checks) for additional information. -This command has one optional flag: +## Flags -* `-json` - If specified, the version information is formatted as a JSON object, - and no upgrade or security information is included. +This command has one optional flag: --> **Note:** Platform information was added to the `version` command in Terraform 0.15. +* `-json` - Formats version information as a JSON object. No upgrade or security information is included. ## Example diff --git a/website/docs/cli/commands/workspace/delete.mdx b/website/docs/cli/commands/workspace/delete.mdx index 3c7f54ea4f38..4b4f3f3c6c16 100644 --- a/website/docs/cli/commands/workspace/delete.mdx +++ b/website/docs/cli/commands/workspace/delete.mdx @@ -1,11 +1,11 @@ --- -page_title: 'Command: workspace delete' -description: The terraform workspace delete command is used to delete a workspace. +page_title: terraform workspace delete command reference +description: The terraform workspace delete command deletes the specified workspace. --- -# Command: workspace delete +# `terraform workspace delete` command -The `terraform workspace delete` command is used to delete an existing workspace. +The `terraform workspace delete` command deletes the specified workspace. ## Usage diff --git a/website/docs/cli/commands/workspace/index.mdx b/website/docs/cli/commands/workspace/index.mdx index d3a9798f6d60..c7d3dba49787 100644 --- a/website/docs/cli/commands/workspace/index.mdx +++ b/website/docs/cli/commands/workspace/index.mdx @@ -1,12 +1,11 @@ --- -page_title: 'Command: workspace' -description: The workspace command helps you manage workspaces. +page_title: terraform workspace command reference +description: The terraform workspace command helps you manage workspaces. --- -# Command: workspace +# `terraform workspace` command -The `terraform workspace` command is used to manage -[workspaces](/terraform/language/state/workspaces). +The `terraform workspace` command group helps you manage [workspaces](/terraform/language/state/workspaces). This command is a container for further subcommands that each have their own page in the documentation. diff --git a/website/docs/cli/commands/workspace/list.mdx b/website/docs/cli/commands/workspace/list.mdx index d7d2e6eee285..74a0b266e204 100644 --- a/website/docs/cli/commands/workspace/list.mdx +++ b/website/docs/cli/commands/workspace/list.mdx @@ -1,11 +1,11 @@ --- -page_title: 'Command: workspace list' -description: The terraform workspace list command is used to list all existing workspaces. +page_title: terraform workspace list command reference +description: The terraform workspace list command lists all existing workspaces. --- -# Command: workspace list +# `terraform workspace list` command -The `terraform workspace list` command is used to list all existing workspaces. +The `terraform workspace list` command lists all existing workspaces. ## Usage diff --git a/website/docs/cli/commands/workspace/new.mdx b/website/docs/cli/commands/workspace/new.mdx index 28b4d1c30d4e..5b07fae6de15 100644 --- a/website/docs/cli/commands/workspace/new.mdx +++ b/website/docs/cli/commands/workspace/new.mdx @@ -1,9 +1,9 @@ --- -page_title: 'Command: workspace new' -description: The terraform workspace new command is used to create a new workspace. +page_title: terraform workspace new command reference +description: The terraform workspace new command creates a new workspace with the specified name. --- -# Command: workspace new +# `terraform workspace new` command The `terraform workspace new` command is used to create a new workspace. diff --git a/website/docs/cli/commands/workspace/select.mdx b/website/docs/cli/commands/workspace/select.mdx index 497a56544623..17816e23beaf 100644 --- a/website/docs/cli/commands/workspace/select.mdx +++ b/website/docs/cli/commands/workspace/select.mdx @@ -1,12 +1,11 @@ --- -page_title: 'Command: workspace select' -description: The terraform workspace select command is used to choose a workspace. +page_title: terraform workspace select` command reference +description: The terraform workspace select command selects a workspace. --- -# Command: workspace select +# `terraform workspace select` command -The `terraform workspace select` command is used to choose a different -workspace to use for further operations. +The `terraform workspace select` selects a different workspace to use for further operations. ## Usage diff --git a/website/docs/cli/commands/workspace/show.mdx b/website/docs/cli/commands/workspace/show.mdx index c6063f22fddc..548573ebbab1 100644 --- a/website/docs/cli/commands/workspace/show.mdx +++ b/website/docs/cli/commands/workspace/show.mdx @@ -1,17 +1,17 @@ --- -page_title: 'Command: workspace show' -description: The terraform workspace show command is used to output the current workspace. +page_title: terraform workspace show command reference +description: The terraform workspace show command outputs the current workspace. --- -# Command: workspace show +# `terraform workspace show` command -The `terraform workspace show` command is used to output the current workspace. +The `terraform workspace show` command outputs the current workspace. ## Usage Usage: `terraform workspace show` -The command will display the current workspace. +The command displays the current workspace. ## Example diff --git a/website/docs/cli/import/importability.mdx b/website/docs/cli/import/importability.mdx deleted file mode 100644 index fdc3fe91c059..000000000000 --- a/website/docs/cli/import/importability.mdx +++ /dev/null @@ -1,16 +0,0 @@ ---- -page_title: 'Import: Resource Importability' -description: |- - Each resource in Terraform must implement some basic logic to become - importable. As a result, you cannot import all Terraform resources. ---- - -# Resource Importability - -Each resource in Terraform must implement some basic logic to become -importable. As a result, you cannot import all Terraform resources. - -The resources that you can import are documented at the bottom of -each resource documentation page in the [Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository. - -To make a resource importable, refer to [Extending Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import). diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx index 68eba8ed4c8e..22af5cbe6650 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.mdx @@ -1,26 +1,42 @@ --- -page_title: Import +page_title: Import existing infrastructure resources overview description: >- - Terraform can import and manage existing infrastructure. This can help you - transition your infrastructure to Terraform. + The Terraform import features let you import and manage existing infrastructure resources so that you can begin managing your infrastructure as code. --- -# Import +# Import existing resources overview + +This topic provides an overview of the Terraform commands that let you import existing infrastructure resources so that you can manage them with Terraform. > **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. -Terraform can import existing infrastructure resources. This functionality lets you bring existing resources under Terraform management. --> **Note:** Terraform v1.5.0 and later supports `import` blocks. Unlike the `terraform 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](/terraform/language/import). +## Workflows + +You can import an existing resource to state from the Terraform CLI. You can also perform import operations using HCP Terraform. To import multiple resources, use the `import` block. -## State Only +### Import to state -~> **Warning:** Terraform expects that each remote object is bound to a _single_ resource address. You should import each remote object to _one_ Terraform resource address. If you import the same object multiple times, Terraform may exhibit unwanted behavior. See [State](/terraform/language/state) for more details. +Before you run `terraform import` you must manually write a `resource` configuration block for the resource. The resource block describes where Terraform should map the imported object. The `terraform import` CLI command can only import resources into the [state](/terraform/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](/terraform/language/import). -Before you run `terraform import` you must manually write a `resource` configuration block for the resource. The resource block describes where Terraform should map the imported object. +Terraform expects each remote object to be bound to a single resource address. You should import each remote object to one Terraform resource address. Importing the same object multiple times may result in unwanted behavior. Refer to [State](/terraform/language/state) for more details. + +### HCP Terraform + +When you use Terraform on the command line with HCP Terraform, commands such as `apply` run inside your HCP Terraform environment. However, the `import` command runs locally, so it does not have access to information from HCP Terraform. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in HCP Terraform. + +### Import multiple resources + +You can specify multiple resources in the `import` block to import more than one resource at a time. You can also review imports as part of your normal plan and apply workflow. Refer to the [`import` block reference ](/terraform/language/import) in the Terraform configuration language documentation for addtitional information. + +## Resource importability + +Each resource in Terraform must implement some basic logic to become +importable. As a result, you cannot import all Terraform resources. -## HCP Terraform +The resources that you can import are documented at the bottom of +each resource documentation page in the [Terraform Registry](https://registry.terraform.io/). If you have issues importing a resource, report an issue in the relevant provider repository. -When you use Terraform on the command line with HCP Terraform, many commands like `apply` run inside your HCP Terraform environment. However, the `import` command runs locally, so it does not have access to information from HCP Terraform. To successfully perform an import, you may need to set local variables equivalent to any remote workspace variables in HCP Terraform. +To make a resource importable, refer to [Extending Terraform: Resources — Import](/terraform/plugin/sdkv2/resources/import). \ No newline at end of file diff --git a/website/docs/cli/import/usage.mdx b/website/docs/cli/import/usage.mdx index 9e2ced76ae62..ea9ddc2def1c 100644 --- a/website/docs/cli/import/usage.mdx +++ b/website/docs/cli/import/usage.mdx @@ -1,16 +1,23 @@ --- -page_title: 'Import: Usage' -description: The `terraform import` command is used to import existing infrastructure. +page_title: Import existing resources +description: Learn now to use the `terraform import` command to import existing infrastructure resources. --- -# Import Usage +# Import existing resources + +This topic describes how to use the `terraform import` command to import existing infrastructure resources so that you can manage them as code. > **Hands-on:** Try the [Import Terraform Configuration](/terraform/tutorials/state/state-import?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +## Overview + +Use the `terraform import` command to import existing infrastructure to Terraform state. The `terraform import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, such as an AWS VPC. + +Complete the following steps to import resources: -Use the `terraform import` command to import existing infrastructure to Terraform state. +1. Add the resource you want to manage with Terraform to your Terraform configuration. +1. Run the `terraform import` command. -The `terraform import` command can only import one resource at a time. It cannot simultaneously import an entire collection of resources, like an AWS VPC. ~> Warning: Terraform expects that each remote object it is managing will be bound to only one resource address, which is normally guaranteed by Terraform @@ -20,8 +27,12 @@ If you import the same object multiple times, Terraform may exhibit unwanted behavior. For more information on this assumption, see [the State section](/terraform/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 Terraform: +## Add the resource to your configuration + +Write a resource block for the resource you want to import in your configuration. +Provide a name for the resource, which is a unique ID that you can use to reference the resource elsewhere in the configuration. + +In the following example, the imported resource is an AWS instance named `example`: ```hcl resource "aws_instance" "example" { @@ -29,15 +40,11 @@ resource "aws_instance" "example" { } ``` -The name "example" here is local to the module where it is declared and is -chosen by the configuration author. This is distinct from any ID issued by -the remote system, which may change over time while the resource name -remains constant. +You do not have to complete the body of the resource block. Instead, you can finish defining arguments after the instance is imported. -If desired, you can leave the body of the resource block blank for now and -return to fill it in once the instance is imported. +## Run the `terraform import` command -Now `terraform import` can be run to attach an existing instance to this +Run `terraform import` to attach an existing instance to the resource configuration: ```shell diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx index 3fc3538f98d5..77b852ca8b39 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.mdx @@ -1,25 +1,28 @@ --- -page_title: Provisioning Infrastructure - Terraform CLI -description: 'Learn about commands for core provisioning tasks: plan, apply, and destroy.' +page_title: Terraform workflow for provisioning infrastructure overview +description: Learn about the Terraform workflow for provisioning infrastructure using core commands from the Terraform CLI. --- -# Provisioning Infrastructure with Terraform +# Terraform workflow for provisioning infrastructure overview -Terraform's primary function is to create, modify, and destroy infrastructure +This topic provides overview information about the Terraform workflow for provisioning infrastructure using the Terraform CLI. + +## Workflows + +You can use Terraform to create, modify, and destroy infrastructure resources to match the desired state described in a -[Terraform configuration](/terraform/language). +[Terraform configuration](/terraform/language). The +Terraform binary includes commands and subcommands for a wide variety of infrastructure lifecycle management +actions, but the following commands provide basic provisioning tasks: -When people refer to "running Terraform," they generally mean performing these -provisioning actions in order to affect real infrastructure objects. The -Terraform binary has many other subcommands for a wide variety of administrative -actions, but these basic provisioning tasks are the core of Terraform. +- `terrafrom plan` +- `terraform apply` +- `terraform destroy` -Terraform's provisioning workflow relies on three commands: `plan`, `apply`, and -`destroy`. All of these commands require an -[initialized](/terraform/cli/init) working directory, and all of them act +All of these commands require an [initialized](/terraform/cli/init) working directory, and all of them act only upon the currently selected [workspace](/terraform/cli/workspaces). -## Planning +### Plan The `terraform plan` command evaluates a Terraform configuration to determine the desired state of all the resources it declares, then compares that desired @@ -40,7 +43,7 @@ exact changes. For details, see [the `terraform plan` command](/terraform/cli/commands/plan). -## Applying +### Apply The `terraform apply` command performs a plan just like `terraform plan` does, but then actually carries out the planned changes to each resource using the @@ -56,7 +59,7 @@ infrastructure has changed in the minutes since the original plan was created. For details, see [the `terraform apply` command](/terraform/cli/commands/apply). -## Destroying +### Destroy The `terraform destroy` command destroys all of the resources being managed by the current working directory and workspace, using state data to determine which From c9a871c23867422dbdb1db60054a906294bd6e2e Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 9 Dec 2024 15:54:06 -0800 Subject: [PATCH 06/11] completed seo refresh for internals --- website/data/internals-nav-data.json | 2 +- .../docs/internals/credentials-helpers.mdx | 18 +++++----- website/docs/internals/debugging.mdx | 14 +++++--- website/docs/internals/functions-meta.mdx | 6 ++-- website/docs/internals/graph.mdx | 34 ++++++------------- website/docs/internals/index.mdx | 18 ++++------ website/docs/internals/json-format.mdx | 16 ++++----- website/docs/internals/login-protocol.mdx | 21 ++++++------ .../docs/internals/machine-readable-ui.mdx | 19 ++++++----- .../internals/module-registry-protocol.mdx | 14 ++++---- website/docs/internals/provider-meta.mdx | 29 +++++++--------- .../provider-network-mirror-protocol.mdx | 15 ++++---- .../internals/provider-registry-protocol.mdx | 14 +++----- .../internals/remote-service-discovery.mdx | 23 +++++++------ 14 files changed, 110 insertions(+), 133 deletions(-) diff --git a/website/data/internals-nav-data.json b/website/data/internals-nav-data.json index b6b0479945eb..f9291d89916f 100644 --- a/website/data/internals-nav-data.json +++ b/website/data/internals-nav-data.json @@ -25,7 +25,7 @@ "path": "provider-registry-protocol" }, { - "title": "Resource Graph", + "title": "Dependency Graph", "path": "graph" }, { diff --git a/website/docs/internals/credentials-helpers.mdx b/website/docs/internals/credentials-helpers.mdx index c9caa6ceb72d..a65d63921b74 100644 --- a/website/docs/internals/credentials-helpers.mdx +++ b/website/docs/internals/credentials-helpers.mdx @@ -1,11 +1,17 @@ --- -page_title: Credentials Helpers +page_title: Create Credentials Helpers description: >- - Credentials helpers are external programs that know how to store and retrieve - API tokens for remote Terraform services. + Credentials helpers are external programs that can store and retrieve + API tokens for remote Terraform services. Learn how to create credentials helpers. --- -# Credentials Helpers +# Create Credentials Helpers + +This topic describes how to write and install a credentials helper so that you can customize how Terraform obtains credentials. To learn +how to configure a credentials helper that was already installed, refer to +[Credentials Helpers](/terraform/cli/config/config-file#credentials-helpers) in the Terraform CLI documentation. + +## Introduction For Terraform-specific features that interact with remote network services, such as [module registries](/terraform/registry) and @@ -17,10 +23,6 @@ Credentials helpers offer an alternative approach that allows you to customize how Terraform obtains credentials using an external program, which can then directly access an existing secrets management system in your organization. -This page is about how to write and install a credentials helper. To learn -how to configure a credentials helper that was already installed, see -[the CLI config Credentials Helpers section](/terraform/cli/config/config-file#credentials-helpers). - ## How Terraform finds Credentials Helpers A credentials helper is a normal executable program that is installed in a diff --git a/website/docs/internals/debugging.mdx b/website/docs/internals/debugging.mdx index 7734519d9520..31e9ba4d750f 100644 --- a/website/docs/internals/debugging.mdx +++ b/website/docs/internals/debugging.mdx @@ -1,15 +1,17 @@ --- -page_title: Debugging +page_title: Enable logs to debug Terraform description: >- - Terraform has detailed logs which can be enabled by setting the TF_LOG - environment variable to any value. This will cause detailed logs to appear on - stderr + Enable Terraform to generate logs so that you can debug unexpected behaviors. --- -# Debugging Terraform +# Enable Terraform logs + +This topic describes how to enable Terraform logs so that you can debug unexpected behaviors. > **Hands-on:** Try the [Create Dynamic Expressions](/terraform/tutorials/configuration-language/troubleshooting-workflow#bug-reporting-best-practices?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +## Set the `TF_LOG` variable + Terraform has detailed logs that you can enable by setting the `TF_LOG` environment variable to any value. Enabling this setting causes detailed logs to appear on `stderr`. You can set `TF_LOG` to one of the log levels (in order of decreasing verbosity) `TRACE`, `DEBUG`, `INFO`, `WARN` or `ERROR` to change the verbosity of the logs. @@ -18,6 +20,8 @@ Setting `TF_LOG` to `JSON` outputs logs at the `TRACE` level or higher, and uses ~> **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. +## Set the `TF_LOG_CORE` variable + Logging can be enabled separately for Terraform itself and the provider plugins using the `TF_LOG_CORE` or `TF_LOG_PROVIDER` environment variables. These take the same level arguments as `TF_LOG`, but only activate a subset of the logs. diff --git a/website/docs/internals/functions-meta.mdx b/website/docs/internals/functions-meta.mdx index 734a341d25db..b227843f72a4 100644 --- a/website/docs/internals/functions-meta.mdx +++ b/website/docs/internals/functions-meta.mdx @@ -1,13 +1,13 @@ --- -page_title: Functions Metadata +page_title: terraform metadata functions command reference description: >- The `terraform metadata functions` command prints signatures for all the functions available in the current Terraform version. --- -# Functions Metadata +# `terraform metadata functions` command -The `terraform metadata functions` command is used to print signatures for the functions available in the current Terraform version. +The `terraform metadata functions` command prints signatures for the functions available in the current Terraform version. -> `terraform metadata functions` requires **Terraform v1.4 or later**. diff --git a/website/docs/internals/graph.mdx b/website/docs/internals/graph.mdx index 77b99a7f6d97..087be693da64 100644 --- a/website/docs/internals/graph.mdx +++ b/website/docs/internals/graph.mdx @@ -1,38 +1,24 @@ --- -page_title: Resource Graph +page_title: Dependency Graph description: >- - Terraform builds a dependency graph from the Terraform configurations, and - walks this graph to 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. + Learn how Terraform builds a dependency graph from the Terraform configurations and + uses the graph to generate plans, refresh state, perform other operations. --- -# Resource Graph +# Dependency Graph -Terraform builds a -[dependency graph](https://en.wikipedia.org/wiki/Dependency_graph) -from the Terraform configurations, and walks this graph to -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. +This topic explains the dependency graph Terraform builds from Terraform configurations. This is an advanced topic and not required to understand how to use Terraform. -~> **Advanced Topic!** This page covers technical details -of Terraform. You don't need to understand these details to -effectively use Terraform. The details are documented here for -those who wish to learn about them without having to go -spelunking through the source code. +## Introduction -For some background on graph theory, and a summary of how -Terraform applies it, see the HashiCorp 2016 presentation +Terraform builds a dependency graph and uses it to perform operations, such as generate plans and refresh state. +For background on graph theory and a summary of how +Terraform applies it, refer the HashiCorp 2016 presentation [_Applying Graph Theory to Infrastructure as Code_](https://www.youtube.com/watch?v=Ce3RNfRbdZ0). -This presentation also covers some similar ideas to the following -guide. ## Graph Nodes -There are only a handful of node types that can exist within the -graph. We'll cover these first before explaining how they're -determined and built: +The following node types can exist within the graph: - **Resource Node** - Represents a single resource. If you have the `count` metaparameter set, then there will be one resource diff --git a/website/docs/internals/index.mdx b/website/docs/internals/index.mdx index eebfa5bb0114..57c250fe753b 100644 --- a/website/docs/internals/index.mdx +++ b/website/docs/internals/index.mdx @@ -1,17 +1,11 @@ --- -page_title: Internals +page_title: Terraform internals overview description: >- - Learn how Terraform generates the resource dependency graph and executes other internal processes. + Learn about internal Terraform processes, such as generating the resource dependency graph. --- -# Terraform Internals +# Terraform internals overview -This section covers the internals of Terraform and explains how -plans are generated, the lifecycle of a provider, etc. The goal -of this section is to remove any notion of "magic" from Terraform. -We want you to be able to trust and understand what Terraform is -doing to function. - --> **Note:** Knowledge of Terraform internals is not -required to use Terraform. If you aren't interested in the internals -of Terraform, you may safely skip this section. +This topic provides overview information about the internals of Terraform. +Topics in this section explain how Terraform generates plans and describe the provider lifecycle. +You do not have to understand Terraform internals to use Terraform. diff --git a/website/docs/internals/json-format.mdx b/website/docs/internals/json-format.mdx index d4cedf2c12e1..584cdf049c5c 100644 --- a/website/docs/internals/json-format.mdx +++ b/website/docs/internals/json-format.mdx @@ -1,17 +1,18 @@ --- -page_title: 'Internals: JSON Output Format' +page_title: JSON output format overview description: >- - Terraform provides a machine-readable JSON representation of state, - configuration and plan. + Terraform can print details about state, configuration, and proposed infrastructure plans to the terminal in JSON format. Learn about the JSON representation. --- -# JSON Output Format +# JSON Output Format Overview --> **Note:** This format is available in Terraform 0.12 and later. +This topic provides overview information about the JSON output Terraform prints to the terminal. + +## Introduction When Terraform plans to make changes, it prints a human-readable summary to the terminal. It can also, when run with `-out=`, write a much more detailed binary plan file, which can later be used to apply those changes. -Since the format of plan files isn't suited for use with external tools (and likely never will be), Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. +Terraform can output a machine-readable JSON representation of a plan file's changes. It can also convert state files to the same format, to simplify data loading and provide better long-term compatibility. Use `terraform show -json ` to generate a JSON representation of a plan or state file. See [the `terraform show` documentation](/terraform/cli/commands/show) for more details. @@ -25,9 +26,6 @@ value `"1.0"`. The semantics of this version are: backward-compatible. Reject any input which reports an unsupported major version. -We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). - ## Format Summary The following sections describe the JSON output format by example, using a pseudo-JSON notation. diff --git a/website/docs/internals/login-protocol.mdx b/website/docs/internals/login-protocol.mdx index 1350239f54e3..c3394866deb5 100644 --- a/website/docs/internals/login-protocol.mdx +++ b/website/docs/internals/login-protocol.mdx @@ -1,16 +1,14 @@ --- -page_title: Login Protocol +page_title: Login protocol reference description: >- - The login protocol is used for authenticating Terraform against servers - providing Terraform-native services. + The login protocol authenticates Terraform against servers that provide Terraform-native services. Learn about the login protocol. --- -# Server-side Login Protocol +# Login Protocol Reference -~> **Note:** You don't need to read these docs to _use_ -[`terraform login`](/terraform/cli/commands/login). The information below is for -anyone intending to implement the server side of `terraform login` in order to -offer Terraform-native services in a third-party system. +This topic provides reference information about the login protocol Terraform uses for authentication against servers that profide Terraform-native services. You can use this reference information to offer Terraform-native services in a third-party system. + +## Introduction The `terraform login` command supports performing an OAuth 2.0 authorization request using configuration provided by the target host. You may wish to @@ -18,11 +16,12 @@ implement this protocol if you are producing a third-party implementation of any [Terraform-native services](/terraform/internals/remote-service-discovery), such as a Terraform module registry. -First, Terraform uses -[remote service discovery](/terraform/internals/remote-service-discovery) to +## OAuth Configuration + +Terraform uses [remote service discovery](/terraform/internals/remote-service-discovery) to find the OAuth configuration for the host. The host must support the service name `login.v1` and define for it an object containing OAuth client -configuration values, like this: +configuration values. The following example describes a client that authenticates at ports `10000` and `10010`: ```json { diff --git a/website/docs/internals/machine-readable-ui.mdx b/website/docs/internals/machine-readable-ui.mdx index a2979246f9e3..99af5e109183 100644 --- a/website/docs/internals/machine-readable-ui.mdx +++ b/website/docs/internals/machine-readable-ui.mdx @@ -1,17 +1,18 @@ --- -page_title: 'Internals: Machine-Readable UI' +page_title: Machine-readable output reference description: >- - Terraform provides a machine-readable streaming JSON UI output for plan, - apply, and refresh operations. + Terraform provides streamd machine-readable UI output in JSON format so that you can integrate with monitoring software. Learn about the machine-readlable output. --- -# Machine-Readable UI +# Machine-readable UI Output Reference --> **Note:** This format is available in Terraform 0.15.3 and later. +This topic provides reference information about the machine-readable output Terraform prints. -By default, many Terraform commands display UI output as unstructured text, intended to be read by a user via a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface. +## Introduction -For long-running commands such as `plan`, `apply`, `refresh`, and `test`, the `-json` flag outputs a stream of JSON UI messages, one per line. These can be processed one message at a time, with integrating software filtering, combining, or modifying the output as desired. +By default, many Terraform commands display UI output as unstructured text that is intended to be read in a terminal emulator. This text stream is not a stable interface for integrations. Some commands support a `-json` flag, which enables a structured JSON output mode with a defined interface. + +For long-running commands such as `plan`, `apply`, `refresh`, and `test`, the `-json` flag outputs a stream of JSON UI messages. The ouptut messages appear one per line so that you can process the messages by integrating software filtering, combining, or modifying the output as desired. The first message output has type `version`, and includes a `ui` key, which as of Terraform 1.1.0 has value `"1.0"`. The semantics of this version are: @@ -23,8 +24,8 @@ value `"1.0"`. The semantics of this version are: backward-compatible. Reject any input which reports an unsupported major version. -We will introduce new major versions only within the bounds of -[the Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises). +Refer to +[Terraform 1.0 Compatibility Promises](/terraform/language/v1-compatibility-promises) for additional information. ## Sample JSON Output diff --git a/website/docs/internals/module-registry-protocol.mdx b/website/docs/internals/module-registry-protocol.mdx index 8edd97b084d5..71ceff93a93d 100644 --- a/website/docs/internals/module-registry-protocol.mdx +++ b/website/docs/internals/module-registry-protocol.mdx @@ -1,16 +1,18 @@ --- -page_title: Module Registry Protocol +page_title: Module registry protocol reference description: |- - The module registry protocol is implemented by a host intending to be the - host of one or more Terraform modules, specifying which modules are available - and where to find their distribution packages. + Terraform discovers modules available for installation using the module registry protocol. Learn about the module registry protocol so consumers can find your modules. --- -# Module Registry Protocol +# Module Registry Protocol Reference + +This topic provides reference information about the module registry protocol. -> Third-party module registries are supported only in Terraform CLI 0.11 and later. Prior versions do not support this protocol. -The module registry protocol is what Terraform CLI uses to discover metadata +## Introduction + +The Terraform CLI uses the module registry protocol to discover metadata about modules available for installation and to locate the distribution package for a selected module. diff --git a/website/docs/internals/provider-meta.mdx b/website/docs/internals/provider-meta.mdx index 0e25a8f41208..50bb31dbf393 100644 --- a/website/docs/internals/provider-meta.mdx +++ b/website/docs/internals/provider-meta.mdx @@ -1,39 +1,36 @@ --- -page_title: Provider Metadata +page_title: Collect Provider Metadata description: >- - For advanced use cases, modules can provide some pre-defined metadata for - providers. + Provider developers can enable the modules created for the their providers to collect provider metadata. --- -# Provider Metadata +# Collect Provider Metadata -In some situations it's beneficial for a provider to offer an interface +This topic describes how to create an inferface in the providers you develop that allows you to collect metadata that is unrelated to the resources in the module, such as usage statistics. This is an advanced topic and is not required to use Terraform. + +## Introduction + +In some situations it is beneficial for a provider to offer an interface through which modules can pass it information unrelated to the resources in the module, but scoped on a per-module basis. -Provider Metadata allows a provider to declare metadata fields it expects, +Provider metadata allows a provider to declare metadata fields it expects, which individual modules can then populate independently of any provider configuration. While provider configurations are often shared between modules, provider metadata is always module-specific. -Provider Metadata is intended primarily for the situation where an official +Provider metadata is intended primarily for the situation where an official module is developed by the same vendor that produced the provider it is intended to work with, to allow the vendor to indirectly obtain usage 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 -of Terraform. You don't need to understand these details to -effectively use Terraform. The details are documented here for -module authors and provider developers working on advanced -functionality. -~> **Experimental Feature!** This functionality is still considered -experimental, and anyone taking advantage of it should [coordinate +~> **Experimental Feature:** This functionality is +experimental. You should [coordinate with the Terraform team](https://github.com/hashicorp/terraform/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. +so that they can understand how you are using this functionality. Doing so ensures that your use cases are taken into account as the feature evolves. ## Defining the Schema diff --git a/website/docs/internals/provider-network-mirror-protocol.mdx b/website/docs/internals/provider-network-mirror-protocol.mdx index 89ea2652620b..7178de4725e9 100644 --- a/website/docs/internals/provider-network-mirror-protocol.mdx +++ b/website/docs/internals/provider-network-mirror-protocol.mdx @@ -1,19 +1,16 @@ --- -page_title: Provider Network Mirror Protocol +page_title: Provider network mirror protocol reference description: |- - The provider network mirror protocol is implemented by a server intending - to provide a mirror or read-through caching proxy for Terraform providers, - as an alternative distribution source from the provider's origin provider - registry. + The provider network mirror protocol lets you provide an alternate installation source for your providers. Learn about the provider network mirror protocol. --- -# Provider Network Mirror Protocol +# Provider Network Mirror Protocol Reference + +This topic provides reference information about the provider network mirror protocol. You can implement an alternative installation source for Terraform providers and make the source available over the provider network mirror protocol, regardless of their origin registries. -> Provider network mirrors are supported only in Terraform CLI v0.13.2 and later. Prior versions do not support this protocol. -The provider network mirror protocol is an optional protocol which you can -implement to provide an alternative installation source for Terraform providers, -regardless of their origin registries. +## Introduction Terraform uses network mirrors only if you activate them explicitly in [the CLI configuration's `provider_installation` block](/terraform/cli/config/config-file#provider-installation). diff --git a/website/docs/internals/provider-registry-protocol.mdx b/website/docs/internals/provider-registry-protocol.mdx index e344d88e7fe7..c832e482540e 100644 --- a/website/docs/internals/provider-registry-protocol.mdx +++ b/website/docs/internals/provider-registry-protocol.mdx @@ -1,18 +1,14 @@ --- -page_title: Provider Registry Protocol +page_title: Provider registry protocol reference description: |- - The provider registry protocol is implemented by a host intending to be the - origin host for one or more Terraform providers, specifying which providers - are available and where to find their distribution packages. + Use the provider registry protocol to enable Terraform to discover metadata about providers available for installation and to locate their distribution packages. --- -# Provider Registry Protocol +# Provider Registry Protocol Reference --> Third-party provider registries are supported only in Terraform CLI 0.13 and later. Prior versions do not support this protocol. +This topic provides reference information about the provider registry protocol. The protocol allows the Terraform CLI to discover metadata about the providers available for installation and to locate the distribution packages for a selected provider. -The provider registry protocol is what Terraform CLI uses to discover metadata -about providers available for installation and to locate the distribution -packages for a selected provider. +## Introduction The primary implementation of this protocol is the public [Terraform Registry](https://registry.terraform.io/) at `registry.terraform.io`. diff --git a/website/docs/internals/remote-service-discovery.mdx b/website/docs/internals/remote-service-discovery.mdx index 04c2a9847817..5aeb17888c3c 100644 --- a/website/docs/internals/remote-service-discovery.mdx +++ b/website/docs/internals/remote-service-discovery.mdx @@ -1,22 +1,23 @@ --- -page_title: 'Internals: Remote Service Discovery' +page_title: Remote service discovery protocol reference description: |- - Remote service discovery is a protocol used to locate Terraform-native - services provided at a user-friendly hostname. + The remote service discovery protocol presents Terraform-native services at a human-readable hostname. Learn about the remote service discovery protocol. --- -# Remote Service Discovery +# Remote Service Discovery Protocol Reference -Terraform implements much of its functionality in terms of remote services. -While in many cases these are generic third-party services that are useful -to many applications, some of these services are tailored specifically to -Terraform's needs. We call these _Terraform-native services_, and Terraform -interacts with them via the remote service discovery protocol described below. +This topic provides reference information about the remote service discovery protocol in Terraform. + +## Introduction + +Terraform implements much of its functionality as remote services. +Some of these are native services that Terraform +interacts with through the remote service discovery protocol. ## User-facing Hostname -Terraform-native services are provided, from a user's perspective, at a -user-facing "friendly hostname" which serves as the key for configuration and +Terraform provides native services at a +human-readable hostname. The hostname is the key for configuration and for any authentication credentials required. The discovery protocol's purpose is to map from a user-provided hostname to From b593f18579818889121fa3f6ea93045e566c6676 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Tue, 10 Dec 2024 11:35:09 -0800 Subject: [PATCH 07/11] Update website/docs/cli/cloud/command-line-arguments.mdx Co-authored-by: Judith Malnick --- website/docs/cli/cloud/command-line-arguments.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx index 57518f2433e9..8483a8adf262 100644 --- a/website/docs/cli/cloud/command-line-arguments.mdx +++ b/website/docs/cli/cloud/command-line-arguments.mdx @@ -1,6 +1,6 @@ --- page_title: -ignore-remote-version reference -description: Use the -ignore-remote-version flat to override CLI-driven commands for HCP Terraform runs. +description: Use the -ignore-remote-version flag to override CLI-driven commands for HCP Terraform runs. --- # `-ignore-remote-version` reference From 3b15748662d2b9d90b0a05751ab2e70f1dcf5826 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Fri, 13 Dec 2024 13:48:44 -0800 Subject: [PATCH 08/11] Apply suggestions from code review Co-authored-by: rita <8647768+ritsok@users.noreply.github.com> --- website/docs/cli/auth/index.mdx | 8 ++++---- website/docs/cli/cloud/index.mdx | 4 ++-- website/docs/cli/code/index.mdx | 6 +++--- website/docs/cli/commands/index.mdx | 2 +- website/docs/cli/config/index.mdx | 1 - website/docs/cli/import/index.mdx | 4 ++-- website/docs/cli/inspect/index.mdx | 2 +- website/docs/cli/plugins/index.mdx | 2 +- website/docs/cli/run/index.mdx | 4 ++-- website/docs/cli/state/inspect.mdx | 2 +- website/docs/cli/state/move.mdx | 2 +- website/docs/cli/state/recover.mdx | 2 +- website/docs/cli/state/taint.mdx | 2 +- website/docs/cli/test/index.mdx | 2 +- website/docs/cli/workspaces/index.mdx | 2 +- website/docs/internals/index.mdx | 2 +- website/docs/internals/json-format.mdx | 4 ++-- website/docs/internals/machine-readable-ui.mdx | 2 +- website/docs/internals/provider-registry-protocol.mdx | 2 +- website/docs/intro/vs/boto.mdx | 2 +- 20 files changed, 28 insertions(+), 29 deletions(-) diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index 2b1f70a3e5ac..b32e3dac1f88 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Get an API token for HCP Terraform and Terraform Enterprise +page_title: Get an API token for HCP Terraform or Terraform Enterprise description: >- Use the terraform login and terraform logout commands get an API token for your HCP Terraform or Terraform Enterprise account. @@ -18,7 +18,7 @@ This topic describes how to use the `terraform login` and `terraform logout` to Terraform runs to provision infrastructure, offering a collaboration-focused environment that makes it easier for teams to use Terraform together. -You can integrate the Terraform CLI with Terraform web platform in the following ways: +You can integrate the Terraform CLI with HCP Terraform and Terraform Enterprise in the following ways: - Use the Terraform CLI as a front-end for [CLI-driven runs](/terraform/cloud-docs/run/cli) in HCP Terraform - Use HCP Terraform or Terraform Enterprise as a state backend and a private module registry. @@ -28,6 +28,6 @@ with your HCP Terraform account. ## Authentication -Run the `terraform login` command to automate the process of getting an API token for your HCP Terraform user account. Refer to the [`terraform login` command](/terraform/cli/commands/login) reference documentation for details. +Run the `terraform login` command to generate an API token for your HCP Terraform user account. Refer to the [`terraform login` command](/terraform/cli/commands/login) reference documentation for details. -Run the `terrafom logout` coommand to end your HCP Terraform or Terraform Enterprise session. Refer to the [`terraform logout` command](/terraform/cli/commands/logout) reference documentation for details. +Run the `terraform logout` command to end your HCP Terraform or Terraform Enterprise session. Refer to the [`terraform logout` command](/terraform/cli/commands/logout) reference documentation for details. diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx index e97651d4f452..a8c93cb532c7 100644 --- a/website/docs/cli/cloud/index.mdx +++ b/website/docs/cli/cloud/index.mdx @@ -1,10 +1,10 @@ --- -page_title: Use HCP Terraform and Terraform Enterprise with Terraform CLI overview +page_title: Use HCP Terraform or Terraform Enterprise with the Terraform CLI description: >- Learn how to use HCP Terraform and Terraform Enterprise on the command line with the Terraform CLI. --- -# Use HCP Terraform with Terraform CLI Overview +# Use HCP Terraform with the Terraform CLI The Terraform CLI integration with HCP Terraform lets you use HCP Terraform and Terraform Enterprise on the command line. In the documentation HCP Terraform instructions also apply to Terraform Enterprise, except where explicitly stated. diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 032e975a6d1e..8d6e086138ff 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -1,13 +1,13 @@ --- -page_title: Format and validate Terraform configuration from the CLI +page_title: Format and validate Terraform configuration using the Terraform CLI description: >- - Learn about the Terraform commands that help validate, format, and upgrade code written in the + Learn about the Terraform commands that validate, format, and upgrade code written in HCL. Terraform configuration language. --- # Write and modify Terrafrom configuration from the CLI -This topic provides an overview of the Terraform CLI commands you can use to programmatically write and modify Terraform configuration code. +This topic provides an overview of the Terraform CLI commands you can use to develop, format, and validate your Terraform configuration. ## Introduction diff --git a/website/docs/cli/commands/index.mdx b/website/docs/cli/commands/index.mdx index d26b5dc293f6..3f0c33948ecc 100644 --- a/website/docs/cli/commands/index.mdx +++ b/website/docs/cli/commands/index.mdx @@ -5,7 +5,7 @@ description: The Terrafrom CLI includes commands for provisioning infrastructure # Terraform CLI Overview -This topic provides an overview of the Terraform command line. +This topic provides an overview of the Terraform command line interface. > **Hands-on:** Try the [Terraform: Get Started](/terraform/tutorials/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorials. diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.mdx index fbe40f3a51d3..117d55825eb4 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.mdx @@ -2,7 +2,6 @@ page_title: Terraform CLI configuration overview description: >- The CLI config-file and supported Terraform environment variables let you customize Terraform CLI behavior. - Learn how Terraform CLI configuration works. --- # Terraform CLI configuration overview diff --git a/website/docs/cli/import/index.mdx b/website/docs/cli/import/index.mdx index 22af5cbe6650..6d1e7b13a316 100644 --- a/website/docs/cli/import/index.mdx +++ b/website/docs/cli/import/index.mdx @@ -1,7 +1,7 @@ --- -page_title: Import existing infrastructure resources overview +page_title: Import existing infrastructure resources description: >- - The Terraform import features let you import and manage existing infrastructure resources so that you can begin managing your infrastructure as code. + Terraform lets you import existing infrastructure into state so that you can begin managing your infrastructure as code. --- # Import existing resources overview diff --git a/website/docs/cli/inspect/index.mdx b/website/docs/cli/inspect/index.mdx index 6397de7fbf49..cd323c1724b1 100644 --- a/website/docs/cli/inspect/index.mdx +++ b/website/docs/cli/inspect/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Inspect infrastructure commands overview +page_title: Inspect infrastructure description: >- The terraform inspect commands return dependency information and outputs. Learn how to use terraform inspect commands to understand your infrastructure. diff --git a/website/docs/cli/plugins/index.mdx b/website/docs/cli/plugins/index.mdx index 8ff267cb017d..82f8bb3203ce 100644 --- a/website/docs/cli/plugins/index.mdx +++ b/website/docs/cli/plugins/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Manage Terraform plugins overview +page_title: Manage Terraform plugins description: >- Providers are types of plugins for Terraform that manage infrastructure resources. Learn about managing plugins using the Terraform CLI. --- diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx index 77b852ca8b39..e91930758168 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.mdx @@ -1,6 +1,6 @@ --- -page_title: Terraform workflow for provisioning infrastructure overview -description: Learn about the Terraform workflow for provisioning infrastructure using core commands from the Terraform CLI. +page_title: Terraform workflow for provisioning infrastructure +description: Learn how to use the Terraform CLI to provision infrastructure. --- # Terraform workflow for provisioning infrastructure overview diff --git a/website/docs/cli/state/inspect.mdx b/website/docs/cli/state/inspect.mdx index dd9accd2d451..74f200ca5089 100644 --- a/website/docs/cli/state/inspect.mdx +++ b/website/docs/cli/state/inspect.mdx @@ -1,5 +1,5 @@ --- -page_title: Inspect Terraform state overview +page_title: Inspect Terraform state description: The `terraform state` group of commands help you inspect Terraform state. Learn how inspecting Terraform state can help you read and update state. --- diff --git a/website/docs/cli/state/move.mdx b/website/docs/cli/state/move.mdx index 5256be914bd9..252184d103e8 100644 --- a/website/docs/cli/state/move.mdx +++ b/website/docs/cli/state/move.mdx @@ -1,5 +1,5 @@ --- -page_title: Move resources overview +page_title: Move resources description: >- Terraform state commands can move and remove resources and transfer existing resources to a different provider. Learn how about changing or moving resources. --- diff --git a/website/docs/cli/state/recover.mdx b/website/docs/cli/state/recover.mdx index 68155abe8f57..8189731d8892 100644 --- a/website/docs/cli/state/recover.mdx +++ b/website/docs/cli/state/recover.mdx @@ -1,5 +1,5 @@ --- -page_title: Recover state from backup overview +page_title: Recover state from backup description: >- Learn how to restore state backups and override Terraform state protections to fix state errors with the Terraform CLI. --- diff --git a/website/docs/cli/state/taint.mdx b/website/docs/cli/state/taint.mdx index 42673141f934..cb3e06d7dce3 100644 --- a/website/docs/cli/state/taint.mdx +++ b/website/docs/cli/state/taint.mdx @@ -1,5 +1,5 @@ --- -page_title: Recreate resources overview +page_title: Recreate resources description: The -replace flag and taint command help you replace infrastructure objects. Learn how the -replace flag and taint command can help you recreate resources. --- diff --git a/website/docs/cli/test/index.mdx b/website/docs/cli/test/index.mdx index 7eeebd6c32f2..08177edce984 100644 --- a/website/docs/cli/test/index.mdx +++ b/website/docs/cli/test/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Testing features in Terraform overview +page_title: Testing features in Terraform description: >- Learn about the terraform test command, which runs structured tests and validations for your configuration to ensure correctness in your infrastructure. diff --git a/website/docs/cli/workspaces/index.mdx b/website/docs/cli/workspaces/index.mdx index b776fcb45ca8..3baca17bd462 100644 --- a/website/docs/cli/workspaces/index.mdx +++ b/website/docs/cli/workspaces/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Manage workspaces overview +page_title: Manage workspaces description: >- Workspaces are separate instances of Terraform state data. Learn commands for managing workspaces. --- diff --git a/website/docs/internals/index.mdx b/website/docs/internals/index.mdx index 57c250fe753b..f025c4b7d09f 100644 --- a/website/docs/internals/index.mdx +++ b/website/docs/internals/index.mdx @@ -1,5 +1,5 @@ --- -page_title: Terraform internals overview +page_title: Terraform internals description: >- Learn about internal Terraform processes, such as generating the resource dependency graph. --- diff --git a/website/docs/internals/json-format.mdx b/website/docs/internals/json-format.mdx index 584cdf049c5c..815f89afab10 100644 --- a/website/docs/internals/json-format.mdx +++ b/website/docs/internals/json-format.mdx @@ -1,7 +1,7 @@ --- -page_title: JSON output format overview +page_title: JSON output format description: >- - Terraform can print details about state, configuration, and proposed infrastructure plans to the terminal in JSON format. Learn about the JSON representation. + Learn how to configure Terraform to print JSON-formatted details about state, configuration, and proposed infrastructure plans. --- # JSON Output Format Overview diff --git a/website/docs/internals/machine-readable-ui.mdx b/website/docs/internals/machine-readable-ui.mdx index 99af5e109183..05f4c20fb2da 100644 --- a/website/docs/internals/machine-readable-ui.mdx +++ b/website/docs/internals/machine-readable-ui.mdx @@ -1,7 +1,7 @@ --- page_title: Machine-readable output reference description: >- - Terraform provides streamd machine-readable UI output in JSON format so that you can integrate with monitoring software. Learn about the machine-readlable output. + Terraform streams machine-readable output in JSON format, letting you use third-party tools to monitor operations. --- # Machine-readable UI Output Reference diff --git a/website/docs/internals/provider-registry-protocol.mdx b/website/docs/internals/provider-registry-protocol.mdx index c832e482540e..a8acc4e948a4 100644 --- a/website/docs/internals/provider-registry-protocol.mdx +++ b/website/docs/internals/provider-registry-protocol.mdx @@ -1,7 +1,7 @@ --- page_title: Provider registry protocol reference description: |- - Use the provider registry protocol to enable Terraform to discover metadata about providers available for installation and to locate their distribution packages. + Use the provider registry protocol to enable Terraform to discover metadata about available providers and locate their distribution packages. --- # Provider Registry Protocol Reference diff --git a/website/docs/intro/vs/boto.mdx b/website/docs/intro/vs/boto.mdx index 588de6f3b02c..698e10a28dc4 100644 --- a/website/docs/intro/vs/boto.mdx +++ b/website/docs/intro/vs/boto.mdx @@ -1,6 +1,6 @@ --- page_title: Terraform versus Boto, Fog, and other cloud provider client libraries -description: Learn how Terraform's high level syntax compares to Boto, Flog, and other cloud provider client libraries. +description: Learn how Terraform's syntax compares to Boto, Flog, and other cloud provider client libraries. --- # Terraform versus Boto, Fog, and other cloud provider client libraries From 8dc4aead294d98abbf9a9a546bd8ecc02a8640ba Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Fri, 13 Dec 2024 14:07:19 -0800 Subject: [PATCH 09/11] re-added upgrade commands --- website/data/cli-nav-data.json | 16 +++ website/docs/cli/commands/0.12upgrade.mdx | 117 ++++++++++++++++++++++ website/docs/cli/commands/0.13upgrade.mdx | 89 ++++++++++++++++ website/docs/cli/commands/apply.mdx | 3 +- 4 files changed, 223 insertions(+), 2 deletions(-) create mode 100644 website/docs/cli/commands/0.12upgrade.mdx create mode 100644 website/docs/cli/commands/0.13upgrade.mdx diff --git a/website/data/cli-nav-data.json b/website/data/cli-nav-data.json index 6bc6030ed713..2bae97955caf 100644 --- a/website/data/cli-nav-data.json +++ b/website/data/cli-nav-data.json @@ -331,6 +331,14 @@ { "title": "workspace show", "href": "/cli/commands/workspace/show" + }, + { + "title": "0.12upgrade", + "href": "/cli/commands/0.12upgrade" + }, + { + "title": "0.13upgrade", + "href": "/cli/commands/0.13upgrade" } ] }, @@ -398,6 +406,14 @@ { "title": "workspace delete", "path": "commands/workspace/delete" }, { "title": "workspace show", "path": "commands/workspace/show" } ] + }, + { + "title": "0.12upgrade", + "path": "commands/0.12upgrade" + }, + { + "title": "0.13upgrade", + "path": "commands/0.13upgrade" } ] }, diff --git a/website/docs/cli/commands/0.12upgrade.mdx b/website/docs/cli/commands/0.12upgrade.mdx new file mode 100644 index 000000000000..ef4cebb75ef7 --- /dev/null +++ b/website/docs/cli/commands/0.12upgrade.mdx @@ -0,0 +1,117 @@ +--- +page_title: terraform 0.12upgrade command reference +description: >- + The `terraform 0.12upgrade` command automatically rewrites existing configurations for + Terraform 0.12 compatibility. +--- + +# `terraform 0.12upgrade` command + +The `terraform 0.12upgrade` command applies several automatic upgrade rules to +help prepare a module that was written for Terraform v0.11 to be used +with Terraform v0.12. + +-> **This command is available only in Terraform v0.12 releases.** For more information, see [the Terraform v0.12 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-12). + +## Usage + +Usage: `terraform 0.12upgrade [options] [dir]` + +By default, `0.12upgrade` changes configuration files in the current working +directory. However, you can provide an explicit path to another directory if +desired, which may be useful for automating migrations of several modules in +the same repository. + +When run with no other options, the command will first explain what it is +going to do and prompt for confirmation: + +``` +$ terraform 0.12upgrade + +This command will rewrite the configuration files in the given directory so +that they use the new syntax features from Terraform v0.12, and will identify +any constructs that may need to be adjusted for correct operation with +Terraform v0.12. + +We recommend using this command in a clean version control work tree, so that +you can easily see the proposed changes as a diff against the latest commit. +If you have uncommitted changes already present, we recommend aborting this +command and dealing with them before running this command again. + +Would you like to upgrade the module in the current directory? + Only 'yes' will be accepted to confirm. + + Enter a value: yes +``` + +The `0.12upgrade` subcommand requires access to providers used in the +configuration in order to analyze their resource types, so it's important to +run `terraform init` first to install these. In some rare cases, a configuration +that worked in v0.11 may have syntax errors in v0.12, in which case +`terraform init` will run in a special mode where it installs only enough to +run the upgrade command, after which you can run `terraform init` again to +complete initialization. + +Many of the rewrite rules are completely automatic, but in some cases the +tool cannot determine enough information from the configuration alone to make +a decision, and so it will instead add a comment to the configuration for +user review. All such comments contain the string `TF-UPGRADE-TODO` to make +them easier to find. + +After upgrading, the configuration will also be reformatted into the standard +Terraform style and expressions rewritten to use the more-readable v0.12 syntax +features. + +We recommend running this command with a clean version control work tree so +that you can use VCS tools to review the proposed changes, including any +`TF-UPGRADE-TODO` comments, and make any revisions required before committing +the change. + +Once upgraded the configuration will no longer be compatible with Terraform +v0.11 and earlier. When upgrading a shared module that is called from multiple +configurations, you may need to +[fix existing configurations to a previous version](/terraform/language/modules/syntax#version) +to allow for a gradual upgrade. If the module is published via +[a Terraform registry](/terraform/registry), assign a new _major_ version number +to the upgraded module source to represent the fact that this is a breaking +change for v0.11 callers. If a module is installed directly from a version +control system such as Git, +[use specific revisions](/terraform/language/modules/sources#selecting-a-revision) +to control which version is used by which caller. + +The command-line options are all optional. The available options are: + +* `-yes` - Skip the initial introduction messages and interactive confirmation. + Use this when running the command in batch from a script. + +* `-force` - Override the heuristic that attempts to detect if a configuration + is already written for v0.12 or later. Some of the transformations made by + this command are not idempotent, so re-running against the same module may + change the meanings of some expressions in the module. + +## Batch Usage + +After you've experimented with the `0.12upgrade` command in some confined +situations, if you have a repository containing multiple modules you may +wish to batch-upgrade them all and review them together. Recursive upgrades +are not supported by the tool itself, but if you are on a Unix-style system +you can achieve this using the `find` command as follows: + +``` +find . -name '*.tf' -printf "%h\n" | uniq | xargs -n1 terraform 0.12upgrade -yes +``` + +On Mac OS X, the `find` included with the system does not support the `-printf` argument. You can install GNU find using Homebrew in order to use that argument: + +``` +brew install findutils +``` + +Once installed, run the above command line using `gfind` instead of `find`. + +Note that the above includes the `-yes` option to override the interactive +prompt, so be sure you have a clean work tree before running it. + +Because upgrading requires access to the configuration's provider plugins, +all of the directories must be initialized with `terraform init` prior to +running the above. \ No newline at end of file diff --git a/website/docs/cli/commands/0.13upgrade.mdx b/website/docs/cli/commands/0.13upgrade.mdx new file mode 100644 index 000000000000..0cc459b42bef --- /dev/null +++ b/website/docs/cli/commands/0.13upgrade.mdx @@ -0,0 +1,89 @@ +--- +page_title: terraform 0.13upgrade command reference +description: >- + The `terraform 0.13upgrade` command updates existing configurations to use the new + provider source features from Terraform 0.13. +--- + +# `terraform 0.13upgrade` command + +The `terraform 0.13upgrade` command updates existing configuration to add an +explicit `source` attribute for each provider used in a given module. The +provider source settings are stored in a `required_providers` block. + +-> **This command is available only in Terraform v0.13 releases.** For more information, see [the Terraform v0.13 upgrade guide](/terraform/language/v1.1.x/upgrade-guides/0-13). + +## Usage + +Usage: `terraform 0.13upgrade [options] [dir]` + +The primary purpose of the `0.13upgrade` command is to determine which +providers are in use for a module, detect the source address for those +providers where possible, and record this information in a +[`required_providers` block][required-providers]. + +[required-providers]: /terraform/language/providers/requirements + +~> Note: the command ignores `.tf.json` files and override files in the module. + +If the module already has a `required_providers` block, the command updates it +in-place. Otherwise, a new block is added to the `versions.tf` file. + +By default, `0.13upgrade` changes configuration files in the current working +directory. However, you can provide an explicit path to another directory if +desired, which may be useful for automating migrations of several modules in +the same repository. + +When run with no other options, the command will first explain what it is +going to do and prompt for confirmation: + +``` +$ terraform 0.13upgrade + +This command will update the configuration files in the given directory to use +the new provider source features from Terraform v0.13. It will also highlight +any providers for which the source cannot be detected, and advise how to +proceed. + +We recommend using this command in a clean version control work tree, so that +you can easily see the proposed changes as a diff against the latest commit. +If you have uncommited changes already present, we recommend aborting this +command and dealing with them before running this command again. + +Would you like to upgrade the module in the current directory? + Only 'yes' will be accepted to confirm. + + Enter a value: yes +``` + +We recommend running this command with a clean version control work tree so +that you can use VCS tools to review the proposed changes, including any +`TF-UPGRADE-TODO` comments, and make any revisions required before committing +the change. + +There is one command-line option: + +* `-yes` - Skip the initial introduction messages and interactive confirmation. + Use this when running the command in batch from a script. + +## Batch Usage + +After you've experimented with the `0.13upgrade` command in some confined +situations, if you have a repository containing multiple modules you may +wish to batch-upgrade them all and review them together. Recursive upgrades +are not supported by the tool itself, but if you are on a Unix-style system +you can achieve this using the `find` command as follows: + +``` +$ find . -name '*.tf' | xargs -n1 dirname | uniq | xargs -n1 terraform 0.13upgrade -yes +``` + +On a Windows system with PowerShell, you can use this command: + +``` +Get-Childitem -Recurse -Include *.tf | Split-Path | ` +Select-Object -Unique | ForEach-Object { terraform 0.13upgrade -yes $_.FullName } +``` + +Note that the above commands include the `-yes` option to override the +interactive prompt, so be sure you have a clean work tree before running it. \ No newline at end of file diff --git a/website/docs/cli/commands/apply.mdx b/website/docs/cli/commands/apply.mdx index 026b8e882af7..2eb5a9a8c64a 100644 --- a/website/docs/cli/commands/apply.mdx +++ b/website/docs/cli/commands/apply.mdx @@ -1,7 +1,6 @@ --- page_title: terraform apply command reference -description: >- - The terraform apply command executes the actions proposed in a Terraform plan +description: The `terraform apply` command executes the actions proposed in a Terraform plan to create, update, or destroy infrastructure. --- From 19936b67dac97b8850b2b08b352ff6d143b3ba98 Mon Sep 17 00:00:00 2001 From: trujillo-adam <47586768+trujillo-adam@users.noreply.github.com> Date: Mon, 16 Dec 2024 08:32:13 -0800 Subject: [PATCH 10/11] Apply suggestions from code review Co-authored-by: rita <8647768+ritsok@users.noreply.github.com> --- website/docs/cli/auth/index.mdx | 2 +- website/docs/cli/code/index.mdx | 1 - website/docs/cli/config/index.mdx | 2 +- website/docs/cli/run/index.mdx | 2 +- 4 files changed, 3 insertions(+), 4 deletions(-) diff --git a/website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.mdx index b32e3dac1f88..dc783d43a7ee 100644 --- a/website/docs/cli/auth/index.mdx +++ b/website/docs/cli/auth/index.mdx @@ -1,7 +1,7 @@ --- page_title: Get an API token for HCP Terraform or Terraform Enterprise description: >- - Use the terraform login and terraform logout commands get + Use the `terraform login` and `terraform logout` commands get an API token for your HCP Terraform or Terraform Enterprise account. --- diff --git a/website/docs/cli/code/index.mdx b/website/docs/cli/code/index.mdx index 8d6e086138ff..bc681b34e535 100644 --- a/website/docs/cli/code/index.mdx +++ b/website/docs/cli/code/index.mdx @@ -2,7 +2,6 @@ page_title: Format and validate Terraform configuration using the Terraform CLI description: >- Learn about the Terraform commands that validate, format, and upgrade code written in HCL. - Terraform configuration language. --- # Write and modify Terrafrom configuration from the CLI diff --git a/website/docs/cli/config/index.mdx b/website/docs/cli/config/index.mdx index 117d55825eb4..e329f751bdda 100644 --- a/website/docs/cli/config/index.mdx +++ b/website/docs/cli/config/index.mdx @@ -1,7 +1,7 @@ --- page_title: Terraform CLI configuration overview description: >- - The CLI config-file and supported Terraform environment variables let you customize Terraform CLI behavior. + The CLI configuration file and supported Terraform environment variables let you customize Terraform CLI behavior. --- # Terraform CLI configuration overview diff --git a/website/docs/cli/run/index.mdx b/website/docs/cli/run/index.mdx index e91930758168..bc57c38cd613 100644 --- a/website/docs/cli/run/index.mdx +++ b/website/docs/cli/run/index.mdx @@ -3,7 +3,7 @@ page_title: Terraform workflow for provisioning infrastructure description: Learn how to use the Terraform CLI to provision infrastructure. --- -# Terraform workflow for provisioning infrastructure overview +# Terraform workflow for provisioning infrastructure This topic provides overview information about the Terraform workflow for provisioning infrastructure using the Terraform CLI. From 922aff286902d500beddcae5e0728cd557f66972 Mon Sep 17 00:00:00 2001 From: trujillo-adam Date: Mon, 16 Dec 2024 10:41:17 -0800 Subject: [PATCH 11/11] placed commands in backticks in descs --- website/docs/cli/commands/console.mdx | 2 +- website/docs/cli/commands/destroy.mdx | 2 +- website/docs/cli/commands/fmt.mdx | 2 +- website/docs/cli/commands/force-unlock.mdx | 2 +- website/docs/cli/commands/get.mdx | 2 +- website/docs/cli/commands/graph.mdx | 2 +- website/docs/cli/commands/import.mdx | 2 +- website/docs/cli/commands/init.mdx | 2 +- website/docs/cli/commands/login.mdx | 2 +- website/docs/cli/commands/logout.mdx | 2 +- website/docs/cli/commands/modules.mdx | 4 ++-- website/docs/cli/commands/plan.mdx | 2 +- website/docs/cli/commands/providers.mdx | 2 +- 13 files changed, 14 insertions(+), 14 deletions(-) diff --git a/website/docs/cli/commands/console.mdx b/website/docs/cli/commands/console.mdx index cc2df57dbaec..f740b2e6d555 100644 --- a/website/docs/cli/commands/console.mdx +++ b/website/docs/cli/commands/console.mdx @@ -1,7 +1,7 @@ --- page_title: terraform console command reference description: >- - The terraform console command opens an interactive console for evaluating + The `terraform console` command opens an interactive console for evaluating expressions. --- diff --git a/website/docs/cli/commands/destroy.mdx b/website/docs/cli/commands/destroy.mdx index a1cd4746118d..376942ce39e7 100644 --- a/website/docs/cli/commands/destroy.mdx +++ b/website/docs/cli/commands/destroy.mdx @@ -1,7 +1,7 @@ --- page_title: terraform destroy command reference description: >- - The terraform destroy command deprovisions all objects managed by a Terraform + The `terraform destroy` command deprovisions all objects managed by a Terraform configuration. --- diff --git a/website/docs/cli/commands/fmt.mdx b/website/docs/cli/commands/fmt.mdx index 85bf224b983d..26706c60898f 100644 --- a/website/docs/cli/commands/fmt.mdx +++ b/website/docs/cli/commands/fmt.mdx @@ -1,7 +1,7 @@ --- page_title: terraform fmt command reference description: >- - The terraform fmt command formats Terraform configuration contents so that it matches the canonical format + The `terraform fmt` command formats Terraform configuration contents so that it matches the canonical format and style. --- diff --git a/website/docs/cli/commands/force-unlock.mdx b/website/docs/cli/commands/force-unlock.mdx index 4c169d6becdf..b26eb3e1b80d 100644 --- a/website/docs/cli/commands/force-unlock.mdx +++ b/website/docs/cli/commands/force-unlock.mdx @@ -1,7 +1,7 @@ --- page_title: terraform force-unlock command reference description: >- - The terraform force-unlock command unlocks the state for a configuration. It + The `terraform force-unlock` command unlocks the state for a configuration. It does not modify your infrastructure. --- diff --git a/website/docs/cli/commands/get.mdx b/website/docs/cli/commands/get.mdx index e43946cddf3c..9b0254331c72 100644 --- a/website/docs/cli/commands/get.mdx +++ b/website/docs/cli/commands/get.mdx @@ -1,6 +1,6 @@ --- page_title: terraform get command reference -description: The terraform get command downloads and updates modules. +description: The `terraform get` command downloads and updates modules. --- # `terraform get` command diff --git a/website/docs/cli/commands/graph.mdx b/website/docs/cli/commands/graph.mdx index cd0a3906dbcc..12a471977f0f 100644 --- a/website/docs/cli/commands/graph.mdx +++ b/website/docs/cli/commands/graph.mdx @@ -1,7 +1,7 @@ --- page_title: terraform graph command reference description: >- - The terraform graph command generates a visual representation of a + The `terraform graph` command generates a visual representation of a configuration or execution plan that you can use to generate charts. --- diff --git a/website/docs/cli/commands/import.mdx b/website/docs/cli/commands/import.mdx index fae730dfab6e..c3097e7394ff 100644 --- a/website/docs/cli/commands/import.mdx +++ b/website/docs/cli/commands/import.mdx @@ -1,6 +1,6 @@ --- page_title: terraform import command reference -description: The terraform import command imports existing resources into Terraform state. +description: The `terraform import` command imports existing resources into Terraform state. --- # `terraform import` command reference diff --git a/website/docs/cli/commands/init.mdx b/website/docs/cli/commands/init.mdx index 26579347ba2e..08604186b880 100644 --- a/website/docs/cli/commands/init.mdx +++ b/website/docs/cli/commands/init.mdx @@ -1,7 +1,7 @@ --- page_title: terraform init command reference description: >- - The terraform init command initializes a working directory containing + The `terraform init` command initializes a working directory containing configuration files and installs plugins for required providers. --- diff --git a/website/docs/cli/commands/login.mdx b/website/docs/cli/commands/login.mdx index 961b8451a977..9a4cb535a7db 100644 --- a/website/docs/cli/commands/login.mdx +++ b/website/docs/cli/commands/login.mdx @@ -1,7 +1,7 @@ --- page_title: terraform login command reference description: >- - The terraform login command obtains an API token for HCP Terraform, Terraform Enterprise, or other host that + The `terraform login` command obtains an API token for HCP Terraform, Terraform Enterprise, or other host that offers Terraform services. --- diff --git a/website/docs/cli/commands/logout.mdx b/website/docs/cli/commands/logout.mdx index 3c4817b4f797..8351a6a232fd 100644 --- a/website/docs/cli/commands/logout.mdx +++ b/website/docs/cli/commands/logout.mdx @@ -1,7 +1,7 @@ --- page_title: terraform logout command reference description: >- - The terraform logout command removes credentials stored after using the terraform + The `terraform logout` command removes credentials stored after using the terraform login command. --- diff --git a/website/docs/cli/commands/modules.mdx b/website/docs/cli/commands/modules.mdx index 00db42dce736..16ea52db6f97 100644 --- a/website/docs/cli/commands/modules.mdx +++ b/website/docs/cli/commands/modules.mdx @@ -1,7 +1,7 @@ --- -page_title: 'Command: modules' +page_title: terraform modules command reference description: >- - The terraform modules command prints source and version data about all declared + The `terraform modules` command prints source and version data about all declared modules in Terraform configuration. --- diff --git a/website/docs/cli/commands/plan.mdx b/website/docs/cli/commands/plan.mdx index c4a215bd161a..7cbbcf6fa222 100644 --- a/website/docs/cli/commands/plan.mdx +++ b/website/docs/cli/commands/plan.mdx @@ -1,7 +1,7 @@ --- page_title: terraform plan command reference description: >- - The terraform plan command creates an execution plan with a preview of the + The `terraform plan` command creates an execution plan with a preview of the changes that Terraform will make to your infrastructure. --- diff --git a/website/docs/cli/commands/providers.mdx b/website/docs/cli/commands/providers.mdx index 3222d8f637dc..c1a2f3315816 100644 --- a/website/docs/cli/commands/providers.mdx +++ b/website/docs/cli/commands/providers.mdx @@ -1,7 +1,7 @@ --- page_title: 'Command: providers' description: >- - The terraform providers command prints information about the providers + The `terraform providers` command prints information about the providers required in the current configuration. ---