Implement Update

9min
Terraform

Note: We recommend using the Terraform Plugin Framework for new provider development because it offers significant advantages compared to the SDKv2. Refer to the Plugin Framework tutorials to learn how to create providers using the framework.

In this tutorial, you will add update capabilities to the order resource of a provider that interacts with the API of a fictional coffee-shop application called Hashicups. To do this, you will:

Update your schema.
Add a last_updated attribute to the order schema. This attribute will update to the current date time whenever the order resource is updated.
Implement update.
This update function invokes a PUT request to the /orders/{orderId} endpoint with the update order items in the request body. After the update function runs, it invokes resourceOrderRead to retrieve the order's updated values.

Prerequisites

To follow this tutorial, you need:

a Golang 1.15+ installed and configured.
the Terraform 0.14+ CLI installed locally.
Docker and Docker Compose to run an instance of HashiCups locally.

Navigate to your terraform-provider-hashicups directory. Next, fetch new changes.

$ git fetch

Then, checkout the implement-create branch. This step is optional but recommended to ensure that your code matches the code from the previous tutorials.

$ git checkout implement-create

Clone the implement-create branch of the Terraform HashiCups Provider repository.

$ git clone --branch implement-create https://github.com/hashicorp/terraform-provider-hashicups

Change into the cloned repository.

$ cd terraform-provider-hashicups

Then, install all the provider's dependencies.

$ go mod tidy

Build provider binary

Next, build the binary and move it into your user Terraform plugins directory. This allows you to sideload and test the custom provider. Select the tab for your operating system for specific instructions.

$ make install
go build -o terraform-provider-hashicups
mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/darwin_amd64

Build the provider binary.

$ go build -o terraform-provider-hashicups

Retrieve your system's OS and ARCH. You can find a full list of supported GOOS and GOARCH here.

$ export OS_ARCH="$(go env GOHOSTOS)_$(go env GOHOSTARCH)"

Create the appropriate subdirectory within the user plugins directory for the HashiCups provider if it doesn't exist already.

$ mkdir -p ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Next, move the binary to the appropriate subdirectory within your user plugins directory.

$ mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Build the provider binary.

$ go build -o terraform-provider-hashicups.exe

Create the appropriate subdirectory within the user plugins directory for the HashiCups provider if it doesn't exist already, replacing [OS_ARCH] with your system's OS_ARCH. You can find a full list of supported GO_ARCH here.

$ mkdir -p %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Then, move the binary to the appropriate subdirectory within your user plugins directory, replacing [OS_ARCH] with your system's OS_ARCH.

$ move terraform-provider-hashicups.exe %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Tip

The Perform CRUD operations with Providers tutorial explains why and how to sideload custom providers. Refer to it to learn more about where to install custom providers and how to reference them in your configuration.

Run HashiCups API

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

$ cd docker_compose

Then, run docker-compose up to spin up a local instance of HashiCups on port 19090.

$ docker-compose up

Leave this terminal running.

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

$ curl localhost:19090/health
ok

Create a HashiCups user

Create a user on HashiCups named education with the password test123. If you already did this in a previous tutorial, you can skip signing up and reuse your previous token.

$ 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/signin -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 in the previous step.

$ export HASHICUPS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU

Apply example configuration

Navigate to the terraform-provider-hashicups/examples directory. This contains a sample Terraform configuration for the Terraform HashiCups provider.

$ cd examples

Initialize your workspace.

$ terraform init

Apply the configuration. This creates an order and returns its values in your output.

$ terraform apply --auto-approve
Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Navigate to your terraform-provider-hashicups directory.

$ cd ..

Your directory should have the following structure.

$ tree -L 2
.
├── Makefile
├── README.md
├── docker_compose
│   ├── conf.json
│   └── docker-compose.yml
├── examples
│   ├── coffee
│   ├── main.tf
│   ├── terraform.tfstate
│   └── terraform.tfstate.backup
├── go.mod
├── go.sum
├── hashicups
│   ├── data_source_coffee.go
│   ├── data_source_order.go
│   ├── provider.go
│   └── resource_order.go
├── main.go
└── vendor

If you're stuck at any point during this tutorial, refer to the implement-update branch to see the changes implemented in this tutorial.

Update schema

In hashicups/resource_order.go, update your order schema to include a parameter named last_updated.

hashicups/resource_order.go

"last_updated": &schema.Schema{
  Type:     schema.TypeString,
  Optional: true,
  Computed: true,
},

Your order schema should look like the following.

hashicups/resource_order.go

func resourceOrder() *schema.Resource {
  return &schema.Resource{
    ...
    Schema: map[string]*schema.Schema{
      "last_updated": &schema.Schema{
        Type:     schema.TypeString,
        Optional: true,
        Computed: true,
      },
      "items": &schema.Schema{
        ...
      },
      ...
    },
  },
}

Implement update

Now that you have defined the order resource schema, replace the resourceOrderUpdate function in hashicups/resource_order.go with the following code snippet. This function will update the order resource if there are any changes to the order items.

hashicups/resource_order.go

func resourceOrderUpdate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  c := m.(*hc.Client)

  orderID := d.Id()

  if d.HasChange("items") {
    items := d.Get("items").([]interface{})
    ois := []hc.OrderItem{}

    for _, item := range items {
      i := item.(map[string]interface{})

      co := i["coffee"].([]interface{})[0]
      coffee := co.(map[string]interface{})

      oi := hc.OrderItem{
        Coffee: hc.Coffee{
          ID: coffee["id"].(int),
        },
        Quantity: i["quantity"].(int),
      }
      ois = append(ois, oi)
    }

    _, err := c.UpdateOrder(orderID, ois)
    if err != nil {
      return diag.FromErr(err)
    }

    d.Set("last_updated", time.Now().Format(time.RFC850))
  }

  return resourceOrderRead(ctx, d, m)
}

Notice the m (meta) input parameter contains the HashiCups API Client set by the ConfigureContextFunc defined above. If an unauthenticated API Client is provided (no username/password), this function will fail and return an error message.

The function determines whether there are discrepancies in the items property between the configuration and the state.

Tip

The HasChange() function enables you to invoke different APIs or build a targeted request body to update your resource when a specific property changes.

If there are discrepancies, the function will update the order with the new configuration. Then, it will update the last_updated attribute to the current timestamp. Finally, it will call resourceOrderRead to update the resource's state.

Note

Update functions rarely update the resource ID. However, if the ID becomes blank during the update process, the provider assumes the resource is destroyed and all state is removed.

Import the time library.

hashicups/resource_order.go

import (
  "context"
  "strconv"
  "time"

  hc "github.com/hashicorp-demoapp/hashicups-client-go"
  "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

Test the provider

Now that you've added update capabilities to the order resource, verify that it works.

First, confirm that you are in the terraform-provider-hashicups root directory.

$ pwd
~/terraform-provider-hashicups

$ make install
go build -o terraform-provider-hashicups
mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/darwin_amd64

Build the provider binary.

$ go build -o terraform-provider-hashicups

Retrieve your system's OS and ARCH. You can find a full list of supported GOOS and GOARCH here.

$ export OS_ARCH="$(go env GOHOSTOS)_$(go env GOHOSTARCH)"

Create the appropriate subdirectory within the user plugins directory for the HashiCups provider if it doesn't exist already.

$ mkdir -p ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Next, move the binary to the appropriate subdirectory within your user plugins directory.

$ mv terraform-provider-hashicups ~/.terraform.d/plugins/hashicorp.com/edu/hashicups/0.2/$OS_ARCH

Build the provider binary.

$ go build -o terraform-provider-hashicups.exe

$ mkdir -p %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Then, move the binary to the appropriate subdirectory within your user plugins directory, replacing [OS_ARCH] with your system's OS_ARCH.

$ move terraform-provider-hashicups.exe %APPDATA%\terraform.d\plugins\hashicorp.com\edu\hashicups\0.2\[OS_ARCH]

Tip

Navigate to the terraform-provider-hashicups/examples directory. This contains a sample Terraform configuration for the Terraform HashiCups provider.

$ cd examples

Update your hashicups_order.edu resource in main.tf.

examples/main.tf

resource "hashicups_order" "edu" {
  items {
    coffee {
      id = 3
    }
    quantity = 2
  }
  items {
    coffee {
      id = 2
    }
    quantity = 3
  }
}

Initialize your workspace to refresh your HashiCups provider.

$ terraform init

Apply the configuration to update your order and set the last_updated attribute.

$ terraform apply --auto-approve
Apply complete! Resources: 0 added, 1 changed, 0 destroyed.

Verify that the provider updated your order by invoking the HashiCups API. Substitute the order number with your order ID and the auth token with your auth token.

$ curl -X GET -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders/1

Next steps

In this tutorial, you added update capabilities to the order resource.

If you were stuck during this tutorial, checkout the implement-update branch to see the changes implemented in this tutorial.

The Terraform Provider Scaffold is a quick-start repository for creating a Terraform provider. Use this GitHub template when you're ready to create a custom provider.
To learn more about the Terraform Plugin SDK, refer to the Terraform Plugin SDK Documentation.