feat: support and document attaching a debugger to the provider (#617)

* feat: support and document attaching a debugger to the provider

* chore: fix documentation

CONTRIBUTION.md

@@ -389,40 +389,49 @@ If you want to onboard resources of a STACKIT service `foo` that was not yet in
 To test your changes locally, you have to compile the provider (requires Go 1.22) and configure the Terraform CLI to use the local version.
 
 1. Clone the repository.
-2. Set the provider address to a custom address for local development. It must correspond to the same address that is included in the dev_overrides block, in step 4.
+1. Create a `.terraformrc` config file in your home directory (`~`) for the terraform CLI with the following content:
-   In `main.go` replace the address `registry.terraform.io/providers/stackitcloud/stackit` with `local-dev.com/stackit/stackit`.
-3. Go to the repository root and compile the provider locally to any location by running `go build -o <PATH_TO_BINARY>`. The binary name must start with `terraform-provider`, e.g. `terraform-provider-stackit`.
-4. Create a `.terraformrc` config file in your home directory (`~`) for the terraform CLI with the following content:
 
-```
+	```
-provider_installation {
+	provider_installation {
-    dev_overrides {
+   	   dev_overrides {
-        "local-dev.com/stackit/stackit" = "<PATH_TO_BINARY>"
+	      "registry.terraform.io/stackitcloud/stackit" = "<PATH_TO_BINARY>"
-    }
+	   }
 
-    # For all other providers, install them directly from their origin provider
+	   # For all other providers, install them directly from their origin provider
-    # registries as normal. If you omit this, Terraform will _only_ use
+	   # registries as normal. If you omit this, Terraform will _only_ use
-    # the dev_overrides block, and so no other providers will be available.
+	   # the dev_overrides block, and so no other providers will be available.
-    direct {}
+	   direct {}
-}
+	}
-```
+	```
+1. Copy one of the folders in the [examples](examples/) folder to a location of your choosing, and define the Terraform variables according to its README. The main.tf file needs some additional configuration to use the local provider:
 
-4. Copy one of the folders in the [examples](examples/) folder to a location of your choosing, and define the Terraform variables according to its README. The main.tf file needs some additional configuration to use the local provider:
+	```
+	terraform {
+	   required_providers {
+	      stackit = {
+	         source = "registry.terraform.io/stackitcloud/stackit"
+	      }
+	   }
+	}
+	```
 
-```
+1. Go to the copied example and initialize Terraform by running `terraform init -reconfigure -upgrade`. This will throw an error ("Failed to query available provider packages") which can be ignored since we are using the local provider build.
-terraform {
-  required_providers {
-    stackit = {
-      source = "local-dev.com/stackit/stackit"
-    }
-  }
-}
-```
-
-5. Go to the copied example and initialize Terraform by running `terraform init -reconfigure -upgrade`. This will throw an error ("Failed to query available provider packages") which can be ignored since we are using the local provider build.
    > Note: Terraform will store its resources' states locally. To allow multiple people to use the same resources, check [Setup for multi-person usage](#setup-centralized-terraform-state)
-6. Setup authentication by setting the env var `STACKIT_SERVICE_ACCOUNT_TOKEN` as a valid token (see [Authentication](#authentication) for more details on how to autenticate).
+1. Setup authentication by setting the env var `STACKIT_SERVICE_ACCOUNT_TOKEN` as a valid token (see [Authentication](#authentication) for more details on how to autenticate).
-7. Run `terraform plan` or `terraform apply` commands.
+1. Run `terraform plan` or `terraform apply` commands.
+1. To debug the terraform provider, execute the following steps:
+	* install the compiled terraform provider to binary path defined in the .terraformrc file
+	* run the terraform provider from your IDE with the `-debug` flag set
+	* The provider will emit the setting for the env variable `TF_REATTACH_PROVIDERS`, e.g.
+
+	```shell
+		TF_REATTACH_PROVIDERS='{"registry.terraform.io/stackitcloud/stackit":{"Protocol":"grpc","ProtocolVersion":6,"Pid":123456,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin47110815"}}}'
+	```
+
+Starting terraform with this environment variable set will automatically connect to the running IDE session, instead of starting a new GRPC server with the plugin. This allows to set
+breakpoints and inspect the state of the provider.
+	
+
 
 #### Setup centralized Terraform state
 

main.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"context"
+	"flag"
 	"log"
 
 	"github.com/hashicorp/terraform-plugin-framework/providerserver"
@@ -14,8 +15,12 @@ var (
 )
 
 func main() {
+	var debug bool
+	flag.BoolVar(&debug, "debug", false, "allows debugging the provider")
+	flag.Parse()
 	err := providerserver.Serve(context.Background(), stackit.New(version), providerserver.ServeOpts{
 		Address: "registry.terraform.io/stackitcloud/stackit",
+		Debug:   debug,
 	})
 	if err != nil {
 		log.Fatal(err.Error())