Socket
Book a DemoInstallSign in
Socket

KubeDiagrams

Package Overview
Dependencies
Maintainers
1
Versions
7
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

KubeDiagrams

Generate Kubernetes architecture diagrams from Kubernetes manifest files, kustomization files, Helm charts, helmfiles, and actual cluster state

pipPyPI
Version
0.4.0
Maintainers
1

KubeDiagrams

license python version Socket Badge pypi version PyPI Downloads Docker Stars Docker Image Version Docker Pulls contributors

philippemerle%2FKubeDiagrams | Trendshift

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. Compared to these existing tools, the main originalities of KubeDiagrams are the support of:

KubeDiagrams is available as a Python package in PyPI, a container image in DockerHub, a kubectl plugin, a Nix flake, and a GitHub Action, see here for more details.

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

5G Core Network Functions

Kubernetes Operators

Kubernetes Control Planes

Other examples

Prerequisites

Following software must be installed:

Getting Started

From PyPI

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

# 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

# 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 dot, dot_json, gif, jp2, jpe, jpeg, jpg, 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

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.

Features

Kubernetes built-in resources

KubeDiagrams supported the following 47 Kubernetes resource types:

KindApiGroupVersionsIcon
APIServiceapiregistration.k8s.iov1beta1 v1APIService
ClusterRolerbac.authorization.k8s.iov1beta1 v1ClusterRole
ClusterRoleBindingrbac.authorization.k8s.iov1beta1 v1ClusterRoleBinding
ConfigMapv1ConfigMap
CronJobbatchv1beta1 v1CronJob
CSIDriverstorage.k8s.iov1beta1 v1CSIDriver
CSINodestorage.k8s.iov1CSINode
CSIStorageCapacitystorage.k8s.iov1CSIStorageCapacity
CustomResourceDefinitionapiextensions.k8s.iov1beta1 v1CustomResourceDefinition
DaemonSetapps extensionsv1beta1 v1beta2 v1DaemonSet
Deploymentapps extensionsv1beta1 v1beta2 v1Deployment
Endpointsv1Endpoints
EndpointSlicediscovery.k8s.iov1EndpointSlice
Grouprbac.authorization.k8s.iov1Group
HorizontalPodAutoscalerautoscalingv1 v2beta1 v2beta2 v2HorizontalPodAutoscaler
Ingressnetworking.k8s.io extensionsv1beta1 v1Ingress
IngressClassnetworking.k8s.iov1beta1 v1IngressClass
Jobbatchv1beta1 v1Job
Leasecoordination.k8s.iov1Lease
LimitRangev1LimitRange
MutatingWebhookConfigurationadmissionregistration.k8s.iov1beta1 v1MutatingWebhookConfiguration
Namespacev1Namespace
NetworkAttachmentDefinitionk8s.cni.cncf.iov1NetworkAttachmentDefinition
NetworkPolicynetworking.k8s.iov1NetworkPolicy
Nodev1Node
PersistentVolumev1PersistentVolume
PersistentVolumeClaimv1PersistentVolumeClaim
Podv1Pod
PodDisruptionBudgetpolicyv1beta1 v1PodDisruptionBudget
PodSecurityPolicypolicy extensionsv1beta1 v1PodSecurityPolicy
PodTemplatev1PodTemplate
PriorityClassscheduling.k8s.iov1beta1 v1PriorityClass
ReplicaSetappsv1ReplicaSet
ReplicationControllerv1ReplicationController
ResourceQuotav1ResourceQuota
Rolerbac.authorization.k8s.iov1beta1 v1Role
RoleBindingrbac.authorization.k8s.iov1beta1 v1RoleBinding
RuntimeClassnode.k8s.iov1RuntimeClass
Secretv1Secret
Servicev1Service
ServiceAccountv1ServiceAccount
StatefulSetappsv1beta1 v1beta2 v1StatefulSet
StorageClassstorage.k8s.iov1beta1 v1StorageClass
Userrbac.authorization.k8s.iov1User
ValidatingWebhookConfigurationadmissionregistration.k8s.iov1beta1 v1ValidatingWebhookConfiguration
VerticalPodAutoscalerautoscaling.k8s.iov1VerticalPodAutoscaler
VolumeAttachmentstorage.k8s.iov1VolumeAttachment

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

Currently, there are 16 unsupported Kubernetes resource types:

KindApiGroup
Binding
ComponentStatus
Event
ControllerRevisionapps
TokenReviewauthentication.k8s.io
LocalSubjectAccessReviewauthorization.k8s.io
SelfSubjectAccessReviewauthorization.k8s.io
SelfSubjectReviewauthorization.k8s.io
SelfSubjectRulesReviewauthorization.k8s.io
SubjectAccessReviewauthorization.k8s.io
CertificateSigningRequestcertificates.k8s.io
Eventevents.k8s.io
FlowSchemaflowcontrol.apiserver.k8s.io
PriorityLevelConfigurationflowcontrol.apiserver.k8s.io
NodeMetricsmetrics.k8s.io
PodMetricsmetrics.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, and examples/argo/KubeDiagrams.yaml. Following lists some custom resources already supported in examples.

KindApiGroupVersionsIcon
Applicationargoproj.iov1alpha1Application
EventBusargoproj.iov1alpha1EventBus
EventSourceargoproj.iov1alpha1EventSource
Rolloutargoproj.iov1alpha1Rollout
Sensorargoproj.iov1alpha1Sensor
Workflowargoproj.iov1alpha1Workflow
Serviceserving.knative.devv1Service
Routeroute.openshift.iov1Route
Charthelm.k0sproject.iov1beta1Chart
ControlNodeautopilot.k0sproject.iov1beta2ControlNode
EtcdMemberetcd.k0sproject.iov1beta1EtcdMember
Planautopilot.k0sproject.iov1beta2Plan
UpdateConfigautopilot.k0sproject.iov1beta2UpdateConfig
Alertmanagermonitoring.coreos.comv1Alertmanager
Prometheusmonitoring.coreos.comv1Prometheus
PrometheusRulemonitoring.coreos.comv1PrometheusRule
ServiceMonitormonitoring.coreos.comv1ServiceMonitor
LeaderWorkerSetleaderworkerset.x-k8s.iov1LeaderWorkerSet
Certificatecert-manager.iov1alpha1 v1alpha2 v1Certificate
ClusterIssuercert-manager.iov1alpha1 v1alpha2 v1ClusterIssuer
Issuercert-manager.iov1alpha1 v1alpha2 v1Issuer

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.yml file (see the clusters list).

Label KeyCluster TitleBackground ColorRecommended
app.kubernetes.io/instanceK8s Instance: label valueStatic BadgeYes
releaseRelease: label valueStatic BadgeNo
helm.sh/chartHelm Chart: label valueStatic BadgeYes
chartChart: label valueStatic BadgeNo
app.kubernetes.io/nameK8s Application: label valueStatic BadgeYes
appApplication: label valueStatic BadgeNo
tierTier: label valueStatic BadgeNo
app.kubernetes.io/componentK8s Component: label valueStatic BadgeYes
componentComponent: label valueStatic BadgeNo
serviceMicroservice: label valueStatic BadgeNo
rbac.authorization.k8s.io/aggregate-to-adminAdmin ClusterRole AggregationtransparentYes
rbac.authorization.k8s.io/aggregate-to-editEdit ClusterRole AggregationtransparentYes
rbac.authorization.k8s.io/aggregate-to-viewView ClusterRole AggregationtransparentYes

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.yml file.

Annotation KeyCluster TitleBackground ColorRecommended
helm.sh/hookannotation valueStatic BadgeYes

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.yml file (see the edges map).

Edge KindEdge StyleEdge ColorMeaning
REFERENCEsolidblackUsed when a resource refers to another resource directly
SELECTORdashedblackUsed when a resource refers to other resources via a selector
OWNERdottedblackUsed when a resource owns another resource
COMMUNICATIONsolidbrownUsed 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 all 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 diagram:

Custom diagram

This previous diagram contains three custom clusters labelled with Amazon Web Service, Account: Philippe Merle and My Elastic Kubernetes Cluster, three custom nodes labelled with Users, Elastic Kubernetes Services, and Philippe Merle, and two custom edges labelled with use and calls. The rest of this custom diagram is generated from actual cluster state for a deployed WordPress application automatically. Have a look to examples/wordpress/custom_diagram.kd and examples/online-boutique/custom_diagram.kd to see how to define custom diagrams, clusters, nodes and edges declaratively.

KubeDiagrams Interactive Viewer

KubeDiagrams could output diagrams in the dot_json format. For instance, type:

kube-diagrams examples/wordpress/*.yaml -o wordpress.dot_json

Diagrams in the dot_json format can be viewed and manipulated interactively thanks to KubeDiagrams Interactive Viewer. For instance, type:

open interactive_viewer/index.html

Then open the wordpress.dot_json file:

KubeDiagrams Interactive Viewer

KubeDiagrams Interactive Viewer allows users to zoom in/out diagrams, to see cluster/node/edge tooltips, open/close clusters, move clusters/nodes interactively, and save as PNG/JPG images.

Architecture

Following figure shows the software architecture of KubeDiagrams.

Architecture.png

Real-World Use Cases

Following provides links to real-world use cases.

Documentation

KubeDiagrams could be used to generate architectural diagrams documenting your Kubernetes applications (manifests, Helm charts, helmfiles, or cluster state). See following links:

Architectural defects identification

Diagrams generated by KubeDiagrams could help you to identify architectural defects in your own or used Kubernetes applications. See following links:

Debugging

Generated diagrams could help you to debug your own or used Kubernetes applications. See following links:

Your own real-world use cases

Don't hesitate to submit your own real-world use cases as pull requests.

What do they say about it?

Papers

Talks

Blogs

Social Networks

Referencing sites

Your own contributions

Don't hesitate to submit your own papers, talks, blogs, social network posts, and referencing sites as pull requests.

Star History

Star History Chart

Issue Stats

Issue Stats

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

FOSSA Status

Keywords

kubernetes architecture diagrams

FAQs

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts