Skip to main content

kdotnet-dump

A tool to create and download .NET process dumps from Kubernetes pods, supporting both standard and hardened (non-root) containers.

Purpose

Creating .NET dumps from containers running in Kubernetes can be challenging, especially with:

  • Non-root containers - Can't install tools or write to most filesystem locations
  • Chiseled/distroless-style runtime containers - Missing package managers and common shell tooling
  • Restricted Pod Security Standards - Limited privileges and capabilities
  • Large dump files - Can exceed 350MB, causing kubectl cp to fail

kdotnet-dump solves these problems by:

  1. Using ephemeral debug containers to isolate diagnostic tooling from application containers
  2. Automatically detecting container UID/GID and matching security context
  3. Automatically detecting and downloading dotnet-dump in the debug container (no need to bake it into app images)
  4. Use a ephemeral debug container to download if the debuggee container doesn't contain the required tools or a shell. This is automatically dedected.
  5. Using chunked base64 transfer to handle large files reliably
  6. Working with /proc/1/root/tmp to share filesystem between debug and target containers

Installation

The tool is published to kdotnet-dump · PyPI, which is the prefered method of installation:

pip install kdotnet-dump

If you want to install from local sources (e.g. for debugging), you can also use

git clone https://github.com/gprossliner/kdotnet-dump.git
cd kdotnet-dump
pip install -e .

No additional dependencies required - just Python 3 and kubectl.

Command Line Arguments

usage: kdotnet-dump [-h] [--strategy {same-container,debug-container}]
                [-n NAMESPACE] [-l SELECTOR] [--dump-type {mini,heap,triage,full}]
                [--dump-pid DUMP_PID] [--debug-image DEBUG_IMAGE] [-v]
                [pod]

positional arguments:
  pod                   Pod name (or use --selector)

optional arguments:
  -h, --help            Show this help message and exit
  -v, --version         Show kdotnet-dump version and exit
  
  --strategy {same-container,debug-container}
                        Strategy to create the dump (default: debug-container)
                        - same-container: Runs dotnet-dump in the target container (requires root)
                        - debug-container: Uses ephemeral debug container (works with non-root)
  
  -n, --namespace NAMESPACE
                        Kubernetes namespace (default: default)
  
  -l, --selector SELECTOR
                        Label selector to find pod (e.g., app=myapp)
                        Use this instead of specifying pod name directly
  
  --dump-type {mini,heap,triage,full}
                        Dump type (default: mini)
                        - mini: Minimal dump with stacks and exception info
                        - heap: Includes heap memory
                        - triage: Minimal info for initial diagnosis
                        - full: Complete memory dump (can be very large)
  
  --dump-pid DUMP_PID   Process ID to dump (default: 1)
                        Usually PID 1 is the main application process
  
  --debug-image DEBUG_IMAGE
                        Debug container image to use
                        (default: mcr.microsoft.com/dotnet/sdk:latest)

When installed from PyPI/release artifacts, -v/--version prints the package version (for example v0.1.3). When run directly from source without an installed package, it prints unknown.

Examples

Basic Usage - Find pod by label selector

kdotnet-dump -n production -l app=api --dump-type mini

This will:

  1. Find a pod with label app=api in namespace production
  2. Create an ephemeral debug container
  3. Download and run dotnet-dump to create a mini dump
  4. Download the dump to ./latest_dump

Specify pod name directly

kdotnet-dump -n production my-app-pod-12345 --dump-type full

Create full heap dump for memory analysis

kdotnet-dump -l app=api --dump-type heap

Use custom debug image (e.g., specific .NET SDK version)

kdotnet-dump -l app=api --debug-image mcr.microsoft.com/dotnet/sdk:8.0

Use same-container strategy (requires root)

kdotnet-dump -l app=api --strategy same-container --dump-type mini

Analyzing Dumps

On Linux

dotnet tool install -g dotnet-dump
dotnet-dump analyze ./latest_dump

On macOS (using Docker)

macOS doesn't support analyzing Linux dumps natively. Use a Docker container with the correct platform.

If you got the dump from a locally running kind cluster in MacOS Docker Desktop, the platform should be linux/arm64.

If you got the dump from a kubernetes cluster running on Linux, you may use the platform linux/amd64.

If you are not sure, you can use the sosstatus command to verify the platform of the dump.

# For Apple Silicon (M1/M2/M3), specify linux/arm64 platform
# This is the correct choice if you run locally on MacOS with a kind cluster
# For a different environment you may need to change the platform
docker run --rm -it --platform linux/arm64 \
  -v $(pwd):/dumps \
  mcr.microsoft.com/dotnet/sdk:10.0 \
  bash

# Inside the container
dotnet tool install dotnet-dump
dotnet tool run dotnet-dump analyze /dumps/latest_dump

Common dotnet-dump commands:

clrthreads          # List managed threads
clrstack            # Show managed stack trace
dumpheap -stat      # Show heap statistics
sos help            # Show all available commands

How It Works

  1. Pod Discovery: Finds target pod using label selector or name
  2. Container Detection: Identifies the default container and extracts UID/GID
  3. Security Context Matching: Creates debug container with same UID/GID as target
  4. Shared Process Namespace: Uses --share-processes to access target container's processes
  5. Dump Creation: Downloads dotnet-dump and creates dump in /proc/1/root/tmp/dumps
  6. File Transfer: Uses chunked base64 encoding to reliably download large files

Same Container Strategy

Simpler but requires:

  • Container running as root
  • Writable /tmp directory
  • Works by installing dotnet-dump directly in the target container

Requirements

Kubernetes Cluster

  • Kubernetes 1.23+ (for ephemeral containers)
  • Kubernetes 1.28+ recommended (for UID/GID detection from status)

RBAC Permissions

For debug-container strategy, the user needs:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: ephemeral-container-access
  labels:
    # This label causes the ClusterRole to be aggregated to the edit / admin role
    rbac.authorization.k8s.io/aggregate-to-edit: "true"
    rbac.authorization.k8s.io/aggregate-to-admin: "true"
rules:
- apiGroups: [""]
  resources: ["pods/ephemeralcontainers"]
  verbs: ["patch", "create", "get"]

Target Container Requirements

  • .NET application running (tested with .NET 8.0, 9.0, 10.0)
  • Writable /tmp directory OR mounted emptyDir volume
    • For readOnlyRootFilesystem: true, mount emptyDir at /tmp

Troubleshooting

"Access to the path '/.dotnet' is denied"

This occurs in non-root containers. Use --strategy debug-container (default).

"Read-only file system" errors

For containers with readOnlyRootFilesystem: true, ensure /tmp has an emptyDir mount:

volumeMounts:
- name: tmp
  mountPath: /tmp
volumes:
- name: tmp
  emptyDir: {}

Large files fail with websocket errors

The tool automatically uses chunked transfer for reliability. If issues persist, the chunks are 10MB by default and can't be adjusted without code changes.

"No pods found with selector"

Verify the label selector matches your pods:

kubectl get pods -l app=myapp -n your-namespace

Testing

Integration tests are available in the tests/ directory:

pip install -r tests/requirements.txt
pytest tests/test_entry.py -v

Tests deploy sample applications and verify dump creation across different configurations:

  • Root vs non-root containers
  • Debian vs Alpine vs Chiseled images
  • With and without readOnlyRootFilesystem

License

MIT

Metadata

Release files for kdotnet-dump 0.1.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kdotnet-dump 0.1.5
File Size Uploaded Provenance Actions
kdotnet_dump-0.1.5.tar.gz 17.1 kB With provenance Details for kdotnet_dump-0.1.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kdotnet-dump 0.1.5
File Interpreter ABI Platform Actions
kdotnet_dump-0.1.5-py3-none-any.whl Python 3 none any Details for kdotnet_dump-0.1.5-py3-none-any.whl

Total release size: 31.6 kB

Release files / kdotnet_dump-0.1.5.tar.gz

Download URL kdotnet_dump-0.1.5.tar.gz
Size 17.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cddae123ca09a15da91e561f3ad04971b4d62cdc0b3afd6c38a532d194f5d9b8
BLAKE2b-256 checksum
How to use checksums
28262ecd29df1ffc476317151eb05dc86b9b07a7b39fd848ae08e20e5b12660c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 10, 2026.

Transparency log

Release files / kdotnet_dump-0.1.5-py3-none-any.whl

Download URL kdotnet_dump-0.1.5-py3-none-any.whl
Size 14.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6b2e6ddcd05a160ed28de8d285f54c292db70a292bd7258c92067cfce575415d
BLAKE2b-256 checksum
How to use checksums
bb690ed58d77f82dca57a35775c3b7ec59de0777d4d099456f3530445f6097c3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 10, 2026.

Transparency log

Security for kdotnet-dump 0.1.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for kdotnet_dump-0.1.5.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Mar 10, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page