Skip to content
TanStackIntent
TanStack Intent/Registry/diagrams-js

diagrams-js

A TypeScript port of the diagrams Python library for drawing cloud system architecture diagrams as code

plugin-kubernetes

feature
332 linesSource

>-

Kubernetes Plugin for diagrams-js

Bidirectional conversion between Kubernetes YAML manifests and architecture diagrams.

Quick Start

Installation

shell
npm install @diagrams-js/plugin-kubernetes

Import from Kubernetes YAML

ts
import { Diagram } from "diagrams-js";
import { kubernetesPlugin } from "@diagrams-js/plugin-kubernetes";

const diagram = Diagram("My K8s Application");

// Register the plugin
await diagram.registerPlugins([kubernetesPlugin]);

// Import from Kubernetes YAML
const k8sYaml = `
apiVersion: apps/v1
kind: Deployment
metadata:
  name: web-deployment
spec:
  replicas: 3
  selector:
    matchLabels:
      app: web
  template:
    spec:
      containers:
      - name: web
        image: nginx:latest
        ports:
        - containerPort: 80
`;

await diagram.import(k8sYaml, "kubernetes");

// Render the diagram
const svg = await diagram.render();

Export to Kubernetes YAML

ts
import { Diagram, Node } from "diagrams-js";
import { kubernetesPlugin } from "@diagrams-js/plugin-kubernetes";

const diagram = Diagram("My K8s Application");

// Create nodes with Kubernetes metadata
const deployment = diagram.add(Node("web-deployment"));
deployment.metadata = {
  kubernetes: {
    kind: "Deployment",
    namespace: "default",
    spec: {
      replicas: 3,
      selector: { matchLabels: { app: "web" } },
      template: {
        spec: {
          containers: [{ name: "web", image: "nginx:latest", ports: [{ containerPort: 80 }] }],
        },
      },
    },
  },
};

// Register plugin and export
await diagram.registerPlugins([kubernetesPlugin]);
const k8sYaml = await diagram.export("kubernetes");

Features

Import Capabilities

  • Parse Kubernetes YAML manifests (single or multi-document)
  • Create nodes for each resource with appropriate Kubernetes icons
  • Support for all common Kubernetes resource types
  • Create edges for service-to-deployment relationships
  • Create clusters for namespaces
  • Store Kubernetes-specific metadata on nodes

Supported Resource Types

Workloads:

  • Deployment
  • StatefulSet
  • DaemonSet
  • ReplicaSet
  • Pod
  • Job
  • CronJob

Services & Networking:

  • Service
  • Ingress
  • NetworkPolicy

Storage:

  • ConfigMap
  • Secret
  • PersistentVolume
  • PersistentVolumeClaim
  • StorageClass

RBAC:

  • Role
  • RoleBinding
  • ClusterRole
  • ClusterRoleBinding
  • ServiceAccount

Cluster:

  • Namespace
  • Node
  • HorizontalPodAutoscaler

Export Capabilities

  • Export diagrams to Kubernetes YAML format
  • Generate valid Kubernetes manifests
  • Preserve resource configuration (replicas, selectors, ports, etc.)
  • Support for multi-document YAML output

Configuration

Custom Resource Mappings

You can customize which icons are used for specific Kubernetes resources:

ts
import { Diagram } from "diagrams-js";
import { createKubernetesPlugin } from "@diagrams-js/plugin-kubernetes";

const diagram = Diagram("My K8s Application");

// Create plugin with custom resource mappings
const plugin = createKubernetesPlugin({
  defaultNamespace: "production",
  imageMappings: {
    // 1. Provider icon mapping - use built-in provider icons
    "my-custom-deployment": {
      provider: "onprem",
      type: "compute",
      resource: "Server",
    },
    "my-custom-service": {
      provider: "onprem",
      type: "database",
      resource: "Postgresql",
    },

    // 2. Direct URL string - use a custom image URL
    "my-frontend": "https://example.com/react-icon.png",

    // 3. URL object - same as string but as object
    "my-backend": {
      url: "https://example.com/node-icon.svg",
    },

    // 4. Iconify icon - use icons from Iconify (https://iconify.design/)
    // Format: { iconify: "prefix:name" }
    "custom-app": {
      iconify: "logos:kubernetes",
    },
    "redis-cache": {
      iconify: "logos:redis",
    },
  },
});

await diagram.registerPlugins([plugin]);

Iconify Icons

The plugin supports Iconify icons, which provides access to 200,000+ open source icons:

ts
{
  iconify: "logos:kubernetes"; // Kubernetes logo
  iconify: "logos:redis"; // Redis logo
  iconify: "mdi:server"; // Material Design server icon
}

Mapping Priority

The plugin checks mappings by resource name first, then falls back to resource kind:

yaml
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-api # Would normally show Deployment icon
ts
// This mapping by RESOURCE NAME takes precedence
imageMappings: {
  "my-api": { iconify: "logos:aws" }  // Shows AWS icon instead of Deployment
}

// This mapping by KIND is the fallback
imageMappings: {
  "Deployment": { iconify: "logos:kubernetes" }  // Used if no "my-api" mapping
}

Examples

Visualize a Manifest

ts
import { Diagram } from "diagrams-js";
import { kubernetesPlugin } from "@diagrams-js/plugin-kubernetes";

const diagram = Diagram("Production Architecture");
await diagram.registerPlugins([kubernetesPlugin]);
await diagram.import(k8sYaml, "kubernetes");
const svg = await diagram.render();

Import Multiple Manifests

ts
const diagram = Diagram("Environment Comparison");
await diagram.registerPlugins([kubernetesPlugin]);
await diagram.import([stagingManifest, productionManifest], "kubernetes");

Export with Metadata

ts
const deployment = diagram.add(Node("api"));
deployment.metadata = {
  kubernetes: {
    kind: "Deployment",
    namespace: "production",
    spec: { replicas: 5, selector: { matchLabels: { app: "api" } } },
  },
};
const k8sYaml = await diagram.export("kubernetes");

Round-trip

ts
await diagram.import(existingK8sYaml, "kubernetes");
// ... modify diagram ...
const updatedYaml = await diagram.export("kubernetes");

API Reference

kubernetesPlugin

Pre-created instance:

ts
import { kubernetesPlugin } from "@diagrams-js/plugin-kubernetes";
await diagram.registerPlugins([kubernetesPlugin]);

Provides importer (name: "kubernetes", .yml/.yaml) and exporter (name: "kubernetes", .yaml).

createKubernetesPlugin(config?)

Factory for custom configuration:

ts
import { createKubernetesPlugin, type ImageMappings } from "@diagrams-js/plugin-kubernetes";

const plugin = createKubernetesPlugin({
  defaultNamespace: "production",
  imageMappings: {
    "custom-app": { iconify: "logos:kubernetes" },
    "my-deployment": { provider: "k8s", type: "compute", resource: "Deploy" },
  },
});

await diagram.registerPlugins([plugin]);

Config: defaultNamespace (default: "default"), imageMappings.

Best Practices

  • Use descriptive resource names — name: user-service not svc1
  • Store metadata for round-trip — Keep kind, namespace, spec in node.metadata.kubernetes
  • Service selectors create edges — Service→Deployment edges are auto-created when selectors match labels
  • Use namespaces — Organize resources; each namespace becomes a cluster
  • Multi-document YAML — Separate resources with ---

Troubleshooting

  • Plugin not found — Register before import/export: await diagram.registerPlugins([kubernetesPlugin])
  • Metadata typing — node.metadata is Record<string, any>
  • Missing icons — Use imageMappings with provider, URL, or Iconify
  • Import fails — Ensure apiVersion, kind, metadata.name are present

Further Reading

  • diagrams-js Plugin System: See diagrams-js-plugin-system skill
  • diagrams-js Documentation: https://diagrams-js.hatemhosny.dev
  • Kubernetes Documentation: https://kubernetes.io/docs/
  • Iconify Icons: https://iconify.design/