website: Further clarify configuration validation and when API access…

… is available (#586)

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

@@ -13,6 +13,8 @@ This page describes implementation details for validating entire data source con
 - [Single attribute validation](/plugin/framework/validation#attribute-validation) is a schema-based mechanism for implementing attribute-specific validation logic.
 - [Type validation](/plugin/framework/validation#type-validation) is a schema-based mechanism for implementing reusable validation logic for any attribute using the type.
 
+-> Configuration validation in Terraform occurs without provider configuration ("offline"), so therefore the data source `Configure` method will not have been called. To implement validation with a configured API client, use logic within the `Read` method, which occurs during Terraform's planning phase when possible.
+
 ## ConfigValidators Method
 
 The [`datasource.DataSourceWithConfigValidators` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#DataSourceWithConfigValidators) follows a similar pattern to attribute validation and allows for a more declarative approach. This enables consistent validation logic across multiple data sources. Each validator intended for this interface must implement the [`datasource.ConfigValidator` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/datasource#ConfigValidator).
@@ -76,4 +78,4 @@ func (d ThingDataSource) ValidateConfig(ctx context.Context, req datasource.Vali
             "The data source may return unexpected results.",
     )
 }
-```
+```

website/docs/plugin/framework/providers/validate-configuration.mdx

@@ -13,6 +13,8 @@ This page describes implementation details for validating entire provider config
 - [Single attribute validation](/plugin/framework/validation#attribute-validation) is a schema-based mechanism for implementing attribute-specific validation logic.
 - [Type validation](/plugin/framework/validation#type-validation) is a schema-based mechanism for implementing reusable validation logic for any attribute using the type.
 
+-> Configuration validation in Terraform occurs without provider configuration ("offline"), so therefore the provider `Configure` method will not have been called. To implement validation with a configured API client, use logic within the `Configure` method, which occurs during Terraform's planning phase.
+
 ## ConfigValidators Method
 
 The [`provider.ProviderWithConfigValidators` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/provider#ProviderWithConfigValidators) follows a similar pattern to attribute validation and allows for a more declarative approach. This enables consistent validation logic across multiple providers. Each validator intended for this interface must implement the [`provider.ConfigValidator` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/provider#ConfigValidator).

website/docs/plugin/framework/resources/plan-modification.mdx

@@ -7,28 +7,28 @@ description: >-
 
 # Plan Modification
 
-After [validation](/plugin/framework/validation) and before applying configuration changes, Terraform generates a plan that describes the expected values and behaviors of those changes. Providers can then tailor the plan to match the expected end state. For example, they may replace unknown values with expected known values or mark a resource that must be replaced. Users can perform this plan modification for an attribute or an entire resource.
+After [validation](/plugin/framework/validation) and before applying configuration changes, Terraform generates a plan that describes the expected values and behaviors of those changes. Resources can then tailor the plan to match the expected end state, prevent errant in-place updates, or return any [diagnostics](/plugin/framework/diagnostics).
 
-## Plan Modification Process
-
-Terraform and the framework support three types of plan modification on resources:
+Terraform and the framework support multiple types of plan modification on resources:
 
-- Adjusting attribute values, such as providing a known remote default value when a configuration is not present.
+- Adjusting unknown attribute values, such as providing a known remote default value when a configuration is not present.
 - Marking resources that should be replaced, such as when an in-place update is not supported for a change.
-- Returning warning or error diagnostics on planned resource destruction with Terraform 1.3 and later.
+- Returning warning or error diagnostics on planned resource creation, update, or deletion.
+
+Plan modification can be added on resource schema attributes or an entire resource. Use resource-based plan modification if access to the [configured resource](/plugin/framework/resources/configure) is necessary.
+
+## Plan Modification Process
 
 When the provider receives a request to generate the plan for a resource change via the framework, the following occurs:
 
 1. If the plan differs from the current resource state, the framework marks computed attributes that are null in the configuration as unknown in the plan. This is intended to prevent unexpected Terraform errors. Providers can later enter any values that may be known.
-1. Apply attribute plan modifiers.
-1. Apply resource plan modifiers.
+1. Run attribute plan modifiers.
+1. Run resource plan modifiers.
 
 When the `Resource` interface `Update` method runs to apply a change, all attribute state values must match their associated planned values or Terraform will generate a `Provider produced inconsistent result` error. You can mark values as [unknown](/plugin/framework/types#unknown) in the plan if the full expected value is not known.
 
 Refer to the [Resource Instance Change Lifecycle document](https://github.com/hashicorp/terraform/blob/main/docs/resource-instance-change-lifecycle.md) for more details about the concepts and processes relevant to the plan and apply workflows.
 
-~> **NOTE:** Providers and data sources do not use the same planning mechanism as resources within Terraform. Neither support the concept of plan modification. Data sources should set any planned values in the `Read` method.
-
 ## Attribute Plan Modification
 
 You can supply the attribute type `PlanModifiers` field with a list of plan modifiers for that attribute. For example:
@@ -79,11 +79,11 @@ func (m stringDefaultModifier) MarkdownDescription(ctx context.Context) string {
     return fmt.Sprintf("If value is not configured, defaults to `%s`", m.Default)
 }
 
-// Modify runs the logic of the plan modifier.
+// PlanModifyString runs the logic of the plan modifier.
 // Access to the configuration, plan, and state is available in `req`, while
 // `resp` contains fields for updating the planned value, triggering resource
 // replacement, and returning diagnostics.
-func (m stringDefaultModifier) ModifyString(ctx context.Context, req planmodifier.StringRequest, resp *planmodifier.StringResponse) {
+func (m stringDefaultModifier) PlanModifyString(ctx context.Context, req planmodifier.StringRequest, resp *planmodifier.StringResponse) {
     // If the value is unknown or known, do not set default value.
     if !req.PlanValue.IsNull() {
         return

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

@@ -13,6 +13,8 @@ This page describes implementation details for validating entire resource config
 - [Single attribute validation](/plugin/framework/validation#attribute-validation) is a schema-based mechanism for implementing attribute-specific validation logic.
 - [Type validation](/plugin/framework/validation#type-validation) is a schema-based mechanism for implementing reusable validation logic for any attribute using the type.
 
+-> Configuration validation in Terraform occurs without provider configuration ("offline"), so therefore the resource `Configure` method will not have been called. To implement validation with a configured API client, use [plan modification](/plugin/framework/resources/plan-modification#resource-plan-modification) instead, which occurs during Terraform's planning phase.
+
 ## ConfigValidators Method
 
 The [`resource.ResourceWithConfigValidators` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ResourceWithConfigValidators) follows a similar pattern to attribute validation and allows for a more declarative approach. This enables consistent validation logic across multiple resources. Each validator intended for this interface must implement the [`resource.ConfigValidator` interface](https://pkg.go.dev/github.com/hashicorp/terraform-plugin-framework/resource#ConfigValidator).