{"_id":"@diagrams-js/plugin-kubernetes","_rev":"3-c913f05e5f343e2545bcb6f659693d6b","name":"@diagrams-js/plugin-kubernetes","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@diagrams-js/plugin-kubernetes","version":"0.1.0","keywords":["architecture","diagrams","diagrams-as-code","diagrams-js","k8s","kubernetes","plugin"],"author":{"name":"diagrams-js"},"license":"MIT","_id":"@diagrams-js/plugin-kubernetes@0.1.0","maintainers":[{"name":"hatemhosny","email":"hatemhosny@gmail.com"}],"homepage":"https://diagrams-js.hatemhosny.dev/","bugs":{"url":"https://github.com/diagrams-js/plugin-kubernetes/issues"},"dist":{"shasum":"de2b616900b9be547828e2368e0a4df6e05aceb0","tarball":"https://registry.npmjs.org/@diagrams-js/plugin-kubernetes/-/plugin-kubernetes-0.1.0.tgz","fileCount":5,"integrity":"sha512-38hIQLgCCvV4Q+08M6khymhLJmnG23PMtfdFPRdiPhn+jHaK4I/p84Ex9pREk9dNAL1vvzssEbl6gFi0/5gxCA==","signatures":[{"sig":"MEUCIQDtyQMvIq8kRSNtSYYRJvklMolwIoRg+K7eieK+fNMcVQIgYBtfGZYnC950fQ9AM4DnUboYw6xMXEbs4TIHxlKq0wo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":30397},"pnpm":{"overrides":{"vite":"npm:@voidzero-dev/vite-plus-core@latest","vitest":"npm:@voidzero-dev/vite-plus-test@latest"}},"type":"module","exports":{".":"./dist/index.js","./package.json":"./package.json"},"gitHead":"7a6e0e790528f000f2d07a8f2b24b7f7c2ae7540","scripts":{"dev":"vp build --watch","fix":"vp check --fix","test":"vp test","build":"vp pack src/index.ts && vp check --fix","check":"vp check","prepare":"vp config","version:major":"npm version major --no-git-tag-version","version:minor":"npm version minor --no-git-tag-version","version:patch":"npm version patch --no-git-tag-version","prepublishOnly":"vp run build"},"_npmUser":{"name":"hatemhosny","email":"hatemhosny@gmail.com"},"repository":{"url":"git+https://github.com/diagrams-js/plugin-kubernetes.git"},"_npmVersion":"11.6.4","description":"Kubernetes import/export plugin for diagrams-js","directories":{},"_nodeVersion":"24.4.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.0","devDependencies":{"vitest":"^3.0.0","vite-plus":"^0.1.14","typescript":"^6.0.2","@types/node":"^25.5.0","diagrams-js":"^0.3.1","@tanstack/intent":"^0.0.29"},"peerDependencies":{"diagrams-js":"^0.3.1"},"_npmOperationalInternal":{"tmp":"tmp/plugin-kubernetes_0.1.0_1776367908915_0.8219023486977954","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@diagrams-js/plugin-kubernetes","version":"0.2.0","keywords":["architecture","diagrams","diagrams-as-code","diagrams-js","k8s","kubernetes","plugin"],"author":{"name":"diagrams-js"},"license":"MIT","_id":"@diagrams-js/plugin-kubernetes@0.2.0","maintainers":[{"name":"hatemhosny","email":"hatemhosny@gmail.com"}],"homepage":"https://diagrams-js.hatemhosny.dev/","bugs":{"url":"https://github.com/diagrams-js/plugin-kubernetes/issues"},"dist":{"shasum":"f4232e670468c250a7e3263bb21d649370eef9ce","tarball":"https://registry.npmjs.org/@diagrams-js/plugin-kubernetes/-/plugin-kubernetes-0.2.0.tgz","fileCount":5,"integrity":"sha512-hpRK/SNEeH43zzjw05JS99Ad8hsNCA78P9RBQviVliBclx2ff/vbEb2s2u6gdg4AkMElWBIt2tqYWNlWvmJHsQ==","signatures":[{"sig":"MEUCIQDAK0F+qoCfsF97Zoky1kT+R8BybyiT0e1iQlF5+zHD4QIgfkhKzFUA8exiGdP77K+ht3p1xePBsQ1YrAyd+diYUHc=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@diagrams-js%2fplugin-kubernetes@0.2.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"unpackedSize":30399},"pnpm":{"overrides":{"vite":"npm:@voidzero-dev/vite-plus-core@latest","vitest":"npm:@voidzero-dev/vite-plus-test@latest"}},"type":"module","exports":{".":"./dist/index.js","./package.json":"./package.json"},"gitHead":"0dfeda88062cf706ef05c3ac0068ec0db6cab5db","scripts":{"dev":"vp build --watch","fix":"vp check --fix","test":"vp test","build":"vp pack src/index.ts && vp check --fix","check":"vp check","prepare":"vp config","version:major":"npm version major --no-git-tag-version","version:minor":"npm version minor --no-git-tag-version","version:patch":"npm version patch --no-git-tag-version","prepublishOnly":"vp run build"},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9cda0c82-c28d-4078-a71c-df0969d6a8a2"}},"repository":{"url":"git+https://github.com/diagrams-js/plugin-kubernetes.git"},"_npmVersion":"11.6.4","description":"Kubernetes import/export plugin for diagrams-js","directories":{},"_nodeVersion":"24.4.1","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.0","devDependencies":{"vitest":"^3.0.0","vite-plus":"^0.1.14","typescript":"^6.0.2","@types/node":"^25.5.0","diagrams-js":"^0.5.0","@tanstack/intent":"^0.0.29"},"peerDependencies":{"diagrams-js":"^0.5.0"},"_npmOperationalInternal":{"tmp":"tmp/plugin-kubernetes_0.2.0_1776908860523_0.6506095259861813","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@diagrams-js/plugin-kubernetes","version":"0.3.0","description":"Kubernetes import/export plugin for diagrams-js","keywords":["architecture","diagrams","diagrams-as-code","diagrams-js","k8s","kubernetes","plugin"],"homepage":"https://diagrams-js.hatemhosny.dev/","bugs":{"url":"https://github.com/diagrams-js/plugin-kubernetes/issues"},"license":"MIT","author":{"name":"diagrams-js"},"repository":{"url":"git+https://github.com/diagrams-js/plugin-kubernetes.git"},"type":"module","exports":{".":"./dist/index.js","./package.json":"./package.json"},"publishConfig":{"access":"public"},"scripts":{"build":"vp pack src/index.ts && vp check --fix","dev":"vp build --watch","test":"vp test","check":"vp check","fix":"vp check --fix","prepublishOnly":"vp run build","prepare":"vp config","version:patch":"npm version patch --no-git-tag-version","version:minor":"npm version minor --no-git-tag-version","version:major":"npm version major --no-git-tag-version"},"devDependencies":{"@tanstack/intent":"^0.0.29","@types/node":"^25.5.0","diagrams-js":"^0.7.0","typescript":"^6.0.2","vite-plus":"^0.1.14","vitest":"^3.0.0"},"peerDependencies":{"diagrams-js":">=0.7.0"},"packageManager":"pnpm@10.33.0","pnpm":{"overrides":{"vite":"npm:@voidzero-dev/vite-plus-core@latest","vitest":"npm:@voidzero-dev/vite-plus-test@latest"}},"gitHead":"e99e6a2d28cbe5b907848c65bb0bb3348eefffcf","_id":"@diagrams-js/plugin-kubernetes@0.3.0","_nodeVersion":"24.4.1","_npmVersion":"11.6.4","dist":{"integrity":"sha512-2dvHHxM9X+O1r72VJ3jGxgk6vpOubFgddkjJqtUVUvb4xysSIr60IhYSm8uOqH8COO1Xbgmz/pl8GJ/hcrw0yw==","shasum":"2b75e9283ad0fe2ca0d98994727169d3d20acf44","tarball":"https://registry.npmjs.org/@diagrams-js/plugin-kubernetes/-/plugin-kubernetes-0.3.0.tgz","fileCount":5,"unpackedSize":30400,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@diagrams-js%2fplugin-kubernetes@0.3.0","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHd93A/nzVnOmRMbX2yughxG4Xyq/uHB4ULDbDbyxfkBAiEA46zikcKH6g7WV1Lj2MneSmWLnCKHXEilOc6mn5WI60U="}]},"_npmUser":{"name":"GitHub Actions","email":"npm-oidc-no-reply@github.com","trustedPublisher":{"id":"github","oidcConfigId":"oidc:9cda0c82-c28d-4078-a71c-df0969d6a8a2"}},"directories":{},"maintainers":[{"name":"hatemhosny","email":"hatemhosny@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plugin-kubernetes_0.3.0_1777847107706_0.459921196684435"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-16T19:31:48.815Z","modified":"2026-05-03T22:25:08.150Z","0.1.0":"2026-04-16T19:31:49.095Z","0.2.0":"2026-04-23T01:47:40.686Z","0.3.0":"2026-05-03T22:25:07.847Z"},"bugs":{"url":"https://github.com/diagrams-js/plugin-kubernetes/issues"},"author":{"name":"diagrams-js"},"license":"MIT","homepage":"https://diagrams-js.hatemhosny.dev/","keywords":["architecture","diagrams","diagrams-as-code","diagrams-js","k8s","kubernetes","plugin"],"repository":{"url":"git+https://github.com/diagrams-js/plugin-kubernetes.git"},"description":"Kubernetes import/export plugin for diagrams-js","maintainers":[{"name":"hatemhosny","email":"hatemhosny@gmail.com"}],"readme":"# @diagrams-js/plugin-kubernetes\n\nKubernetes import/export plugin for diagrams-js. Convert between Kubernetes YAML manifests and architecture diagrams.\n\n## Installation\n\n```bash\nnpm install @diagrams-js/plugin-kubernetes\n```\n\n## Usage\n\n### Import from Kubernetes YAML\n\n```typescript\nimport { Diagram } from \"diagrams-js\";\nimport { kubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\nconst diagram = Diagram(\"My K8s Application\");\n\n// Register the plugin\nawait diagram.registerPlugins([kubernetesPlugin]);\n\n// Import from Kubernetes YAML\nconst k8sYaml = `\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web-deployment\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: web\n  template:\n    spec:\n      containers:\n      - name: web\n        image: nginx:latest\n        ports:\n        - containerPort: 80\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: web-service\nspec:\n  selector:\n    app: web\n  ports:\n  - port: 80\n    targetPort: 80\n`;\n\nawait diagram.import(k8sYaml, \"kubernetes\");\n\n// Render the diagram\nconst svg = await diagram.render();\n```\n\n### Export to Kubernetes YAML\n\n```typescript\nimport { Diagram, Node } from \"diagrams-js\";\nimport { kubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\nconst diagram = Diagram(\"My K8s Application\");\n\n// Create nodes with Kubernetes metadata\nconst deployment = diagram.add(Node(\"web-deployment\"));\ndeployment.metadata = {\n  kubernetes: {\n    kind: \"Deployment\",\n    namespace: \"default\",\n    spec: {\n      replicas: 3,\n      selector: { matchLabels: { app: \"web\" } },\n      template: {\n        spec: {\n          containers: [\n            {\n              name: \"web\",\n              image: \"nginx:latest\",\n              ports: [{ containerPort: 80 }],\n            },\n          ],\n        },\n      },\n    },\n  },\n};\n\nconst service = diagram.add(Node(\"web-service\"));\nservice.metadata = {\n  kubernetes: {\n    kind: \"Service\",\n    namespace: \"default\",\n    spec: {\n      selector: { app: \"web\" },\n      ports: [{ port: 80 }],\n    },\n  },\n};\n\n// Create relationship\nservice.to(deployment);\n\n// Register plugin and export\nawait diagram.registerPlugins([kubernetesPlugin]);\nconst k8sYaml = await diagram.export(\"kubernetes\");\n\nconsole.log(k8sYaml);\n```\n\n## Features\n\n### Import\n\n- Parse Kubernetes YAML manifests (single or multi-document)\n- Create nodes for each resource with appropriate Kubernetes icons\n- Support for Deployments, Services, ConfigMaps, Secrets, and more\n- Create edges for service-to-deployment relationships\n- Create clusters for namespaces\n- Store Kubernetes-specific metadata on nodes\n\n### Supported Resource Types\n\n- **Workloads**: Deployment, StatefulSet, DaemonSet, ReplicaSet, Pod, Job, CronJob\n- **Services**: Service, Ingress\n- **Storage**: ConfigMap, Secret, PersistentVolume, PersistentVolumeClaim, StorageClass\n- **RBAC**: Role, RoleBinding, ClusterRole, ClusterRoleBinding, ServiceAccount\n- **Cluster**: Namespace, Node, HorizontalPodAutoscaler, NetworkPolicy\n\n### Export\n\n- Export diagrams to Kubernetes YAML format\n- Generate valid Kubernetes manifests\n- Preserve resource configuration (replicas, selectors, ports, etc.)\n- Support for multi-document YAML output\n\n## Configuration\n\n### Custom Resource Mappings\n\nYou can customize which icons are used for specific Kubernetes resources. The plugin supports multiple mapping formats:\n\n**Mapping Priority:**\n\n1. **Resource name** (e.g., `my-custom-app`) - takes precedence\n2. **Resource kind** (e.g., `Deployment`, `Service`) - fallback\n\n```typescript\nimport { Diagram } from \"diagrams-js\";\nimport { createKubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\nconst diagram = Diagram(\"My K8s Application\");\n\n// Create plugin with custom resource mappings\nconst plugin = createKubernetesPlugin({\n  defaultNamespace: \"production\",\n  imageMappings: {\n    // 1. Provider icon mapping - use built-in provider icons\n    \"my-custom-deployment\": {\n      provider: \"onprem\",\n      type: \"compute\",\n      resource: \"Server\",\n    },\n\n    // 2. Direct URL string - use a custom image URL\n    \"my-custom-service\": \"https://example.com/service-icon.png\",\n\n    // 3. URL object - same as string but as object\n    \"my-storage\": {\n      url: \"https://example.com/storage-icon.svg\",\n    },\n\n    // 4. Iconify icon - use icons from Iconify (https://iconify.design/)\n    // Format: { iconify: \"prefix:name\" }\n    \"custom-app\": {\n      iconify: \"logos:kubernetes\",\n    },\n    \"redis-cache\": {\n      iconify: \"logos:redis\",\n    },\n  },\n});\n\nawait diagram.registerPlugins([plugin]);\n```\n\n### `ImageMappings` Type\n\nExported TypeScript type for defining resource mappings with full type safety:\n\n```typescript\nimport { createKubernetesPlugin, ImageMappings } from \"@diagrams-js/plugin-kubernetes\";\n\nconst mappings: ImageMappings = {\n  \"my-deployment\": { provider: \"k8s\", type: \"compute\", resource: \"Deploy\" },\n  \"my-app\": { iconify: \"logos:kubernetes\" },\n  \"custom-resource\": \"https://example.com/icon.svg\",\n};\n\nconst plugin = createKubernetesPlugin({ imageMappings: mappings });\n```\n\n## Iconify Icons\n\nThe plugin supports [Iconify](https://iconify.design/) icons, which provides access to 200,000+ open source icons. Use the `{ iconify: \"prefix:name\" }` format:\n\n- Browse icons at https://icon-sets.iconify.design/\n- Common prefixes: `logos:` (technology logos), `mdi:` (Material Design)\n- Examples:\n  - `{ iconify: \"logos:kubernetes\" }` - Kubernetes logo\n  - `{ iconify: \"logos:redis\" }` - Redis logo\n  - `{ iconify: \"mdi:server\" }` - Server icon\n\n## Working with Clusters\n\nThe Kubernetes plugin automatically creates clusters for namespaces when importing multi-namespace manifests:\n\n```typescript\nconst multiNsYaml = `\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: app\n  namespace: production\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: app\n  namespace: staging\n`;\n\nawait diagram.import(multiNsYaml, \"kubernetes\");\n// Creates two clusters: \"production\" and \"staging\"\n```\n\n## Examples\n\n### Visualize a Microservices Architecture\n\n```typescript\nimport { Diagram } from \"diagrams-js\";\nimport { kubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\nconst k8sYaml = `\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: frontend\n  namespace: production\nspec:\n  replicas: 3\n  selector:\n    matchLabels:\n      app: frontend\n  template:\n    spec:\n      containers:\n      - name: frontend\n        image: nginx:alpine\n        ports:\n        - containerPort: 80\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: frontend-service\n  namespace: production\nspec:\n  selector:\n    app: frontend\n  ports:\n  - port: 80\n---\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: api\n  namespace: production\nspec:\n  replicas: 2\n  selector:\n    matchLabels:\n      app: api\n  template:\n    spec:\n      containers:\n      - name: api\n        image: node:18\n        ports:\n        - containerPort: 3000\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: api-service\n  namespace: production\nspec:\n  selector:\n    app: api\n  ports:\n  - port: 3000\n---\napiVersion: apps/v1\nkind: StatefulSet\nmetadata:\n  name: postgres\n  namespace: production\nspec:\n  serviceName: postgres\n  replicas: 1\n  selector:\n    matchLabels:\n      app: postgres\n  template:\n    spec:\n      containers:\n      - name: postgres\n        image: postgres:15\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: postgres-service\n  namespace: production\nspec:\n  selector:\n    app: postgres\n  ports:\n  - port: 5432\n`;\n\nconst diagram = Diagram(\"Production Architecture\");\nawait diagram.registerPlugins([kubernetesPlugin]);\nawait diagram.import(k8sYaml, \"kubernetes\");\n\nconst svg = await diagram.render();\n```\n\n### Import Multiple Manifest Files\n\nCompare staging and production configurations:\n\n```typescript\nconst stagingManifest = `\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web\n  namespace: staging\nspec:\n  replicas: 1\n  template:\n    spec:\n      containers:\n      - name: web\n        image: myapp:staging\n`;\n\nconst productionManifest = `\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web\n  namespace: production\nspec:\n  replicas: 5\n  template:\n    spec:\n      containers:\n      - name: web\n        image: myapp:latest\n`;\n\nconst diagram = Diagram(\"Environment Comparison\");\nawait diagram.registerPlugins([kubernetesPlugin]);\n\n// Each manifest gets its own cluster\nawait diagram.import([stagingManifest, productionManifest], \"kubernetes\");\n```\n\n### Export with Custom Metadata\n\n```typescript\nimport { Diagram, Node } from \"diagrams-js\";\nimport { kubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\nconst diagram = Diagram(\"Production Stack\");\n\nconst deployment = diagram.add(Node(\"api\"));\ndeployment.metadata = {\n  kubernetes: {\n    kind: \"Deployment\",\n    namespace: \"production\",\n    labels: {\n      app: \"api\",\n      tier: \"backend\",\n      env: \"production\",\n    },\n    spec: {\n      replicas: 5,\n      selector: {\n        matchLabels: { app: \"api\" },\n      },\n      template: {\n        spec: {\n          containers: [\n            {\n              name: \"api\",\n              image: \"myapp:latest\",\n              resources: {\n                limits: {\n                  cpu: \"1000m\",\n                  memory: \"512Mi\",\n                },\n                requests: {\n                  cpu: \"200m\",\n                  memory: \"256Mi\",\n                },\n              },\n            },\n          ],\n        },\n      },\n    },\n  },\n};\n\nawait diagram.registerPlugins([kubernetesPlugin]);\nconst k8sYaml = await diagram.export(\"kubernetes\");\n```\n\n### Round-trip Conversion\n\nImport a manifest, modify it, then export back:\n\n```typescript\nconst diagram = Diagram(\"Modified Stack\");\nawait diagram.registerPlugins([kubernetesPlugin]);\n\n// Import existing manifest\nawait diagram.import(existingK8sYaml, \"kubernetes\");\n\n// Add a new resource\nconst monitoring = diagram.add(Node(\"prometheus\"));\nmonitoring.metadata = {\n  kubernetes: {\n    kind: \"Deployment\",\n    namespace: \"monitoring\",\n    spec: {\n      replicas: 1,\n      selector: { matchLabels: { app: \"prometheus\" } },\n      template: {\n        spec: {\n          containers: [\n            {\n              name: \"prometheus\",\n              image: \"prom/prometheus:latest\",\n              ports: [{ containerPort: 9090 }],\n            },\n          ],\n        },\n      },\n    },\n  },\n};\n\n// Export modified configuration\nconst updatedYaml = await diagram.export(\"kubernetes\");\n```\n\n## Best Practices\n\n### 1. Use Descriptive Resource Names\n\nResource names become node labels, so use clear, descriptive names:\n\n```yaml\n# ✅ Good\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: user-service\nspec:\n  ...\n\n# ❌ Avoid\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: svc1\nspec:\n  ...\n```\n\n### 2. Store Metadata for Round-trip\n\nWhen creating nodes programmatically, store Kubernetes metadata:\n\n```typescript\nconst node = diagram.add(Node(\"my-deployment\"));\nnode.metadata = {\n  kubernetes: {\n    kind: \"Deployment\",\n    namespace: \"default\",\n    spec: {\n      replicas: 3,\n      selector: { matchLabels: { app: \"my-app\" } },\n      template: {\n        spec: {\n          containers: [\n            {\n              name: \"app\",\n              image: \"nginx:latest\",\n            },\n          ],\n        },\n      },\n    },\n  },\n};\n```\n\n### 3. Handle Service Selectors\n\nThe plugin automatically creates edges when Service selectors match Deployment labels:\n\n```yaml\n# Deployment labels\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web\n  labels:\n    app: web\n    tier: frontend\n\n# Service selector matches\napiVersion: v1\nkind: Service\nmetadata:\n  name: web-service\nspec:\n  selector:\n    app: web  # Matches deployment label\n  ports:\n  - port: 80\n```\n\n### 4. Use Namespaces\n\nOrganize resources with namespaces for better visualization:\n\n```yaml\n# Production resources\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: api\n  namespace: production\n\n# Staging resources\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: api\n  namespace: staging\n```\n\n### 5. Multi-document YAML\n\nUse `---` separator for multiple resources in a single file:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: web\n---\napiVersion: v1\nkind: Service\nmetadata:\n  name: web-service\n---\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: web-config\n```\n\n## Troubleshooting\n\n### Plugin Not Found\n\nMake sure to register the plugin before using import/export:\n\n```typescript\n// ✅ Correct order\nawait diagram.registerPlugins([kubernetesPlugin]);\nawait diagram.import(k8sYaml, \"kubernetes\");\n\n// ❌ Wrong order\nawait diagram.import(k8sYaml, \"kubernetes\"); // Will fail!\nawait diagram.registerPlugins([kubernetesPlugin]);\n```\n\n### Type Errors with Metadata\n\nThe metadata property is typed as `Record<string, any>`, so you can access it directly:\n\n```typescript\nnode.metadata = {\n  kubernetes: { ... }\n};\n```\n\n### Missing Icons\n\nThe plugin maps common Kubernetes resources to provider icons automatically. For custom resources or when you want specific icons:\n\n```typescript\nconst plugin = createKubernetesPlugin({\n  imageMappings: {\n    // Option 1: Use a provider icon\n    \"my-deployment\": { provider: \"k8s\", type: \"compute\", resource: \"Deploy\" },\n\n    // Option 2: Use a custom image URL\n    \"my-app\": \"https://example.com/icon.svg\",\n\n    // Option 3: Use Iconify (200,000+ icons!)\n    \"custom-resource\": { iconify: \"logos:kubernetes\" },\n  },\n});\n```\n\n### Import Fails\n\nEnsure your Kubernetes YAML is valid and contains the required fields:\n\n```typescript\n// Validate before importing\ntry {\n  await diagram.import(k8sYaml, \"kubernetes\");\n} catch (error) {\n  console.error(\"Import failed:\", error.message);\n}\n```\n\nRequired fields for a valid Kubernetes resource:\n\n- `apiVersion`\n- `kind`\n- `metadata.name`\n\n## Runtime Support\n\nThe Kubernetes plugin supports all diagrams-js runtimes:\n\n- **Browser** ✅\n- **Node.js** ✅\n- **Deno** ✅\n- **Bun** ✅\n\n## API Reference\n\n### `kubernetesPlugin`\n\nPre-created Kubernetes plugin instance (no configuration needed).\n\n```typescript\nimport { kubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\n// ✅ Use the pre-created instance\nawait diagram.registerPlugins([kubernetesPlugin]);\n```\n\nThe plugin provides:\n\n- **Importer**: `name: \"kubernetes\"`, supports `.yml` and `.yaml` files\n- **Exporter**: `name: \"kubernetes\"`, exports to `.yaml` format\n\n### `createKubernetesPlugin(config?)`\n\nFactory function for creating a Kubernetes plugin with custom configuration.\n\n```typescript\nimport { createKubernetesPlugin } from \"@diagrams-js/plugin-kubernetes\";\n\n// ✅ Create plugin with custom configuration\nconst customPlugin = createKubernetesPlugin({\n  defaultNamespace: \"production\",\n  imageMappings: {\n    \"custom-app\": { iconify: \"logos:kubernetes\" },\n  },\n});\n\nawait diagram.registerPlugins([customPlugin]);\n```\n\n**Parameters:**\n\n- `config` (optional): `KubernetesPluginConfig`\n  - `defaultNamespace`: Default namespace for exports (default: \"default\")\n  - `ImageMappings`: Custom resource to icon mappings (see [Configuration](#configuration) section)\n\n**Returns:** `DiagramsPlugin` - The plugin instance\n\n**Complete Example with All Mapping Types:**\n\n```typescript\nconst plugin = createKubernetesPlugin({\n  defaultNamespace: \"production\",\n  imageMappings: {\n    // Provider icons - use built-in diagrams-js icons\n    \"my-deployment\": { provider: \"k8s\", type: \"compute\", resource: \"Deploy\" },\n    \"my-db\": { provider: \"k8s\", type: \"storage\", resource: \"Sts\" },\n\n    // Custom URL - use any image URL\n    frontend: \"https://example.com/react.png\",\n    backend: { url: \"https://example.com/node.svg\" },\n\n    // Iconify icons - 200,000+ icons available\n    kubernetes: { iconify: \"logos:kubernetes\" },\n    redis: { iconify: \"logos:redis\" },\n    docker: { iconify: \"logos:docker\" },\n  },\n});\n\nawait diagram.registerPlugins([plugin]);\n```\n\n### Plugin Capabilities\n\nThe plugin provides two capabilities:\n\n#### Importer\n\n- **Name:** `kubernetes`\n- **Extensions:** `.yml`, `.yaml`\n- **MIME Types:** `text/yaml`, `application/x-yaml`\n\n#### Exporter\n\n- **Name:** `kubernetes`\n- **Extension:** `.yaml`\n- **MIME Type:** `text/yaml`\n\n## Further Reading\n\n- diagrams-js Plugin System: See plugin system documentation\n- diagrams-js Documentation: https://diagrams-js.hatemhosny.dev\n- Kubernetes Documentation: https://kubernetes.io/docs/\n- Iconify Icons: https://iconify.design/\n\n## License\n\nMIT\n","readmeFilename":"README.md"}