k8s-d2

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

★ 62 Open GitHub ↗

Generate k8s diagrams of your cluster using D2

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# k8s-d2

[![Go Report Card](https://goreportcard.com/badge/github.com/vieitesss/k8s-d2)](https://goreportcard.com/report/github.com/vieitesss/k8s-d2)
[![License](https://img.shields.io/github/license/vieitesss/k8s-d2)](https://raw.githubusercontent.com/vieitesss/k8s-d2/main/LICENSE)
[![Release](https://img.shields.io/github/v/release/vieitesss/k8s-d2)](https://github.com/vieitesss/k8s-d2/releases)

A command-line tool that generates [D2](https://d2lang.com/) diagram files from Kubernetes cluster topology. Visualize your cluster's namespaces, workloads, services, and their relationships as code.

> Note: This README tracks the `main` branch. If you are using the latest stable release, check the matching Git tag or the [release notes](https://github.com/vieitesss/k8s-d2/releases) for the shipped CLI behavior and flags.

![k8s-d2 Example Diagram](https://raw.githubusercontent.com/vieitesss/k8s-d2/main/assets/example.svg)

## Features

- Generate D2 diagrams from live Kubernetes clusters
- Visualize workloads (Deployments, StatefulSets, DaemonSets) with distinct icons
- Map service-to-workload relationships with port information
- Visualize ingress and external service entrypoints
- Filter by namespace or view entire cluster
- Track ConfigMaps and Secrets per namespace
- Use D2 automatic layout for cleaner topology diagrams
- Output to file or stdout for pipeline integration
- Generate SVG images directly via [Kroki](https://kroki.io/) API (no local D2 installation required)

## Installation

### Homebrew (macOS/Linux)

```bash
brew install vieitesss/tap/k8s-d2
```

### Go Install

```bash
go install github.com/vieitesss/k8s-d2@latest
```

### Pre-compiled Binaries

Download the latest release for your platform from the [releases page](https://github.com/vieitesss/k8s-d2/releases), then extract the archive and move the `k8sdd` binary to your PATH:

```bash
tar -xzf k8s-d2_*_*.tar.gz
sudo mv k8sdd /usr/local/bin/  # Linux/macOS
```

For Windows, extract the `.zip` file and add the binary to your PATH.

### Build from Source

```bash
git clone https://github.com/vieitesss/k8s-d2.git
cd k8s-d2
go build -o k8sdd .
```

## Quick Start

Generate a diagram from your current Kubernetes context:

```bash
k8sdd diagram -o cluster.d2
```

Render the diagram with D2:

```bash
d2 cluster.d2 cluster.svg
```

Or generate an SVG directly (no D2 installation required):

```bash
k8sdd diagram -i cluster.svg
```

By default, SVG generation uses `https://kroki.io` with a `30s` timeout.

Use a private or self-hosted Kroki deployment when needed:

```bash
k8sdd diagram -i cluster.svg --kroki-base-url https://kroki.internal --kroki-timeout 60s
```

## Flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--kubeconfig` | | `~/.kube/config` | Path to kubeconfig file |
| `--namespace` | `-n` | | Filter by specific namespaces (repeat or comma-separated) |
| `--all-namespaces` | `-A` | `false` | Include system namespaces |
| `--output` | `-o` | stdout | Output D2 file path |
| `--image` | `-i` | | Output SVG image file (uses Kroki API) |
| `--kroki-base-url` | | `https://kroki.io` | Kroki base URL for SVG generation |
| `--kroki-timeout` | | `30s` | Kroki request timeout for SVG generation |
| `--include-storage` | | `false` | Include PVCs with storage class labels |
| `--quiet` | `-q` | `false` | Suppress progress indicators and log messages |

> **Note:** `--output` and `--image` are mutually exclusive.
>
> `--kroki-base-url` and `--kroki-timeout` are only used with `--image`. When set, the Kroki base URL must not be empty and the timeout must be greater than `0`.

`--include-storage` adds PVC nodes to the diagram and shows each PVC's storage class as label metadata when available. It does not render `StorageClass` objects as separate nodes.

## Requirements

- Kubernetes cluster access via kubeconfig
- Valid KUBECONFIG or `~/.kube/config` file
- [D2](https://d2lang.com/) for rendering diagrams locally (optional - you can use `--image` flag to generate SVG via Kroki API instead)

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Acknowledgments

Built with:
- [Cobra](https://github.com/spf13/cobra) - CLI framework
- [client-go](https://github.com/kubernetes/client-go) - Kubernetes API client
- [D2](https://d2lang.com/) - Declarative diagramming language
- [Kroki](https://kroki.io/) - Diagram rendering API

k8s-d2

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README