exec credential provider: v1 documentation #28429

ankeesler · 2021-06-15T20:18:02Z

Adds documentation for client-go credential plugin GA version.

KEP: https://github.com/kubernetes/enhancements/tree/master/keps/sig-auth/541-external-credential-providers

k8sio-netlify-preview-bot · 2021-06-15T20:18:06Z

👷 Deploy Preview for kubernetes-io-vnext-staging processing.

🔨 Explore the source changes: a30e63d

🔍 Inspect the deploy log: https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/60eda78e8ab3f60007f4af52

liggitt · 2021-06-16T14:43:34Z

content/en/docs/reference/access-authn-authz/authentication.md

-      apiVersion: "client.authentication.k8s.io/v1beta1"
+      # set an environment variable, pass an argument to the tool that indicates which version the exec plugin expects,
+      # or read the version from the ExecCredential object in the KUBERNETES_EXEC_INFO environment variable.
+      apiVersion: "client.authentication.k8s.io/v1"


when we have multiple versions available, we've added per-version examples in tabs

see https://github.com/kubernetes/website/blame/master/content/en/docs/reference/access-authn-authz/extensible-admission-controllers.md#L98 as an example

i went ahead and added tabs for all of the non-trivial API objects.

6a3abda

liggitt · 2021-06-16T14:44:39Z

content/en/docs/reference/access-authn-authz/authentication.md

+      # returned. Valid values are "Never" (this exec plugin never uses standard input),
+      # "IfAvailable" (this exec plugin wants to use standard input if it is available),
+      # or "Always" (this exec plugin requires standard input to function). Required.
+      interactiveMode: IfAvailable


I assume people will copy/paste this example blindly, and interactive credential plugins are perhaps not the ideal... would it make sense to make the example be "Never"?

ok, i can get on board with interactive credential plugins are perhaps not the ideal. maybe s/ideal/the norm/? i originally had IfAvailable because it was the default in v1beta1, but i think your argument makes sense. 5c22507

liggitt · 2021-06-16T14:45:07Z

content/en/docs/reference/access-authn-authz/authentication.md

+      apiVersion: "client.authentication.k8s.io/v1"
+      interactiveMode: IfAvailable


same comment about multiple version examples in tabs, and making the default example use "Never"

liggitt · 2021-06-16T14:45:48Z

content/en/docs/reference/access-authn-authz/authentication.md

+to the plugin. Plugins should use the `spec.interactive` field of the input
+`ExecCredential` object from the `KUBERNETES_EXEC_INFO` environment variable in order to
+determine if `stdin` has been provided. A plugin's `stdin` requirements (i.e., whether
+`stdin` is optional, strictly required, or strictly not required in order for the plugin


"strictly not required" reads weirdly... maybe "never used"?

validated "never used" with a couple of other people, so i went with that. c06d8ff

liggitt · 2021-06-16T14:46:31Z

content/en/docs/reference/access-authn-authz/authentication.md


 To use bearer token credentials, the plugin returns a token in the status of the
 [`ExecCredential`](/docs/reference/config-api/client-authentication.v1beta1/#client-authentication-k8s-io-v1beta1-ExecCredential)

 ```json
 {
-  "apiVersion": "client.authentication.k8s.io/v1beta1",
+  "apiVersion": "client.authentication.k8s.io/v1",


multiple tabs for examples in different versions

liggitt · 2021-06-16T14:46:45Z

content/en/docs/reference/access-authn-authz/authentication.md

@@ -1026,6 +1050,7 @@ The following `ExecCredential` manifest describes a cluster information sample.
        "you": ["can", "put", "anything", "here"]
      }
    }


missing trailing comma

wow, good catch; 7d5a81b

PI-Victor · 2021-06-16T14:49:12Z

/assign

ankeesler · 2021-06-17T19:20:09Z

content/en/docs/reference/access-authn-authz/authentication.md

+[kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) (see table
+below for valid values).
+
+| `interactiveMode` Value | Meaning |


@PI-Victor do you know of a way that I can ensure that this table renders without splitting words on different lines?

sorry i missed this, @sftim have any idea on this one? does it need some special css code to fix this?

Ah, HTML table layout.

I would raise a separate issue about the rendering and label it area/web-development.

raised issue here: #28815

unfortunately couldn't coax the bot into applying the area/web-development...perhaps someone can enlighten me

liggitt · 2021-06-18T15:10:56Z

preview at https://deploy-preview-28429--kubernetes-io-vnext-staging.netlify.app/docs/reference/access-authn-authz/authentication/

liggitt · 2021-06-18T15:13:19Z

content lgtm, though hold for v1 API merge

ankeesler · 2021-07-06T17:44:55Z

v1 API has merged - kubernetes/kubernetes#102890

sftim · 2021-07-06T18:10:27Z

content/en/docs/reference/access-authn-authz/authentication.md

+[kubeconfig](/docs/concepts/configuration/organize-cluster-access-kubeconfig/) (see table
+below for valid values).
+
+| `interactiveMode` Value | Meaning |


Optionally: add a caption using the table shortcode.

added a caption here: cbbded0

PI-Victor · 2021-07-06T20:17:38Z

to quote an ex-team lead, i think we beat this one to death.

@ankeesler i see there are no more PRs for this enhancement and it's not marked as 'At Risk' do you still have any more work for this or can you squash so we can merge it?

ankeesler · 2021-07-06T20:21:12Z

i have no more work associated with this enhancement - i have squashed into one commit. thanks for keeping this moving forward.

sftim · 2021-07-08T16:54:55Z

/sig auth
@ankeesler if this is ready for review please retitle it to remove the “WIP:”

sftim

per issue #28013 we could also document that kubeconfig exec has a security risk,
and emphasize that this risk is present whenever you use a config from an untrusted source without checking it

That improvement is not required for this PR to merge.

enj

Minor stuff.

content/en/docs/reference/access-authn-authz/authentication.md

enj · 2021-07-12T20:37:38Z

content/en/docs/reference/access-authn-authz/authentication.md

+`ExecCredential` object from the `KUBERNETES_EXEC_INFO` environment variable in order to
+determine if `stdin` has been provided. A plugin's `stdin` requirements (i.e., whether
+`stdin` is optional, strictly required, or never used in order for the plugin
+to run successfully) must be declared via the `user.exec.interactiveMode` field in the


Should this note that the "must" is only true for the v1 API?

gave this a go here e4653f1

enj · 2021-07-12T20:38:43Z

content/en/docs/reference/access-authn-authz/authentication.md


 To use bearer token credentials, the plugin returns a token in the status of the
 [`ExecCredential`](/docs/reference/config-api/client-authentication.v1beta1/#client-authentication-k8s-io-v1beta1-ExecCredential)
+{{< /table >}}


Er, should this be higher up in the doc right after the table ends?

whoops. fbe3f67

ankeesler · 2021-07-13T14:22:34Z

@sftim i'm considering your comment above about adding something in the docs about #28013. appreciate you calling that out.

@enj do you have an opinion on whether we should add something in this PR for the above doc issue? my gut feel was to keep the PR specifically targeted at GA stuff on the grounds that smaller PRs are usually better.

enj · 2021-07-13T14:31:41Z

@enj do you have an opinion on whether we should add something in this PR for the above doc issue? my gut feel was to keep the PR specifically targeted at GA stuff on the grounds that smaller PRs are usually better.

+1 to keeping this PR targeted at GA stuff with a follow-up PR to add docs around not running kubeconfigs from untrusted sources.

Feel free to squash, this PR looks ready to me.

Signed-off-by: Andrew Keesler <akeesler@vmware.com>

ankeesler · 2021-07-13T14:48:01Z

cool, thanks @enj. PR hath been squashed

enj · 2021-07-13T14:48:07Z

/lgtm

k8s-ci-robot · 2021-07-13T14:48:15Z

LGTM label has been added.

Git tree hash: 515d5b71a372a3f9349c53f5a0f814313a857ca3

PI-Victor · 2021-07-21T13:52:31Z

/approve

k8s-ci-robot · 2021-07-21T13:52:48Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: PI-Victor

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

The pull request process is described here

Needs approval from an approver in each of these files:

~~content/en/OWNERS~~ [PI-Victor]

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 added this to the 1.22 milestone Jun 15, 2021

k8s-ci-robot added the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jun 15, 2021

k8s-ci-robot added the language/en Issues or PRs related to English language label Jun 15, 2021

k8s-ci-robot requested review from lavalamp and liggitt June 15, 2021 20:18

k8s-ci-robot added sig/docs Categorizes an issue or PR as relevant to SIG Docs. cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Jun 15, 2021

ankeesler mentioned this pull request Jun 15, 2021

External client-go credential providers kubernetes/enhancements#541

Closed

ankeesler force-pushed the exec-credential-v1 branch 2 times, most recently from 1bda5d9 to 0cfc62d Compare June 16, 2021 14:16

liggitt reviewed Jun 16, 2021

View reviewed changes

k8s-ci-robot assigned PI-Victor Jun 16, 2021

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Jun 17, 2021

ankeesler force-pushed the exec-credential-v1 branch 2 times, most recently from 297c8aa to 6a3abda Compare June 17, 2021 19:18

ankeesler commented Jun 17, 2021

View reviewed changes

sftim reviewed Jul 6, 2021

View reviewed changes

ankeesler mentioned this pull request Jul 6, 2021

I want my table to render without splitting words #28815

Closed

ankeesler force-pushed the exec-credential-v1 branch from cbbded0 to c83eb20 Compare July 6, 2021 20:20

k8s-ci-robot added the sig/auth Categorizes an issue or PR as relevant to SIG Auth. label Jul 8, 2021

ankeesler changed the title ~~WIP: exec credential provider: v1 documentation~~ exec credential provider: v1 documentation Jul 8, 2021

k8s-ci-robot removed the do-not-merge/work-in-progress Indicates that a PR should not merge because it is a work in progress. label Jul 8, 2021

sftim reviewed Jul 11, 2021

View reviewed changes

enj suggested changes Jul 12, 2021

View reviewed changes

exec credential provider: v1 documentation

a30e63d

Signed-off-by: Andrew Keesler <akeesler@vmware.com>

ankeesler force-pushed the exec-credential-v1 branch from e4653f1 to a30e63d Compare July 13, 2021 14:47

k8s-ci-robot assigned enj Jul 13, 2021

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Jul 13, 2021

ankeesler mentioned this pull request Jul 19, 2021

KEP-541: KEP updates for GA RC kubernetes/enhancements#2827

Merged

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Jul 21, 2021

k8s-ci-robot merged commit 83f6cb6 into kubernetes:dev-1.22 Jul 21, 2021

		apiVersion: "client.authentication.k8s.io/v1"
		interactiveMode: IfAvailable

exec credential provider: v1 documentation #28429

exec credential provider: v1 documentation #28429

Conversation

ankeesler commented Jun 15, 2021

k8sio-netlify-preview-bot commented Jun 15, 2021 • edited by netlify bot Loading

Choose a reason for hiding this comment

ankeesler Jun 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ankeesler Jun 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ankeesler Jun 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ankeesler Jun 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ankeesler Jun 17, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PI-Victor commented Jun 16, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liggitt commented Jun 18, 2021

liggitt commented Jun 18, 2021

ankeesler commented Jul 6, 2021

Choose a reason for hiding this comment

Choose a reason for hiding this comment

PI-Victor commented Jul 6, 2021

ankeesler commented Jul 6, 2021

sftim commented Jul 8, 2021

sftim left a comment

Choose a reason for hiding this comment

enj left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ankeesler Jul 13, 2021 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ankeesler Jul 13, 2021 • edited Loading

Choose a reason for hiding this comment

ankeesler commented Jul 13, 2021

enj commented Jul 13, 2021

ankeesler commented Jul 13, 2021

enj commented Jul 13, 2021

k8s-ci-robot commented Jul 13, 2021

PI-Victor commented Jul 21, 2021

k8s-ci-robot commented Jul 21, 2021

k8sio-netlify-preview-bot commented Jun 15, 2021 •

edited by netlify bot

Loading

ankeesler Jun 17, 2021 •

edited

Loading

ankeesler Jun 17, 2021 •

edited

Loading

ankeesler Jun 17, 2021 •

edited

Loading

ankeesler Jun 17, 2021 •

edited

Loading

ankeesler Jun 17, 2021 •

edited

Loading

ankeesler Jul 13, 2021 •

edited

Loading

ankeesler Jul 13, 2021 •

edited

Loading