Skip to content

Commit 9207c3b

Browse files
robin-norwoodaustinvalle
robin-norwood
and
austinvalle
authored
Update docs titles and descriptions for SEO and style guide (#1066)
* Update docs titles and descriptions for SEO and style guide * Update code-walkthrough.mdx * Update accessing-values.mdx * Update testing.mdx * Update configure.mdx * Update index.mdx * Update timeouts.mdx * Update validate-configuration.mdx * Update diagnostics.mdx * Update close.mdx * Update configure.mdx * Update index.mdx * Update open.mdx * Update renew.mdx * Update validate-configuration.mdx * Update documentation.mdx * Update errors.mdx * Update implementation.mdx * Update index.mdx * Update bool.mdx * Update dynamic.mdx * Update float32.mdx * Update float64.mdx * Update index.mdx * Use offocial name for framework * Updates from review feedback * Update website/docs/plugin/framework/handling-data/terraform-concepts.mdx Co-authored-by: Austin Valle <[email protected]> --------- Co-authored-by: Austin Valle <[email protected]>
1 parent e6e64e1 commit 9207c3b

File tree

134 files changed

+508
-420
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

134 files changed

+508
-420
lines changed

‎website/docs/plugin/framework/acctests.mdx

+5-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
2-
page_title: 'Plugin Development - Framework: Acceptance Tests'
2+
page_title: Acceptance tests
33
description: >-
4-
How to write acceptance tests for providers built on the framework. Acceptance
5-
tests imitate applying configuration files.
4+
Learn how to write acceptance tests for providers built on the framework.
5+
Acceptance tests help ensure your provider works as expected by imitating
6+
Terraform operations.
67
---
78

8-
# Acceptance Tests
9+
# Acceptance tests
910

1011
Implement provider resource and data source acceptance tests with the [terraform-plugin-testing module](/terraform/plugin/testing). These tests are designed to execute Terraform commands against real Terraform configurations, simulating practitioner experiences with creating, refreshing, updating, and deleting infrastructure.
1112

‎website/docs/plugin/framework/data-sources/configure.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Configure Data Sources'
2+
page_title: Configure data sources
33
description: >-
4-
How to configure data sources with provider data or clients in the provider development framework.
4+
Learn how to configure data sources with provider data or clients in the
5+
Terraform plugin framework.
56
---
67

7-
# Configure Data Sources
8+
# Configure data sources
89

910
[Data sources](/terraform/plugin/framework/data-sources) may require provider-level data or remote system clients to operate correctly. The framework supports the ability to configure this data and/or clients once within the provider, then pass that information to data sources by adding the `Configure` method.
1011

‎website/docs/plugin/framework/data-sources/index.mdx

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Data Sources'
2+
page_title: Data sources
33
description: >-
4-
How to build data sources in the provider development framework. Data sources
5-
allow Terraform to reference external data.
4+
Data sources allow Terraform to reference external data. Learn how the
5+
framework can help you implement data sources.
66
---
77

8-
# Data Sources
8+
# Data sources
99

1010
[Data sources](/terraform/language/data-sources) are an abstraction that allow Terraform to reference external data. Unlike [managed resources](/terraform/language/resources), Terraform does not manage the lifecycle of the resource or data. Data sources are intended to have no side-effects.
1111

‎website/docs/plugin/framework/data-sources/timeouts.mdx

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
2-
page_title: 'Plugin Development - Framework: Timeouts'
2+
page_title: Timeouts
33
description: >-
4-
How to use timeouts with the provider development framework.
4+
Learn how to implement timeouts with the Terraform plugin framework.
55
---
66

77
# Timeouts

‎website/docs/plugin/framework/data-sources/validate-configuration.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Validate Data Source Configurations'
2+
page_title: Validate data source configurations
33
description: >-
4-
How to validate data source configurations with the provider development framework.
4+
Learn how to validate data source configurations with the Terraform plugin
5+
framework.
56
---
67

7-
# Validate Configuration
8+
# Validate data source configurations
89

910
[Data sources](/terraform/plugin/framework/data-sources) support validating an entire practitioner configuration in either declarative or imperative logic. Feedback, such as required syntax or acceptable combinations of values, is returned via [diagnostics](/terraform/plugin/framework/diagnostics).
1011

‎website/docs/plugin/framework/debugging.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
---
2-
page_title: Plugin Development - Debugging Framework Providers
3-
description: How to implement debugger support in Framework Terraform providers.
2+
page_title: Debugging framework providers
3+
description: >-
4+
Learn how to implement debugger support in framework Terraform providers.
45
---
56

6-
# Debugging Framework Providers
7+
# Debugging framework Providers
78

89
This page contains implementation details for inspecting runtime information of a Terraform provider developed with Framework via a debugger tool by adjusting the [provider server](/terraform/plugin/framework/provider-servers) implementation. Review the top level [Debugging](/terraform/plugin/debugging) page for information pertaining to the overall Terraform provider debugging process and other inspection options, such as log-based debugging.
910

‎website/docs/plugin/framework/deprecations.mdx

+5-3
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Deprecations, Removals, and Renames Best Practices'
3-
description: 'Recommendations for deprecations, removals, and renames.'
2+
page_title: Deprecations, removals, and renames
3+
description:
4+
Use the following recommendations to handle deprecations, removals, and
5+
renames in framework providers.
46
---
57

6-
# Deprecations, Removals, and Renames
8+
# Deprecations, removals, and renames
79

810
Terraform is trusted for managing many facets of infrastructure across many organizations. Part of that trust is due to consistent versioning guidelines and setting expectations for various levels of upgrades. Ensuring backwards compatibility for all patch and minor releases, potentially in concert with any upcoming major changes, is recommended and supported by the Terraform development framework. This allows operators to iteratively update their Terraform configurations rather than require massive refactoring.
911

‎website/docs/plugin/framework/diagnostics.mdx

+4-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,10 @@
11
---
2-
page_title: 'Plugin Development - Framework: Errors and Warnings'
3-
description: |-
4-
How to return errors and warnings from the Terraform provider development
5-
framework.
2+
page_title: Errors and warnings
3+
description: >-
4+
Learn how to return errors and warnings from the Terraform plugin framework.
65
---
76

8-
# Returning Errors and Warnings
7+
# Returning errors and warnings
98

109
Providers use `Diagnostics` to surface errors and warnings to practitioners,
1110
such as contextual messages returned from Terraform CLI at the end of

‎website/docs/plugin/framework/ephemeral-resources/close.mdx

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
page_title: 'Plugin Development - Framework: Open Ephemeral Resources'
2+
page_title: Closing ephemeral resources
33
description: >-
4-
How to implement ephemeral resource close in the provider development framework.
4+
Learn how to close ephemeral resource in the Terraform plugin framework.
55
---
66

7-
# Close Ephemeral Resources
7+
# Closing Ephemeral Resources
88

99
Close is an optional part of the Terraform lifecycle for an ephemeral resource, which is different from the [managed resource lifecycle](https://github.com/hashicorp/terraform/blob/main/docs/resource-instance-change-lifecycle.md). During any Terraform operation (like [`terraform plan`](/terraform/cli/commands/plan) or [`terraform apply`](/terraform/cli/commands/apply)), when an ephemeral resource's data is needed, Terraform initially retrieves that data with the [`Open`](/terraform/plugin/framework/ephemeral-resources/open) lifecycle handler. Once the ephemeral resource data is no longer needed, Terraform calls the provider `CloseEphemeralResource` RPC, in which the framework calls the [`ephemeral.EphemeralResourceWithClose` interface `Close` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/ephemeral#EphemeralResourceWithClose). The request contains any `Private` data set in the latest `Open` or `Renew` call.
1010

‎website/docs/plugin/framework/ephemeral-resources/configure.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Configure Ephemeral Resources'
2+
page_title: Configuring ephemeral resources
33
description: >-
4-
How to configure ephemeral resources with provider data or clients in the provider development framework.
4+
Learn how to configure ephemeral resources with provider data or clients in
5+
the Terraform plugin framework.
56
---
67

7-
# Configure Ephemeral Resources
8+
# Configuring ephemeral resources
89

910
[Ephemeral Resources](/terraform/plugin/framework/ephemeral-resources) may require provider-level data or remote system clients to operate correctly. The framework supports the ability to configure this data and/or clients once within the provider, then pass that information to ephemeral resources by adding the `Configure` method.
1011

‎website/docs/plugin/framework/ephemeral-resources/index.mdx

+5-5
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,12 @@
11
---
2-
page_title: 'Plugin Development - Framework: Ephemeral Resources'
2+
page_title: Ephemeral resources
33
description: >-
4-
How to build ephemeral resources in the provider development framework. Ephemeral
5-
resources allow Terraform to reference external data, while guaranteeing that this
6-
data will not be persisted in plan or state.
4+
Ephemeral resources allow Terraform to reference external data, while
5+
guaranteeing that this data will not be persisted in plan or state. Learn how
6+
to implement ephemeral resources in the Terraform plugin framework.
77
---
88

9-
# Ephemeral Resources
9+
# Ephemeral resources
1010

1111
<Highlight>
1212

‎website/docs/plugin/framework/ephemeral-resources/open.mdx

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
page_title: 'Plugin Development - Framework: Open Ephemeral Resources'
2+
page_title: Opening ephemeral resources
33
description: >-
4-
How to implement ephemeral resource open in the provider development framework.
4+
Learn how to open ephemeral resource in the Terraform plugin framework.
55
---
66

7-
# Open Ephemeral Resources
7+
# Opening ephemeral resources
88

99
Open is part of the Terraform lifecycle for an ephemeral resource, which is different from the [managed resource lifecycle](https://github.com/hashicorp/terraform/blob/main/docs/resource-instance-change-lifecycle.md). During any Terraform operation (like [`terraform plan`](/terraform/cli/commands/plan) or [`terraform apply`](/terraform/cli/commands/apply)), when an ephemeral resource's data is needed, Terraform calls the provider `OpenEphemeralResource` RPC, in which the framework calls the [`ephemeral.EphemeralResource` interface `Open` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/ephemeral#EphemeralResource.Open). The request contains the configuration supplied to Terraform for the ephemeral resource. The response contains the ephemeral result data. The data is defined by the [schema](/terraform/plugin/framework/handling-data/schemas) of the ephemeral resource.
1010

‎website/docs/plugin/framework/ephemeral-resources/renew.mdx

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
page_title: 'Plugin Development - Framework: Open Ephemeral Resources'
2+
page_title: Renewing ephemeral resources
33
description: >-
4-
How to implement ephemeral resource renew in the provider development framework.
4+
Learn how to renew ephemeral resource in the Terraform plugin framework.
55
---
66

7-
# Renew Ephemeral Resources
7+
# Renewing ephemeral resources
88

99
Renew is an optional part of the Terraform lifecycle for an ephemeral resource, which is different from the [managed resource lifecycle](https://github.com/hashicorp/terraform/blob/main/docs/resource-instance-change-lifecycle.md). During any Terraform operation (like [`terraform plan`](/terraform/cli/commands/plan) or [`terraform apply`](/terraform/cli/commands/apply)), when an ephemeral resource's data is needed, Terraform initially retrieves that data with the [`Open`](/terraform/plugin/framework/ephemeral-resources/open) lifecycle handler. During `Open`, ephemeral resources can opt to include a timestamp in the `RenewAt` response field to indicate to Terraform when a provider must renew an ephemeral resource. If an ephemeral resource's data is still in-use and the `RenewAt` timestamp has passed, Terraform calls the provider `RenewEphemeralResource` RPC, in which the framework calls the [`ephemeral.EphemeralResourceWithRenew` interface `Renew` method](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/ephemeral#EphemeralResourceWithRenew). The request contains any `Private` data set in the latest `Open` or `Renew` call. The response contains `Private` data and an optional `RenewAt` field for further renew executions.
1010

‎website/docs/plugin/framework/ephemeral-resources/validate-configuration.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Validate Ephemeral Resource Configurations'
2+
page_title: Validate ephemeral resource configurations
33
description: >-
4-
How to validate ephemeral resource configurations with the provider development framework.
4+
Learn how to validate ephemeral resource configurations with the Terraform
5+
plugin framework.
56
---
67

7-
# Validate Configuration
8+
# Validate ephemeral resource configurations
89

910
[Ephemeral resources](/terraform/plugin/framework/ephemeral-resources) support validating an entire practitioner configuration in either declarative or imperative logic. Feedback, such as required syntax or acceptable combinations of values, is returned via [diagnostics](/terraform/plugin/framework/diagnostics).
1011

‎website/docs/plugin/framework/functions/concepts.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Function Concepts'
2+
page_title: Provider-defined functions
33
description: >-
4-
Terraform concepts for provider-defined functions.
4+
Learn how provider-defined functions enable Terraform providers to define
5+
functions for practitions to use in their Terraform configurations.
56
---
67

7-
# Function Concepts
8+
# Provider-defined functions
89

910
This page describes Terraform concepts relating to provider-defined functions within framework-based provider code. Provider-defined functions are supported in Terraform 1.8 and later. The [What is Terraform](/terraform/intro), [Terraform language](/terraform/language), and [Plugin Development](/terraform/plugin) documentation covers more general concepts behind Terraform's workflow, its configuration, and how it interacts with providers.
1011

‎website/docs/plugin/framework/functions/documentation.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Document Functions'
2+
page_title: Documenting functions
33
description: >-
4-
How to document provider-defined functions.
4+
Learn how to document provider-defined functions with the Terraform plugin
5+
framework.
56
---
67

7-
# Document Functions
8+
# Documenting functions
89

910
When a function is [implemented](/terraform/plugin/framework/functions/implementation), ensure the function is discoverable by practitioners with usage information.
1011

‎website/docs/plugin/framework/functions/errors.mdx

+6-6
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Function Errors'
3-
description: |-
4-
How to return function errors from the Terraform provider development
5-
framework.
2+
page_title: Returning errors from functions
3+
description: >-
4+
Learn how to return errors from provider-defined functions with the Terraform
5+
plugin framework.
66
---
77

8-
# Returning Function Errors
8+
# Returning errors from function
99

1010
Providers use [`FuncError`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/function#FuncError) to
1111
surface a practitioner-facing error generated during execution of provider-defined functions. These errors are
@@ -159,4 +159,4 @@ func (f *ExampleFunction) Run(ctx context.Context, req function.RunRequest, resp
159159

160160
resp.Error = function.ConcatFuncErrors(resp.Error, function.FuncErrorFromDiags(ctx, diags))
161161
}
162-
```
162+
```

‎website/docs/plugin/framework/functions/implementation.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Implement Functions'
2+
page_title: Implement provider-defined functions
33
description: >-
4-
How to implement provider-defined functions in the provider development framework.
4+
Learn how to implement provider-defined functions with the Terraform
5+
plugin framework.
56
---
67

7-
# Implement Functions
8+
# Implement provider-defined functions
89

910
The framework supports implementing functions based on Terraform's [concepts for provider-defined functions](/terraform/plugin/framework/functions/concepts). It is recommended to understand those concepts before implementing a function since the terminology is used throughout this page and there are details that simplify function handling as compared to other provider concepts. Provider-defined functions are supported in Terraform 1.8 and later.
1011

‎website/docs/plugin/framework/functions/index.mdx

+6-5
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,13 @@
11
---
2-
page_title: 'Plugin Development - Framework: Functions'
2+
page_title: Provider-defined functions overview
33
description: >-
4-
How to build functions in the provider development framework. Provider-defined
5-
functions expose logic beyond Terraform's built-in functions and simplify
6-
practitioner configurations.
4+
Provider-defined functions expose logic beyond Terraform's built-in functions
5+
that practitioners can use to simplify Terraform configurations. Learn how the
6+
plugin framework can help you implement provider-defined functions.
77
---
88

9-
# Functions
9+
10+
# Provider-defined functions
1011

1112
Functions are an abstraction that allow providers to expose computational logic beyond Terraform's [built-in functions](/terraform/language/functions) and simplify practitioner configurations. Provider-defined functions are supported in Terraform 1.8 and later.
1213

‎website/docs/plugin/framework/functions/parameters/bool.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Bool Function Parameter'
2+
page_title: Boolean function parameters
33
description: >-
4-
Learn the bool function parameter type in the provider development framework.
4+
Learn how to use the boolean function parameter type with the Terraform
5+
plugin framework.
56
---
67

7-
# Bool Function Parameter
8+
# Boolean function parameters
89

910
Bool function parameters expect a boolean true or false value from a practitioner configuration. Values are accessible in function logic by the Go built-in `bool` type, Go built-in `*bool` type, or the [framework bool type](/terraform/plugin/framework/handling-data/types/bool).
1011

‎website/docs/plugin/framework/functions/parameters/dynamic.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Dynamic Function Parameter'
2+
page_title: Dynamic function parameters
33
description: >-
4-
Learn the dynamic function parameter type in the provider development framework.
4+
Learn how to use dynamic fynction paramters with the Terraform plugin
5+
framework.
56
---
67

7-
# Dynamic Function Parameter
8+
# Dynamic function parameters
89

910
<Tip>
1011

‎website/docs/plugin/framework/functions/parameters/float32.mdx

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
---
2-
page_title: 'Plugin Development - Framework: Float32 Function Parameter'
2+
page_title: Float32 function parameters
33
description: >-
4-
Learn the float32 function parameter type in the provider development framework.
4+
Learn how to use the 32-bit floating point function parameter type with the
5+
Terraform plugin framework.
56
---
67

78
# Float32 Function Parameter

‎website/docs/plugin/framework/functions/parameters/float64.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Float64 Function Parameter'
2+
page_title: Float64 function parameters
33
description: >-
4-
Learn the float64 function parameter type in the provider development framework.
4+
Learn how to use the 64-bit floating point function parameter type with the
5+
Terraform plugin framework.
56
---
67

7-
# Float64 Function Parameter
8+
# Float64 function parameters
89

910
<Tip>
1011

‎website/docs/plugin/framework/functions/parameters/index.mdx

+6-5
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
---
2-
page_title: 'Plugin Development - Framework: Function Parameters'
2+
page_title: Function parameters
33
description: >-
4-
Learn the function parameter types in the provider development framework.
5-
Parameters are positional data arguments in a function definition.
4+
The Terraform plugin framework includes multiple built-in function parameter
5+
types and supports dynamic parameters. Parameters are positional data
6+
arguments in a function definition.
67
---
78

8-
# Parameters
9+
# Function parameters
910

1011
Parameters in [function definitions](/terraform/plugin/framework/functions/implementation#definition-method) describes how data values are passed to the function logic. Every parameter type has an associated [value type](/terraform/plugin/framework/handling-data/types), although this data handling is simplified for function implementations over other provider concepts, such as resource implementations.
1112

@@ -126,4 +127,4 @@ func (v CustomStringValue) ValidateParameter(ctx context.Context, req function.V
126127
}
127128
```
128129

129-
Refer to [Custom Types](/terraform/plugin/framework/handling-data/types/custom) for further details on creating provider-defined types and values
130+
Refer to [Custom Types](/terraform/plugin/framework/handling-data/types/custom) for further details on creating provider-defined types and values

‎website/docs/plugin/framework/functions/parameters/int32.mdx

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
11
---
2-
page_title: 'Plugin Development - Framework: Int32 Function Parameter'
2+
page_title: Int32 function parameters
33
description: >-
4-
Learn the int32 function parameter type in the provider development framework.
4+
Learn how to use the 32-bit integer function parameter type with the
5+
Terraform plugin framework.
56
---
67

7-
# Int32 Function Parameter
8+
# Int32 function parameters
89

910
<Tip>
1011

0 commit comments

Comments
 (0)