[KEP-3104] Update KEP with credential plugin allowlist #5479

pmengelbert · 2025-08-13T21:06:24Z

One-line PR description: Update kuberc KEP with credential plugin allowlist

Issue link: Separate kubectl user preferences from cluster configs #3104

Other comments:

Currently, the kubeconfig may specify arbitrary binaries to run as
client-go credential plugins. Due to the fact that kubeconfig files are
often generated, and because they contain a lot of noise, there is
significant friction in manually inspecting the kubeconfig for
suspicious binaries after it is generated.

To encourage secure behavior, we want to introduce an allowlist to the
kuberc, which will describe the conditions under which a binary plugin
may be run. Currently the only condition is the name (absolute path or
basename of a binary found in PATH).

linux-foundation-easycla · 2025-08-13T21:06:30Z

The committers listed above are authorized under a signed CLA.

✅ login: enj / name: Mo Khan (5c0a1a2)
✅ login: pmengelbert / name: Peter Engelbert (b7c62b7, d15a576, 3049564, fc26f15, 23506b7, e72021f, 33248b0, 2276629, ae97a4d)

k8s-ci-robot · 2025-08-13T21:06:30Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

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

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

Needs approval from an approver in each of these files:

keps/sig-cli/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 · 2025-08-13T21:06:33Z

Welcome @pmengelbert!

It looks like this is your first PR to kubernetes/enhancements 🎉. 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/enhancements 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 · 2025-08-13T21:06:34Z

Hi @pmengelbert. Thanks for your PR.

I'm waiting for a kubernetes 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.

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.

enj · 2025-08-14T16:05:29Z

/sig auth

enj · 2025-08-14T16:28:36Z

This LGTM from a SIG Auth perspective (I added us as a participating SIG).

enj · 2025-08-14T16:29:04Z

/ok-to-test

ardaguclu · 2025-08-27T07:03:38Z

keps/sig-cli/3104-introduce-kuberc/README.md

@@ -331,6 +337,31 @@ intended behavior and realizing that targeting options effectively addresses the
 use cases. During command execution, a merge will be occur, with inline overrides
 taking precedence over the defaults.

+`credentialPluginAllowlist` allows the end-user to provide an array of objects


I think, it makes sense to add an example to show how this will be formed.

There is an example in this same PR, below. Or are you asking for something different?

ardaguclu · 2025-08-27T07:04:38Z

keps/sig-cli/3104-introduce-kuberc/README.md

+binary in question must meet all of the required conditions in that entry in
+order to be executed. At the outset, the entry object will have only one field,
+`name`. The path of the binary specified in the kubeconfig will be compared
+against that named in the `name` field. This field may contain a basename, or


Does this support $PATH/cred_plugin?. Does full path cover ~/cred_plugin?

Actually this depends on the behavior of os.LookPath

This reminds me: the function is exec.LookPath, not os.LookPath. I made a mistake in this PR and will update it accordingly.

exec.LookPath doesn't do tilde expansion, but that is POSIX shell behavior and not exec syscall behavior (at least on linux). I believe we should stop short of emulating POSIX substitution rules; the user can add e.g. $HOME/bin to their PATH if they want.

This reminds me: the function is exec.LookPath, not os.LookPath. I made a mistake in this PR and will update it accordingly.

This has been fixed

ardaguclu · 2025-08-27T07:06:00Z

keps/sig-cli/3104-introduce-kuberc/README.md

+execute.  If no criteria set succeeds after comparing the binary to all sets of
+criteria, the operation will be immediately aborted and an error returned. If
+`credentialPluginAllowlist` is not provided, or is explicitly made `nil`, all
+binaries will be allowed. If `credentialPluginAllowlist`'s value is set to the


I think, we should mention about this list will not be applied for some commands such as kubectl config view and the reason?.

ardaguclu · 2025-08-27T07:07:38Z

keps/sig-cli/3104-introduce-kuberc/README.md

+criteria, the operation will be immediately aborted and an error returned. If
+`credentialPluginAllowlist` is not provided, or is explicitly made `nil`, all
+binaries will be allowed. If `credentialPluginAllowlist`'s value is set to the
+empty list `[]`, *all binaries will be prohibited*.


This is API behavior. So I wonder opinions from @liggitt.
credentialPluginAllowlist: nil -- all allowed
credentialPluginAllowlist: [] -- all prohibited

we try to avoid having an empty list and a nil list behave differently ... it tends to confuse users, and some tools that generate config files will not preserve that distinction

instead, having something explicit in the config to indicate this, either as a fixed special value in the list (e.g. credentialPluginAllowlist: ["none"] or credentialPluginAllowlist: [""]) or as a distinct field that works together with the allowlist field (e.g. credentialPluginPolicy: EnableAll | DisableAll | Allowlist)

Thanks. Of the available options, I prefer the explicit policy. I'd prefer to have these nested under a single top-level grouping, such as

credentialPlugin: policy: Allowlist allowlist: - name: credential-plugin.sh

@ardaguclu @liggitt thoughts on the above?

Playing out what it would look like for the three possibly ways they'd want to configure this:

Allow all

absent / default

explicit with nested structure:

credentialPlugin: policy: AllowAll

explicit with peer structure

credentialPluginPolicy: AllowAll

Allow none

nested structure:

credentialPlugin: policy: DisableAll

flat structure:

credentialPluginPolicy: DisableAll

Allowlist

nested structure:

credentialPlugin: policy: Allowlist allowlist: [...]

flat structure:

credentialPluginPolicy: Allowlist credentialPluginAllowlist: [...]

The flat structure seems simpler for the existing cases, and avoids the possibility of ~invalid constructions like credentialPlugin: {}. Are there any other credentialPlugin preferences / options we anticipate wanting to group along with these?

I have pushed changes addressing this, opting for the flat structure.

ardaguclu

Overall looks good to me. I'll defer the final approval from SIG-CLI POV to @soltysh

ardaguclu · 2025-09-05T12:59:02Z

keps/sig-cli/3104-introduce-kuberc/README.md

+reason. The user should instead use `credentialPluginPolicy: DisableAll` in
+this case.
+
+Commands that don't create a client, such as `kubectl config view` will not be


is there any other command that will be exceptional like kubectl config view?

Off the top of my head, there are
kubectl config (any subcommand)
kubectl version
kubectl plugin list

Should I update the KEP with a full list?

hmm... I think it's going to be hard to enumerate every specific command that won't actually use the client. There's lots of commands that only run locally with specific options (e.g. all kubectl create ... --dry-run=client commands, or kubectl {label,annotate,set} --local)

I think the implementation should be structured so that it intercepts attempts to use a non-allowlisted credential plugin and rejects them at time of use, so commands that don't even need the plugin don't start failing for no reason.

I think the implementation should be structured so that it intercepts attempts to use a non-allowlisted credential plugin and rejects them at time of use, so commands that don't even need the plugin don't start failing for no reason.

So that significantly changes the implementation. Maybe we just need to get the list of plugins (allowed, disallowed, etc.) in kubectl/cmd and pass it to client-go (or cli-runtime) to accept/reject this credential exec plugin, when there is a request to API Server?

ardaguclu · 2025-09-05T13:00:29Z

I think, this PR needs a rebase to remove the invalid-commit label. Otherwise, this PR can't be merged.

Currently, the kubeconfig may specify arbitrary binaries to run as client-go credential plugins. Due to the fact that kubeconfig files are often generated, and because they contain a lot of noise, there is significant friction in manually inspecting the kubeconfig for suspicious binaries after it is generated. To encourage secure behavior, we want to introduce an allowlist to the kuberc, which will describe the conditions under which a binary plugin may be run. Currently the only condition is the name (absolute path or basename of a binary found in `PATH`). Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

- Describe behavior when allowlist is `nil` - Describe behavior when allowlist is empty - Describe future plans for field additions Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

In the credential plugin allowlist, consider nil and empty lists an error. Jordan Liggitt has pointed out that treating them differently is generally avoided in APIs, as it can confuse users. In order to make the user's intention more explicit, an additional field, `credentialPluginPolicy` has been added. Its value must be one of `EnableAll | DisableAll | Allowlist`. `EnableAll` and `DisableAll` are self-explanatory and do not require an allowlist. `Allowlist` will use the allowlist as defined in the KEP. Note that this change considers the following cases to be errors: - a policy of `EnableAll` with an allowlist provided - a policy of `DisableAll` with an allowlist provided - a policy of `Allowlist` with no allowlist provided (i.e. a `nil` allowlist` - a policy of `Allowlist` with an explicitly empty allowlist provided Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

pmengelbert · 2025-09-08T18:12:13Z

I think, this PR needs a rebase to remove the invalid-commit label. Otherwise, this PR can't be merged.

Just rebased, and fixed that commit.

k8s-ci-robot requested a review from ardaguclu August 13, 2025 21:06

k8s-ci-robot added the kind/kep Categorizes KEP tracking issues and PRs modifying the KEP directory label Aug 13, 2025

k8s-ci-robot requested a review from soltysh August 13, 2025 21:06

k8s-ci-robot added the sig/cli Categorizes an issue or PR as relevant to SIG CLI. label Aug 13, 2025

github-project-automation bot added this to SIG CLI Aug 13, 2025

k8s-ci-robot added the cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. label Aug 13, 2025

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 Aug 13, 2025

github-project-automation bot moved this to Needs Triage in SIG CLI Aug 13, 2025

k8s-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Aug 13, 2025

k8s-ci-robot added the sig/auth Categorizes an issue or PR as relevant to SIG Auth. label Aug 14, 2025

k8s-ci-robot 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 Aug 14, 2025

enj added this to SIG Auth Aug 15, 2025

enj moved this to Needs Triage in SIG Auth Aug 15, 2025

k8s-ci-robot added cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. and removed cncf-cla: no Indicates the PR's author has not signed the CNCF CLA. labels Aug 19, 2025

pmengelbert mentioned this pull request Aug 25, 2025

[WIP] Add credential plugin allowlist to kuberc kubernetes/kubernetes#133688

Draft

ibihim moved this from Needs Triage to In Review in SIG Auth Aug 25, 2025

ardaguclu reviewed Aug 27, 2025

View reviewed changes

k8s-ci-robot added the do-not-merge/invalid-commit-message Indicates that a PR should not merge because it has an invalid commit message. label Sep 2, 2025

ardaguclu reviewed Sep 5, 2025

View reviewed changes

pmengelbert and others added 7 commits September 8, 2025 14:01

Revise based on feedback

d15a576

- Describe behavior when allowlist is `nil` - Describe behavior when allowlist is empty - Describe future plans for field additions Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Add SIG Auth as participating SIG

5c0a1a2

Fix typos

2276629

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Update TOC for KEP 3104

fc26f15

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Correct os.LookPath to exec.LookPath

e72021f

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Add note about when the allowlist will not apply

ae97a4d

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

Fix typo

3049564

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

pmengelbert force-pushed the pmengelbert/sig-cli/kuberc/4 branch from 49a8abd to 7e85530 Compare September 8, 2025 18:01

pmengelbert added 2 commits September 8, 2025 14:11

Fix typo in KEP

23506b7

Signed-off-by: Peter Engelbert <pmengelbert@gmail.com>

pmengelbert force-pushed the pmengelbert/sig-cli/kuberc/4 branch from 7e85530 to 23506b7 Compare September 8, 2025 18:11

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 Sep 8, 2025

[KEP-3104] Update KEP with credential plugin allowlist #5479

Are you sure you want to change the base?

[KEP-3104] Update KEP with credential plugin allowlist #5479

Conversation

pmengelbert commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linux-foundation-easycla bot commented Aug 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

k8s-ci-robot commented Aug 13, 2025

Uh oh!

k8s-ci-robot commented Aug 13, 2025

Uh oh!

k8s-ci-robot commented Aug 13, 2025

Uh oh!

enj commented Aug 14, 2025

Uh oh!

enj commented Aug 14, 2025

Uh oh!

enj commented Aug 14, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Allow all

Allow none

Allowlist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ardaguclu left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ardaguclu Sep 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ardaguclu commented Sep 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pmengelbert commented Sep 8, 2025

Uh oh!

Uh oh!

pmengelbert commented Aug 13, 2025 •

edited

Loading

linux-foundation-easycla bot commented Aug 13, 2025 •

edited

Loading

ardaguclu Sep 9, 2025 •

edited

Loading

ardaguclu commented Sep 5, 2025 •

edited

Loading