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:
- Using ephemeral debug containers to isolate diagnostic tooling from application containers
- Automatically detecting container UID/GID and matching security context
- Automatically detecting and downloading
dotnet-dumpin the debug container (no need to bake it into app images) - Use a ephemeral debug container to download if the debuggee container doesn't contain the required tools or a shell. This is automatically dedected.
- Using chunked base64 transfer to handle large files reliably
- Working with
/proc/1/root/tmpto 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:
- Find a pod with label
app=apiin namespaceproduction - Create an ephemeral debug container
- Download and run dotnet-dump to create a mini dump
- 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
Debug Container Strategy (Recommended)
- Pod Discovery: Finds target pod using label selector or name
- Container Detection: Identifies the default container and extracts UID/GID
- Security Context Matching: Creates debug container with same UID/GID as target
- Shared Process Namespace: Uses
--share-processesto access target container's processes - Dump Creation: Downloads dotnet-dump and creates dump in
/proc/1/root/tmp/dumps - File Transfer: Uses chunked base64 encoding to reliably download large files
Same Container Strategy
Simpler but requires:
- Container running as root
- Writable
/tmpdirectory - 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
/tmpdirectory OR mounted emptyDir volume- For
readOnlyRootFilesystem: true, mount emptyDir at/tmp
- For
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.