Terraform Plugin Framework

The framework provides two ways to think about schemas:

1. tfprotov6.Schema: The underlying type used by the Terraform plugin-go ecosystem. It is highly verbose and requires manual management of Block fields and SchemaAttribute slices.
2. framework.Schema (Proposed/Conceptual): A higher-level, less verbose wrapper. It uses Go maps where keys are the attribute or block names, reducing boilerplate. It handles defaults for fields like DescriptionKind and simplifies nested block definitions using a NestedBlockType.

Key benefits of the framework-specific schema approach:

• Reduced Verbosity: Uses map keys for names instead of explicit Name fields.
• Discoverability: Types are documented within the framework rather than requiring external tftypes or tfprotov6 imports.
• Abstraction: Hides the complexity of Terraform protocol version changes (e.g., moving from v5 to v6) from the provider developer.

The Terraform Plugin Framework handles diagnostics (errors and warnings) using a dedicated interface-based approach rather than extending the standard Go error interface.

This design choice is made to:

1. Avoid semantic ambiguity: Extending the error interface would force warnings to be treated as errors by standard Go error handling, which is undesirable.
2. Maintain framework ownership: By using a custom interface, the framework can own the abstraction and provide ergonomic methods (like Severity(), Summary(), and Detail()) without the constraints or verbosity of the standard error package requirements.
3. Support extensibility: Using interfaces allows for specialized diagnostic types (e.g., ValidationErrorDiagnostic) that can implement additional capabilities, such as logging or path attribution, while remaining compatible with the core Diagnostic interface.

The framework's architecture can be conceptualized through three implementation patterns. While the actual framework implementation is specific, these patterns illustrate the different ways a developer might interact with the API surface:

1. Pure Struct Pattern

In this pattern, resources and providers are defined as structs containing function fields. This treats the resource as a collection of behaviors (functions) assigned to a value.

2. Pure Interface Pattern

In this pattern, resources and providers are defined as interfaces. This treats the resource as a type that must satisfy a specific contract of methods (e.g., Create, Read, Update, Delete).

3. Mixed Pattern

This pattern uses structs for state and configuration, but delegates core logic to an interface (e.g., a ResourceImplementation interface). This allows for a combination of structured data and polymorphic behavior.

// Example of the Mixed Pattern approach
type Resource struct {
	Schema                *tfprotov5.Schema
	Implementation        func(p ProviderState) ResourceImplementation
}

type ResourceImplementation interface {
	Create(context.Context) []*tfprotov5.Diagnostic
	Read(context.Context) []*tfprotov5.Diagnostic
	Update(context.Context) []*tfprotov5.Diagnostic
	Destroy(context.Context) []*tfprotov5.Diagnostic
}

Data Source level validation can be implemented using two patterns:

1. Declarative Validation: Implement the DataSourceWithConfigValidators interface by providing a ConfigValidators(context.Context) []DataSourceConfigValidator method. This is used for reusable, predefined validation rules (like ConflictingAttributes).
2. Imperative Validation: Implement the DataSourceWithValidateConfig interface by providing a ValidateConfig(context.Context, ValidateDataSourceConfigRequest, *ValidateDataSourceConfigResponse) method. This is used for complex, custom logic that cannot be expressed declaratively.

Validation requests (ValidateDataSourceConfigRequest) provide access to the tfsdk.Config and the TypeName of the data source.

// Declarative approach
func (d *customDataSource) ConfigValidators(ctx context.Context) DataSourceConfigValidators {
    return DataSourceConfigValidators{
        ConflictingAttributes(
            tftypes.NewAttributePath().AttributeName("first_attribute"),
            tftypes.NewAttributePath().AttributeName("second_attribute"),
        ),
    }
}

Resource import is the process of bringing existing, unmanaged resources under Terraform's management by creating their corresponding state in the Terraform statefile.

When a user executes the terraform import command, the Terraform CLI forwards a request to the provider containing a resource address (parsed into a type_name) and an import identifier (id). The provider is responsible for responding with the relevant resource state(s).

Terraform supports two main interaction patterns:

1. 1:1 Import: A single resource address maps to a single resource state. This is the most common pattern.
2. Multiple Resource Import: A single import command can trigger the import of multiple related resources (e.g., importing an S3 bucket also importing its bucket policy). These secondary resources are saved into the state using the same identifier or as indexed resources (e.g., resource.name[0]).

# Example of a 1:1 import command
terraform import aws_security_group.example sg-12345678