Skip to content

Commit

Permalink
Update docs titles and descriptions for SEO and style guide
Browse files Browse the repository at this point in the history
  • Loading branch information
robin-norwood committed Dec 13, 2024
1 parent 4260861 commit 8224e21
Show file tree
Hide file tree
Showing 134 changed files with 506 additions and 418 deletions.
9 changes: 5 additions & 4 deletions website/docs/plugin/framework/acctests.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
---
page_title: 'Plugin Development - Framework: Acceptance Tests'
page_title: Acceptance tests
description: >-
How to write acceptance tests for providers built on the framework. Acceptance
tests imitate applying configuration files.
Learn how to write acceptance tests for providers built on the framework.
Acceptance tests help ensure your provider works as expected by imitating
Terraform operations.
---

# Acceptance Tests
# Acceptance tests

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.

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/data-sources/configure.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Configure Data Sources'
page_title: Configure data sources
description: >-
How to configure data sources with provider data or clients in the provider development framework.
Learn how to configure data sources with provider data or clients in the
Terraform provider framework.
---

# Configure Data Sources
# Configure data sources

[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.

Expand Down
8 changes: 4 additions & 4 deletions website/docs/plugin/framework/data-sources/index.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
page_title: 'Plugin Development - Framework: Data Sources'
page_title: Data sources
description: >-
How to build data sources in the provider development framework. Data sources
allow Terraform to reference external data.
Data sources allow Terraform to reference external data. Learn how the
provider framework can help you implement data sources.
---

# Data Sources
# Data sources

[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.

Expand Down
4 changes: 2 additions & 2 deletions website/docs/plugin/framework/data-sources/timeouts.mdx
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
page_title: 'Plugin Development - Framework: Timeouts'
page_title: Timeouts
description: >-
How to use timeouts with the provider development framework.
Learn how to implement timeouts with the Terraform provider framework.
---

# Timeouts
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Validate Data Source Configurations'
page_title: Validate data source configurations
description: >-
How to validate data source configurations with the provider development framework.
Learn how to validate data source configurations with the Terraform provider
framework.
---

# Validate Configuration
# Validate data source configurations

[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).

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/debugging.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
---
page_title: Plugin Development - Debugging Framework Providers
description: How to implement debugger support in Framework Terraform providers.
page_title: Debugging framework providers
description: >-
Learn how to implement debugger support in framework Terraform providers.
---

# Debugging Framework Providers
# Debugging framework Providers

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.

Expand Down
8 changes: 5 additions & 3 deletions website/docs/plugin/framework/deprecations.mdx
Original file line number Diff line number Diff line change
@@ -1,9 +1,11 @@
---
page_title: 'Plugin Development - Deprecations, Removals, and Renames Best Practices'
description: 'Recommendations for deprecations, removals, and renames.'
page_title: Deprecations, removals, and renames
description:
Use the following recommendations to handle deprecations, removals, and
renames in framework providers.
---

# Deprecations, Removals, and Renames
# Deprecations, removals, and renames

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.

Expand Down
9 changes: 4 additions & 5 deletions website/docs/plugin/framework/diagnostics.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,10 @@
---
page_title: 'Plugin Development - Framework: Errors and Warnings'
description: |-
How to return errors and warnings from the Terraform provider development
framework.
page_title: Errors and warnings
description: >-
Learn how to return errors and warnings from the Terraform provider framework.
---

# Returning Errors and Warnings
# Returning errors and warnings

Providers use `Diagnostics` to surface errors and warnings to practitioners,
such as contextual messages returned from Terraform CLI at the end of
Expand Down
6 changes: 3 additions & 3 deletions website/docs/plugin/framework/ephemeral-resources/close.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
page_title: 'Plugin Development - Framework: Open Ephemeral Resources'
page_title: Closing ephemeral resources
description: >-
How to implement ephemeral resource close in the provider development framework.
Learn how to close ephemeral resource in the Terraform provider framework.
---

# Close Ephemeral Resources
# Closing Ephemeral Resources

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.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Configure Ephemeral Resources'
page_title: Configuring ephemeral resources
description: >-
How to configure ephemeral resources with provider data or clients in the provider development framework.
Learn how to configure ephemeral resources with provider data or clients in
the Terraform provider framework.
---

# Configure Ephemeral Resources
# Configuring ephemeral resources

[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.

Expand Down
10 changes: 5 additions & 5 deletions website/docs/plugin/framework/ephemeral-resources/index.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
---
page_title: 'Plugin Development - Framework: Ephemeral Resources'
page_title: Ephemeral resources
description: >-
How to build ephemeral resources in the provider development framework. Ephemeral
resources allow Terraform to reference external data, while guaranteeing that this
data will not be persisted in plan or state.
Ephemeral resources allow Terraform to reference external data, while
guaranteeing that this data will not be persisted in plan or state. Learn how
to implement ephemeral resources in the Terraform provider framework.
---

# Ephemeral Resources
# Ephemeral resources

<Highlight>

Expand Down
6 changes: 3 additions & 3 deletions website/docs/plugin/framework/ephemeral-resources/open.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
page_title: 'Plugin Development - Framework: Open Ephemeral Resources'
page_title: Opening ephemeral resources
description: >-
How to implement ephemeral resource open in the provider development framework.
Learn how to open ephemeral resource in the Terraform provider framework.
---

# Open Ephemeral Resources
# Opening ephemeral resources

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.

Expand Down
6 changes: 3 additions & 3 deletions website/docs/plugin/framework/ephemeral-resources/renew.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
---
page_title: 'Plugin Development - Framework: Open Ephemeral Resources'
page_title: Renewing ephemeral resources
description: >-
How to implement ephemeral resource renew in the provider development framework.
Learn how to renew ephemeral resource in the Terraform provider framework.
---

# Renew Ephemeral Resources
# Renewing ephemeral resources

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.

Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Validate Ephemeral Resource Configurations'
page_title: Validate ephemeral resource configurations
description: >-
How to validate ephemeral resource configurations with the provider development framework.
Learn how to validate ephemeral resource configurations with the Terraform
provider framework.
---

# Validate Configuration
# Validate ephemeral resource configurations

[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).

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/functions/concepts.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Function Concepts'
page_title: Provider-defined functions
description: >-
Terraform concepts for provider-defined functions.
Learn how provider-defined functions enable Terraform providers to define
functions for practitions to use in their Terraform configurations.
---

# Function Concepts
# Provider-defined functions

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.

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/functions/documentation.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Document Functions'
page_title: Documenting functions
description: >-
How to document provider-defined functions.
Learn how to document provider-defined functions with the Terraform provider
framework.
---

# Document Functions
# Documenting functions

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

Expand Down
10 changes: 5 additions & 5 deletions website/docs/plugin/framework/functions/errors.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
page_title: 'Plugin Development - Framework: Function Errors'
description: |-
How to return function errors from the Terraform provider development
framework.
page_title: Returning errors from functions
description: >-
Learn how to return errors from provider-defined functions with the Terraform
provider framework.
---

# Returning Function Errors
# Returning errors from function

Providers use [`FuncError`](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/function#FuncError) to
surface a practitioner-facing error generated during execution of provider-defined functions. These errors are
Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/functions/implementation.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Implement Functions'
page_title: Implement provider-defined functions
description: >-
How to implement provider-defined functions in the provider development framework.
Learn how to implement provider-defined functions with the Terraform
provider framework.
---

# Implement Functions
# Implement provider-defined functions

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.

Expand Down
11 changes: 6 additions & 5 deletions website/docs/plugin/framework/functions/index.mdx
Original file line number Diff line number Diff line change
@@ -1,12 +1,13 @@
---
page_title: 'Plugin Development - Framework: Functions'
page_title: Provider-defined functions overview
description: >-
How to build functions in the provider development framework. Provider-defined
functions expose logic beyond Terraform's built-in functions and simplify
practitioner configurations.
Provider-defined functions expose logic beyond Terraform's built-in functions
that practitioners can use to simplify Terraform configurations. Learn how the
provider framework can help you implement provider-defined functions.
---

# Functions

# Provider-defined functions

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.

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/functions/parameters/bool.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Bool Function Parameter'
page_title: Boolean function parameters
description: >-
Learn the bool function parameter type in the provider development framework.
Learn how to use the boolean function parameter type with the Terraform
provider framework.
---

# Bool Function Parameter
# Boolean function parameters

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).

Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Dynamic Function Parameter'
page_title: Dynamic function parameters
description: >-
Learn the dynamic function parameter type in the provider development framework.
Learn how to use dynamic fynction paramters with the Terraform provider
framework.
---

# Dynamic Function Parameter
# Dynamic function parameters

<Tip>

Expand Down
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
---
page_title: 'Plugin Development - Framework: Float32 Function Parameter'
page_title: Float32 function parameters
description: >-
Learn the float32 function parameter type in the provider development framework.
Learn how to use the 32-bit floating point function parameter type with the
Terraform provider framework.
---

# Float32 Function Parameter
Expand Down
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Float64 Function Parameter'
page_title: Float64 function parameters
description: >-
Learn the float64 function parameter type in the provider development framework.
Learn how to use the 64-bit floating point function parameter type with the
Terraform provider framework.
---

# Float64 Function Parameter
# Float64 function parameters

<Tip>

Expand Down
9 changes: 5 additions & 4 deletions website/docs/plugin/framework/functions/parameters/index.mdx
Original file line number Diff line number Diff line change
@@ -1,11 +1,12 @@
---
page_title: 'Plugin Development - Framework: Function Parameters'
page_title: Function parameters
description: >-
Learn the function parameter types in the provider development framework.
Parameters are positional data arguments in a function definition.
The Terraform provider framework includes multiple built-in function parameter
types and supports dynamic parameters. Parameters are positional data
arguments in a function definition.
---

# Parameters
# Function parameters

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.

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/functions/parameters/int32.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Int32 Function Parameter'
page_title: Int32 function parameters
description: >-
Learn the int32 function parameter type in the provider development framework.
Learn how to use the 32-bit integer function parameter type with the
Terraform provider framework.
---

# Int32 Function Parameter
# Int32 function parameters

<Tip>

Expand Down
7 changes: 4 additions & 3 deletions website/docs/plugin/framework/functions/parameters/int64.mdx
Original file line number Diff line number Diff line change
@@ -1,10 +1,11 @@
---
page_title: 'Plugin Development - Framework: Int64 Function Parameter'
page_title: Int64 function parameters
description: >-
Learn the int64 function parameter type in the provider development framework.
Learn how to use the 64-bit integer function parameter type with the
Terraform provider framework.
---

# Int64 Function Parameter
# Int32 function parameters

<Tip>

Expand Down
Loading

0 comments on commit 8224e21

Please sign in to comment.