Debugging¶
Follow the Quickstart guide to start and debug NGINX Ingress Controller in a local Kind cluster or read the walkthrough to step through the full process of configuring an environment.
Parts of these instructions assume you develop using Visual Studio Code, but can be modified and followed for any IDE (Integrated Development Environment).
- Quickstart
- Debug configuration walkthrough
- 1. Build a debug container image
- 2. Deploy the debug container
- 3. Connect your debugger
- Helm configuration options
Quickstart¶
- Set the local variables:
NOTE:
ARCHshould be set toamd64orarm64to match your CPU architecture or debugging will not work as expected. - Create a local Kind cluster:
- Build the NGINX Ingress Controller debug image:
- Load the debug image into the Kind cluster:
- Use the Helm chart to install NGINX Ingress Controller
helm upgrade --install my-release charts/wxingress -f - <<EOF controller: debug: enable: true kind: daemonset service: type: NodePort customPorts: - name: godebug nodePort: 32345 port: 2345 protocol: TCP targetPort: 2345 customPorts: - name: godebug containerPort: 2345 protocol: TCP readyStatus: enable: false image: tag: debug repository: local/nic-debian EOF - Add this launch configuration to the
configurationssection of your VSCode.vscode/launch.jsonfile or IDE equivalent. - Run the configuration from the
Run and Debugmenu, set breakpoints, and start debugging.
Debug configuration walkthrough¶
1. Build a debug container image¶
Create an NGINX Ingress Controller container with either:
1. make <image name> TARGET=debug
This option creates the debug NGINX Ingress Controller binary locally , then loads it into the container image.
1. make <image name> TARGET=debug-container
This options builds the debug NGINX Ingress Controller binary directly inside the container image.
The debug NGINX Ingress Controller binary contains debug symbols and has Delve installed. It uses /dlv as its entrypoint.
The following example builds a Debian image with NGINX Plus on ARM64, tagged as local/nic-debian-plus:debug:
make debian-image-plus TARGET=debug PREFIX=local/nic-debian-plus TAG=debug ARCH=arm64
...
...
=> => naming to docker.io/local/nic-debian-plus:debug
2. Deploy the debug container¶
Use Helm to enable the debug configuration:
controller:
debug:
enable: true
service:
type: NodePort
customPorts:
# only required if you want to connect
# directly to your cluster instead of using kubectl port-forward
- name: godebug
nodePort: 32345
port: 2345
protocol: TCP
targetPort: 2345
customPorts:
- name: godebug
containerPort: 2345
protocol: TCP
readyStatus:
# We recommend deactivating readinessProbes while debugging
# to ensure upgrades and service connections run as expected
enable: false
image:
tag: debug
repository: local/nic-debian-plus
If you are not using Helm, manually add the Delve CLI arguments to the deployment or daemonset:
args:
- --listen=:2345
- --headless=true
- --log=true
- --log-output=debugger,debuglineerr,gdbwire,lldbout,rpc,dap,fncall,minidump,stack
- --accept-multiclient
- --api-version=2
- exec
- ./nginx-ingress
- --continue
- --
<regular NGINX Ingress Controller CLI configuration>
Delve will immediately start NGINX Ingress Controller by default. To prevent this, set controller.debug.continue: false. Delve will then wait for a debugger to connect before starting NGINX Ingress Controller, which is useful for observing start-up behaviour.
3. Connect your debugger¶
Connect to the remote Delve API server through your IDE: - JetBrains - VSCode
Example VSCode configuration:
{
"name": "Debug NIC",
"type": "go",
"request": "attach",
"mode": "remote",
"remotePath": "",
"port":32345,
"host":"<cluster where nodeport is exposed, or localhost if using kubectl port forward>",
"showLog": true,
"cwd": "${workspaceFolder}"
}
You may want to expose the debug port of your cluster via kubectl port-forward :
Helm configuration options¶
| Parameter | Description | Default |
|---|---|---|
controller.debug.enable |
Injects Delve CLI parameters into the args configuration of the NIC container. |
false |
controller.debug.continue |
Sets the --continue Delve flag which continues the NIC process instead of waiting for a debugger to attach. |
true |