add debug documentation
@@ -88,6 +88,64 @@ $ make testacc TESTARGS='-run=TestAccAiven_kafka'
For information about writing acceptance tests, see the main [Terraform contributing guide](https://www.terraform.io/docs/extend/testing/acceptance-tests/index.html).
+## Debugging
+### Requirements
+- [Terraform](https://www.terraform.io/downloads.html) v0.12.26 or greater
+- [Delve](https://github.com/go-delve/delve/tree/master/Documentation/installation) 1.7.X or greater
+
+### Starting the Provider Plugin with `dlv`
+
+To start debugging the provider we use the `dlv debug` command and pass the `-debug` flag to the compiled binary:
+
+```bash
+$ dlv debug -- -debug
+Type 'help' for list of commands.
+(dlv)
+```
+
+Next, we set a breakpoint at a function that we want to look into and continue to start the plugin:
+
+```bash
+(dlv) break resourceServiceCreate
+Breakpoint 1 set at 0x129667b for github.com/aiven/terraform-provider-aiven/aiven.resourceServiceCreate() ./aiven/resource_service.go:806
+(dlv) c
+{"@level":"debug","@message":"plugin address","@timestamp":"2021-10-12T16:36:45.528158+02:00","address":"/tmp/plugin252726151","network":"unix"}
+Provider started, to attach Terraform set the TF_REATTACH_PROVIDERS env var:
+ TF_REATTACH_PROVIDERS='{"registry.terraform.io/aiven/aiven":{"Protocol":"grpc","ProtocolVersion":5,"Pid":3153652,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin252726151"}}}'
+```
+
+Next, in a different terminal session we start terraform using the `TF_REATTACH_PROVIDERS` environment variable:
+
+```bash
+$ export TF_REATTACH_PROVIDERS='{"registry.terraform.io/aiven/aiven":{"Protocol":"grpc","ProtocolVersion":5,"Pid":3153652,"Test":true,"Addr":{"Network":"unix","String":"/tmp/plugin252726151"}}}'
+
+$ terraform init -upgrade
+<...>
+$ terraform plan
+<...>
+$ terraform apply -parallelism=1
+<...>
+aiven_pg.testing: Creating...
+```
+
+Now we can see that the debugged process did hit the breakpoint we specified earlier:
+
+```bash
+> github.com/aiven/terraform-provider-aiven/aiven.resourceServiceCreate() ./aiven/resource_service.go:806 (hits goroutine(326):1 total:1) (PC: 0x129667b)
+ 801: return resourceServiceCreate(ctx, d, m)
+ 802: }
+ 803:
+ 804: }
+ 805:
+=> 806: func resourceServiceCreate(ctx context.Context, d *schema.ResourceData, m interface{}) diag.Diagnostics {
+ 807: client := m.(*aiven.Client)
+ 808: serviceType := d.Get("service_type").(string)
+ 809: userConfig := ConvertTerraformUserConfigToAPICompatibleFormat("service", serviceType, true, d)
+ 810: vpcID := d.Get("project_vpc_id").(string)
+ 811: var apiServiceIntegrations []aiven.NewServiceIntegration
+```
+
+
### Adding Dependencies
This provider uses [Go modules](https://blog.golang.org/using-go-modules).
