tfsdk: Added Debug field to ServeOpts for running providers via debugger and testing processes

[bflad]

Closes #239
Reference: https://www.terraform.io/plugin/sdkv2/debugging

Similar to Terraform Plugin SDK, providers need to be executable via debugger and testing processes for instrumenting the provider code. In this workflow, the caller manages the provider lifecycle, rather than Terraform CLI. The Terraform CLI reattach configuration is output to stdout.

Verified in a framework-based provider by:

• go mod edit -replace=github.com/hashicorp/terraform-plugin-framework=/Users/bflad/src/github.com/hashicorp/terraform-plugin-framework (use this worktree)
• Updated provider main function code to

func main() {
	var debug bool

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

	var err error
	ctx := context.Background()
	serveOpts := tfsdk.ServeOpts{
		Name: "registry.terraform.io/bflad/framework",
	}

	if debug {
		err = tfsdk.Debug(ctx, provider.New, serveOpts)
	} else {
		err = tfsdk.Serve(ctx, provider.New, serveOpts)
	}

	if err != nil {
		fmt.Printf("Error serving provider: %s", err)
		os.Exit(1)
	}
}

• Added provider VSCode configuration to .vscode/launch.json (refer also to terraform-provider-scaffolding)

        {
            "name": "Debug - Attach External CLI",
            "type": "go",
            "request": "launch",
            "mode": "debug",
            // this assumes your workspace is the root of the repo
            "program": "${workspaceFolder}",
            "env": {},
            "args": [
                // pass the debug flag for reattaching
                "-debug",
            ],
        }

• In provider code, set a breakpoint
• Launched debug process
• Copied TF_REATTACH_PROVIDERS string from Outputs > Go Debug
• Exported environment variable and executed Terraform CLI
• Breakpoint hit and halted further execution

[bflad]

Note: This is temporary until terraform-plugin-go is updated: hashicorp/terraform-plugin-go#123

[bflad]

Aside: Instead of introducing an exported function, we could also implement this by adding a Debug bool field to ServeOpts, then triggering this logic via an unexported function. Thinking about that again, maybe that would be a cleaner implementation for providers rather than forcing them to implement the conditional between serving functions.

[bflad]

Opted to go with the ServeOpts approach!

[bflad]

Switched this to using a Debug bool field in ServeOpts and its cleaner for provider implementations (and not bloating the tfsdk function surface area further). 👍

Verified with this main function:

func main() {
	var debug bool

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

	ctx := context.Background()
	serveOpts := tfsdk.ServeOpts{
		Debug: debug,
		Name:  "registry.terraform.io/bflad/framework",
	}

	err := tfsdk.Serve(ctx, provider.New, serveOpts)

	if err != nil {
		fmt.Printf("Error serving provider: %s", err)
		os.Exit(1)
	}
}

[ewbankkit]

Will this work with a muxed provider?

[bflad]

terraform-plugin-mux would likely require its own debug functionality, since providers are served using the terraform-plugin-go server implementations, rather than the SDK or framework implementations. I'll open an issue to investigate that further there, thanks for the call out!

[bflad]

Almost all of this code could be removed via an upstream implementation such as: hashicorp/terraform-plugin-go#137

func Serve(ctx context.Context, providerFunc func() Provider, opts ServeOpts) error {
	var tf6serverOpts []tf6server.ServeOpt

	if opts.Debug {
		tf6serverOpts = append(tf6serverOpts, tf6server.WithManagedDebug())
	}

	return tf6server.Serve(opts.Name, func() tfprotov6.ProviderServer {
		return &server{
			p: providerFunc(),
		}
	}, tf6serverOpts...)
}

It may be worth getting that in before recreating the implementation here.

[bflad]

Rebased on [email protected] and ready for review. 👍

[ewbankkit]

LGTM 🚀.

[github-actions]

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active contributions.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.