Implement Create

15min
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 create an order resource for a Terraform provider that interacts with the API of a fictional coffee-shop application called Hashicups. Then, you will use the schema to create a new order and populate the order. To do this, you will:

Define order resource.
You will add a scaffold that defines an empty schema and functions to create, read, update and delete orders.
Define order schema.
The schema contains fields used to create a new order and retrieved by the read functionality.
Add create functionality.
The create function invokes a POST request to /orders to create a new order.
Add read functionality.
The read function invokes a GET request to /orders/{orderID} to retrieve the order's data. The orders schema contains a nested object, therefore you will use multiple flattening functions to map the response to the order schema.
Add order resource to the provider schema.
This allows you to use the resource in your configuration.

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 debug-tf-provider branch. This step is optional but recommended to ensure that your code matches the code from the previous tutorials.

$ git checkout debug-tf-provider

Clone the debug-tf-providers branch of the Terraform HashiCups Provider repository.

$ git clone --branch debug-tf-providers 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 then run docker-compose up to spin up a local instance of HashiCups on port :19090.

$ cd docker_compose && 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 created, updated and deleted.

$ export HASHICUPS_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1OTEwNzgwODUsInVzZXJfaWQiOjIsInVzZXJuYW1lIjoiZWR1Y2F0aW9uIn0.CguceCNILKdjOQ7Gx0u4UAMlOTaH3Dw-fsll2iXDrYU

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
├── go.mod
├── go.sum
├── hashicups
│   ├── data_source_coffee.go
│   ├── data_source_order.go
│   └── provider.go
├── main.go
└── vendor

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

Define `order` resource

Add the following code snippet to a new file named hashicups/resource_order.go in the hashicups directory. As a general convention, Terraform providers put each resource in their own file, named after the resource, prefixed with resource_.

hashicups/resource_order.go

package hashicups

import (
  "context"

  "github.com/hashicorp/terraform-plugin-sdk/v2/diag"
  "github.com/hashicorp/terraform-plugin-sdk/v2/helper/schema"
)

func resourceOrder() *schema.Resource {
  return &schema.Resource{
    CreateContext: resourceOrderCreate,
    ReadContext:   resourceOrderRead,
    UpdateContext: resourceOrderUpdate,
    DeleteContext: resourceOrderDelete,
    Schema: map[string]*schema.Schema{},
  }
}

func resourceOrderCreate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  return diags
}

func resourceOrderRead(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  return diags
}

func resourceOrderUpdate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  return resourceOrderRead(ctx, d, m)
}

func resourceOrderDelete(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  return diags
}

This serves as a scaffold for the order resource. Notice, the order resource defines create, read, update and delete (CRUD) functionality. In this tutorial, you will only implement create and read to create and read a new order resource.

Format your code.

$ go fmt ./...

Define `order` schema

To create a HashiCups order, you would send a POST request to the /orders endpoint with a list of OrderItems, containing the coffee object and its respective quantity.

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

Replace the line Schema: map[string]*schema.Schema{}, in your resourceOrder function with the following schema. The order resource schema should resemble the request body.

hashicups/resource_order.go

Schema: map[string]*schema.Schema{
  "items": &schema.Schema{
    Type:     schema.TypeList,
    Required: true,
    Elem: &schema.Resource{
      Schema: map[string]*schema.Schema{
        "coffee": &schema.Schema{
          Type:     schema.TypeList,
          MaxItems: 1,
          Required: true,
          Elem: &schema.Resource{
            Schema: map[string]*schema.Schema{
              "id": &schema.Schema{
                Type:     schema.TypeInt,
                Required: true,
              },
              "name": &schema.Schema{
                Type:     schema.TypeString,
                Computed: true,
              },
              "teaser": &schema.Schema{
                Type:     schema.TypeString,
                Computed: true,
              },
              "description": &schema.Schema{
                Type:     schema.TypeString,
                Computed: true,
              },
              "price": &schema.Schema{
                Type:     schema.TypeInt,
                Computed: true,
              },
              "image": &schema.Schema{
                Type:     schema.TypeString,
                Computed: true,
              },
            },
          },
        },
        "quantity": &schema.Schema{
          Type:     schema.TypeInt,
          Required: true,
        },
      },
    },
  },
},

Format your code.

$ go fmt ./...

This order schema should be similar to the order data resource defined in the previous Implement Complex Read tutorial with two significant changes.

The top level id attribute is missing in the order resource, but present in the order data resource. Unlike the order data source, you don't know the order ID ahead of time. When HashiCups provider invokes the HashiCups API, the API generates an order ID which is then assigned as the resource's ID by the HashiCups provider.
items is a required field, not a computed one. This is because the OrderItems need to be defined to create an order.

There are multiple ways to nest maps.

The first (see coffee object) is to define the nested object as an schema.TypeList with 1 item. This is currently the closest way to emulate a nested object.
The second way is to use a schema.TypeMap. This method may be preferable if you only require a key value map of primitive types. However, you should use a validation function to enforce required keys.

Notice that the coffee object is represented as a schema.TypeList of one item. This method was selected because it closely matches the coffee object returned in the response.

Implement create

Now that you have defined the order resource schema, replace the resourceOrderCreate function in hashicups/resource_order.go with the following code snippet. This function will create a new HashiCups order and Terraform resource.

hashicups/resource_order.go

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

  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  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)
  }

  o, err := c.CreateOrder(ois)
  if err != nil {
    return diag.FromErr(err)
  }

  d.SetId(strconv.Itoa(o.ID))

  return diags
}

Since this uses strconv to convert the ID into a string, import the strconv library. Also, import the HashiCups API client library.

hashicups/resource_order.go

import (
  "context"
  "strconv"

  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"
)

Format your code.

$ go fmt ./...

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 retrieves the order attributes using d.Get("items") — order items are located in items as defined in the schema — and typecasts it to a []interface{}. Then, the function transforms the items into a slice of OrderItem, a struct required by the HashiCups API client to create an order.

Finally, upon successful order creation, SetID sets the resource ID to the order ID. The resource ID must be a non-blank string that can be used to read the resource again. If no ID is set, Terraform assumes the resource was not created successfully; as a result, no state will be saved for that resource.

Implement read

Now that you have implemented create, you must implement read to retrieve the resource current state. This will be run during the plan process to determine whether the resource needs to be updated.

Replace the resourceOrderRead function in hashicups/resource_order.go with the following code snippet.

hashicups/resource_order.go

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

  // Warning or errors can be collected in a slice type
  var diags diag.Diagnostics

  orderID := d.Id()

  order, err := c.GetOrder(orderID)
  if err != nil {
    return diag.FromErr(err)
  }

  orderItems := flattenOrderItems(&order.Items)
  if err := d.Set("items", orderItems); err != nil {
    return diag.FromErr(err)
  }

  return diags
}

Format your code.

$ go fmt ./...

This function should be similar to the dataSourceOrderRead function in hashicups/data_resource_order.go with two significant change.

The order resource's read function (resourceOrderRead) uses d.ID() as the order ID. The order data resource's read function (dataSourceOrderRead) uses an order ID provider by the user.
The function uses flattenOrderItems instead of flattenOrderItemsData because the order resource and the order data source uses different schemas. You will define the flattenOrderItems in the next section.

Add flattening functions

The API Client's GetOrder function returns an order object that needs to be "flattened" so the provider can accurately map it to the order schema. An order consists of an order ID and a list of coffee objects and their respective quantities.

As a result, it must go through two flattening functions:

The first flattening function populates the list of coffee objects and their quantities
The second flattening function populates the actual coffee object itself.

Add the following function to your hashicups/resource_order.go file. This is the first flattening function to return a list of order items. The flattenOrderItems function takes an *[]hc.OrderItem as orderItems. If orderItems is not nil, it will iterate through the slice and map its values into a map[string]interface{}.

hashicups/resource_order.go

func flattenOrderItems(orderItems *[]hc.OrderItem) []interface{} {
  if orderItems != nil {
    ois := make([]interface{}, len(*orderItems), len(*orderItems))

    for i, orderItem := range *orderItems {
      oi := make(map[string]interface{})

      oi["coffee"] = flattenCoffee(orderItem.Coffee)
      oi["quantity"] = orderItem.Quantity
      ois[i] = oi
    }

    return ois
  }

  return make([]interface{}, 0)
}

Then, add the second flattening function, flattenCoffee, to your hashicups/resource_order.go file. This is called in the first flattening function. It takes a hc.Coffee and returns a slice with a single object. Notice how this mirrors the coffee schema — a schema.TypeList with a maximum of one item.

hashicups/resource_order.go

func flattenCoffee(coffee hc.Coffee) []interface{} {
  c := make(map[string]interface{})
  c["id"] = coffee.ID
  c["name"] = coffee.Name
  c["teaser"] = coffee.Teaser
  c["description"] = coffee.Description
  c["price"] = coffee.Price
  c["image"] = coffee.Image

  return []interface{}{c}
}

Format your code.

$ go fmt ./...

Add read function to create function

Finally, add resourceOrderRead to the bottom of your resourceOrderCreate function. This will populate the Terraform state to its current state after the resource creation.

hashicups/resource_order.go

func resourceOrderCreate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
  // ...

  d.SetId(strconv.Itoa(o.ID))

  resourceOrderRead(ctx, d, m)

  return diags
}

Format your code.

$ go fmt ./...

Add `order` resource to provider

Now that you've defined the order resource, you can add it to your provider.

In your hashicups/provider.go file, add the order resource to the ResourceMap. Resources and data sources names must follow the <provider>_<resource_name> convention.

hashicups/provider.go

// Provider -
func Provider() *schema.Provider {
  return &schema.Provider{
    Schema: map[string]*schema.Schema{
      "username": &schema.Schema{
        Type:        schema.TypeString,
        Optional:    true,
        DefaultFunc: schema.EnvDefaultFunc("HASHICUPS_USERNAME", nil),
      },
      "password": &schema.Schema{
        Type:        schema.TypeString,
        Optional:    true,
        Sensitive:   true,
        DefaultFunc: schema.EnvDefaultFunc("HASHICUPS_PASSWORD", nil),
      },
    },
    ResourcesMap: map[string]*schema.Resource{
      "hashicups_order": resourceOrder(),
    },
    DataSourcesMap: map[string]*schema.Resource{
      "hashicups_coffees":     dataSourceCoffees(),
      "hashicups_order":       dataSourceOrder(),
    },
    ConfigureContextFunc: providerConfigure,
  }
}

Format your code.

$ go fmt ./...

Test the provider

Now that you've created the order resource with create and read capabilities, 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

Add the following Terraform configuration to main.tf.

examples/main.tf

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

output "edu_order" {
  value = hashicups_order.edu
}

Initialize your workspace to refresh your HashiCups provider then apply the configuration. This should create an order and return its values in your output.

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

Next steps

In this tutorial, you created the order resource with create and read capabilities.

If you were stuck during this tutorial, checkout the implement-create 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.

Prerequisites

Define order resource

Define order schema

Implement create

Implement read

Add flattening functions

Add read function to create function

Add order resource to provider

Test the provider

Next steps

Define `order` resource

Define `order` schema

Add `order` resource to provider