Implement resource delete

7min
|
Terraform

In this tutorial, you will add delete 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:

Implement resource delete.
This delete method uses the HashiCups API client to invoke a DELETE request to the /orders/{orderId} endpoint. After the delete is successful, the framework automatically removes the resource from Terraform's state.
Verify delete functionality.
This ensures that the resource is working as expected.

Prerequisites

To follow this tutorial, you need:

Go 1.21+ installed and configured.
Terraform v1.8+ installed locally.
Docker and Docker Compose to run an instance of HashiCups locally.

Navigate to your terraform-provider-hashicups directory.

Your code should match the 06-update-order directory from the example repository.

If you haven't already done so, clone the Terraform HashiCups Provider repository.

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

Change into the 06-update-order directory of cloned repository.

$ cd terraform-provider-hashicups/06-update-order

Then, install all the provider's dependencies.

$ go mod tidy

Build the 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.

First, find the GOBIN path where Go installs your binaries. Your path may vary depending on how your Go environment variables are configured.

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

If the GOBIN go environment variable is not set, use the default path, /Users/<Username>/go/bin.

Create a new file called .terraformrc in the root directory (~), then add the dev_overrides block below. Change the <PATH> to the value returned from the echo $GOBIN command above.

~/.terraformrc

provider_installation {

  dev_overrides {
    "hashicorp.com/edu/hashicups" = "<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 {}
}

You must create your CLI configuration file in your user %APPDATA% root directory. The physical location of this directory depends on your Windows version and system configuration.

Search for the user environment variables in PowerShell to find its location on your system.

$ $env:APPDATA

In another terminal, change into the directory returned from the command above.

Find the GOBIN path where go installs your binaries. Your path may vary depending on how your Go environment variables are configured.

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

If the GOBIN go environment variable is not set, use the default path, /Users/<Username>/go/bin.

Create a new file called terraform.rc and add the dev_overrides block below. Change the <PATH> to the value returned from the go env GOBIN command above.

terraform.rc

provider_installation {

  dev_overrides {
    "hashicorp.com/edu/hashicups" = "<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 {}
}

Start HashiCups locally

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

$ cd docker_compose

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

$ docker-compose up

Leave this process running in your terminal window. The HashiCups service will print out log messages in this terminal.

In the original terminal window, verify that HashiCups is running by sending a request to its health check endpoint. The HashiCups service will respond with ok.

$ curl localhost:19090/health/readyz
ok

Create a HashiCups user

HashiCups requires a username and password to generate a 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"}

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...

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

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.

Apply example configuration

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

$ cd examples/order

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 ../..

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

Implement delete functionality

The provider uses the Delete method to delete an existing resource.

The delete method follows these steps:

Retrieves values from the state. The method will attempt to retrieve values from the state and convert it to an Order struct (defined in models.go).
Deletes an existing order. The method invokes the API client's DeleteOrder method.

If there are no errors, the framework will automatically remove the resource from Terraform's state.

Open the internal/provider/order_resource.go file.

Replace your Delete method with the following.

internal/provider/order_resource.go

func (r *orderResource) Delete(ctx context.Context, req resource.DeleteRequest, resp *resource.DeleteResponse) {
// Retrieve values from state
    var state orderResourceModel
    diags := req.State.Get(ctx, &state)
    resp.Diagnostics.Append(diags...)
    if resp.Diagnostics.HasError() {
        return
    }

    // Delete existing order
    err := r.client.DeleteOrder(state.ID.ValueString())
    if err != nil {
        resp.Diagnostics.AddError(
            "Error Deleting HashiCups Order",
            "Could not delete order, unexpected error: "+err.Error(),
        )
        return
    }
}

Build and install the updated provider.

$ go install .

Verify delete functionality

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

$ cd examples/order

Destroy the configuration. This will delete your order.

$ terraform destroy -auto-approve
##...
Destroy complete! Resources: 1 destroyed.

Verify that the provider deleted 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
{}

Navigate to the terraform-provider-hashicups directory.

$ cd ../..

Next steps

Congratulations! You have enhanced the order resource with delete capabilities.

If you were stuck during this tutorial, checkout the 07-delete-order directory in the example repository to see the code 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 example repository contains directories corresponding to each tutorial in this collection.
Submit any Terraform Plugin Framework bug reports or feature requests to the development team in the Terraform Plugin Framework Github repository.
Submit any Terraform Plugin Framework questions in the Terraform Plugin Framework Discuss forum.

Update

Import