docs(plugin): document KUSTOMIZE_PLUGIN_HOME and plugin-home resolution by alliasgher · Pull Request #6127 · kubernetes-sigs/kustomize

alliasgher · 2026-04-17T00:08:17Z

Summary

Adds a "Plugin home" section to `plugin/README.md` describing the directory kustomize uses to look up Exec and Go plugins.

The section documents the four-step resolution order kustomize applies to find the plugin home:

`$KUSTOMIZE_PLUGIN_HOME`
`$XDG_CONFIG_HOME/kustomize/plugin`
`$HOME/.config/kustomize/plugin` (used when `$XDG_CONFIG_HOME` is unset)
`$HOME/kustomize/plugin`

It also notes the Windows `$USERPROFILE` fallback for `$HOME` and the relative layout kustomize uses to load an individual plugin (`///`).

Content comes directly from `api/konfig/plugins.go` and `api/internal/plugins/loader/loader.go`.

Fixes #5706.

/kind documentation

k8s-ci-robot · 2026-04-17T00:08:24Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: alliasgher
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2026-04-17T00:08:27Z

Welcome @alliasgher!

It looks like this is your first PR to kubernetes-sigs/kustomize 🎉. Please refer to our pull request process documentation to help your PR have a smooth ride to approval.

You will be prompted by a bot to use commands during the review process. Do not be afraid to follow the prompts! It is okay to experiment. Here is the bot commands documentation.

You can also check if kubernetes-sigs/kustomize has its own contribution guidelines.

You may want to refer to our testing guide if you run into trouble with your tests not passing.

If you are having difficulty getting your pull request seen, please follow the recommended escalation practices. Also, for tips and tricks in the contribution process you may want to read the Kubernetes contributor cheat sheet. We want to make sure your contribution gets all the attention it needs!

Thank you, and welcome to Kubernetes. 😃

k8s-ci-robot · 2026-04-17T00:08:28Z

Hi @alliasgher. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work.

Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

Add a "Plugin home" section to plugin/README.md describing the order in which kustomize resolves the plugin home directory: 1. $KUSTOMIZE_PLUGIN_HOME 2. $XDG_CONFIG_HOME/kustomize/plugin 3. $HOME/.config/kustomize/plugin 4. $HOME/kustomize/plugin Also note the Windows $USERPROFILE fallback and the relative path layout used when loading an individual plugin. Content is taken directly from api/konfig/plugins.go and api/internal/plugins/loader. Signed-off-by: Ali <alliasgher123@gmail.com>

k8s-triage-robot · 2026-07-16T00:22:43Z

The Kubernetes project currently lacks enough contributors to adequately respond to all PRs.

This bot triages PRs according to the following rules:

After 90d of inactivity, lifecycle/stale is applied
After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
After 30d of inactivity since lifecycle/rotten was applied, the PR is closed

You can:

Mark this PR as fresh with /remove-lifecycle stale
Close this PR with /close
Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

kubernetes-prow · 2026-07-16T11:51:50Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: alliasgher
Once this PR has been reviewed and has the lgtm label, please assign varshaprasad96 for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

koba1t · 2026-07-16T11:53:21Z

/ok-to-test

koba1t · 2026-07-18T09:55:37Z

+   unset.
+4. `$HOME/kustomize/plugin`.
+
+If none of the above exist, plugin resolution fails. On Windows,


On Windows, the code does not fall back from HOME to USERPROFILE; homeEnv() directly selects USERPROFILE instead of HOME. Please change this to something like: “On Windows, $USERPROFILE is used in place of $HOME.”

koba1t · 2026-07-18T09:56:10Z

+1. `$KUSTOMIZE_PLUGIN_HOME` — set this to override the default search
+   paths below (useful when plugins live outside `$HOME`).
+2. `$XDG_CONFIG_HOME/kustomize/plugin`.
+3. `$HOME/.config/kustomize/plugin` — used when `$XDG_CONFIG_HOME` is


The note for $HOME/.config/kustomize/plugin does not match the implementation. This candidate is always tried after $XDG_CONFIG_HOME/kustomize/plugin; it is not limited to the case where XDG_CONFIG_HOME is unset. If XDG_CONFIG_HOME is set but that directory does not exist, Kustomize still falls back to $HOME/.config/kustomize/plugin.
Could we describe this as the default XDG-style location, or explicitly say that it is also tried when the configured XDG path does not exist?

koba1t · 2026-07-18T09:58:15Z

+matching the `apiVersion` and `kind` fields of the generator or
+transformer entry in `kustomization.yaml`.
+
 #### Testing


The new heading changes the document hierarchy so that #### Testing becomes a subsection of ### Plugin home. Since that section describes plugin testing in general, could we either move Plugin home after Testing or promote Testing to an ### heading?

koba1t · 2026-07-18T09:59:18Z

+Within the plugin home, an individual plugin is loaded from
+`<apiVersion group>/<apiVersion version>/<lowercase kind>/<Kind>`,
+matching the `apiVersion` and `kind` fields of the generator or
+transformer entry in `kustomization.yaml`.


Please distinguish the Exec and Go plugin paths. Kustomize first tries //// as an executable, then tries the same path with .so for a Go plugin.
Also, generators and transformers entries in kustomization.yaml are file paths. The apiVersion and kind are read from the referenced plugin configuration file, not directly from the list entry itself. An explicit example would make this much clearer.

Updated: the docs now note that generators/transformers entries are file paths whose apiVersion and kind come from the referenced config file, and that kustomize resolves the derived path first as an executable (Exec plugin) then as .so (Go plugin), with an explicit SedTransformer example.

Signed-off-by: Ali <alliasgher123@gmail.com>

kubernetes-prow · 2026-07-19T15:01:41Z

This PR has multiple commits, and the default merge method is: merge.
You can request commits to be squashed using the label: tide/merge-method-squash

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

k8s-ci-robot added kind/documentation Categorizes issue or PR as related to documentation. do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. labels Apr 17, 2026

k8s-ci-robot requested review from koba1t and sarab97 April 17, 2026 00:08

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Apr 17, 2026

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Apr 17, 2026

k8s-ci-robot added the size/S Denotes a PR that changes 10-29 lines, ignoring generated files. label Apr 17, 2026

alliasgher force-pushed the docs/5706-plugin-home branch from a20caf6 to dc29d4b Compare April 17, 2026 00:20

k8s-ci-robot removed the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Apr 17, 2026

alliasgher mentioned this pull request Apr 17, 2026

Document KUSTOMIZE_PLUGIN_HOME #5706

Open

kubernetes-prow Bot added the lifecycle/stale Denotes an issue or PR has remained open with no activity and has become stale. label Jul 16, 2026

koba1t closed this Jul 16, 2026

koba1t reopened this Jul 16, 2026

kubernetes-prow Bot added ok-to-test Indicates a non-member PR verified by an org member that is safe to test. and removed needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. labels Jul 16, 2026

koba1t requested changes Jul 18, 2026

View reviewed changes

docs(plugin): clarify Exec vs Go plugin resolution and config-file paths

4347054

Signed-off-by: Ali <alliasgher123@gmail.com>

kubernetes-prow Bot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. and removed size/S Denotes a PR that changes 10-29 lines, ignoring generated files. labels Jul 19, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(plugin): document KUSTOMIZE_PLUGIN_HOME and plugin-home resolution#6127

docs(plugin): document KUSTOMIZE_PLUGIN_HOME and plugin-home resolution#6127
alliasgher wants to merge 2 commits into
kubernetes-sigs:masterfrom
alliasgher:docs/5706-plugin-home

alliasgher commented Apr 17, 2026

Uh oh!

k8s-ci-robot commented Apr 17, 2026

Uh oh!

k8s-ci-robot commented Apr 17, 2026

Uh oh!

k8s-ci-robot commented Apr 17, 2026

Uh oh!

k8s-triage-robot commented Jul 16, 2026

Uh oh!

kubernetes-prow Bot commented Jul 16, 2026

Uh oh!

koba1t commented Jul 16, 2026

Uh oh!

koba1t Jul 18, 2026

Uh oh!

koba1t Jul 18, 2026

Uh oh!

koba1t Jul 18, 2026

Uh oh!

koba1t Jul 18, 2026

Uh oh!

alliasgher Jul 19, 2026

Uh oh!

kubernetes-prow Bot commented Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

alliasgher commented Apr 17, 2026

Summary

Uh oh!

k8s-ci-robot commented Apr 17, 2026

Uh oh!

k8s-ci-robot commented Apr 17, 2026

Uh oh!

k8s-ci-robot commented Apr 17, 2026

Uh oh!

k8s-triage-robot commented Jul 16, 2026

Uh oh!

kubernetes-prow Bot commented Jul 16, 2026

Uh oh!

koba1t commented Jul 16, 2026

Uh oh!

koba1t Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

koba1t Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

koba1t Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

koba1t Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

alliasgher Jul 19, 2026

Choose a reason for hiding this comment

Uh oh!

kubernetes-prow Bot commented Jul 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants