Skip to content

Commit 6784407

Browse files
SarahFrenchSarahFrench
authored
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
1 parent b41b156 commit 6784407

File tree

6 files changed

+128
-7
lines changed

6 files changed

+128
-7
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,6 @@ vendor/
2727

2828
# Coverage
2929
coverage.txt
30+
31+
# IDEs
32+
.vscode/

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

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
// Highlight a test's name with your cursor and run this debugger configuration
6+
// from the debugger tools in the left-side Activity Bar.
7+
// This will result in the equivalent of this command being run using the debugger:
8+
// `go test -v -run ^<selected text>$ <the current opened file's folder path>`
9+
"name": "Run selected test",
10+
"request": "launch",
11+
"type": "go",
12+
"args": [
13+
"-test.v",
14+
"-test.run",
15+
"^${selectedText}$"
16+
],
17+
// Environment variables can be set from a file or as key-value pairs in the configuration.
18+
// "env": {
19+
// "MY_ENV": "my-value",
20+
// },
21+
// "envFile": "./vscode/private.env",
22+
"mode": "auto",
23+
"program": "${fileDirname}",
24+
"showLog": true // dlv's logs
25+
}
26+
]
27+
}

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

+27
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
{
2+
"version": "0.2.0",
3+
"configurations": [
4+
{
5+
// Runs Terraform using the Terraform configuration specified via the chdir argument
6+
"name": "Run Terraform in debug mode",
7+
"request": "launch",
8+
"type": "go",
9+
"args": [
10+
"-chdir=<absolute path to a Terraform configuration>",
11+
// Change this array to perform different terraform commands with different arguments.
12+
"plan",
13+
"-var='name=value'"
14+
],
15+
// "cwd": "<absolute path to a Terraform configuration>", // An alternative to using the -chdir global flag above.
16+
// Environment variables can be set from a file or as key-value pairs in the configuration.
17+
// "env": {
18+
// "MY_ENV": "my-value",
19+
// },
20+
// "envFile": "./vscode/private.env",
21+
"mode": "debug",
22+
"program": "${workspaceFolder}",
23+
"console": "integratedTerminal", // allows responding to y/n in terminal, e.g. in apply command.
24+
"showLog": false // dlv's logs
25+
}
26+
]
27+
}

‎.vscode/launch.json renamed to ‎docs/debugging-configs/vscode/launch-via-cli/launch.json

File renamed without changes.

‎docs/debugging.md

+71-7
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,45 @@
11
# How to Debug Terraform
22

3+
Contents:
4+
- [Debugging automated tests](#debugging-automated-tests)
5+
- [Debugging automated tests in VSCode](#debugging-automated-tests-in-vscode)
6+
- [Debugging Terraform operations that use real Terraform configurations](#debugging-terraform-operations-that-use-real-terraform-configurations)
7+
- [Launch Terraform with the `dlv` CLI tool](#launch-terraform-with-the-dlv-cli-tool)
8+
- [Launch Terraform with VS Code's debugging tool](#launch-terraform-with-vs-codes-debugging-tool)
9+
10+
311
As Terraform is written in Go you may use [Delve](https://github.com/go-delve/delve) to debug it.
412

5-
## 1. Compile & Start Debug Server
13+
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.
14+
15+
## Debugging automated tests
16+
17+
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.
18+
19+
### Debugging automated tests in VSCode
20+
21+
As described above, debugging tests in VS Code is easily achieved through the Go extension.
22+
23+
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).
24+
25+
When using this launch configuration you must highlight a test's name before starting the debugger:
26+
27+
<p align="center">
28+
<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"/>
29+
</p>
30+
31+
32+
## Debugging Terraform operations that use real Terraform configurations
33+
34+
### Launch Terraform with the `dlv` CLI tool
35+
36+
In this workflow you:
37+
* Build Terraform using compiler flags.
38+
* Start a debug server with a command containing the terraform command you want to debug.
39+
* This command is run in the working directory that contains your Terraform configuration.
40+
* Connect to the debug server to monitor progress through breakpoints.
41+
42+
#### 1. Compile & Start Debug Server
643

744
One way to do it is to compile a binary with the [appropriate compiler flags](https://pkg.go.dev/cmd/compile#hdr-Command_Line):
845

@@ -13,21 +50,48 @@ go install -gcflags="all=-N -l"
1350
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:
1451

1552
```sh
16-
dlv exec $GOBIN/terraform --headless --listen :2345 --log -- apply
53+
# Update the path to the terraform binary if your install directory is influenced by $GOPATH or $GOBIN
54+
dlv exec $HOME/go/bin/terraform --headless --listen :2345 --log -- apply
1755
```
1856

19-
## 2a. Connect via CLI
57+
#### 2a. Connect via CLI
2058

2159
You may connect to the headless debug server via Delve CLI
2260

2361
```sh
2462
dlv connect :2345
2563
```
2664

27-
## 2b. Connect from VS Code
65+
#### 2b. Connect from VS Code
66+
67+
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):
68+
69+
<p align="center">
70+
<img width="75%" alt="vscode debugger" src="./images/vscode-debugging.png"/>
71+
</p>
72+
73+
74+
### Launch Terraform with VS Code's debugging tool
75+
76+
In this workflow you:
77+
* Update the debugger's launch configuration to point at the directory containing your Terraform configuration.
78+
* Start the debugger through VS Code and monitor progress through breakpoints.
79+
80+
#### 1. Update the debugger's launch configuration
81+
82+
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).
83+
84+
To use this launch configuration:
85+
* Prepare a local Terraform project.
86+
* Get the absolute path to that directory.
87+
* Update the launch configuration to use that path, either in the `-chdir` argument or as a `cwd` attribute in the launch configuration.
88+
* Make sure the `args` array's element reflect the command you'd like to debug.
89+
* Provide any required environment variables through the `env` or `envFile` attributes.
90+
91+
#### 2. Run the launch configuration in VS Code
2892

29-
The repository provides a launch configuration, making it possible to use VS Code's native debugging integration:
93+
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.
3094

31-
![vscode debugger](./images/vscode-debugging.png)
95+
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.
3296

33-
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.
97+
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.

‎docs/images/vscode-debugging-test.png

402 KB
Loading

0 commit comments

Comments
 (0)