»Debugging Providers

This guide documents a few different ways to access more information about the runtime operations of Terraform providers. It is intended for Terraform provider developers, though sufficiently advanced users may also be able to use it.

There are two available approaches to debugging Terraform providers. We'll talk about each of them separately and in turn.

»Log-Based Debugging

Log-based debugging is a method of using logging calls to record what is happening in a provider and then examining that record to diagnose issues. Logs can help you debug your provider without access to the environment or configuration.

When developing your provider, think carefully about what information you will need for debugging. Log lines cannot be inserted into the binary after it has been built. You will need to add a new log line and recompile your provider for new information to be surfaced in log output.

• Managing Log Output explains how to turn on logging, filter log output, choose the log format, and specify the log output path.
• Writing Log Output contains details about how to use the tflog package to write log output at varying verbosity levels, add variables to logs, and create subsystems to group logs that relate to distinct sections of code (e.g., the API client).

»Debugger-Based Debugging

Debugger-based debugging is a method of using a debugging tool similar to delve to inspect what is happening in a provider as it is happening, often using breakpoints to pause execution of the provider and examine the values of variables. This method of debugging must be done contemporaneously; the developer doing the debugging needs to actively run Terraform using the appropriate configuration and in the appropriate environment to induce the behavior being examined. It is therefore most useful when a bug is reliably reproducible. This level of analysis enables developers to ask arbitrary questions and step through provider executions, allowing them to explore what is happening in the provider during runtime.

»Enabling Debugging In A Provider

Debugging is available for providers using Terraform Plugin SDK versions 2.0.0 and above. The plugin must also be started in debug mode, called plugin.Debug instead of plugin.Serve. We recommend that you enable this using a flag, as the provider should use plugin.Serve under normal operation, when not being debugged.

func main() {
    var debugMode bool

    flag.BoolVar(&debugMode, "debug", false, "set to true to run the provider with support for debuggers like delve")
    flag.Parse()

    opts := &plugin.ServeOpts{ProviderFunc: provider.New}

    if debugMode {
        // TODO: update this string with the full name of your provider as used in your configs
        err := plugin.Debug(context.Background(), "registry.terraform.io/my-org/my-provider", opts)
        if err != nil {
            log.Fatal(err.Error())
        }
        return
    }

    plugin.Serve(opts)
}

func main() {    var debugMode bool
    flag.BoolVar(&debugMode, "debug", false, "set to true to run the provider with support for debuggers like delve")    flag.Parse()
    opts := &plugin.ServeOpts{ProviderFunc: provider.New}
    if debugMode {        // TODO: update this string with the full name of your provider as used in your configs        err := plugin.Debug(context.Background(), "registry.terraform.io/my-org/my-provider", opts)        if err != nil {            log.Fatal(err.Error())        }        return    }
    plugin.Serve(opts)}

It is important to start a provider in debug mode only when you intend to debug it, as its behavior will change in minor ways from normal operation of providers. The main differences are:

• Terraform will not start the provider process; it must be run manually.
• The provider's constraints will no longer be checked as part of terraform init.
• The provider will no longer be restarted once per walk of the Terraform graph; instead the same provider process will be reused until the command is completed.

»Starting A Provider In Debug Mode

Once a provider has a debug mode added to its main function, it can be activated. Run your debugger, and pass it the provider binary as the command to run, specifying whatever flags, environment variables, or other input is necessary to start your provider in debug mode:

$ dlv exec --headless ./terraform-provider-my-provider -- --debug

$ dlv exec --headless ./terraform-provider-my-provider -- --debug

Connect your debugger (whether it's your IDE or the debugger client) to the debugger server. Have it continue execution (it pauses the process by default) and it will print output like the following to stdout:

Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:

        TF_REATTACH_PROVIDERS='{"registry.terraform.io/my-org/my-provider":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}'

Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:
        TF_REATTACH_PROVIDERS='{"registry.terraform.io/my-org/my-provider":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}'

»Running Terraform With A Provider In Debug Mode

Copy the line starting with TF_REATTACH_PROVIDERS from your provider's output. Either export it, or prefix every Terraform command with it:

TF_REATTACH_PROVIDERS='{"registry.terraform.io/my-org/my-provider":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}' terraform apply

TF_REATTACH_PROVIDERS='{"registry.terraform.io/my-org/my-provider":{"Protocol":"grpc","Pid":3382870,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin713096927"}}}' terraform apply

Run Terraform as usual. Any breakpoints you have set will halt execution and show you the current variable values.