Implement import
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.
Then, checkout the implement-delete
branch. This step is optional but recommended to ensure that your code matches the code from the previous tutorials.
Your directory should have the following structure.
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.
Format your code.
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 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.
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.
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.
Navigate to the terraform-provider-hashicups/examples
directory. This contains a sample Terraform configuration for the Terraform HashiCups provider.
Then, create a new directory named import
.
Navigate into the import
directory.
Create a new file named main.tf
with the following configuration. You will import an existing HashiCups order into the hashicups_order.sample
resource.
Initialize your workspace.
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
.
Import the order into Terraform. Replace the order ID with the one the API returned above.
Use the state
subcommand to verify Terraform successfully imported the HashiCups order.
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.