Merge pull request hashicorp#30173 from hashicorp/ds.mdx-migration-main

Migrate docs to MDX (main)
BurrofillDrKuro · Dec 15, 2021 · 58e4676 · 58e4676
2 parents c4d46e7 + 21cbb5b
commit 58e4676
Show file tree

Hide file tree

Showing 358 changed files with 5,054 additions and 5,868 deletions.
diff --git a/website/README.md b/website/README.md
@@ -8,39 +8,36 @@ The files in this directory are intended to be used in conjunction with
 different documentation sources together and contains the scripts for testing and building the site as
 a whole.
 
+## Modifying Sidebar Navigation
+
+Updates to the sidebar navigation of Terraform docs need to be made in the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository (preferrably in a PR also updating the submodule commit). You can read more about how to make modifications to the navigation in the [README for `terraform-website`](https://github.com/hashicorp/terraform-website#editing-navigation-sidebars).
+
 ## Previewing Changes
 
-You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site. If `terraform-website` isn't in your `GOPATH`, the preview command will clone it to your machine.
+You should preview all of your changes locally before creating a pull request. The build includes content from this repository and the [`terraform-website`](https://github.com/hashicorp/terraform-website/) repository, allowing you to preview the entire Terraform documentation site.
 
 **Set Up Local Environment**
 
 1. [Install Docker](https://docs.docker.com/get-docker/).
-2. Create a `~/go` directory manually or by [installing Go](https://golang.org/doc/install).
-3. Open terminal and set `GOPATH` as an environment variable:
-
-    Bash: `export $GOPATH=~/go`(bash)
-
-    Zsh: `echo -n 'export GOPATH=~/go' >> ~/.zshrc`
-4. Restart your terminal or command line session.
+1. Restart your terminal or command line session.
 
 **Launch Site Locally**
 
 1. Navigate into your local `terraform` top-level directory and run `make website`.
-2. Open `http://localhost:4567` in your web browser. While the preview is running, you can edit pages and Middleman will automatically rebuild them.
-3. When you're done with the preview, press `ctrl-C` in your terminal to stop the server.
+1. Open `http://localhost:4567` in your web browser. While the preview is running, you can edit pages and Next.js will automatically rebuild them.
+1. When you're done with the preview, press `ctrl-C` in your terminal to stop the server.
 
 ## Deploying Changes
 
 Merge the PR to main. The changes will appear in the next major Terraform release.
 
 If you need your changes to be deployed sooner, cherry-pick them to:
-- the current release branch (e.g. `v1.0`) and push. They will be deployed in the next minor version release (once every two weeks).
-- the `stable-website` branch and push. They will be included in the next site deploy (see below). Note that the release process resets `stable-website` to match the release tag, removing any additional commits. So, we recommend always cherry-picking to the version branch first and then to `stable-website` when needed.
+
+- the current release branch (e.g. `v1.1`) and push. They will be deployed in the next minor version release (once every two weeks).
+- the `stable-website` branch and push. They will be included in the next site deploy (see below). Note that the release process resets `stable-website` to match the release tag, removing any additional commits. So, we recommend always cherry-picking to the version branch first and then to `stable-website` when needed.
+
+Once your PR to `stable-website` is merged, open a PR bumping the submodule commit in [`terraform-website`](https://github.com/hashicorp/terraform-website).
 
 ### Deployment
-Currently, HashiCorp uses a CircleCI job to deploy the [terraform.io](terraform.io) site. This job can be run manually by many people within HashiCorp, and also runs automatically whenever a user in the HashiCorp GitHub org merges changes to master in the `terraform-website` repository.
 
-New commits in this repository don't automatically deploy the [terraform.io][] site, but an unrelated site deploy will usually happen within a day. If you can't wait that long, you can do a manual CircleCI build or ask someone in the #proj-terraform-docs channel to do so:
-- Log in to circleci.com, and  make sure you're viewing the HashiCorp organization.
-- Go to the terraform-website project's list of workflows.
-- Find the most recent "website-deploy" workflow, and click the "Rerun workflow from start" button (which looks like a refresh button with a numeral "1" inside).
+New commits in `hashicorp/terraform` and `hashicorp/terraform-cdk` don't automatically deploy the site. To use the latest upstream content, you'll need to open a PR bumping the submodule commit. If your changes aren't being deployed, it's very likely that you need to open a PR to update the submodule commit.
diff --git a/website/docs/cli/auth/index.html.md → website/docs/cli/auth/index.mdx b/website/docs/cli/auth/index.html.md → website/docs/cli/auth/index.mdx
@@ -1,21 +1,22 @@
 ---
-layout: "docs"
-page_title: "Authentication - Terraform CLI"
-description: "Documentation about the login and logout commands that help automate getting an API token for your Terraform Cloud account."
+page_title: Authentication - Terraform CLI
+description: >-
+  Documentation about the login and logout commands that help automate getting
+  an API token for your Terraform Cloud account.
 ---
 
 # CLI Authentication
 
 > **Hands-on:** Try the [Authenticate the CLI with Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-login?in=terraform/cloud&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn.
 
-[Terraform Cloud](/docs/cloud/index.html) and
-[Terraform Enterprise](/docs/enterprise/index.html) are platforms that perform
+[Terraform Cloud](/cloud) and
+[Terraform Enterprise](/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 "Terraform Cloud.")
 
 Terraform CLI integrates with Terraform Cloud in several ways — it can be a
-front-end for [CLI-driven runs](/docs/cloud/run/cli.html) in Terraform Cloud,
+front-end for [CLI-driven runs](/cloud-docs/run/cli) in Terraform Cloud,
 and can also use Terraform Cloud as a state backend and a private module
 registry. All of these integrations require you to authenticate Terraform CLI
 with your Terraform Cloud account.
@@ -26,5 +27,5 @@ Terraform Cloud user account.
 
 For details, see:
 
-- [The `terraform login` command](/docs/cli/commands/login.html)
-- [The `terraform logout` command](/docs/cli/commands/logout.html)
+- [The `terraform login` command](/cli/commands/login)
+- [The `terraform logout` command](/cli/commands/logout)
diff --git a/website/docs/cli/cloud/command-line-arguments.html.md b/website/docs/cli/cloud/command-line-arguments.html.md
diff --git a/website/docs/cli/cloud/command-line-arguments.mdx b/website/docs/cli/cloud/command-line-arguments.mdx
@@ -0,0 +1,24 @@
+---
+page_title: Command Line Arguments
+description: Command Line Arguments
+---
+
+# Command Line Arguments
+
+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
+accept the following option to modify that behavior:
+
+- `-ignore-remote-version` - Override checking that the local and remote
+  Terraform versions agree, making an operation proceed even when there is
+  a mismatch.
+
+  State-modification operations usually require using a local version of the
+  Terraform CLI that is compatible with the Terraform version selected
+  in the remote workspace settings. This prevents the
+  local operation from creating a new state snapshot that the workspace's
+  remote execution environment cannot decode.
+
+  We recommend against using this option unless absolutely necessary. Overriding this check can result
+  in a Terraform Cloud workspace that is no longer able to complete remote operations with the currently
+  selected version of Terraform.
diff --git a/website/docs/cli/cloud/index.html.md b/website/docs/cli/cloud/index.html.md
diff --git a/website/docs/cli/cloud/index.mdx b/website/docs/cli/cloud/index.mdx
@@ -0,0 +1,26 @@
+---
+page_title: Using Terraform Cloud - Terraform CLI
+---
+
+# Using Terraform Cloud with Terraform CLI
+
+The Terraform CLI's integration with Terraform Cloud lets you to use Terraform Cloud and Terraform Enterprise on the command line. In the documentation Terraform Cloud instructions also apply to Terraform Enterprise, except where explicitly stated.
+
+Using Terraform Cloud through the command line is called the [CLI-driven run workflow](/cloud-docs/run/cli). When you use the CLI workflow, operations like `terraform plan` or `terraform apply` are remotely executed in Terraform Cloud's run environment by default, with log output streaming to the local terminal. This lets you use Terraform Cloud features within the familiar Terraform CLI workflow, including variables encrypted at rest in a Terraform Cloud workspace, cost estimates, and policy checking.
+
+> **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
+
+Workspaces can also be configured for local execution, in which case only state is stored in
+Terraform Cloud. In this mode, Terraform Cloud behaves just like a standard state backend.
+
+-> **Note:** The CLI integration is available in Terraform 1.1.0 and later, and Terraform Enterprise 202201-1 and later. Previous versions can use the [`remote` backend](/language/settings/backends/remote). Refer to [Migrating from the remote
+backend](/cli/cloud/migrating) for details about switching to the CLI integration.
+
+## Documentation Summary
+
+- [Terraform Cloud Settings](/cli/cloud/settings) documents the `cloud` block that you must add to your configuration to enable Terraform Cloud support.
+- [Initializing and Migrating](/cli/cloud/migrating) describes
+  how to start using Terraform Cloud with a working directory that already has state data.
+- [Command Line Arguments](/cli/cloud/command-line-arguments) lists the Terraform command flags that are specific to using Terraform with Terraform Cloud.
+
+Refer to the [CLI-driven Run Workflow](/cloud-docs/run/cli) for more details about how to use Terraform Cloud from the command line.
diff --git a/website/docs/cli/cloud/migrating.html.md → website/docs/cli/cloud/migrating.mdx b/website/docs/cli/cloud/migrating.html.md → website/docs/cli/cloud/migrating.mdx
@@ -1,24 +1,23 @@
 ---
-layout: "docs"
-page_title: "Initializing and Migrating to Terraform Cloud - Terraform CLI"
+page_title: Initializing and Migrating to Terraform Cloud - Terraform CLI
 ---
 
 # Initializing and Migrating
 
-After [configuring Terraform Cloud settings](/docs/cli/cloud/settings.html) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/docs/cloud/run/cli.html) for more details.
+After [configuring Terraform Cloud settings](/cli/cloud/settings) for a working directory, you must run `terraform init` to finish setting up. If the working directory has no existing Terraform state, you can start using Terraform with Terraform Cloud right away. Refer to [CLI-driven run workflow](/cloud-docs/run/cli) for more details.
 
 When you run `terraform init` in the following scenarios, Terraform will ask you to choose whether or not to migrate state from any existing workspaces.
 
 1. [**Migrating from local state or state backends:**](#migrating-from-local-state-or-state-backends) If the working directory already has state data in one or more workspaces, Terraform will ask if you would like to migrate that state to new Terraform Cloud workspaces.
 
-2. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block.
+1. [**Migrating from the `remote` backend:**](#migrating-from-the-remote-backend) If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. You will need to switch the `remote` backend block to the `cloud` block.
 
 ## Migrating from Local State or State Backends
 
 > **Hands On:** Try the [Migrate State to Terraform Cloud](https://learn.hashicorp.com/tutorials/terraform/cloud-migrate) tutorial on HashiCorp Learn.
 
 If the working directory already has state data available (using either local state or a [state
-backend](/docs/language/settings/backends/index.html)), Terraform will ask your approval to migrate
+backend](/language/settings/backends)), Terraform will ask your approval to migrate
 that state to Terraform Cloud. You will need permission to manage workspaces in the destination Terraform Cloud organization. This process is interactive and self-documenting, and resembles
 moving between state backends.
 
@@ -32,13 +31,13 @@ Because of this, Terraform will prompt you to rename the working directory's wor
 according to a pattern relative to their existing names. This can indicate the fact that these specific workspaces share configuration. A typical strategy is
 `<COMPONENT>-<ENVIRONMENT>-<REGION>` (e.g.,  `networking-prod-us-east`,
 `networking-staging-us-east`). Refer to [Workspace
-Naming](/docs/cloud/workspaces/naming.html) in the Terraform Cloud documentation for more detail.
+Naming](/cloud-docs/workspaces/naming) in the Terraform Cloud documentation for more detail.
 
 ## Migrating from the `remote` Backend
 
 If the working directory was already connected to Terraform Cloud with the `remote` backend, Terraform can continue using the same Terraform Cloud workspaces. The local names shown for those workspaces will change to match their remote names.
 
-The [`remote` backend](/docs/language/settings/backends/remote.html) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/docs/cloud/run/cli.html) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements.
+The [`remote` backend](/language/settings/backends/remote) was the primary implementation of Terraform Cloud's [CLI-driven run workflow](/cloud-docs/run/cli) for Terraform versions 0.11.13 through 1.0.x. We recommend using the native `cloud` integration for Terraform versions 1.1 or later, as it provides an improved user experience and various enhancements.
 
 ### Block Replacement
 
@@ -49,7 +48,7 @@ block.
 #### Single Workspace
 
 If you were using a single workspace with the `name` argument, change the block
-  label to `cloud`.
+label to `cloud`.
 
 ```diff
 terraform {