Skip to main content

spirldbg cli utility

spirldbg is a command line utility (CLI) that can help debug your environment and issues related to SPIRL deployments. You can request SVIDs and trust bundles, inspect and save them. Also you can do it over the standard Workload API, or the SDS protocol used by Envoy and Istio.

$ spirldbg --help

Usage:
    spirldbg [command]

Available commands:
    version              Displays the version
    check                Performs quick automatic checks - presence of API socket file, fetching of svids/trust bundles
    svid-x509            Get a x509 SVID
    svid-jwt             Get a JWT SVID
    trust-bundle-x509    Get an X.509 trust bundle
    trust-bundle-jwt     Get a JWT trust bundle

Global flags:
    -h, --help         prints help for the command
        --summary      prints a summary of what commands are available
        --advanced     when used with -h, prints advanced flags help

Use "spirldbg [command] --help" for more information about a command.

Using spirldbg with Kubernetes​

SPIRL provides ready-to-use Docker images for running spirldbg inside Kubernetes clusters. If you want to debug a pod in your cluster, you can run the kubectl debug command. Once you are inside the debug container, you can immediately use the spirldbg tool, since it's embedded in the image. There are two ways you can use it, each with its own pros and cons.

Option 1: Starting an ephemeral container in the target pod​

kubectl debug -it target-pod --image=public.ecr.aws/d1i7q6j7/spirldbg:latest \
  --target=target-container --profile=general

This command will spin up an ephemeral container in the pod "target-pod", targeting container "target-container". This means your new ephemeral container will share the process space. The inconvenience here is that you can't directly access the file system of the target container, so you can't directly access the socket file that provides access to the SPIFFE API. To access the socket file, you need to go through the special /proc/1/root filesystem path, which gives access to the filesystem of the debugged container. You might need to use a different PID instead of "1" depending on the main process of the target container your are debugging, which you can get using ps command.

So, for example, if your SPIFFE endpoint socket path is usually /run/secrets/workload-spiffe-uds/socket, then to access it in this ephemeral container you will need to use the path /proc/1/root/run/secrets/workload-spiffe-uds/socket. To fetch a test SVID you could use this command:

spirldbg svid-x509 --spiffe-endpoint-socket=unix:///proc/1/root/run/secrets/workload-spiffe-uds/socket

Option 2: Starting an ephemeral container in a clone of the target pod​

kubectl debug -it target-pod --image=public.ecr.aws/d1i7q6j7/spirldbg:latest \ 
  --copy-to=debugged-pod --same-node=true --set-image=\*=public.ecr.aws/d1i7q6j7/spirldbg:latest

In this mode, you will clone the target pod definition into a new pod "debugged-pod", and containers within that pod will have their underlying image replaced by the spirldbg image. The pod definitions for mount points will remain the same, so you will be able to access your SPIFFE endpoint socket at the same path as your app running in the target pod. However, you are not running in the target pod directly, and you will need to manually delete this cloned pod:

kubectl delete pod debugged-pod

Download spirldbg​

# Linux amd64
curl -o spirldbg-v0.0.8.tar.gz https://spirl-releases.s3.us-west-2.amazonaws.com/spirldbg/v0.0.8/spirldbg-v0.0.8-linux-amd64.tar.gz && tar -zxvf spirldbg-v0.0.8.tar.gz

# Linux arm64
curl -o spirldbg-v0.0.8.tar.gz https://spirl-releases.s3.us-west-2.amazonaws.com/spirldbg/v0.0.8/spirldbg-v0.0.8-linux-arm64.tar.gz && tar -zxvf spirldbg-v0.0.8.tar.gz

# macOS amd64
curl -o spirldbg-v0.0.8.tar.gz https://spirl-releases.s3.us-west-2.amazonaws.com/spirldbg/v0.0.8/spirldbg-v0.0.8-darwin-amd64.tar.gz && tar -zxvf spirldbg-v0.0.8.tar.gz

# macOS arm64
curl -o spirldbg-v0.0.8.tar.gz https://spirl-releases.s3.us-west-2.amazonaws.com/spirldbg/v0.0.8/spirldbg-v0.0.8-darwin-arm64.tar.gz && tar -zxvf spirldbg-v0.0.8.tar.gz