Implement Create and Read with the Terraform Plugin Framework

The Terraform Plugin Framework is a new way to develop Terraform plugins. It has features that were missing from the Terraform Plugin SDKv2, including the ability to:

• determine whether a value was set in the config, the state, or the plan.
• determine whether a value is null, unknown, or the empty value.
• have structured types like objects.
• natively use nested attributes.

In this tutorial, you will add create and read functionality to a provider for a fictional coffee shop app (HashiCups), using the Terraform Plugin Framework. First, you will review the provider and resource schema to understand how providers can use the plugin framework to map Go structs to schema attributes. Then, you will explore the steps associated with creating and reading a resource before implementing it yourself. Finally, you will test the provider.

The HashiCups API has unprotected endpoints that let you list all coffees and ingredients for a particular coffee. Once authenticated, you can create, read, update, and delete (CRUD) orders. The HashiCups provider interfaces with the HashiCups REST API through a GoLang client library. This allows you to manage HashiCups orders through Terraform.

»Prerequisites

For this tutorial, you will need:

• Go 1.16+ installed and configured. the
• Terraform v1.0.3+ installed locally.
• Docker and Docker Compose to run an instance of HashiCups locally.
• jq installed.

»Set up your development environment

Clone the boilerplate branch of the Terraform HashiCups (plugin-framework) Provider repository. This serves as the boilerplate for your provider workspace.

$ git clone --branch boilerplate https://github.com/hashicorp/terraform-provider-hashicups-pf

$ git clone --branch boilerplate https://github.com/hashicorp/terraform-provider-hashicups-pf

Change into the cloned repository.

$ cd terraform-provider-hashicups-pf

$ cd terraform-provider-hashicups-pf

»Start HashiCups locally

The HashiCups provider requires a running instance of HashiCups. Navigate to the docker_compose directory.

$ cd docker_compose

$ cd docker_compose

Run docker-compose up to spin up a local instance of HashiCups on port 19090.

$ docker-compose up

$ docker-compose up

Leave this process running in your terminal window. This will contain HashiCups' log messages.

In another terminal window, verify that HashiCups is running by sending a request to its health check endpoint.

$ curl localhost:19090/health
ok

$ curl localhost:19090/health
ok

»Create HashiCups user

HashiCups requires a username and password to generate an JSON web token (JWT) which is used to authenticate against protected endpoints. You will use this user to authenticate to the HashiCups provider to manage your orders.

Create a user on HashiCups named education with the password test123.

$ curl -X POST localhost:19090/signup -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU"}

$ curl -X POST localhost:19090/signup -d '{"username":"education", "password":"test123"}'
{"UserID":1,"Username":"education","token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU"}

Set the HASHICUPS_TOKEN environment variable to the token you retrieved from invoking the /signup endpoint. You will use this later in the tutorial to verify that Terraform has created your HashiCups order.

$ export HASHICUPS_TOKEN=ey...

$ export HASHICUPS_TOKEN=ey...

The terminal containing your HashiCups logs will record the sign up operation.

api_1  | 2020-12-10T09:19:50.601Z [INFO]  Handle User | signup

api_1  | 2020-12-10T09:19:50.601Z [INFO]  Handle User | signup

Now that the HashiCups app is running, you are ready to start working on the Terraform provider.

»Explore the HashiCups provider

Navigate out of the docker_compose directory.

$ cd ..

$ cd ..

Open the main.go file. The main function imports the hashicups package and the terraform-plugin-framework/tfsdk package. The tfsdk package allows Terraform to communicate with the provider.

package main

import (
    "context"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "terraform-provider-hashicups/hashicups"
)

func main() {
    tfsdk.Serve(context.Background(), hashicups.New, tfsdk.ServeOpts{
        Name: "hashicups",
    })
}

package main

import (
    "context"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "terraform-provider-hashicups/hashicups"
)

func main() {
    tfsdk.Serve(context.Background(), hashicups.New, tfsdk.ServeOpts{
        Name: "hashicups",
    })
}

Open hashicups/provider.go.

First, the provider calls the New function to call an instance of the provider. Notice that this file also defines a provider struct with a client. Like SDKv2, Terraform providers should interface with an API client instead of directly submitting requests to the API.

package hashicups

import (
    "context"
    "os"

    "github.com/hashicorp-demoapp/hashicups-client-go"
    "github.com/hashicorp/terraform-plugin-framework/diag"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "github.com/hashicorp/terraform-plugin-framework/types"
)

var stderr = os.Stderr

func New() tfsdk.Provider {
    return &provider{}
}

type provider struct {
    configured bool
    client     *hashicups.Client
}

package hashicups

import (
    "context"
    "os"

    "github.com/hashicorp-demoapp/hashicups-client-go"
    "github.com/hashicorp/terraform-plugin-framework/diag"
    "github.com/hashicorp/terraform-plugin-framework/tfsdk"
    "github.com/hashicorp/terraform-plugin-framework/types"
)

var stderr = os.Stderr

func New() tfsdk.Provider {
    return &provider{}
}

type provider struct {
    configured bool
    client     *hashicups.Client
}

Next, the provider defines a schema that Terraform will use to configure the HashiCups API client. The providerData struct maps these schema attributes to Go-friendly values.

// GetSchema
func (p *provider) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "host": {
                Type:     types.StringType,
                Optional: true,
                Computed: true,
            },
            "username": {
                Type:     types.StringType,
                Optional: true,
                Computed: true,
            },
            "password": {
                Type:      types.StringType,
                Optional:  true,
                Computed:  true,
                Sensitive: true,
            },
        },
    }, nil
}

// Provider schema struct
type providerData struct {
    Username types.String `tfsdk:"username"`
    Host     types.String `tfsdk:"host"`
    Password types.String `tfsdk:"password"`
}

// GetSchema
func (p *provider) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "host": {
                Type:     types.StringType,
                Optional: true,
                Computed: true,
            },
            "username": {
                Type:     types.StringType,
                Optional: true,
                Computed: true,
            },
            "password": {
                Type:      types.StringType,
                Optional:  true,
                Computed:  true,
                Sensitive: true,
            },
        },
    }, nil
}

// Provider schema struct
type providerData struct {
    Username types.String `tfsdk:"username"`
    Host     types.String `tfsdk:"host"`
    Password types.String `tfsdk:"password"`
}

»Review the Configure function

The Configure function configures the API client and adds it to the provider.

func (p *provider) Configure(ctx context.Context, req tfsdk.ConfigureProviderRequest, resp *tfsdk.ConfigureProviderResponse) {
##...

func (p *provider) Configure(ctx context.Context, req tfsdk.ConfigureProviderRequest, resp *tfsdk.ConfigureProviderResponse) {
##...

The func (p*provider) sets the reference data for your provider as variable p. The function takes three arguments:

1. ctx context.Context is part of Go's standard library and commonly used to make API requests.
2. req tfsdk.ConfigureProviderRequest represents the request Terraform sends to the provider during the Configure step. It is a required request struct in the tfsdk library and specifies the values from a Terraform configuration block, along with other runtime information from Terraform.
3. resp *tfsdk.ConfigureProviderResponse represents the response from the provider. It is a required response struct. You can use this to return error and warning messages.

The Configure function performs the following steps:

1. Retrieves the provider data from the configuration. First, it creates a variable named config to hold the provider data defined by the providerData struct. Then, the provider data is retrieved from the configuration and written to the config variable with req.Config.Get(ctx, &config). If the provider is unable to retrieve provider data from the configuration, it will throw an error when you try to initialize the provider. This code ensures that error is returned in the response.

   // Retrieve provider data from configuration
   var config providerData
   diags := req.Config.Get(ctx, &config)
   resp.Diagnostics.Append(diags...)
   if resp.Diagnostics.HasError() {
     return
   }
   

   hashicups/provider.go

   // Retrieve provider data from configuration
   var config providerData
   diags := req.Config.Get(ctx, &config)
   resp.Diagnostics.Append(diags...)
   if resp.Diagnostics.HasError() {
     return
   }
   

2. Validates whether the username, password, or host exists. The provider checks if username is not configured in the Terraform configuration or in an environment variable. The provider returns an error if the value is unknown. Then, the provider tries to retrieve the value from an environment variable or from your Terraform configuration. If this value is a null value or an empty string, the provider will return with a diagnostic error. The provider repeats this process for the password and host attributes.

   // User must provide a user to the provider
   var username string
   if config.Username.Unknown {
     // Cannot connect to client with an unknown value
     resp.Diagnostics.AddWarning(
       "Unable to create client",
       "Cannot use unknown value as username",
     )
     return
   }
   
   if config.Username.Null {
     username = os.Getenv("HASHICUPS_USERNAME")
   } else {
       username = config.Username.Value
   }
   
   if username == "" {
     // Error vs warning - empty value must stop execution
       resp.Diagnostics.AddError(
       "Unable to find username",
       "Username cannot be an empty string",
     )
     return
   }
   ##...
   

   hashicups/provider.go

   // User must provide a user to the provider
   var username string
   if config.Username.Unknown {
     // Cannot connect to client with an unknown value
     resp.Diagnostics.AddWarning(
       "Unable to create client",
       "Cannot use unknown value as username",
     )
     return
   }
   
   if config.Username.Null {
     username = os.Getenv("HASHICUPS_USERNAME")
   } else {
       username = config.Username.Value
   }
   
   if username == "" {
     // Error vs warning - empty value must stop execution
       resp.Diagnostics.AddError(
       "Unable to find username",
       "Username cannot be an empty string",
     )
     return
   }
   ##...
   

3. Creates a new API client. The provider will create a new API client with the configuration values and add it to the provider. This allows the provider to connect to and interact with the HashiCups API.

   // Create a new HashiCups client and set it to the provider client
   c, err := hashicups.NewClient(&host, &username, &password)
   if err != nil {
     resp.Diagnostics.AddError(
       "Unable to create client",
       "Unable to create hashicups client:\n\n"+err.Error(),
     )
     return
   }
   
   p.client = c
   p.configured = true
   

   hashicups/provider.go

   // Create a new HashiCups client and set it to the provider client
   c, err := hashicups.NewClient(&host, &username, &password)
   if err != nil {
     resp.Diagnostics.AddError(
       "Unable to create client",
       "Unable to create hashicups client:\n\n"+err.Error(),
     )
     return
   }
   
   p.client = c
   p.configured = true
   

»Define resources and data sources

The GetResources and GetDataSources functions define your provider's resources and data sources. This boilerplate version of the HashiCups provider has one resource named hashicups_order and does not define any data sources.

// GetResources - Defines provider resources
func (p *provider) GetResources(_ context.Context) (map[string]tfsdk.ResourceType, diag.Diagnostics) {
    return map[string]tfsdk.ResourceType{
        "hashicups_order": resourceOrderType{},
    }, nil
}

// GetDataSources - Defines provider data sources
func (p *provider) GetDataSources(_ context.Context) (map[string]tfsdk.DataSourceType, diag.Diagnostics) {
    return map[string]tfsdk.DataSourceType{}, nil
}

// GetResources - Defines provider resources
func (p *provider) GetResources(_ context.Context) (map[string]tfsdk.ResourceType, diag.Diagnostics) {
    return map[string]tfsdk.ResourceType{
        "hashicups_order": resourceOrderType{},
    }, nil
}

// GetDataSources - Defines provider data sources
func (p *provider) GetDataSources(_ context.Context) (map[string]tfsdk.DataSourceType, diag.Diagnostics) {
    return map[string]tfsdk.DataSourceType{}, nil
}

»Explore resource order

Open the hashicups/resource_order.go file. As a general convention, Terraform providers put each resource in their own file, named after the resource, prefixed with resource_.

Find the resourceOrderType struct and its schema. The GetSchema function defines the order resource's schema.

type resourceOrderType struct{}

// Order Resource schema
func (r resourceOrderType) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{},
    }, nil
}

type resourceOrderType struct{}

// Order Resource schema
func (r resourceOrderType) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{},
    }, nil
}

Next, find the NewResource function, which creates a new instance of your resource.

// New resource instance
func (r resourceOrderType) NewResource(_ context.Context, p tfsdk.Provider) (tfsdk.Resource, diag.Diagnostics) {
    return resourceOrder{
        p: *(p.(*provider)),
    }, nil
}

// New resource instance
func (r resourceOrderType) NewResource(_ context.Context, p tfsdk.Provider) (tfsdk.Resource, diag.Diagnostics) {
    return resourceOrder{
        p: *(p.(*provider)),
    }, nil
}

Below this, find the four functions the provider uses to perform CRUD (create, read, update, delete) operations. In the later sections, you will implement the create and read functionality.

// Create a new resource
func (r resourceOrder) Create(ctx context.Context, req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
}

// Read resource information
func (r resourceOrder) Read(ctx context.Context, req tfsdk.ReadResourceRequest, resp *tfsdk.ReadResourceResponse) {
}

// Update resource
func (r resourceOrder) Update(ctx context.Context, req tfsdk.UpdateResourceRequest, resp *tfsdk.UpdateResourceResponse) {
}

// Delete resource
func (r resourceOrder) Delete(ctx context.Context, req tfsdk.DeleteResourceRequest, resp *tfsdk.DeleteResourceResponse) {
}

// Import resource
func (r resourceOrder) ImportState(ctx context.Context, req tfsdk.ImportResourceStateRequest, resp *tfsdk.ImportResourceStateResponse) {
  tfsdk.ResourceImportStateNotImplemented(ctx, "", resp)
}

// Create a new resource
func (r resourceOrder) Create(ctx context.Context, req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
}

// Read resource information
func (r resourceOrder) Read(ctx context.Context, req tfsdk.ReadResourceRequest, resp *tfsdk.ReadResourceResponse) {
}

// Update resource
func (r resourceOrder) Update(ctx context.Context, req tfsdk.UpdateResourceRequest, resp *tfsdk.UpdateResourceResponse) {
}

// Delete resource
func (r resourceOrder) Delete(ctx context.Context, req tfsdk.DeleteResourceRequest, resp *tfsdk.DeleteResourceResponse) {
}

// Import resource
func (r resourceOrder) ImportState(ctx context.Context, req tfsdk.ImportResourceStateRequest, resp *tfsdk.ImportResourceStateResponse) {
  tfsdk.ResourceImportStateNotImplemented(ctx, "", resp)
}

»Define order schema

The resource schema defines the resources's attributes and its metadata. Post a new order to the HashiCups API to review the structure of the data it sends.

$ curl -X POST -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders -d '[{"coffee": { "id":1 }, "quantity":4}, {"coffee": { "id":3 }, "quantity":3}]' | jq .

{
  "id": 1, "items": [
    {
      "coffee": {
        "id": 1, "name": "Packer Spiced Latte", "teaser": "Packed with goodness
        to spice up your images", "description": "", "price": 350, "image":
        "/packer.png", "ingredients": null
      }, "quantity": 4
    }, {
      "coffee": {
        "id": 3, "name": "Nomadicano", "teaser": "Drink one today and you will
        want to schedule another", "description": "", "price": 150, "image":
        "/nomad.png", "ingredients": null
      }, "quantity": 3
    }
  ]
}

$ curl -X POST -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders -d '[{"coffee": { "id":1 }, "quantity":4}, {"coffee": { "id":3 }, "quantity":3}]' | jq .

{
  "id": 1, "items": [
    {
      "coffee": {
        "id": 1, "name": "Packer Spiced Latte", "teaser": "Packed with goodness
        to spice up your images", "description": "", "price": 350, "image":
        "/packer.png", "ingredients": null
      }, "quantity": 4
    }, {
      "coffee": {
        "id": 3, "name": "Nomadicano", "teaser": "Drink one today and you will
        want to schedule another", "description": "", "price": 150, "image":
        "/nomad.png", "ingredients": null
      }, "quantity": 3
    }
  ]
}

In the hashicups/resource_order.go file, replace the GetSchema function with the following definition. This schema maps closely to the response body for creating a new HashiCups order.

// Order Resource schema
func (r resourceOrderType) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "id": {
                Type: types.StringType,
                // When Computed is true, the provider will set value --
                // the user cannot define the value
                Computed: true,
            },
            "last_updated": {
                Type:     types.StringType,
                Computed: true,
            },
            "items": {
                // If Required is true, Terraform will throw error if user
                // doesn't specify value
                // If Optional is true, user can choose to supply a value
                Required: true,
                Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{
                    "quantity": {
                        Type:     types.NumberType,
                        Required: true,
                    },
                    "coffee": {
                        Required: true,
                        Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{
                            "id": {
                                Type:     types.NumberType,
                                Required: true,
                            },
                            "name": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "teaser": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "description": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "price": {
                                Type:     types.NumberType,
                                Computed: true,
                            },
                            "image": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                        }),
                    },
                }, tfsdk.ListNestedAttributesOptions{}),
            },
        },
    }, nil
}

// Order Resource schema
func (r resourceOrderType) GetSchema(_ context.Context) (tfsdk.Schema, diag.Diagnostics) {
    return tfsdk.Schema{
        Attributes: map[string]tfsdk.Attribute{
            "id": {
                Type: types.StringType,
                // When Computed is true, the provider will set value --
                // the user cannot define the value
                Computed: true,
            },
            "last_updated": {
                Type:     types.StringType,
                Computed: true,
            },
            "items": {
                // If Required is true, Terraform will throw error if user
                // doesn't specify value
                // If Optional is true, user can choose to supply a value
                Required: true,
                Attributes: tfsdk.ListNestedAttributes(map[string]tfsdk.Attribute{
                    "quantity": {
                        Type:     types.NumberType,
                        Required: true,
                    },
                    "coffee": {
                        Required: true,
                        Attributes: tfsdk.SingleNestedAttributes(map[string]tfsdk.Attribute{
                            "id": {
                                Type:     types.NumberType,
                                Required: true,
                            },
                            "name": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "teaser": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "description": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                            "price": {
                                Type:     types.NumberType,
                                Computed: true,
                            },
                            "image": {
                                Type:     types.StringType,
                                Computed: true,
                            },
                        }),
                    },
                }, tfsdk.ListNestedAttributesOptions{}),
            },
        },
    }, nil
}

Schemas in providers, resources, and data sources follow a few rules:

• You must define either a Type or an Attributes field.
  • The Type property of a tfsdk.Attribute specifies the type of the attribute. Attributes commonly have types defined in the terraform-plugin-framework/types package, like types.StringType and types.NumberType.
  • The Attributes property of a tfsdk.Attribute specifies an attribute's nested attributes. Nested attributes are attributes that are grouped beneath another attribute; this can include items like a list of objects, a set of objects, or nested objects.
• You must determine your Required, Computed, Optional fields.
  • If an attribute has Required set to true, the user must define it. The attribute cannot have Computed or Optional set to true.
  • If an attribute only has Computed set to true, the provider can set this attribute's value and considers it read-only.
  • If an attribute only has Optional set to true, the user is free to set the attribute or omit it.
  • If an attribute has both Computed and Optional set to true, Terraform will not validate the presence or absence of the value.

»Review HashiCups models

Open hashicups/models.go.

This file defines a series of Go structs that map to the schema you defined above. The provider uses these models to parse the resource's configuration, plan, and state. Each field in the struct must have an associated field tag (for example, tfsdk:"_") so the provider knows the relationship between the field in the struct and the corresponding attribute in the schema. These structs' field tags must match the schemas' exactly or the provider will throw an error.

package hashicups

import (
    "github.com/hashicorp/terraform-plugin-framework/types"
)

// Order -
type Order struct {
    ID          types.String `tfsdk:"id"`
    Items       []OrderItem  `tfsdk:"items"`
    LastUpdated types.String `tfsdk:"last_updated"`
}

// OrderItem -
type OrderItem struct {
    Coffee   Coffee `tfsdk:"coffee"`
    Quantity int    `tfsdk:"quantity"`
}

// Coffee -
// This Coffee struct is for Order.Items[].Coffee which does not have an
// ingredients field in the schema defined in the provider code. Since the
// resource schema must match the struct exactly (any extra field will return an
// error), this struct has Ingredients commented out.
type Coffee struct {
    ID          int          `tfsdk:"id"`
    Name        types.String `tfsdk:"name"`
    Teaser      types.String `tfsdk:"teaser"`
    Description types.String `tfsdk:"description"`
    Price       types.Number `tfsdk:"price"`
    Image       types.String `tfsdk:"image"`
    // Ingredients []Ingredient   `tfsdk:"ingredients"`
}

package hashicups

import (
    "github.com/hashicorp/terraform-plugin-framework/types"
)

// Order -
type Order struct {
    ID          types.String `tfsdk:"id"`
    Items       []OrderItem  `tfsdk:"items"`
    LastUpdated types.String `tfsdk:"last_updated"`
}

// OrderItem -
type OrderItem struct {
    Coffee   Coffee `tfsdk:"coffee"`
    Quantity int    `tfsdk:"quantity"`
}

// Coffee -
// This Coffee struct is for Order.Items[].Coffee which does not have an
// ingredients field in the schema defined in the provider code. Since the
// resource schema must match the struct exactly (any extra field will return an
// error), this struct has Ingredients commented out.
type Coffee struct {
    ID          int          `tfsdk:"id"`
    Name        types.String `tfsdk:"name"`
    Teaser      types.String `tfsdk:"teaser"`
    Description types.String `tfsdk:"description"`
    Price       types.Number `tfsdk:"price"`
    Image       types.String `tfsdk:"image"`
    // Ingredients []Ingredient   `tfsdk:"ingredients"`
}

The create and read functions use these models to parse the resource's plan and state. state.

»Implement create functionality

The provider uses the Create function to create a new resource based on the schema data.

The create function follows these steps:

1. Checks whether the provider and API Client are configured. If they are not, the provider responds with an error.
2. Retrieves values from the plan. The function will attempt to retrieve values from the plan and convert it to an Order struct (defined in models.go).
3. Generates an API request body from the plan values. The function loops through each plan item and maps it to a hashicups.OrderItem. This is what the API client needs to create a new order.
4. Creates a new order. The function invokes the API client's CreateOrder method.
5. Maps response body to resource schema attributes. After the function creates an order, it maps the hashicups.Order response to []OrderItem so the provider can update the Terraform state.
6. Sets state to new order.

Open the hashicups/resource_order.go file.

Replace your Create function with the following.

// Create a new resource
func (r resourceOrder) Create(ctx context.Context, req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    if !r.p.configured {
        resp.Diagnostics.AddError(
            "Provider not configured",
            "The provider hasn't been configured before apply, likely because it depends on an unknown value from another resource. This leads to weird stuff happening, so we'd prefer if you didn't do that. Thanks!",
        )
        return
    }

    // Retrieve values from plan
    var plan Order
    diags := req.Plan.Get(ctx, &plan)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // Generate API request body from plan
    var items []hashicups.OrderItem
    for _, item := range plan.Items {
        items = append(items, hashicups.OrderItem{
            Coffee: hashicups.Coffee{
                ID: item.Coffee.ID,
            },
            Quantity: item.Quantity,
        })
    }

    // Create new order
    order, err := r.p.client.CreateOrder(items)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error creating order",
            "Could not create order, unexpected error: "+err.Error(),
        )
        return
    }

    // Map response body to resource schema attribute
    var ois []OrderItem
    for _, oi := range order.Items {
        ois = append(ois, OrderItem{
            Coffee: Coffee{
                ID:          oi.Coffee.ID,
                Name:        types.String{Value: oi.Coffee.Name},
                Teaser:      types.String{Value: oi.Coffee.Teaser},
                Description: types.String{Value: oi.Coffee.Description},
                Price:       types.Number{Value: big.NewFloat(oi.Coffee.Price)},
                Image:       types.String{Value: oi.Coffee.Image},
            },
            Quantity: oi.Quantity,
        })
    }

    // Generate resource state struct
    var result = Order{
        ID:          types.String{Value: strconv.Itoa(order.ID)},
        Items:       ois,
        LastUpdated: types.String{Value: string(time.Now().Format(time.RFC850))},
    }

    diags = resp.State.Set(ctx, result)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

// Create a new resource
func (r resourceOrder) Create(ctx context.Context, req tfsdk.CreateResourceRequest, resp *tfsdk.CreateResourceResponse) {
    if !r.p.configured {
        resp.Diagnostics.AddError(
            "Provider not configured",
            "The provider hasn't been configured before apply, likely because it depends on an unknown value from another resource. This leads to weird stuff happening, so we'd prefer if you didn't do that. Thanks!",
        )
        return
    }

    // Retrieve values from plan
    var plan Order
    diags := req.Plan.Get(ctx, &plan)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // Generate API request body from plan
    var items []hashicups.OrderItem
    for _, item := range plan.Items {
        items = append(items, hashicups.OrderItem{
            Coffee: hashicups.Coffee{
                ID: item.Coffee.ID,
            },
            Quantity: item.Quantity,
        })
    }

    // Create new order
    order, err := r.p.client.CreateOrder(items)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error creating order",
            "Could not create order, unexpected error: "+err.Error(),
        )
        return
    }

    // Map response body to resource schema attribute
    var ois []OrderItem
    for _, oi := range order.Items {
        ois = append(ois, OrderItem{
            Coffee: Coffee{
                ID:          oi.Coffee.ID,
                Name:        types.String{Value: oi.Coffee.Name},
                Teaser:      types.String{Value: oi.Coffee.Teaser},
                Description: types.String{Value: oi.Coffee.Description},
                Price:       types.Number{Value: big.NewFloat(oi.Coffee.Price)},
                Image:       types.String{Value: oi.Coffee.Image},
            },
            Quantity: oi.Quantity,
        })
    }

    // Generate resource state struct
    var result = Order{
        ID:          types.String{Value: strconv.Itoa(order.ID)},
        Items:       ois,
        LastUpdated: types.String{Value: string(time.Now().Format(time.RFC850))},
    }

    diags = resp.State.Set(ctx, result)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

»Implement read functionality

The provider uses the Read function to retrieve the resource's information and update the Terraform state to reflect the resource's current state. The provider invokes this function before every apply to generate an accurate diff between the resource's current state and the configuration.

The read function follows these steps:

1. Gets the current state. If it is unable to, the provider responds with an error.
2. Retrieves order ID from state.
3. Gets the order's information. The function invokes the API client's GetOrder method with the order ID.
4. Maps response body to resource schema attributes. After the function retrieves the order, it maps the hashicups.Order response to []OrderItem so the provider can update the Terraform state.
5. Set state to new order.

Replace your Read function with the following:

// Read resource information
func (r resourceOrder) Read(ctx context.Context, req tfsdk.ReadResourceRequest, resp *tfsdk.ReadResourceResponse) {
    // Get current state
    var state Order
    diags := req.State.Get(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // Get order from API and then update what is in state from what the API returns
    orderID := state.ID.Value

    // Get order current value
    order, err := r.p.client.GetOrder(orderID)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error reading order",
            "Could not read orderID "+orderID+": "+err.Error(),
        )
        return
    }

    // Map response body to resource schema attribute
    state.Items = []OrderItem{}
    for _, item := range order.Items {
        state.Items = append(state.Items, OrderItem{
            Coffee: Coffee{
                ID:          item.Coffee.ID,
                Name:        types.String{Value: item.Coffee.Name},
                Teaser:      types.String{Value: item.Coffee.Teaser},
                Description: types.String{Value: item.Coffee.Description},
                Price:       types.Number{Value: big.NewFloat(item.Coffee.Price)},
                Image:       types.String{Value: item.Coffee.Image},
            },
            Quantity: item.Quantity,
        })
    }

    // Set state
    diags = resp.State.Set(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

// Read resource information
func (r resourceOrder) Read(ctx context.Context, req tfsdk.ReadResourceRequest, resp *tfsdk.ReadResourceResponse) {
    // Get current state
    var state Order
    diags := req.State.Get(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // Get order from API and then update what is in state from what the API returns
    orderID := state.ID.Value

    // Get order current value
    order, err := r.p.client.GetOrder(orderID)
    if err != nil {
        resp.Diagnostics.AddError(
            "Error reading order",
            "Could not read orderID "+orderID+": "+err.Error(),
        )
        return
    }

    // Map response body to resource schema attribute
    state.Items = []OrderItem{}
    for _, item := range order.Items {
        state.Items = append(state.Items, OrderItem{
            Coffee: Coffee{
                ID:          item.Coffee.ID,
                Name:        types.String{Value: item.Coffee.Name},
                Teaser:      types.String{Value: item.Coffee.Teaser},
                Description: types.String{Value: item.Coffee.Description},
                Price:       types.Number{Value: big.NewFloat(item.Coffee.Price)},
                Image:       types.String{Value: item.Coffee.Image},
            },
            Quantity: item.Quantity,
        })
    }

    // Set state
    diags = resp.State.Set(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }
}

Replace the import statement at the top of resource_order.go with the following:

 import (
     "context"
     "math/big"
     "strconv"
     "time"


     "github.com/hashicorp-demoapp/hashicups-client-go"
     "github.com/hashicorp/terraform-plugin-framework/diag"
     "github.com/hashicorp/terraform-plugin-framework/tfsdk"
     "github.com/hashicorp/terraform-plugin-framework/types"
 )

 import (
     "context"
     "math/big"
     "strconv"
     "time"


     "github.com/hashicorp-demoapp/hashicups-client-go"
     "github.com/hashicorp/terraform-plugin-framework/diag"
     "github.com/hashicorp/terraform-plugin-framework/tfsdk"
     "github.com/hashicorp/terraform-plugin-framework/types"
 )

Periodically format your code. Use the following command from within the hashicups directory.

$ go fmt ./...

$ go fmt ./...

If you were stuck at any step, check out the create-read-order branch to see the changes implemented in this tutorial.

»Build the provider

Now that you have implemented the read functionality, you are ready to build your provider.

Terraform verifies provider versions and checksums at the terraform init phase. Terraform downloads your providers from either the provider registry, or from a local registry. However, while building your provider, you will want to try a test configuration against a development build of a provider that doesn't have an associated version number yet, and doesn't have an official set of checksums listed in a provider registry.

As a convenience for provider development, Terraform supports a special additional block dev_overrides in a CLI configuration file called .terraformrc. This block overrides all other configured installation methods.

Terraform searches for the .terraformrc file in your home directory and applies any configuration settings you set.

$ go env GOBIN
/Users/<Username>/go/bin

$ go env GOBIN
/Users/<Username>/go/bin

provider_installation {

  dev_overrides {
      "hashicorp.com/edu/hashicups-pf" = "<PATH>"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, Terraform will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

provider_installation {

  dev_overrides {
      "hashicorp.com/edu/hashicups-pf" = "<PATH>"
  }

  # For all other providers, install them directly from their origin provider
  # registries as normal. If you omit this, Terraform will _only_ use
  # the dev_overrides block, and so no other providers will be available.
  direct {}
}

In the terraform-provider-hashicups-pf directory, update your go.mod file.

$ go mod tidy

$ go mod tidy

Build the provider binary.

$ go install

$ go install

Now that the provider is in your GOBIN directory, you can use the provider in your Terraform configuration.

»Apply the provider

The Terraform provider you just modified is ready to communicate with your API endpoint to create an order. In future tutorials, you will implement further functionality for your provider.

Navigate to the examples directory. This directory contains a sample configuration file to test create and read functionality.

$ cd examples

$ cd examples

Apply your configuration to create the order. Notice how the execution plan shows a proposed order, with additional information about the order. Terraform returns a warning about using the dev_overrides block. Remember to confirm the apply step with a yes.

$ terraform apply

╷
│ Warning: Provider development overrides are in effect
│
│ The following provider development overrides are set in the CLI configuration:
│  - hashicorp.com/edu/hashicups-pf-test in /Users/rachel/go/bin
│
│ The behavior may therefore not match any released version of the provider and applying changes may cause the state to become incompatible with published releases.
╵

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # hashicups_order.edu will be created
  + resource "hashicups_order" "edu" {
      + id           = (known after apply)
      ## ...
    }

Plan: 1 to add, 0 to change, 0 to destroy.

## ...

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

hashicups_order.edu: Creating...
hashicups_order.edu: Creation complete after 0s [id=21]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

edu_order = {
  "id" = "1"
  "items" = tolist([
    {
      "coffee" = {
        "description" = ""
        "id" = 3
        "image" = "/nomad.png"
        "name" = "Nomadicano"
        "price" = 150
        "teaser" = "Drink one today and you will want to schedule another"
      }
      "quantity" = 2
    },
    {
      "coffee" = {
        "description" = ""
        "id" = 1
        "image" = "/packer.png"
        "name" = "Packer Spiced Latte"
        "price" = 350
        "teaser" = "Packed with goodness to spice up your images"
      }
      "quantity" = 2
    },
  ])
  "last_updated" = "Thursday, 22-Jul-21 03:26:51 PDT"
}

$ terraform apply

╷
│ Warning: Provider development overrides are in effect
│
│ The following provider development overrides are set in the CLI configuration:
│  - hashicorp.com/edu/hashicups-pf-test in /Users/rachel/go/bin
│
│ The behavior may therefore not match any released version of the provider and applying changes may cause the state to become incompatible with published releases.
╵

Terraform used the selected providers to generate the following execution plan. Resource actions are indicated with the following symbols:
  + create

Terraform will perform the following actions:

  # hashicups_order.edu will be created
  + resource "hashicups_order" "edu" {
      + id           = (known after apply)
      ## ...
    }

Plan: 1 to add, 0 to change, 0 to destroy.

## ...

Do you want to perform these actions?
  Terraform will perform the actions described above.
  Only 'yes' will be accepted to approve.

  Enter a value: yes

hashicups_order.edu: Creating...
hashicups_order.edu: Creation complete after 0s [id=21]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Outputs:

edu_order = {
  "id" = "1"
  "items" = tolist([
    {
      "coffee" = {
        "description" = ""
        "id" = 3
        "image" = "/nomad.png"
        "name" = "Nomadicano"
        "price" = 150
        "teaser" = "Drink one today and you will want to schedule another"
      }
      "quantity" = 2
    },
    {
      "coffee" = {
        "description" = ""
        "id" = 1
        "image" = "/packer.png"
        "name" = "Packer Spiced Latte"
        "price" = 350
        "teaser" = "Packed with goodness to spice up your images"
      }
      "quantity" = 2
    },
  ])
  "last_updated" = "Thursday, 22-Jul-21 03:26:51 PDT"
}

Once the apply completes, the provider saves the resource's state. View the state by running terraform state show <resource_name>.

$ terraform state show hashicups_order.edu
# hashicups_order.edu:
resource "hashicups_order" "edu" {
    id           = "1"
    items        = [
        {      },
      # (2 unchanged elements hidden)
    ]
    last_updated = "Thursday, 22-Jul-21 03:26:51 PDT"
}

$ terraform state show hashicups_order.edu
# hashicups_order.edu:
resource "hashicups_order" "edu" {
    id           = "1"
    items        = [
        {      },
      # (2 unchanged elements hidden)
    ]
    last_updated = "Thursday, 22-Jul-21 03:26:51 PDT"
}

The (known after apply) values in the execution plan during the terraform apply state have all been populated, since the order was successfully created.

»Verify order created

When you create an order in HashiCups using Terraform, the terminal containing your HashiCups logs will have recorded operations invoked by the HashiCups provider.

api_1  | 2021-07-22T10:26:31.179Z [INFO]  Handle User | signin
api_1  | 2021-07-22T10:26:51.179Z [INFO]  Handle User | signin
api_1  | 2021-07-22T10:26:51.195Z [INFO]  Handle Orders | CreateOrder

api_1  | 2021-07-22T10:26:31.179Z [INFO]  Handle User | signin
api_1  | 2021-07-22T10:26:51.179Z [INFO]  Handle User | signin
api_1  | 2021-07-22T10:26:51.195Z [INFO]  Handle Orders | CreateOrder

The provider invoked a total of 3 operations.

1. The provider invoked the first signin operation when you ran terraform apply to retrieve the current state of the resources. Because there are no resources, it only authenticates the user.
2. The provider invoked the second signin operation after you confirmed the apply run. The provider authenticated using the provided credentials to retrieve and save the JWT token.
3. The provider invoked the CreateOrder operation to create the order defined by the Terraform configuration. Since this is a protected endpoint, it used the saved JWT token from the signin operation.

Verify that Terraform created the order by retrieving the order details via the API.

$ curl -X GET  -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders/1
{"id":1,"items":[{"coffee":{"id":3,"name":"Nomadicano","teaser":"Drink one today and you will want to schedule another","description":"","price":150,"image":"/nomad.png","ingredients":null},"quantity":2},{"coffee":{"id":2,"name":"Vaulatte","teaser":"Nothing gives you a safe and secure feeling like a Vaulatte","description":"","price":200,"image":"/vault.png","ingredients":null},"quantity":2}]}

$ curl -X GET  -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders/1
{"id":1,"items":[{"coffee":{"id":3,"name":"Nomadicano","teaser":"Drink one today and you will want to schedule another","description":"","price":150,"image":"/nomad.png","ingredients":null},"quantity":2},{"coffee":{"id":2,"name":"Vaulatte","teaser":"Nothing gives you a safe and secure feeling like a Vaulatte","description":"","price":200,"image":"/vault.png","ingredients":null},"quantity":2}]}

The order's properties should be the same as that of your hashicups_order.edu resource.

»Next steps

Congratulations! You have created the order resource with create and read capabilities.

If you were stuck during this tutorial, checkout the create-read-order branch to see the changes implemented in this tutorial.

• To learn more about the Terraform Plugin Framework, refer to the Terraform Plugin Framework documentation.
• For a full capability comparison between the SDKv2 and the Plugin Framework, refer to the Which SDK Should I Use? documentation.
• The Terraform HashiCups (plugin-framework) provider's main branch contains the complete HashiCups provider. It includes a data source written with the plugin framework and implements create, read, update and delete functionality for the order resource.