{"id":26124426,"url":"https://github.com/dnaeon/kustomize-dot","last_synced_at":"2025-04-13T14:43:04.625Z","repository":{"id":253535439,"uuid":"840414576","full_name":"dnaeon/kustomize-dot","owner":"dnaeon","description":"CLI app and kustomize KRM Function plugin which renders a graph of Kubernetes resources and their origins","archived":false,"fork":false,"pushed_at":"2025-03-12T11:12:13.000Z","size":526,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"v1","last_synced_at":"2025-04-05T23:46:41.444Z","etag":null,"topics":["graphviz","graphviz-dot","kubernetes","kustomize","kustomize-plugin"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-2-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dnaeon.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["dnaeon"]}},"created_at":"2024-08-09T16:46:13.000Z","updated_at":"2025-03-12T11:12:10.000Z","dependencies_parsed_at":"2024-08-17T14:27:32.782Z","dependency_job_id":"b410b923-5b38-4081-bdfb-750347c2115e","html_url":"https://github.com/dnaeon/kustomize-dot","commit_stats":null,"previous_names":["dnaeon/kustomize-dot"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnaeon%2Fkustomize-dot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnaeon%2Fkustomize-dot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnaeon%2Fkustomize-dot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dnaeon%2Fkustomize-dot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dnaeon","download_url":"https://codeload.github.com/dnaeon/kustomize-dot/tar.gz/refs/heads/v1","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248731768,"owners_count":21152838,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphviz","graphviz-dot","kubernetes","kustomize","kustomize-plugin"],"created_at":"2025-03-10T16:08:19.152Z","updated_at":"2025-04-13T14:43:04.596Z","avatar_url":"https://github.com/dnaeon.png","language":"Go","funding_links":["https://github.com/sponsors/dnaeon"],"categories":[],"sub_categories":[],"readme":"# kustomize-dot\n\n[![Build Status](https://github.com/dnaeon/kustomize-dot/actions/workflows/test.yaml/badge.svg)](https://github.com/dnaeon/kustomize-dot/actions/workflows/test.yaml/badge.svg)\n[![Go Reference](https://pkg.go.dev/badge/github.com/dnaeon/kustomize-dot.svg)](https://pkg.go.dev/github.com/dnaeon/kustomize-dot)\n[![Go Report Card](https://goreportcard.com/badge/github.com/dnaeon/kustomize-dot)](https://goreportcard.com/report/github.com/dnaeon/kustomize-dot)\n[![codecov](https://codecov.io/gh/dnaeon/kustomize-dot/branch/master/graph/badge.svg)](https://codecov.io/gh/dnaeon/kustomize-dot)\n\n`kustomize-dot` is a CLI and [kustomize](https://kustomize.io/)\n[KRM Function plugin](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md),\nwhich generates a graph of Kubernetes resources and their origin.\n\n![Hello World](./images/hello-world.svg)\n\n# Requirements\n\n* Go version 1.22.x or later\n* Docker for local development\n* [kustomize](https://kustomize.io/) for building manifests\n\n# Installation\n\nThere are multiple ways to install `kustomize-dot`.\n\nIn order to build `kustomize-dot` from the latest repo sources execute the\nfollowing command.\n\n``` shell\nmake build\n```\n\nIf you prefer installing `kustomize-dot` using `go install` execute the\nfollowing command instead.\n\n``` shell\ngo install github.com/dnaeon/kustomize-dot/cmd/kustomize-dot@latest\n```\n\nBuild a Docker image of `kustomize-dot`.\n\n``` shell\nmake docker-build\n```\n\n# Usage\n\n`kustomize-dot` can operate in two modes - as a standalone CLI application, or\nas a\n[KRM Function plugin](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/containerized_krm_functions/).\n\nIn order to generate a graph of the Kubernetes resources and their origin when\nbuilding a kustomization target we need to enable the `originAnnotations` build\noption in our `kustomization.yaml` file.\n\n``` yaml\nbuildMetadata:\n  - originAnnotations\n```\n\n## CLI\n\nThe following section provides some examples on how to use `kustomize-dot` as a\nstandalone CLI app.\n\nThe following example is based on the official\n[kustomize helloWorld example](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/helloWorld).\n\n``` yaml\n---\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nmetadata:\n  name: hello-world\n\nbuildMetadata:\n  - originAnnotations\n\nresources:\n  - https://github.com/kubernetes-sigs/kustomize//examples/helloWorld/?timeout=120\n```\n\nIn order to generate the graph we can build the manifests using `kustomize\nbuild`, pipe the resources to `kustomize-dot` for generating the [Dot\nrepresentation](https://graphviz.org/doc/info/lang.html), and finally pipe the\nresult to `dot` for rendering the graph.\n\nThe [fixtures package](./pkg/fixtures) contains ready to render resources, which\nhave already been built using `kustomize build`. The following command will\nrender the graph for the [kustomize helloWorld\nexample](https://github.com/kubernetes-sigs/kustomize/tree/master/examples/helloWorld).\n\n``` shell\nkustomize-dot generate -f pkg/fixtures/hello-world.yaml | \\\n    dot -T svg -o graph.svg\n```\n\nOr you could execute the following command instead, which will generate the same\ngraph.\n\n``` shell\nkustomize build examples/hello-world | \\\n    kustomize-dot generate -f - | \\\n    dot -T svg -o graph.svg\n```\n\nThe following example builds the graph of resources for\n[kube-prometheus operator](https://github.com/prometheus-operator/kube-prometheus).\n\n``` shell\nkustomize-dot generate -f pkg/fixtures/kube-prometheus.yaml\n```\n\nThe [resulting graph is big](./images/kube-prometheus-full.svg) enough to be\nconfusing.\n\n`kustomize-dot` is flexible and supports filtering of resources, highlighting of\nresources or whole namespaces, setting graph layout direction, etc. This is\nuseful when we want to get a more focused view of the resulting graph.\n\nFor example the following graph will _keep_ only resources from the `default`\nand `kube-system` namespaces.\n\n``` shell\nkustomize-dot generate -f pkg/fixtures/kube-prometheus.yaml \\\n    --keep-namespace default \\\n    --keep-namespace kube-system\n```\n\nThe result looks like this.\n\n![kube-prometheus-1](./images/kube-prometheus-1.svg)\n\nWe can also highlight the resources from the different namespaces, e.g.\n\n```shell\nkustomize-dot generate -f pkg/fixtures/kube-prometheus.yaml \\\n    --keep-namespace default \\\n    --keep-namespace kube-system \\\n    --highlight-namespace default=pink \\\n    --highlight-namespace kube-system=yellow\n```\n\nThis is what the graph above looks like when we've applied highlighting to it.\n\n![kube-prometheus-2](./images/kube-prometheus-2.svg)\n\nThe following example will keep only the `ConfigMap` resources from the\n`monitoring` namespace.\n\n```shell\nkustomize-dot generate -f pkg/fixtures/kube-prometheus.yaml \\\n    --keep-namespace monitoring \\\n    --keep-kind ConfigMap\n```\n\nAnd this is what the graph for the `ConfigMap` resources looks like.\n\n![kube-prometheus-3](./images/kube-prometheus-3.svg)\n\nThe `--keep-kind`, `--keep-namespace`, `--drop-kind`, `--drop-namespace`,\n`--highlight-kind` and `--highlight-namespace` options may be repeated any\nnumber of times, which allows the filters to be applied on many resource kinds\nand namespaces.\n\nThis example keeps resources from the `monitoring` namespace only, but drops all\n`ConfigMap` resources from it, and then highlights various kinds with different\ncolors.\n\n``` shell\nkustomize-dot generate -f pkg/fixtures/kube-prometheus.yaml \\\n    --keep-namespace monitoring \\\n    --drop-kind ConfigMap \\\n    --highlight-kind service=yellow \\\n    --highlight-kind servicemonitor=orange \\\n    --highlight-kind serviceaccount=lightgray \\\n    --highlight-kind deployment=magenta \\\n    --highlight-kind prometheusrule=lightgreen \\\n    --highlight-kind networkpolicy=cyan\n```\n\nThe resulting graph looks like this.\n\n![kube-prometheus-4](./images/kube-prometheus-4.svg)\n\n## KRM Function\n\nWhen `kustomize-dot` is invoked as a [KRM Function\nplugin](https://kubectl.docs.kubernetes.io/guides/extending_kustomize/containerized_krm_functions/)\nit acts as a transformer in accordance to the [KRM Function\nspec](https://github.com/kubernetes-sigs/kustomize/blob/master/cmd/config/docs/api-conventions/functions-spec.md),\nwhich accepts a `ResourceList` as input on `stdin` and outputs a single\n`ConfigMap` with the [Dot\nrepresentation](https://graphviz.org/doc/info/lang.html) of the resources and\ntheir origin on `stdout`.\n\nThe KRM Function supports the same features as the CLI application, allowing the\nuser to filter out specific resources, set graph layout and highlight resources\nand namespaces.\n\nThe following is an example configuration for the `kustomize-dot` KRM Function\nplugin. You can find this example in the\n[examples/kube-prometheus-transformer](./examples/kube-prometheus-transformer)\ndirectory of this repo.\n\n``` yaml\n# transformer.yaml\n---\napiVersion: dnaeon.github.io/v1\nkind: KustomizeDot\nmetadata:\n  name: kustomize-dot\n  annotations:\n    config.kubernetes.io/function: |\n      container:\n        image: dnaeon/kustomize-dot:latest\nspec:\n  # Graph layout direction - TB, BT, LR or RL\n  layout: LR\n\n  # Highlight resources of a given kind with the specified color\n  highlightKinds:\n    Deployment: green\n    Service: yellow\n    Role: pink\n\n  # Highlight all resources from a given namespace with the specified color\n  highlightNamespaces:\n    default: orange\n    kube-system: pink\n\n  # Drop specified resources from the graph\n  dropKinds:\n    # - ConfigMap\n    # - RoleBinding\n\n  # Drop all resources from the specified namespaces\n  dropNamespaces:\n    - foo\n    - bar\n\n  # Keep the specified resources only and drop anything else\n  keepKinds:\n    # - baz\n    # - qux\n\n  # Keep the resources from the specified namespaces only, and drop anything\n  # else.\n  keepNamespaces:\n    # - monitoring\n```\n\nAnd this is an example kustomization file, which uses our KRM Function plugin as\na transformer.\n\n``` yaml\n# kustomization.yaml\n---\napiVersion: kustomize.config.k8s.io/v1beta1\nkind: Kustomization\nmetadata:\n  name: kube-prometheus\n\nbuildMetadata:\n  - originAnnotations\n\nresources:\n  - https://github.com/prometheus-operator/kube-prometheus//\n\ntransformers:\n  - transformer.yaml\n```\n\nThe following command will build the manifests and then pass them to our plugin,\nwhich will generate the Dot representation of the resources. The output will\ncontain a single `ConfigMap` named `kustomize-dot`, whose data is the actual\n`dot` representation of the graph.\n\n``` shell\nkustomize build --enable-alpha-plugins examples/kube-prometheus-transformer\n```\n\nOr you can pipe the output directly to `dot(1)` and render the graph, e.g.\n\n``` shell\nkustomize build --enable-alpha-plugins examples/kube-prometheus-transformer | \\\n    yq '.data.dot' | \\\n    dot -Tsvg -o graph.svg\n```\n\n# Tests\n\nRun the tests.\n\n``` shell\nmake test\n```\n\nRun test coverage.\n\n``` shell\nmake test-cover\n```\n\n# Contributing\n\n`kustomize-dot` is hosted on\n[Github](https://github.com/dnaeon/kustomize-dot). Please contribute by\nreporting issues, suggesting features or by sending patches using pull requests.\n\n# License\n\n`kustomize-dot` is Open Source and licensed under the [BSD\nLicense](http://opensource.org/licenses/BSD-2-Clause).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnaeon%2Fkustomize-dot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdnaeon%2Fkustomize-dot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdnaeon%2Fkustomize-dot/lists"}