Implement import

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 import capabilities to the order resource of the HashiCups Terraform provider, which interacts with the API of a fictional coffee-shop application. To do this, you will implement a ResourceImporter() function. This function retrieves an existing HashiCups order and brings it into Terraform state, enabling Terraform to manage it.

Prerequisites

To follow this tutorial, you need:

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

If you have just completed the previous provider tutorials, follow the steps below. If not, switch to the "New set up" tab.

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

$ git fetch

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

$ git checkout implement-delete

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

$ git clone --branch implement-delete 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 a HASHICUPS_TOKEN environment variable to the token generated in the previous step. You will use this later in the tutorial to verify your HashiCups order has been imported.

$ 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-import branch to see the changes implemented in this tutorial.

Implement import

In hashicups/resource_order.go, add the following Importer attribute to the end of the resourceOrder() schema.

hashicups/resource_order.go

func resourceOrder() *schema.Resource {
  return &schema.Resource{
    # ..
    Schema: map[string]*schema.Schema{
      # ..
    },
    Importer: &schema.ResourceImporter{
       StateContext: schema.ImportStatePassthroughContext,
    },
  }
}

Format your code.

$ go fmt ./...

Notice that StateContext is set to schema.ImportStatePassthroughContext. When you invoke the import command, you provide the order ID in the command. For example:

$ terraform import hashicups_order.sample order_id

Terraform passes the order_id value to the read function (resourceOrderRead), which then populates the resource's (hashicups_order.sample) state. This is the preferred method but requires a Read function that can retrieve the entire resource state using d.Id() only.

Tip

This import method highlights the importance of selecting a descriptive and unique resource ID. A good resource ID can retrieve the resource state via API. In some cases, you can construct an ID from multiple attributes (for example, <region>:<resource_id>).

Test the provider

Test the new provider capability by importing an order resource.

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

Then, create a new directory named import.

$ mkdir import

Navigate into the import directory.

$ cd import

Create a new file named main.tf with the following configuration. You will import an existing HashiCups order into the hashicups_order.sample resource.

examples/import/main.tf

terraform {
  required_providers {
    hashicups = {
      version = "0.2"
      source  = "hashicorp.com/edu/hashicups"
    }
  }
}

provider "hashicups" {
  username = "education"
  password = "test123"
}

resource "hashicups_order" "sample" {}

output "sample_order" {
  value = hashicups_order.sample
}

Initialize your workspace.

$ terraform init

Create an order via the HashiCups API. Take note of the order id in the response; the one below is 3. This will be the order number you import into hashicups_order.sample.

$ curl -X POST -H "Authorization: ${HASHICUPS_TOKEN}" localhost:19090/orders -d '[{"coffee": { "id":1 }, "quantity":4}, {"coffee": { "id":3 }, "quantity":3}]'
{
  "id": 3,
  "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
    }
  ]
}

Import the order into Terraform. Replace the order ID with the one the API returned above.

$ terraform import hashicups_order.sample 3
hashicups_order.sample: Importing from ID "3"...
hashicups_order.sample: Import prepared!
  Prepared hashicups_order for import
hashicups_order.sample: Refreshing state... [id=3]
Import successful!
The resources that were imported are shown above. These resources are now in
your Terraform state and will henceforth be managed by Terraform.

Use the state subcommand to verify Terraform successfully imported the HashiCups order.

$ terraform state show hashicups_order.sample
# hashicups_order.sample:
resource "hashicups_order" "sample" {
    id = "3"
    items {
        quantity = 4
        coffee {
            id     = 1
            image  = "/packer.png"
            name   = "Packer Spiced Latte"
            price  = 350
            teaser = "Packed with goodness to spice up your images"
        }
    }
    items {
        quantity = 3
        coffee {
            id     = 3
            image  = "/nomad.png"
            name   = "Nomadicano"
            price  = 150
            teaser = "Drink one today and you will want to schedule another"
        }
    }
}

Next steps

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

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

To start building a custom provider using a template, see the Terraform Provider Scaffold. Use this GitHub template when you are ready to create a custom provider.
To learn more about implementing imports, refer to the Resource - Import Documentation.
To learn how to import resources into Terraform, refer to the Import Terraform configuration tutorial.
To learn more about the Terraform Plugin SDK, refer to the Terraform Plugin SDK Documentation.

Delete

Publish