Add .vscode/ to .gitignore, add launch configuration samples elsewhere in repo, update debugging docs (#36527)

* Remove .vscode/ from version control

* Add section about debugging automated tests

* Update existing debugging advice to reference  example file, deduplicate text about automated tests

* Add details about launching TF ni debug mode from within VS Code

* Respond to review feedback, other small edits like full-stops

.gitignore

@@ -27,3 +27,6 @@ vendor/
 
 # Coverage
 coverage.txt
+
+# IDEs
+.vscode/

docs/debugging-configs/vscode/debug-automated-tests/launch.json

@@ -0,0 +1,27 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            // Highlight a test's name with your cursor and run this debugger configuration
+            // from the debugger tools in the left-side Activity Bar.
+            // This will result in the equivalent of this command being run using the debugger:
+            // `go test -v -run ^<selected text>$ <the current opened file's folder path>`
+            "name": "Run selected test",
+            "request": "launch",
+            "type": "go",
+            "args": [
+                "-test.v",
+                "-test.run",
+                "^${selectedText}$"
+            ],
+            // Environment variables can be set from a file or as key-value pairs in the configuration.
+            // "env": {
+            //     "MY_ENV": "my-value",
+            // },
+            // "envFile": "./vscode/private.env",
+            "mode": "auto",
+            "program": "${fileDirname}",
+            "showLog": true // dlv's logs
+        }
+    ]
+}

docs/debugging-configs/vscode/launch-from-vscode-debugger/launch.json

@@ -0,0 +1,27 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        {
+            // Runs Terraform using the Terraform configuration specified via the chdir argument
+            "name": "Run Terraform in debug mode",
+            "request": "launch",
+            "type": "go",
+            "args": [
+                "-chdir=<absolute path to a Terraform configuration>",
+                // Change this array to perform different terraform commands with different arguments.
+                "plan",
+                "-var='name=value'"
+            ],
+            // "cwd": "<absolute path to a Terraform configuration>", // An alternative to using the -chdir global flag above.
+            // Environment variables can be set from a file or as key-value pairs in the configuration.
+            // "env": {
+            //     "MY_ENV": "my-value",
+            // },
+            // "envFile": "./vscode/private.env",
+            "mode": "debug",
+            "program": "${workspaceFolder}",
+            "console": "integratedTerminal", // allows responding to y/n in terminal, e.g. in apply command.
+            "showLog": false // dlv's logs
+        }
+    ]
+}

docs/debugging.md

@@ -1,8 +1,45 @@
 # How to Debug Terraform
 
+Contents:
+- [Debugging automated tests](#debugging-automated-tests)
+    - [Debugging automated tests in VSCode](#debugging-automated-tests-in-vscode)
+- [Debugging Terraform operations that use real Terraform configurations](#debugging-terraform-operations-that-use-real-terraform-configurations)
+    - [Launch Terraform with the `dlv` CLI tool](#launch-terraform-with-the-dlv-cli-tool)
+    - [Launch Terraform with VS Code's debugging tool](#launch-terraform-with-vs-codes-debugging-tool)
+
+
 As Terraform is written in Go you may use [Delve](https://github.com/go-delve/delve) to debug it.
 
-## 1. Compile & Start Debug Server
+GoLand includes [debugging features](https://www.jetbrains.com/help/go/debugging-code.html), and the [Go extension for VS Code](https://code.visualstudio.com/docs/languages/go#_debugging) makes it easy to use Delve when debugging Go codebases in VS Code. 
+
+## Debugging automated tests
+
+Debugging an automated test is often the most straightforward workflow for debugging a section of the codebase. For example, the Go extension for VS Code](https://code.visualstudio.com/docs/languages/go#_debugging) adds `run test | debug test` options above all tests in a `*_test.go` file. These allow debugging without any prior configuration.
+
+### Debugging automated tests in VSCode
+
+As described above, debugging tests in VS Code is easily achieved through the Go extension.
+
+If you need more control over how tests are run while debugging, e.g. environment variable values, look at the [example debugger launch configuration 'Run selected test'](./debugging-configs/vscode/debug-automated-tests/launch.json). You can adapt this example to create your own [launch configuration file](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations).
+
+When using this launch configuration you must highlight a test's name before starting the debugger:
+
+<p align="center">
+    <img width="75%" alt="Debugging a single test using the example 'Run selected test' debugger configuration shared in this repository" src="./images/vscode-debugging-test.png"/>
+</p>
+
+
+## Debugging Terraform operations that use real Terraform configurations
+
+### Launch Terraform with the `dlv` CLI tool
+
+In this workflow you:
+* Build Terraform using compiler flags.
+* Start a debug server with a command containing the terraform command you want to debug.
+    * This command is run in the working directory that contains your Terraform configuration.
+* Connect to the debug server to monitor progress through breakpoints.
+
+#### 1. Compile & Start Debug Server
 
 One way to do it is to compile a binary with the [appropriate compiler flags](https://pkg.go.dev/cmd/compile#hdr-Command_Line):
 
@@ -13,10 +50,11 @@ go install -gcflags="all=-N -l"
 This enables you to then execute the compiled binary via Delve, pass any arguments and spin up a debug server which you can then connect to:
 
 ```sh
-dlv exec $GOBIN/terraform --headless --listen :2345 --log -- apply
+# Update the path to the terraform binary if your install directory is influenced by $GOPATH or $GOBIN
+dlv exec $HOME/go/bin/terraform --headless --listen :2345 --log -- apply
 ```
 
-## 2a. Connect via CLI
+#### 2a. Connect via CLI
 
 You may connect to the headless debug server via Delve CLI
 
@@ -24,10 +62,36 @@ You may connect to the headless debug server via Delve CLI
 dlv connect :2345
 ```
 
-## 2b. Connect from VS Code
+#### 2b. Connect from VS Code
 
-The repository provides a launch configuration, making it possible to use VS Code's native debugging integration:
+The repository provides [an example 'Connect to dlv server' launch configuration](./debugging-configs/vscode/launch-via-cli/launch.json), making it possible to use VS Code's native debugging integration via the [Go extension for VS Code](https://code.visualstudio.com/docs/languages/go#_debugging):
 
-![vscode debugger](./images/vscode-debugging.png)
+<p align="center">
+    <img width="75%" alt="vscode debugger" src="./images/vscode-debugging.png"/>
+</p>
 
-Note that this debugging workflow is different from the test-based one, which itself shouldn't require any of the above steps above nor the mentioned launch configuration. Meaning, that if you already have a test that hits the right lines of code you want to be debugging, or you can write one, then that may be an easier workflow.
+
+### Launch Terraform with VS Code's debugging tool
+
+In this workflow you:
+* Update the debugger's launch configuration to point at the directory containing your Terraform configuration.
+* Start the debugger through VS Code and monitor progress through breakpoints.
+
+#### 1. Update the debugger's launch configuration
+
+Look at the [example debugger launch configuration 'Run Terraform in debug mode'](./debugging-configs/vscode/launch-from-vscode-debugger/launch.json). You can adapt this example to create your own [launch configuration file](https://code.visualstudio.com/docs/editor/debugging#_launch-configurations).
+
+To use this launch configuration:
+* Prepare a local Terraform project.
+* Get the absolute path to that directory.
+* Update the launch configuration to use that path, either in the `-chdir` argument or as a `cwd` attribute in the launch configuration.
+* Make sure the `args` array's element reflect the command you'd like to debug.
+* Provide any required environment variables through the `env` or `envFile` attributes.
+
+#### 2. Run the launch configuration in VS Code
+
+Navigate to the Run and Debug view in the left-side Activity Bar. After selecting the `Run Terraform in debug mode` configuration in the Run and Debug view from the left-side, press the green arrow.
+
+This is equivalent to running a Terraform CLI command in the local Terraform project's directory. For example, if you run and debug a plan command that saves a plan file, that plan file will be created.
+
+This workflow is useful if you need to set up a complicated prior state to replicate a bug or if you want to debug code behaviour given a specific configuration.