Skip to main content

Debugging containers in GAP

You can run an ephemeral debug container in any pod in GAP using the kubectl debug command. This is useful for debugging networking issues, inspecting the filesystem of a running container, or running diagnostic commands. Ephemeral container only run as long as the debugging session is active, and are automatically removed when you exit the session.

Running ephemeral debug containers

Replace <pod-name> and <namespace-name> with the name of the pod and namespace you want to debug.

Basic usage for most debugging scenarios:

Option 1 for Mac users (with explicit --custom parameter)

kubectl debug -it <pod-name> -n <namespace-name> \
--image="gjensidige.azurecr.io/platform/debug@sha256:f0efb274fd1e0a7f2c5cbc6f2c38341f62c491fc4e1f4101fe59a7846d890936" \
--custom=<(echo '{"securityContext":{"readOnlyRootFilesystem":true,"runAsNonRoot":false,"runAsUser":10001}}') \
--profile=restricted

Option 2 for Mac and Windows users (with --custom in a file)

# Create a file named debug.json with the following content:
{
"securityContext": {
"readOnlyRootFilesystem": true,
"runAsNonRoot": false,
"runAsUser": 10001
}
}
kubectl debug -it <pod-name> -n <namespace-name> \
--image="gjensidige.azurecr.io/platform/debug@sha256:f0efb274fd1e0a7f2c5cbc6f2c38341f62c491fc4e1f4101fe59a7846d890936" \
--custom=debug.json \
--profile=restricted

Mounting a temporary volume

For some debugging scenarios, you might need to mount a temporary volume. If a command fails with an error message indicating that the filesystem is not writable, you need to run the debug container with a volume mount as shown below:

kubectl debug -it <pod-name> -n <namespace-name> --image="gjensidige.azurecr.io/platform/debug@sha256:f0efb274fd1e0a7f2c5cbc6f2c38341f62c491fc4e1f4101fe59a7846d890936" --profile=restricted --custom=<(echo '{"volumeMounts":[{"mountPath":"/home/gap","name":"tmp"}],"securityContext":{"readOnlyRootFilesystem":true,"runAsNonRoot":false,"runAsUser":10001}}')

Debugging network connectivity

Replace service / host / namespace / ports as needed. Internal service FQDN pattern: <service>.<namespace>.svc.cluster.local.

HTTP (curl + telnet)

# Plain HTTP request with verbose headers
curl -v http://api-service.backend/healthz

# Specify port explicitly
curl -v http://api-service.backend:8080/ready

# Just test TCP port without HTTP (quick open/close)
telnet api-service.backend 8080

HTTPS / TLS

# Ignore certificate validation (internal/self‑signed)
curl -vk https://secure-api.backend/healthz

# Pure TCP check (does not validate cert)
telnet secure-api.backend 443

Generic TCP service

# Is a port open?
telnet some-tcp-service.backend 9000