Merge pull request #26723 from hashicorp/oct20_language_and_cli_docs

website: TF-153: Split core Terraform docs into "Language" and "CLI"

website/docs/backends/config.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "docs"
+layout: "language"
 page_title: "Backends: Configuration"
 sidebar_current: "docs-backends-config"
 description: |-

website/docs/backends/index.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "docs"
+layout: "language"
 page_title: "Backends"
 sidebar_current: "docs-backends-index"
 description: |-

website/docs/backends/init.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "docs"
+layout: "language"
 page_title: "Backends: Init"
 sidebar_current: "docs-backends-init"
 description: |-

website/docs/backends/operations.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "docs"
+layout: "language"
 page_title: "Backends: Remote Operations (plan, apply, etc.)"
 sidebar_current: "docs-backends-operations"
 description: |-

website/docs/backends/state.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "docs"
+layout: "language"
 page_title: "Backends: State Storage and Locking"
 sidebar_current: "docs-backends-state"
 description: |-

website/docs/backends/types/artifactory.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: artifactory"
 sidebar_current: "docs-backends-types-standard-artifactory"
 description: |-

website/docs/backends/types/azurerm.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: azurerm"
 sidebar_current: "docs-backends-types-standard-azurerm"
 description: |-

website/docs/backends/types/consul.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: consul"
 sidebar_current: "docs-backends-types-standard-consul"
 description: |-

website/docs/backends/types/cos.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: cos"
 sidebar_current: "docs-backends-types-standard-cos"
 description: |-

website/docs/backends/types/etcd.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: etcd"
 sidebar_current: "docs-backends-types-standard-etcdv2"
 description: |-

website/docs/backends/types/etcdv3.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: etcdv3"
 sidebar_current: "docs-backends-types-standard-etcdv3"
 description: |-

website/docs/backends/types/gcs.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: gcs"
 sidebar_current: "docs-backends-types-standard-gcs"
 description: |-

website/docs/backends/types/http.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: http"
 sidebar_current: "docs-backends-types-standard-http"
 description: |-

website/docs/backends/types/index.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend: Supported Backend Types"
 sidebar_current: "docs-backends-types-index"
 description: |-

website/docs/backends/types/kubernetes.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: Kubernetes"
 sidebar_current: "docs-backends-types-standard-kubernetes"
 description: |-

website/docs/backends/types/local.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: local"
 sidebar_current: "docs-backends-types-enhanced-local"
 description: |-

website/docs/backends/types/manta.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: manta"
 sidebar_current: "docs-backends-types-standard-manta"
 description: |-

website/docs/backends/types/oss.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: oss"
 sidebar_current: "docs-backends-types-standard-oss"
 description: |-

website/docs/backends/types/pg.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: pg"
 sidebar_current: "docs-backends-types-standard-pg"
 description: |-

website/docs/backends/types/remote.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: remote"
 sidebar_current: "docs-backends-types-enhanced-remote"
 description: |-

website/docs/backends/types/s3.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: s3"
 sidebar_current: "docs-backends-types-standard-s3"
 description: |-

website/docs/backends/types/swift.html.md

@@ -1,5 +1,5 @@
 ---
-layout: "backend-types"
+layout: "language"
 page_title: "Backend Type: swift"
 sidebar_current: "docs-backends-types-standard-swift"
 description: |-

website/docs/cli-index.html.md

@@ -1,43 +1,20 @@
 ---
 layout: "docs"
-page_title: "Documentation"
+page_title: "Terraform CLI Documentation"
 sidebar_current: "docs-home"
 description: |-
-  Documentation for Terraform's core open source features, including the
-  configuration language, the commands, and the main Terraform providers.
+  Documentation for Terraform's CLI-based workflows.
 ---
 
 # Terraform CLI Documentation
 
-Welcome to the Terraform CLI documentation!
+> **Hands-on:** Try the [Terraform: Get Started](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) collection on HashiCorp Learn.
 
-## What's in This Section of the Docs?
+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 section contains reference documentation for Terraform's core open source
-features, including the
-[configuration language](/docs/configuration/index.html), the
-[command-line tools](/docs/commands/index.html), and the main
-[Terraform providers](/docs/providers/index.html). Use the navigation sidebar
-to browse the various subsections.
-
-## Who is This For?
-
-The Terraform CLI docs are relevant to _all Terraform users,_ including open
-source users and Terraform Cloud users.
-
-Since these docs are reference material, they are mainly written for
-_intermediate and advanced users,_ who need to find complete and detailed
-information quickly.
-
-- **New user?** Try the
-  [Get Started collection](https://learn.hashicorp.com/collections/terraform/aws-get-started?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS)
-  at HashiCorp Learn, then return
-  here once you've used Terraform to manage some simple resources.
-- **Curious about Terraform?** See [Introduction to Terraform](/intro/index.html)
-  for a broad overview of what Terraform is and why people use it.
-
-## What's Elsewhere?
-
-This is not the only section of the Terraform docs! You can find out more at the
-[Terraform docs home page](/docs/index.html), or you can jump between sections
-using the "Other Docs" area of the navigation sidebar.
+Notably, this documentation does not cover the syntax and usage of the Terraform
+language. For that, see the
+[Terraform Language Documentation](/docs/configuration/index.html).

website/docs/cli/auth/index.html.md

@@ -0,0 +1,29 @@
+---
+layout: "docs"
+page_title: "Authentication - Terraform CLI"
+---
+
+# 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 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,
+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.
+
+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
+Terraform Cloud user account.
+
+For details, see:
+
+- [The `terraform login` command](/docs/commands/login.html)
+- [The `terraform logout` command](/docs/commands/logout.html)

website/docs/cli/code/index.html.md

@@ -0,0 +1,43 @@
+---
+layout: "docs"
+page_title: "Writing and Modifying Code - Terraform CLI"
+---
+
+# Writing and Modifying Terraform Code
+
+The [Terraform language](/docs/configuration/index.html) is Terraform's primary
+user interface, and all of Terraform's workflows rely on configurations written
+in the Terraform language.
+
+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.
+
+- [The `terraform console` command](/docs/commands/console.html) starts an
+  interactive shell for evaluating Terraform
+  [expressions](/docs/configuration/expressions.html), which can be a faster way
+  to verify that a particular resource argument results in the value you expect.
+
+
+- [The `terraform fmt` command](/docs/commands/fmt.html) rewrites Terraform
+  configuration files to a canonical format and style, so you don't have to
+  waste time making minor adjustments for readability and consistency. It works
+  well as a pre-commit hook in your version control system.
+
+- [The `terraform validate` command](/docs/commands/validate.html) validates the
+  syntax and arguments of the Terraform configuration files in a directory,
+  including argument and attribute names and types for resources and modules.
+  The `plan` and `apply` commands automatically validate a configuration before
+  performing any other work, so `validate` isn't a crucial part of the core
+  workflow, but it can be very useful as a pre-commit hook or as part of a
+  continuous integration pipeline.
+
+- [The `0.13upgrade` command](/docs/commands/0.13upgrade.html) and
+  [the `0.12upgrade` command](/docs/commands/0.12upgrade.html) can automatically
+  modify the configuration files in a Terraform module to help deal with major
+  syntax changes that occurred in the 0.13 and 0.12 releases of Terraform. Both
+  of these commands are only available in the Terraform version they are
+  associated with, and you are expected to upgrade older code to be compatible
+  with 0.12 before attempting to make it compatible with 0.13. For more detailed
+  information about updating code for new Terraform versions, see the [upgrade
+  guides](/upgrade-guides/index.html) in the Terraform language docs.

website/docs/cli/config/index.html.md

@@ -0,0 +1,22 @@
+---
+layout: "docs"
+page_title: "CLI Configuration - Terraform CLI"
+---
+
+# CLI Configuration
+
+Terraform CLI can be configured with some 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,
+most of the global settings relate to advanced or automated workflows, or
+unusual environmental conditions like running Terraform on an airgapped
+instance.
+
+- The [CLI config file](/docs/commands/cli-config.html) configures provider
+  installation and security features.
+- Several [environment variables](/docs/commands/environment-variables.html) can
+  configure Terraform's inputs and outputs; this includes some alternate ways to
+  provide information that is usually passed on the command line or read from
+  the state of the shell.

website/docs/cli/init/index.html.md

@@ -0,0 +1,71 @@
+---
+layout: "docs"
+page_title: "Initializing Working Directories - Terraform CLI"
+---
+
+# Initializing Working Directories
+
+Terraform expects to be invoked from a working directory that contains
+configuration files written in
+[the Terraform language](/docs/configuration/index.html). Terraform uses
+configuration content from this directory, and also uses the directory to store
+settings, cached plugins and modules, and sometimes state data.
+
+A working directory must be initialized before Terraform can perform any
+operations in it (like provisioning infrastructure or modifying state).
+
+## Working Directory Contents
+
+A Terraform working directory typically contains:
+
+- A Terraform configuration describing resources Terraform should manage. This
+  configuration is expected to change over time.
+- A hidden `.terraform` directory, which Terraform uses to manage cached
+  provider plugins and modules, record which
+  [workspace](/docs/cli/workspaces/index.html) is currently active, and
+  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).
+
+## Initialization
+
+Run the `terraform init` command to initialize a working directory that contains
+a Terraform configuration. After initialization, you will be able to perform
+other commands, like `terraform plan` and `terraform apply`.
+
+If you try to run a command that relies on initialization without first
+initializing, the command will fail with an error and explain that you need to
+run init.
+
+Initialization performs several tasks to prepare a directory, including
+accessing state in the configured backend, downloading and installing provider
+plugins, and downloading modules. Under some conditions (usually when changing
+from one backend to another), it might ask the user for guidance or
+confirmation.
+
+For details, see [the `terraform init` command](/docs/commands/init.html).
+
+## Reinitialization
+
+Certain types of changes to a Terraform configuration can require
+reinitialization before normal operations can continue. This includes changes to
+provider requirements, module sources or version constraints, and backend
+configurations.
+
+You can reinitialize a directory by running `terraform init` again. In fact, you
+can reinitialize at any time; the init command is idempotent, and will have no
+effect if no changes are required.
+
+If reinitialization is required, any commands that rely on initialization will
+fail with an error and tell you so.
+
+## Reinitializing Only Modules
+
+The `terraform get` command will download modules referenced in the
+configuration, but will not perform the other required initialization tasks.
+This command is only useful for niche workflows, and most Terraform users can
+ignore it in favor of `terraform init`.