From 044c439dbc6ef1697546a96aad968497cb3a1f8b Mon Sep 17 00:00:00 2001 From: Judith Malnick Date: Tue, 8 Jun 2021 06:58:55 -0700 Subject: [PATCH] Gloss of top docs pages (#28891) * clarify input variables opening sentence * adjust variables description * claraify providers text and add learn callout * add description to providers page * add desscription and clarify provider configuration * add deprecation note to versions in proivder configs * add hands on callout and clarify next steps in intro * link to language collection from language docs * give more context about configurtion language up front * clarify output top page * reorganize for each intro to present feature before notes * move description before link out and remove passive voice * fix typo * clarify purpose of plan * move explanation before learn link and fully spell boolean * add a syntax heading to separate intro from details * add learn callout to module source docs * clean up intro to provider requirements and add link * Apply suggestions from code review Co-authored-by: Tu Nguyen * Apply suggestions from code review Co-authored-by: Tu Nguyen Co-authored-by: Tu Nguyen --- website/docs/cli/commands/plan.html.md | 15 +++++----- .../docs/language/data-sources/index.html.md | 8 ++--- .../language/expressions/conditionals.html.md | 6 ++-- website/docs/language/index.html.md | 14 ++++----- .../language/meta-arguments/for_each.html.md | 16 +++++----- website/docs/language/modules/sources.html.md | 4 +++ .../language/providers/configuration.html.md | 29 +++++++++---------- website/docs/language/providers/index.html.md | 9 +++++- .../language/providers/requirements.html.md | 27 ++++++++--------- website/docs/language/values/outputs.html.md | 9 ++++-- .../docs/language/values/variables.html.md | 11 +++---- website/intro/index.html.markdown | 14 +++++---- 12 files changed, 89 insertions(+), 73 deletions(-) diff --git a/website/docs/cli/commands/plan.html.md b/website/docs/cli/commands/plan.html.md index 29a4ccaae..03847cdf8 100644 --- a/website/docs/cli/commands/plan.html.md +++ b/website/docs/cli/commands/plan.html.md @@ -8,18 +8,19 @@ description: |- # Command: plan -> **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. +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 `terraform plan` command creates an execution plan. By default, creating -a plan consists of: - -* Reading the current state of any already-existing remote objects to make sure +* Reads the current state of any already-existing remote objects to make sure that the Terraform state is up-to-date. -* Comparing the current configuration to the prior state and noting any +* Compares the current configuration to the prior state and noting any differences. -* Proposing a set of change actions that should, if applied, make the remote +* Proposes a set of change actions that should, if applied, make the remote objects match the configuration. +> **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. + The plan command alone will not actually carry out the proposed changes, and so you can use this command to check whether the proposed changes match what you expected before you apply the changes or share your changes with your diff --git a/website/docs/language/data-sources/index.html.md b/website/docs/language/data-sources/index.html.md index 589dfa3c6..35af54b4e 100644 --- a/website/docs/language/data-sources/index.html.md +++ b/website/docs/language/data-sources/index.html.md @@ -8,12 +8,10 @@ description: |- # Data Sources -> **Hands-on:** Try the [Query data sources](https://learn.hashicorp.com/tutorials/terraform/data-sources?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. +_Data sources_ allow Terraform use information defined outside of Terraform, +defined by another separate Terraform configuration, or modified by functions. -_Data sources_ allow data to be fetched or computed for use elsewhere -in Terraform configuration. Use of data sources allows a Terraform -configuration to make use of information defined outside of Terraform, -or defined by another separate Terraform configuration. +> **Hands-on:** Try the [Query Data Sources](https://learn.hashicorp.com/tutorials/terraform/data-sources) tutorial on HashiCorp Learn. Each [provider](/docs/language/providers/index.html) may offer data sources alongside its set of [resource](/docs/language/resources/index.html) diff --git a/website/docs/language/expressions/conditionals.html.md b/website/docs/language/expressions/conditionals.html.md index 138e2b0e5..cd7bc0129 100644 --- a/website/docs/language/expressions/conditionals.html.md +++ b/website/docs/language/expressions/conditionals.html.md @@ -5,10 +5,12 @@ page_title: "Conditional Expressions - Configuration Language" # Conditional Expressions +A _conditional expression_ uses the value of a boolean expression to select one of +two values. + > **Hands-on:** Try the [Create Dynamic Expressions](https://learn.hashicorp.com/tutorials/terraform/expressions?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. -A _conditional expression_ uses the value of a bool expression to select one of -two values. +## Syntax The syntax of a conditional expression is as follows: diff --git a/website/docs/language/index.html.md b/website/docs/language/index.html.md index 49067f802..c370623fc 100644 --- a/website/docs/language/index.html.md +++ b/website/docs/language/index.html.md @@ -8,13 +8,14 @@ page_title: "Overview - Configuration Language" This is the documentation for Terraform's configuration language. It is relevant to users of [Terraform CLI](/docs/cli/index.html), [Terraform Cloud](/docs/cloud/index.html), and -[Terraform Enterprise](/docs/enterprise/index.html). +[Terraform Enterprise](/docs/enterprise/index.html). Terraform's language is +its primary user interface. Configuration files you write in Terraform +language tell Terraform what plugins to install, what infrastructure to create, +and what data to fetch. Terraform language also lets you define dependencies +between resources and create multiple similar resources from a single +configuration block. -> **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. - -_The Terraform language is Terraform's primary user interface._ In every edition -of Terraform, a configuration written in the Terraform language is always at the -heart of the workflow. +> **Hands-on:** Try the [Write Terraform Configuration](https://learn.hashicorp.com/collections/terraform/configuration-language) tutorials on HashiCorp Learn. ## About the Terraform Language @@ -115,4 +116,3 @@ resource "aws_subnet" "az" { cidr_block = cidrsubnet(aws_vpc.main.cidr_block, 4, count.index+1) } ``` - diff --git a/website/docs/language/meta-arguments/for_each.html.md b/website/docs/language/meta-arguments/for_each.html.md index 1a8bfe50b..ea5b30004 100644 --- a/website/docs/language/meta-arguments/for_each.html.md +++ b/website/docs/language/meta-arguments/for_each.html.md @@ -5,14 +5,6 @@ page_title: "The for_each Meta-Argument - Configuration Language" # The `for_each` Meta-Argument --> **Version note:** `for_each` was added in Terraform 0.12.6. Module support -for `for_each` was added in Terraform 0.13, and previous versions can only use -it with resources. - --> **Note:** A given resource or module block cannot use both `count` and `for_each`. - -> **Hands-on:** Try the [Manage Similar Resources With For Each](https://learn.hashicorp.com/tutorials/terraform/for-each?in=terraform/0-13&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. - By default, a [resource block](/docs/language/resources/syntax.html) configures one real infrastructure object (and similarly, a [module block](/docs/language/modules/syntax.html) includes a @@ -22,10 +14,18 @@ pool of compute instances) without writing a separate block for each one. Terraform has two ways to do this: [`count`](/docs/language/meta-arguments/count.html) and `for_each`. +> **Hands-on:** Try the [Manage Similar Resources With For Each](https://learn.hashicorp.com/tutorials/terraform/for-each?in=terraform/configuration-language) tutorial on HashiCorp Learn. + If a resource or module block includes a `for_each` argument whose value is a map or a set of strings, Terraform will create one instance for each member of that map or set. +-> **Version note:** `for_each` was added in Terraform 0.12.6. Module support +for `for_each` was added in Terraform 0.13; previous versions can only use +it with resources. + +-> **Note:** A given resource or module block cannot use both `count` and `for_each`. + ## Basic Syntax `for_each` is a meta-argument defined by the Terraform language. It can be used diff --git a/website/docs/language/modules/sources.html.md b/website/docs/language/modules/sources.html.md index 94da03653..fd5cce8d8 100644 --- a/website/docs/language/modules/sources.html.md +++ b/website/docs/language/modules/sources.html.md @@ -14,6 +14,10 @@ Terraform uses this during the module installation step of `terraform init` to download the source code to a directory on local disk so that it can be used by other Terraform commands. +> **Hands-on:** Try our HashiCorp Learn tutorials to use modules from [the +> registry](https://learn.hashicorp.com/tutorials/terraform/module-use) +>or [locally](https://learn.hashicorp.com/tutorials/terraform/module-create). + The module installer supports installation from a number of different source types, as listed below. diff --git a/website/docs/language/providers/configuration.html.md b/website/docs/language/providers/configuration.html.md index 20cc28dcb..6a7d8ad60 100644 --- a/website/docs/language/providers/configuration.html.md +++ b/website/docs/language/providers/configuration.html.md @@ -3,21 +3,23 @@ layout: "language" page_title: "Provider Configuration - Configuration Language" sidebar_current: "docs-config-providers" description: |- - Providers are responsible in Terraform for managing the lifecycle of a resource: create, read, update, delete. + Learn how to configure provider settings and alias providers to use multiple + different provider configurations in the same Terraform project. --- # Provider Configuration -Terraform relies on plugins called "providers" to interact with remote systems. +Providers alow Terraform to interact with cloud providers, SaaS providers, and +other APIs. -Terraform configurations must declare which providers they require, so that -Terraform can install and use them. Additionally, some providers require -configuration (like endpoint URLs or cloud regions) before they can be used. +Some providers require you to configure them with endpoint URLs, cloud regions, +or other settings before Terraform can use them. This page documents how to +configure settings for providers. -- This page documents how to configure settings for providers. - -- The [Provider Requirements](/docs/language/providers/requirements.html) page documents how - to declare providers so Terraform can install them. +Additionally, all Terraform configurations must declare which providers they +require so that Terraform can install and use them. The +[Provider Requirements](/docs/language/providers/requirements.html) +page documents how to declare providers so Terraform can install them. ## Provider Configuration @@ -182,7 +184,7 @@ from their parents. -## `version`: An Older Way to Manage Provider Versions +## `version` (Deprecated) [inpage-versions]: #provider-versions @@ -193,11 +195,6 @@ constraint in a provider configuration is only used if `required_providers` does not include one for that provider. **The `version` argument in provider configurations is deprecated.** -In Terraform 0.13 and later, version constraints should always be declared in +In Terraform 0.13 and later, always declare provider version constraints in [the `required_providers` block](/docs/language/providers/requirements.html). The `version` argument will be removed in a future version of Terraform. - --> **Note:** The `version` meta-argument made sense before Terraform 0.13, since -Terraform could only install providers that were distributed by HashiCorp. Now -that Terraform can install providers from multiple sources, it makes more sense -to keep version constraints and provider source addresses together. diff --git a/website/docs/language/providers/index.html.md b/website/docs/language/providers/index.html.md index 44f830101..648224b9c 100644 --- a/website/docs/language/providers/index.html.md +++ b/website/docs/language/providers/index.html.md @@ -1,11 +1,18 @@ --- layout: "language" page_title: "Providers - Configuration Language" +description: |- + Terraform providers are plugins that allow Terraform to create resources and + use data sources from services, cloud providers, and other APIs. Read about + how to discover, install, and use providers. --- # Providers -Terraform relies on plugins called "providers" to interact with remote systems. +> **Hands-on:** Try the [Perform CRUD Operations with Providers](https://learn.hashicorp.com/tutorials/terraform/provider-use?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. + +Terraform relies on plugins called "providers" to interact with cloud providers, +SaaS providers, and other APIs. Terraform configurations must declare which providers they require so that Terraform can install and use them. Additionally, some providers require diff --git a/website/docs/language/providers/requirements.html.md b/website/docs/language/providers/requirements.html.md index 128192432..90e4cd8a4 100644 --- a/website/docs/language/providers/requirements.html.md +++ b/website/docs/language/providers/requirements.html.md @@ -5,21 +5,22 @@ page_title: "Provider Requirements - Configuration Language" # Provider Requirements +Terraform relies on plugins called "providers" to interact with remote systems. +Terraform configurations must declare which providers they require, so that +Terraform can install and use them. This page documents how to declare providers +so Terraform can install them. + +> **Hands-on:** Try the [Perform CRUD Operations with Providers](https://learn.hashicorp.com/tutorials/terraform/provider-use) tutorial on HashiCorp Learn. + +Additionally, some providers require configuration (like endpoint URLs or cloud +regions) before they can be used. The [Provider +Configuration](/docs/language/providers/configuration.html) page documents how +to configure settings for providers. + -> **Note:** This page is about a feature of Terraform 0.13 and later; it also describes how to use the more limited version of that feature that was available in Terraform 0.12. -Terraform relies on plugins called "providers" to interact with remote systems. - -Terraform configurations must declare which providers they require, so that -Terraform can install and use them. Additionally, some providers require -configuration (like endpoint URLs or cloud regions) before they can be used. - -- This page documents how to declare providers so Terraform can install them. - -- The [Provider Configuration](/docs/language/providers/configuration.html) page documents how to configure - settings for providers. - ## Requiring Providers Each Terraform module must declare which providers it requires, so that @@ -223,7 +224,7 @@ and commit it to version control along with your configuration. If a lock file is present, Terraform Cloud, CLI, and Enterprise will all obey it when installing providers. -> **Hands-on:** Try the [Lock and Upgrade Provider Versions](https://learn.hashicorp.com/tutorials/terraform/provider-versioning?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. +> **Hands-on:** Try the [Lock and Upgrade Provider Versions](https://learn.hashicorp.com/tutorials/terraform/provider-versioning) tutorial on HashiCorp Learn. ### Best Practices for Provider Versions @@ -289,7 +290,7 @@ compatible with Terraform v0.11 or later and should never be declared in a ## In-house Providers Anyone can develop and distribute their own Terraform providers. See -the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) +the [Call APIs with Terraform Providers](https://learn.hashicorp.com/collections/terraform/providers) collection on HashiCorp Learn for more about provider development. diff --git a/website/docs/language/values/outputs.html.md b/website/docs/language/values/outputs.html.md index 35b8aa441..824929fd5 100644 --- a/website/docs/language/values/outputs.html.md +++ b/website/docs/language/values/outputs.html.md @@ -8,12 +8,15 @@ description: |- # Output Values +Output values make information about your infrastructure available on the +command line, and can expose information for other Terraform configurations to +use. Output values are similar to return values in programming languages. + > **Hands-on:** Try the [Output Data From -Terraform](https://learn.hashicorp.com/tutorials/terraform/outputs?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) +Terraform](https://learn.hashicorp.com/tutorials/terraform/outputs) tutorial on HashiCorp Learn. -Output values are like the return values of a Terraform module, and have several -uses: +Output values have several uses: - A child module can use outputs to expose a subset of its resource attributes to a parent module. diff --git a/website/docs/language/values/variables.html.md b/website/docs/language/values/variables.html.md index 3c167eb1d..f25f79aef 100644 --- a/website/docs/language/values/variables.html.md +++ b/website/docs/language/values/variables.html.md @@ -3,17 +3,18 @@ layout: "language" page_title: "Input Variables - Configuration Language" sidebar_current: "docs-config-variables" description: |- - Input variables are parameters for Terraform modules. - This page covers configuration syntax for variables. + Input variables allow you to customize Terraform configuration according to + set parameters. Learn about input variable syntax, including how to declare, + define, and reference variables in root and child modules. --- # Input Variables > **Hands-on:** Try the [Customize Terraform Configuration with Variables](https://learn.hashicorp.com/tutorials/terraform/variables?in=terraform/configuration-language&utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial on HashiCorp Learn. -Input variables serve as parameters for a Terraform module, allowing aspects -of the module to be customized without altering the module's own source code, -and allowing modules to be shared between different configurations. +Input variables let you customize aspects of Terraform modules without altering +the module's own source code. This allows you to share modules across different +Terraform configurations, making your module composable and reusable. When you declare variables in the root module of your configuration, you can set their values using CLI options and environment variables. diff --git a/website/intro/index.html.markdown b/website/intro/index.html.markdown index 3f8a18f44..3d5a64c70 100644 --- a/website/intro/index.html.markdown +++ b/website/intro/index.html.markdown @@ -17,6 +17,8 @@ If you are already familiar with the basics of Terraform, the [documentation](/docs/index.html) provides a better reference guide for all available features as well as internals. +> **Hands-on:** Try the [Get Started](https://learn.hashicorp.com/tutorials/terraform/infrastructure-as-code) tutorials on HashiCorp Learn. + ## What is Terraform? Terraform is a tool for building, changing, and versioning infrastructure @@ -71,9 +73,9 @@ possible human errors. ## Next Steps -See the page on [Terraform use cases](/intro/use-cases.html) to see the -multiple ways Terraform can be used. Then see -[how Terraform compares to other software](/intro/vs/index.html) -to see how it fits into your existing infrastructure. Finally, continue onwards with -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 to use -Terraform to manage real infrastructure and to see how it works. +- Learn about common [Terraform use cases](/intro/use-cases.html) to find multiple +ways you can use Terraform. +- Learn [how Terraform compares to other infrastructure tools](/intro/vs/index.html). +- Try the [Terraform: Get + Started](https://learn.hashicorp.com/collections/terraform/aws-get-started) + tutorials on HashiCorp Learn to use Terraform to manage real infrastructure.