Debug a Terraform Provider

11min
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 custom error messages to a Terraform provider that interacts with the API of a fictional coffee-shop application called Hashicups and view detailed Terraform provider logs.

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

$ git checkout implement-complex-read

Clone the implement-complex-read branch of the Terraform HashiCups Provider repository.

$ git clone --branch implement-complex-read 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

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
│   └── provider.go
├── main.go
└── vendor

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

Update error messages

In your hashicups/provider.go file, the providerConfigure function returns an interface{} and a diag.Diagnostics type. diag.Diagnostics can return multiple errors and warnings to Terraform, giving users more robust error and warning messages.

hashicups/provider.go

func providerConfigure(...) (interface{}, diag.Diagnostics) {
  ...
}

The diag.FromError() function casts standard Go errors to diag.Diagnostics type notifying the user whenever the provider errors.

Replace the return nil, diag.FromError(err) line in your providerConfigure function with the following code snippet. There should be two replacements — one where the user's HashiCups credentials provided and the other where its not. Notice how this appends a diag.Diagnostic type to the existing diags variable; this allows your provider to return multiple error message. This will produce an error message containing Summary and Detail contents.

hashicups/provider.go

diags = append(diags, diag.Diagnostic{
  Severity: diag.Error,
  Summary:  "Unable to create HashiCups client",
  Detail:   "Unable to auth user for authenticated HashiCups client",
})

return nil, diags

Your providerConfigure function should look like the following.

hashicups/provider.go

func providerConfigure(ctx context.Context, d *schema.ResourceData) (interface{}, diag.Diagnostics) {
  username := d.Get("username").(string)
  password := d.Get("password").(string)

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

  if (username != "") && (password != "") {
    c, err := hashicups.NewClient(nil, &username, &password)
    if err != nil {
      diags = append(diags, diag.Diagnostic{
        Severity: diag.Error,
        Summary:  "Unable to create HashiCups client",
        Detail:   "Unable to auth user for authenticated HashiCups client",
      })
      return nil, diags
    }

    return c, diags
  }

  c, err := hashicups.NewClient(nil, nil, nil)
  if err != nil {
    diags = append(diags, diag.Diagnostic{
      Severity: diag.Error,
      Summary:  "Unable to create HashiCups client",
      Detail:   "Unable to auth user for unauthenticated HashiCups client",
    })
    return nil, diags
  }

  return c, diags
}

Format your code.

$ go fmt ./...

Notice how the Diagnostic severity is set to diag.Error. There are two levels of severity — diag.Error and diag.Warning. You will create and view a warning message in the next section.

Test error message

Now that you've added a custom error message, verify that the provider returns your error message.

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 provider configuration so it uses the wrong credentials.

examples/main.tf

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

Next, initialize your workspace to refresh your HashiCups provider, then apply. This should return the error message you defined above.

$ terraform init && terraform apply --auto-approve
## ...
module.psl.data.hashicups_coffees.all: Refreshing state...

Error: Unable to create HashiCups client

Unable to auth user for authenticated HashiCups client

Because your provider errors, your Terraform state doesn't update when you ran the terraform apply.

Add warning message

Add the following snippet after diags is declared in providerConfigure function.

hashicups/provider.go

diags = append(diags, diag.Diagnostic{
  Severity: diag.Warning,
  Summary:  "Warning Message Summary",
  Detail:   "This is the detailed warning message from providerConfigure",
})

Your providerConfigure function should look like the following.

hashicups/provider.go

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

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

  diags = append(diags, diag.Diagnostic{
    Severity: diag.Warning,
    Summary:  "Warning Message Summary",
    Detail:   "This is the detailed warning message from providerConfigure",
  })

  ...
}

Format your code.

$ go fmt ./...

Notice that you have set the Diagnostic's severity to diag.Warning. When you use your provider, both warning and messages appear because diags contains both. A warning message will only appear when the provider also errors.

The Diagnostic's detail contains additional information about the warning message, including which function it was triggered in. This could provide handy while debugging.

Test warning message

Now that you've added a warning message and updated your Terraform log level, verify that the provider returns both your warning and error message.

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

Then, 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

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

Next, initialize your workspace to refresh your HashiCups provider, then apply. This should return both a warning and error message.

$ terraform init && terraform apply --auto-approve
## ...
module.psl.data.hashicups_coffees.all: Refreshing state...

Warning: Warning Message Summary

This is the detailed warning message from providerConfigure


Error: Unable to create HashiCups client

Unable to authenticate user for authenticated HashiCups client

Because your provider errors, your Terraform state doesn't update when you ran the terraform apply.

Fix provider

Comment out or remove the warning message, then recompile your Terraform provider.

hashicups/provider.go

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

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

  diags = append(diags, diag.Diagnostic{
    Severity: diag.Warning,
    Summary:  "Warning Message Summary",
    Detail:   "This is the detailed warning message from providerConfigure",
  })

  ...
}

Fix your Terraform configuration to use the correct credentials.

examples/main.tf

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

Finally, re-initializing your workspace and applying the configuration.

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

There should be no errors or warning messages.

Tip

You can also retrieve detailed Terraform and provider logs by setting the environment variable TF_LOG. Please include a detailed logs with any bug reports so the author can identify and address the bug. To learn more about log levels and how to interpret a crash log, refer to the Debugging Terraform Documentation.

Next steps

In this tutorial, you added error and warning messages to your HashiCups provider and implemented a nested read function.

If you were stuck during this tutorial, checkout the debug-tf-providers 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.