KubeDiagrams

!python version !contributors

!KubeDiagrams Logo

Generate Kubernetes architecture diagrams from Kubernetes manifest files, kustomization files, Helm charts, helmfile descriptors, and actual cluster state.

There are several tools to generate Kubernetes architecture diagrams, see here for a detailed list and comparison. Compared to these existing tools, the main originalities of KubeDiagrams are the support of:

• most of all Kubernetes built-in resources,
• any Kubernetes custom resources,
• customizable resource clustering,
• any Kubernetes resource relationships,
• declarative custom diagrams,
• an interactive diagram viewer,
• a modern web application,
• a plugin for JetBrains IDEs,
• main input formats such as Kubernetes manifest files, customization files, Helm charts, helmfile descriptors, and actual cluster state,
• main output formats such as D2, DOT, draw.io, GIF, JPEG, Mermaid, PDF, PNG, SVG, and TIFF,
• D2 Diagram Generation
• Mermaid Diagram Generation,
• editable draw.io export,
• a very large set of examples.

An Online KubeDiagrams Service is freely available at https://kubediagrams.lille.inria.fr/.

Read Real-World Use Cases and What do they say about it to discover how KubeDiagrams is really used and appreciated.

Try it on your own Kubernetes manifests, Helm charts, helmfiles, and actual cluster state!

Examples

Architecture diagram for official Kubernetes WordPress tutorial manifests: !WordPress Manifests

Architecture diagram for official Kubernetes ZooKeeper tutorial manifests: !ZooKeeper Manifest

Architecture diagram of a deployed Cassandra instance: !Deployed Cassandra Instance

Architecture diagram for Train Ticket：A Benchmark Microservice System: !train-ticket.png

Architecture diagram of the Minikube Ingress Addon: !Minikube Ingress Addon

Architecture diagram for the Kube Prometheus Stack chart: !kube-prometheus-stack.png

Architecture diagram for free5gc-k8s manifests: !free5gc-k8s-diagram.png

Architecture diagram for open5gs-k8s manifests: !open5gs-k8s-diagram.png

Architecture diagram for the Towards5GS-helm chart: !towards5gs_free5gc.png

Architecture diagram for a deployed CronJob instance: !cronjob-deployed.png

Architecture diagram for NetworkPolicy resources: !network_policies.png

Architecture diagram for an Argo CD example: !argoproj-argocd-example-apps-apps.png

Architecture diagram for an Argo Events example: !argoproj-argo-events-examples.png

Many other architecture diagrams are available into examples/.

Business Applications

1. Bank of Anthos
2. DeathStarBench
3. Official Kubernetes WordPress tutorial
4. Official Kubernetes ZooKeeper tutorial
5. Official Kubernetes Cassandra tutorial
6. Online Boutique
7. OpenTelemetry Demo
8. TeaStore
9. Train Ticket

5G Core Network Functions

1. free5gc-k8s
2. docker-open5gs
3. Gradiant 5G Charts
4. open5gs-k8s
5. OpenAirInterface 5G Core Network
6. Towards5GS-helm

Kubernetes Operators

1. Argo
2. cert-manager
3. External Secrets Operator
4. Gateway API
5. Istio
6. Kube Prometheus Stack
7. LeaderWorkerSet API

Kubernetes Control Planes

1. k0s architecture diagrams
2. minikube architecture diagrams

Other examples

1. Custom Object Items
2. Some Helm charts
3. helmfile
4. Inside workloads
5. Miscellaneous examples

Prerequisites

Following software must be installed:

• Python 3.9 or higher
• dot command (Graphviz)

Getting Started

Online with nothing to install on your machine

You could use KubeDiagrams directly from your favorite Web browser here.

From PyPI

Following command installs KubeDiagrams and all its Python dependencies, i.e., PyYAML, Diagrams, and graphviz2drawio.

# using pip (pip3)
pip install KubeDiagrams

From Nix

Alternatively, you can install via Nix:

nix shell github:philippemerle/KubeDiagrams

From Docker Hub

KubeDiagrams container images are available in Docker Hub. You can download the latest container image via:

docker pull philippemerle/kubediagrams

From source

You can start directly from source:

# clone the KubeDiagrams repository
git clone https://github.com/philippemerle/KubeDiagrams.git
install required Python packages
pip install PyYAML diagrams graphviz2drawio
make KubeDiagrams commands available into $PATH
PATH=$(pwd)/KubeDiagrams/bin:$PATH

From Windows

To use KubeDiagrams from Windows operating system, only the container image is supported currently.

[!NOTE]

> Any contribution would be welcome to translate KubeDiagrams' Unix-based scripts to Windows-based scripts.

Usage

KubeDiagrams provides two commands: kube-diagrams and helm-diagrams.

kube-diagrams

kube-diagrams generates a Kubernetes architecture diagram from one or several Kubernetes manifest files.

kube-diagrams -h
usage: kube-diagrams [-h] [-o OUTPUT] [-f FORMAT] [-c CONFIG] [-v] [--without-namespace] filename [filename ...]
Generate Kubernetes architecture diagrams from Kubernetes manifest files
positional arguments:
  filename              the Kubernetes manifest filename to process
options:
  -h, --help            show this help message and exit
  -o, --output OUTPUT   output diagram filename
  -f, --format FORMAT   output format, allowed formats are d2, dot, dot_json, drawio, gif, jp2, jpe, jpeg, jpg, mermaid, pdf, png, svg, tif, tiff, set to png by default
  --embed-all-icons     embed all icons into svg or dot_json output diagrams
  -c, --config CONFIG   custom kube-diagrams configuration file
  -n, --namespace NAMESPACE
                        visualize only the resources inside a given namespace
  -v, --verbose         verbosity, set to false by default
  --without-namespace   disable namespace cluster generation

kube-diagrams could read Kubernetes manifests from the standard input when given filename is equals to -.

Examples:

# generate a diagram from a manifest
kube-diagrams -o cassandra.png examples/cassandra/cassandra.yml
generate a diagram from a kustomize folder
kubectl kustomize path_to_a_kustomize_folder | kube-diagrams - -o diagram.png
generate a diagram from a helmfile descriptor
helmfile template -f helmfile.yaml | kube-diagrams - -o diagram.png
generate a diagram from the actual default namespace state
kubectl get all -o yaml | kube-diagrams -o default-namespace.png -
generate a diagram of all workload and service resources from all namespaces
kubectl get all --all-namespaces -o yaml | kube-diagrams -o all-namespaces.png -

🧩 kubectl Plugin Support

You can use KubeDiagrams as a kubectl plugin as well for a more integrated Kubernetes workflow. This allows you to run commands like:

kubectl diagrams all -o diagram.png

To enable this, simply symlink or copy the kubectl-diagrams script onto your $PATH:

ln -s $(which kubectl-diagrams) /usr/local/bin/kubectl-diagrams

[!NOTE]

> You will also already need kube-diagrams on your $PATH as well for this to work.

You can alternatively install it via Nix:

nix shell github:philippemerle/KubeDiagrams#kubectl-diagrams

helm-diagrams

helm-diagrams generates a Kubernetes architecture diagram from an Helm chart.

Usage: helm-diagrams <helm-chart-url> [OPTIONS] [FLAGS]
A script to generate a diagram of an Helm chart using kube-diagrams.
Options:
  -o, --output <file>          Specify the output file for the diagram
  -f, --format <format>        Specify the output format (e.g., png, svg)
  --embed-all-icons            Embed all icons into svg or dot_json output diagrams
  -c, --config <file>          Specify the custom kube-diagrams configuration file
  -h, --help                   Display this help message
Any flag supported by helm template, e.g.:
  -g, --generate-name          Generate the name (and omit the NAME parameter)
  --include-crds               Include CRDs in the templated output
  -l, --labels stringToString  Labels that would be added to release metadata. Should be divided by comma. (default [])
  --name-template string       Specify template used to name the release
  --set stringArray            Set values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
  --set-file stringArray       Set values from respective files specified via the command line (can specify multiple or separate values with commas: key1=path1,key2=path2)
  --set-json stringArray       Set JSON values on the command line (can specify multiple or separate values with commas: key1=jsonval1,key2=jsonval2)
  --set-literal stringArray    Set a literal STRING value on the command line
  --set-string stringArray     Set STRING values on the command line (can specify multiple or separate values with commas: key1=val1,key2=val2)
  -f, --values strings         Specify values in a YAML file or a URL (can specify multiple)
  --version string             Specify a version constraint for the chart version to use. This constraint can be a specific tag (e.g. 1.1.1) or it may reference a valid range (e.g. ^2.0.0). If this is not specified, the latest version is used
Examples:
  helm-diagrams https://charts.jetstack.io/cert-manager -o diagram.png
  helm-diagrams https://charts.jetstack.io/cert-manager --set crds.enabled=true -o cert-manager.png
  helm-diagrams oci://ghcr.io/argoproj/argo-helm/argo-cd -f svg
  helm-diagrams --help

[!NOTE]

> helm-diagrams requires that the helm command was installed.

Examples:

# generate a diagram for the Helm chart 'cert-manager' available in HTTP repository 'charts.jetstack.io'
helm-diagrams https://charts.jetstack.io/cert-manager
generate a diagram for the Helm chart 'argo-cd' available in OCI repository 'ghcr.io'
helm-diagrams oci://ghcr.io/argoproj/argo-helm/argo-cd
generate a diagram for the Helm chart 'some-chart' available locally
helm-diagrams some-path/some-chart

With Docker/Podman

KubeDiagrams images are available in Docker Hub.

# For usage with Podman, replace 'docker' by 'podman' in the following lines.
generate a diagram from a manifest
docker run -v "$(pwd)":/work philippemerle/kubediagrams kube-diagrams -o cassandra.png examples/cassandra/cassandra.yml
generate a diagram from a kustomize folder
kubectl kustomize path_to_a_kustomize_folder | docker run -v "$(pwd)":/work -i philippemerle/kubediagrams kube-diagrams - -o diagram.png
generate a diagram from a helmfile descriptor
helmfile template -f helmfile.yaml | docker run -v "$(pwd)":/work -i philippemerle/kubediagrams kube-diagrams - -o diagram.png
generate a diagram from the actual default namespace state
kubectl get all -o yaml | docker run -v "$(pwd)":/work -i philippemerle/kubediagrams kube-diagrams -o default-namespace.png -
generate a diagram of all workload and service resources from all namespaces
kubectl get all --all-namespaces -o yaml | docker run -v "$(pwd)":/work -i philippemerle/kubediagrams kube-diagrams -o all-namespaces.png -
generate a diagram for the Helm chart 'cert-manager' available in HTTP repository 'charts.jetstack.io'
docker run -v "$(pwd)":/work philippemerle/kubediagrams helm-diagrams https://charts.jetstack.io/cert-manager
generate a diagram for the Helm chart 'argo-cd' available in OCI repository 'ghcr.io'
docker run -v "$(pwd)":/work philippemerle/kubediagrams helm-diagrams oci://ghcr.io/argoproj/argo-helm/argo-cd

GitHub Action

You can use KubeDiagrams (and Helm Diagrams) in your GitHub Action workflows.

name: "Your GitHub Action Name"
on:
  workflow_dispatch: # add your specific triggers (https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows)
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: "Generate diagram from Kubernetes manifest"
        uses: philippemerle/KubeDiagrams@main
        with:
          type: "kubernetes"
          args: "-o examples/cassandra/cassandra.png examples/cassandra/cassandra.yml"
- name: "Generate diagram from Helm chart"
        uses: philippemerle/KubeDiagrams@main
        with:
          type: "helm"
          args: "https://charts.jetstack.io/cert-manager"

Action philippemerle/KubeDiagrams@main is available here.

KubeDiagrams Plugin for JetBrains IDEs

!KubeDiagrams Plugin for JetBrains IDEs

The KubeDiagrams Plugin for JetBrains IDEs is available here.

Features

Kubernetes built-in resources

KubeDiagrams supports the following 51 Kubernetes resource types:

| Kind | ApiGroup | Versions | Icon | | :------------------------------: | :----------------------------: | :---------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: | | APIService | apiregistration.k8s.io | v1beta1 v1 | !APIService | | ClusterRole | rbac.authorization.k8s.io | v1beta1 v1 | !ClusterRole | | ClusterRoleBinding | rbac.authorization.k8s.io | v1beta1 v1 | !ClusterRoleBinding | | ComponentStatus | | v1 | !ComponentStatus | | ConfigMap | | v1 | !ConfigMap | | ControllerRevision | apps | v1 | !ControllerRevision | | CronJob | batch | v1beta1 v1 | !CronJob | | CSIDriver | storage.k8s.io | v1beta1 v1 | !CSIDriver | | CSINode | storage.k8s.io | v1 | !CSINode | | CSIStorageCapacity | storage.k8s.io | v1 | !CSIStorageCapacity | | CustomResourceDefinition | apiextensions.k8s.io | v1beta1 v1 | !CustomResourceDefinition | | DaemonSet | apps extensions | v1beta1 v1beta2 v1 | !DaemonSet | | Deployment | apps extensions | v1beta1 v1beta2 v1 | !Deployment | | Endpoints | | v1 | !Endpoints | | EndpointSlice | discovery.k8s.io | v1 | !EndpointSlice | | FlowSchema | flowcontrol.apiserver.k8s.io | v1beta3 v1 | !FlowSchema | | Group | rbac.authorization.k8s.io | v1 | !Group | | HorizontalPodAutoscaler | autoscaling | v1 v2beta1 v2beta2 v2 | !HorizontalPodAutoscaler | | Ingress | networking.k8s.io extensions | v1beta1 v1 | !Ingress | | IngressClass | networking.k8s.io | v1beta1 v1 | !IngressClass | | Job | batch | v1beta1 v1 | !Job | | Lease | coordination.k8s.io | v1 | !Lease | | LimitRange | | v1 | !LimitRange | | MutatingWebhookConfiguration | admissionregistration.k8s.io | v1beta1 v1 | !MutatingWebhookConfiguration | | Namespace | | v1 | !Namespace | | NetworkAttachmentDefinition | k8s.cni.cncf.io | v1 | !NetworkAttachmentDefinition | | NetworkPolicy | networking.k8s.io | v1 | !NetworkPolicy | | Node | | v1 | !Node | | PersistentVolume | | v1 | !PersistentVolume | | PersistentVolumeClaim | | v1 | !PersistentVolumeClaim | | Pod | | v1 | !Pod | | PodDisruptionBudget | policy | v1beta1 v1 | !PodDisruptionBudget | | PodSecurityPolicy | policy extensions | v1beta1 v1 | !PodSecurityPolicy | | PodTemplate | | v1 | !PodTemplate | | PriorityClass | scheduling.k8s.io | v1beta1 v1 | !PriorityClass | | PriorityLevelConfiguration | flowcontrol.apiserver.k8s.io | v1beta3 v1 | !PriorityLevelConfiguration | | ReplicaSet | apps | v1 | !ReplicaSet | | ReplicationController | | v1 | !ReplicationController | | ResourceQuota | | v1 | !ResourceQuota | | Role | rbac.authorization.k8s.io | v1beta1 v1 | !Role | | RoleBinding | rbac.authorization.k8s.io | v1beta1 v1 | !RoleBinding | | RuntimeClass | node.k8s.io | v1 | !RuntimeClass | | Secret | | v1 | !Secret | | Service | | v1 | !Service | | ServiceAccount | | v1 | !ServiceAccount | | StatefulSet | apps | v1beta1 v1beta2 v1 | !StatefulSet | | StorageClass | storage.k8s.io | v1beta1 v1 | !StorageClass | | User | rbac.authorization.k8s.io | v1 | !User | | ValidatingWebhookConfiguration | admissionregistration.k8s.io | v1beta1 v1 | !ValidatingWebhookConfiguration | | VerticalPodAutoscaler | autoscaling.k8s.io | v1 | !VerticalPodAutoscaler | | VolumeAttachment | storage.k8s.io | v1 | !VolumeAttachment |

Note: The mapping between these supported Kubernetes resources and architecture diagrams is defined into bin/kube-diagrams.yaml.

Currently, there are 12 unsupported Kubernetes built-in resource types:

| Kind | ApiGroup | | :--------------------------: | :----------------------------: | | Binding | | | Event | | | TokenReview | authentication.k8s.io | | LocalSubjectAccessReview | authorization.k8s.io | | SelfSubjectAccessReview | authorization.k8s.io | | SelfSubjectReview | authorization.k8s.io | | SelfSubjectRulesReview | authorization.k8s.io | | SubjectAccessReview | authorization.k8s.io | | CertificateSigningRequest | certificates.k8s.io | | Event | events.k8s.io | | NodeMetrics | metrics.k8s.io | | PodMetrics | metrics.k8s.io |

Kubernetes custom resources

The mapping for any Kubernetes custom resources can be also defined into KubeDiagrams configuration files as illustrated in examples/k0s/KubeDiagrams.yml, examples/kube-prometheus-stack/monitoring.coreos.com.kdc, examples/lws/KubeDiagrams.yml, examples/argo/KubeDiagrams.yaml, and examples/external-secrets/external-secrets.io.kdc. Following lists some custom resources already supported in examples.

| Kind | ApiGroup | Versions | Icon | | :------------------------------: | :----------------------------: | :---------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: | | Application | argoproj.io | v1alpha1 | !Application | | EventBus | argoproj.io | v1alpha1 | !EventBus | | EventSource | argoproj.io | v1alpha1 | !EventSource | | Rollout | argoproj.io | v1alpha1 | !Rollout | | Sensor | argoproj.io | v1alpha1 | !Sensor | | Workflow | argoproj.io | v1alpha1 | !Workflow | | Service | serving.knative.dev | v1 | !Service | | Route | route.openshift.io | v1 | !Route | | Chart | helm.k0sproject.io | v1beta1 | !Chart | | ControlNode | autopilot.k0sproject.io | v1beta2 | !ControlNode | | EtcdMember | etcd.k0sproject.io | v1beta1 | !EtcdMember | | Plan | autopilot.k0sproject.io | v1beta2 | !Plan | | UpdateConfig | autopilot.k0sproject.io | v1beta2 | !UpdateConfig | | Alertmanager | monitoring.coreos.com | v1 | !Alertmanager | | Prometheus | monitoring.coreos.com | v1 | !Prometheus | | PrometheusRule | monitoring.coreos.com | v1 | !PrometheusRule | | ServiceMonitor | monitoring.coreos.com | v1 | !ServiceMonitor | | LeaderWorkerSet | leaderworkerset.x-k8s.io | v1 | !LeaderWorkerSet | | Certificate | cert-manager.io | v1alpha1 v1alpha2 v1 | !Certificate | | ClusterIssuer | cert-manager.io | v1alpha1 v1alpha2 v1 | !ClusterIssuer | | Issuer | cert-manager.io | v1alpha1 v1alpha2 v1 | !Issuer | | ExternalSecret | external-secrets.io | v1alpha1 v1beta1 v1 | !ExternalSecret | | SecretStore | external-secrets.io | v1alpha1 v1beta1 v1 | !SecretStore |

Kubernetes resources clustering

With KubeDiagrams, Kubernetes resources can be clustered within the architecture diagrams automatically. KubeDiagrams uses the metadata.namespace resource field as first clustering criteria. Then, the metadata.labels keys can be used to define subclusters. Following table lists the predefined mappings between label keys and cluster titles, and background colors as defined in the bin/kube-diagrams.yaml file (see the clusters list).

| Label Key | Cluster Title | Background Color | Recommended | | :---------------------------: | :----------------------------: | :----------------------------: | :----------------------------: | | app.kubernetes.io/instance | K8s Instance: label value | !Static Badge | Yes | | release | Release: label value | !Static Badge | No | | helm.sh/chart | Helm Chart: label value | !Static Badge | Yes | | chart | Chart: label value | !Static Badge | No | | app.kubernetes.io/name | K8s Application: label value | !Static Badge | Yes | | app | Application: label value | !Static Badge | No | | tier | Tier: label value | !Static Badge | No | | app.kubernetes.io/component | K8s Component: label value | !Static Badge | Yes | | component | Component: label value | !Static Badge | No | | service | Microservice: label value | !Static Badge | No | | rbac.authorization.k8s.io/aggregate-to-admin | Admin ClusterRole Aggregation | transparent | Yes | | rbac.authorization.k8s.io/aggregate-to-edit | Edit ClusterRole Aggregation | transparent | Yes | | rbac.authorization.k8s.io/aggregate-to-view | View ClusterRole Aggregation | transparent | Yes |

Resource clustering could be also annotation-based, i.e. based on metadata.annotations keys. Following table lists the predefined mappings between annotation keys, cluster titles, and background colors as defined in the bin/kube-diagrams.yaml file.

| Annotation Key | Cluster Title | Background Color | Recommended | | :------------: | :----------------: | :----------------: | :----------------: | | helm.sh/hook | annotation value | !Static Badge | Yes |

New label/annotation-based mappings can be easily defined in custom configuration files (see examples/minikube/KubeDiagrams.yml, examples/k0s/KubeDiagrams.yml, examples/free5gc-k8s/KubeDiagrams.yml, examples/open5gs-k8s/KubeDiagrams.yml, examples/towards5gs-helm/KubeDiagrams.yml, examples/lws/KubeDiagrams.yml, and examples/argo/KubeDiagrams.yaml) and provided to KubeDiagrams via the --config command-line option.

Kubernetes resource relationships

With KubeDiagrams, each relationship between Kubernetes resources is represented by a visual edge between visual nodes. Following table lists the predefined edges as defined in the bin/kube-diagrams.yaml file (see the edges map).

| Edge Kind | Edge Style | Edge Color | Meaning | | :-------------: | :--------: | :--------: | :-------------------------------------------------------------------: | | REFERENCE | solid | black | Used when a resource refers to another resource directly | | SELECTOR | dashed | black | Used when a resource refers to other resources via a selector | | OWNER | dotted | black | Used when a resource owns another resource | | COMMUNICATION | solid | brown | Used to represent ingress and egress networking policies between pods |

New edges can be easily defined or redefined in custom configuration files, and provided to KubeDiagrams via the --config command-line option.

Following diagram illustrates most of the visual nodes, edges, and clusters supported by default by KubeDiagrams.

!semiotics.png.

Generated SVG diagrams contain tooltips for each cluster/node/edge as illustrated in images/semiotics.svg

Declarative custom diagrams

By default, KubeDiagrams generates diagrams from data contained into Kubernetes manifest files, actual cluster state, kustomization files, or Helm charts automatically. But sometimes, users would like to customize generated diagrams by adding their own clusters, nodes and edges as illustrated in the following d

... (README truncated for length)