Implement Terraform Provider resources and data sources using the Plugin Framework. Use when developing CRUD operations, schema design, state management, and acceptance testing for provider resources.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Implement Terraform Provider resources and data sources using the Plugin Framework. Use when developing CRUD operations, schema design, state management, and acceptance testing for provider resources.
metadata
{"copyright":"Copyright IBM Corp. 2026","version":"0.0.1"}
Terraform Provider Resources Implementation Guide
Overview
This guide covers developing Terraform Provider resources and data sources using the Terraform Plugin Framework. Resources represent infrastructure objects that Terraform manages through Create, Read, Update, and Delete (CRUD) operations.
func(r *resourceExample) Read(ctx context.Context, req resource.ReadRequest, resp *resource.ReadResponse) {
var data resourceExampleModel
resp.Diagnostics.Append(req.State.Get(ctx, &data)...)
if resp.Diagnostics.HasError() {
return
}
conn := r.Meta().ExampleClient(ctx)
output, err := findExampleByID(ctx, conn, data.ID.ValueString())
if tfresource.NotFound(err) {
resp.Diagnostics.AddWarning(
"Resource not found",
fmt.Sprintf("Example %s not found, removing from state", data.ID.ValueString()),
)
resp.State.RemoveResource(ctx)
return
}
if err != nil {
resp.Diagnostics.AddError(
"Error reading Example",
fmt.Sprintf("Could not read example %s: %s", data.ID.ValueString(), err),
)
return
}
data.Name = types.StringPointerValue(output.Name)
data.ARN = types.StringPointerValue(output.Arn)
resp.Diagnostics.Append(resp.State.Set(ctx, &data)...)
}
Update Operation
func(r *resourceExample) Update(ctx context.Context, req resource.UpdateRequest, resp *resource.UpdateResponse) {
var plan, state resourceExampleModel
resp.Diagnostics.Append(req.Plan.Get(ctx, &plan)...)
resp.Diagnostics.Append(req.State.Get(ctx, &state)...)
if resp.Diagnostics.HasError() {
return
}
conn := r.Meta().ExampleClient(ctx)
if !plan.Description.Equal(state.Description) {
input := &example.UpdateExampleInput{
Id: plan.ID.ValueStringPointer(),
Description: plan.Description.ValueStringPointer(),
}
_, err := conn.UpdateExample(ctx, input)
if err != nil {
resp.Diagnostics.AddError(
"Error updating Example",
fmt.Sprintf("Could not update example %s: %s", plan.ID.ValueString(), err),
)
return
}
}
resp.Diagnostics.Append(resp.State.Set(ctx, &plan)...)
}
Delete Operation
func(r *resourceExample) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
var data resourceExampleModel
resp.Diagnostics.Append(req.State.Get(ctx, &data)...)
if resp.Diagnostics.HasError() {
return
}
conn := r.Meta().ExampleClient(ctx)
_, err := conn.DeleteExample(ctx, &example.DeleteExampleInput{
Id: data.ID.ValueStringPointer(),
})
if tfresource.NotFound(err) {
return
}
if err != nil {
resp.Diagnostics.AddError(
"Error deleting Example",
fmt.Sprintf("Could not delete example %s: %s", data.ID.ValueString(), err),
)
return
}
}
Schema Design
Attribute Types
Terraform Type
Framework Type
Use Case
string
schema.StringAttribute
Names, ARNs, IDs
number
schema.Int64Attribute, schema.Float64Attribute
Counts, sizes
bool
schema.BoolAttribute
Feature flags
list
schema.ListAttribute
Ordered collections
set
schema.SetAttribute
Unordered unique items
map
schema.MapAttribute
Key-value pairs
object
schema.SingleNestedAttribute
Complex nested config
Plan Modifiers
// Force replacement when value changes
stringplanmodifier.RequiresReplace()
// Preserve unknown value during plan
stringplanmodifier.UseStateForUnknown()
// Custom plan modifier
stringplanmodifier.RequiresReplaceIf(
func(ctx context.Context, req planmodifier.StringRequest, resp *stringplanmodifier.RequiresReplaceIfFuncResponse) {
// Custom logic
},
"description",
"markdown description",
)
Validators
// String validators
stringvalidator.LengthBetween(1, 255)
stringvalidator.RegexMatches(regexp.MustCompile(`^[a-z0-9-]+$`), "must be lowercase alphanumeric with hyphens")
stringvalidator.OneOf("option1", "option2", "option3")
// Int64 validators
int64validator.Between(1, 100)
int64validator.AtLeast(1)
int64validator.AtMost(1000)
// List validators
listvalidator.SizeAtLeast(1)
listvalidator.SizeAtMost(10)
functestAccCheckExampleExists(ctx context.Context, name string) resource.TestCheckFunc {
returnfunc(s *terraform.State)error {
rs, ok := s.RootModule().Resources[name]
if !ok {
return fmt.Errorf("Not found: %s", name)
}
conn := acctest.Provider.Meta().(*conns.Client).ExampleClient(ctx)
_, err := findExampleByID(ctx, conn, rs.Primary.ID)
return err
}
}
functestAccCheckExampleDestroy(ctx context.Context) resource.TestCheckFunc {
returnfunc(s *terraform.State)error {
conn := acctest.Provider.Meta().(*conns.Client).ExampleClient(ctx)
for _, rs := range s.RootModule().Resources {
if rs.Type != "provider_example" {
continue
}
_, err := findExampleByID(ctx, conn, rs.Primary.ID)
if tfresource.NotFound(err) {
continue
}
if err != nil {
return err
}
return fmt.Errorf("Example %s still exists", rs.Primary.ID)
}
returnnil
}
}
Running Tests
# Compile tests
go test -c -o /dev/null ./internal/service/<service>
# Run acceptance tests
TF_ACC=1 go test ./internal/service/<service> -run TestAccExample -v -timeout 60m
# Run with specific provider version
TF_ACC=1 go test ./internal/service/<service> -run TestAccExample -v
# Run sweeper to clean up
TF_ACC=1 go test ./internal/service/<service> -sweep=<region> -v
Error Handling
Common Error Patterns
// Handle specific API errorsvar notFound *types.ResourceNotFoundException
if errors.As(err, ¬Found) {
// Resource doesn't exist
}
var conflict *types.ConflictException
if errors.As(err, &conflict) {
// Resource state conflict
}
var throttle *types.ThrottlingException
if errors.As(err, &throttle) {
// Rate limited - SDK handles retry
}
Diagnostics
// Add error
resp.Diagnostics.AddError(
"Error creating resource",
fmt.Sprintf("Could not create resource: %s", err),
)
// Add warning
resp.Diagnostics.AddWarning(
"Resource modified outside Terraform",
"Resource was modified outside of Terraform, state may be inconsistent",
)
// Add attribute error
resp.Diagnostics.AddAttributeError(
path.Root("name"),
"Invalid name",
"Name must be lowercase alphanumeric",
)
Documentation Standards
Resource Documentation
---
subcategory: "Service Name"
layout: "provider"
page_title: "Provider: provider_example"
description: |-
Manages an Example resource.
---# Resource: provider_example
Manages an Example resource.
## Example Usage
### Basic Usage
\```hcl
resource "provider_example" "example" {
name = "my-example"
}
\```
## Argument Reference
* `name` - (Required) Name of the example.
* `description` - (Optional) Description of the example.
## Attribute Reference
* `id` - ID of the example.
* `arn` - ARN of the example.
## Import
Example can be imported using the ID:
\```
$ terraform import provider_example.example example-id-12345
\```
