Merge pull request #598 from hashicorp/mjyocca/allow-tf-attach-provid…

…ers-debug-mode

Enable debug mode on provider, via `TF_REATTACH_PROVIDERS`

CONTRIBUTING.md

@@ -111,3 +111,117 @@ markdown will display correctly on the Registry:
 - ENHANCEMENTS: Use this for smaller new features added.
 - BUG FIXES: Use this for any bugs that were fixed.
 - NOTES: Use this section if you need to include any additional notes on things like upgrading, upcoming deprecations, or any other information you might want to highlight.
+
+
+### Setup Provider to debug locally
+
+Find more information [here](https://www.terraform.io/plugin/debugging#starting-a-provider-in-debug-mode)
+
+Clone the repository and build the provider binary with the necessary Go compiler flags: `-gcflags=all=-N -l`, to disable compiler optimization in order for the debugger to work efficiently.
+
+```sh
+$ git clone [email protected]:hashicorp/terraform-provider-tfe
+$ cd terraform-provider-tfe
+$ go build -gcflags="all=-N -l" -o {where to place the binary}
+```
+
+example, replace {platform}. 
+```sh
+go build -gcflags="all=-N -l" -o bin/registry.terraform.io/hashicorp/tfe/9.9.9/{platform}/terraform-provider-tfe
+```
+
+You can activate the debugger via your editor such as [visual studio code](https://www.terraform.io/plugin/debugging#visual-studio-code) or the Delve CLI.
+
+
+#### Delve
+
+```sh
+dlv exec \
+--accept-multiclient \
+--continue \
+--headless {location of the binary} \
+-- -debug
+```
+
+example 
+```sh
+dlv exec \
+--accept-multiclient \
+--continue \
+--headless bin/registry.terraform.io/hashicorp/tfe/9.9.9/{platform}/terraform-provider-tfe \
+-- -debug
+```
+
+##### Visual Studio Code
+
+Example taken from [here](https://www.terraform.io/plugin/debugging#visual-studio-code)
+```
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Debug Terraform Provider",
+            "type": "go",
+            "request": "launch",
+            "mode": "debug",
+            // this assumes your workspace is the root of the repo
+            "program": "${workspaceFolder}",
+            "env": {},
+            "args": [
+                "-debug",
+            ]
+        }
+    ]
+}
+
+```
+
+You'll know you activated the debugger successfully if you see the following output. 
+
+*For vscode, the output will be located in the Debug Console tab.*
+
+```sh
+# Provider server started
+export TF_REATTACH_PROVIDERS='{...}'
+```
+
+In the other project make sure you're pointing to your local provider binary you created in the previous step.
+
+Can leverage `.terraformrc` file to override Terraform's default installation behaviors and use a local mirror for the providers you wish to use.
+
+example:
+
+```
+provider_installation {
+  filesystem_mirror {
+    path = "" # path to provider binary binary
+    # path = "/Users/{users}/projects/terraform-provider-tfe/bin/" macos example
+    include = ["registry.terraform.io/hashicorp/tfe"]
+  }
+}
+```
+
+Initialize Terraform in the project you wish to debug from via `terraform init`
+
+Should see the following output with the previous examples being used
+
+```
+Initializing provider plugins...
+- Finding latest version of hashicorp/tfe...
+- Installing hashicorp/tfe v9.9.9...
+- Installed hashicorp/tfe v9.9.9 (unauthenticated)
+```
+
+Copy the value of `TF_REATTACH_PROVIDERS` outputted by the debugger session and either export into your shell or lead your Terraform commands setting this value:
+
+```
+TF_REATTACH_PROVIDERS='{...}' terraform {command}
+```
+
+The breakpoints you have set will halt execution and show you the current variable values.
+
+If using the Delve CLI, include the full qualifed path to set a breakpoint.
+
+```
+(delve) b /Users/{user}/path/to/terraform-provider-tfe/tfe/resource_example.go:35
+```

main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"flag"
 	"log"
 	"os"
 
@@ -24,6 +25,14 @@ func main() {
 	logFlags &^= (log.Ldate | log.Ltime)
 	log.SetFlags(logFlags)
 
+	debugFlag := flag.Bool("debug", false, "Start provider in debug mode.")
+	flag.Parse()
+
+	var serveOpts []tf5server.ServeOpt
+
+	if *debugFlag {
+		serveOpts = append(serveOpts, tf5server.WithManagedDebug())
+	}
 	// terraform-plugin-mux here is used to combine multiple Terraform providers
 	// built using different SDK and frameworks in order to combine them into a
 	// single logical provider for Terraform to work with.
@@ -43,7 +52,7 @@ func main() {
 
 	err = tf5server.Serve(tfeProviderName, func() tfprotov5.ProviderServer {
 		return mux.Server()
-	})
+	}, serveOpts...)
 	if err != nil {
 		log.Printf("[ERROR] Could not start serving the ProviderServer: %v", err)
 		os.Exit(1)