ServiceAccountIssuerDiscovery: Add user facing documentation #19328

mtaufen · 2020-02-26T17:21:56Z

Extends the documentation on configuring service accounts to include
details on the ServiceAccountIssuerDiscovery feature.

/cc @VineethReddy02 @liggitt @mikedanese

k8sio-netlify-preview-bot · 2020-02-26T17:22:02Z

Deploy preview for kubernetes-io-vnext-staging processing.

Building with commit 39a7d4f

https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/5e6660592c539200084f9b62

sftim · 2020-02-27T13:06:50Z

This looks like it's pending approval for v1.18 release? If so, @mtaufen, you might want to add a /hold

sftim

@mtaufen thanks for this. Here's some feedback.

Somewhat related to this PR: I recommend creating a new task webpage that explains how to set up Service Account Issuer Discovery and to set --service-account-jwks-uri appropriately.

For the alpha, it's enough to file the issue (against k/website). Please consider adding that task page as a requirement for graduation to beta.

In the issue, mention that this section should link to the new task page.

sftim · 2020-02-27T13:07:43Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+
+{{< note >}}
+The Service Account Issuer Discovery feature is __alpha__ in 1.18 and enabled by
+setting the `ServiceAccountIssuerDiscovery` feature gate to `true` and then


Suggested change

setting the `ServiceAccountIssuerDiscovery` feature gate to `true` and then

enabling the `ServiceAccountIssuerDiscovery` [feature gate](/docs/reference/command-line-tools-reference/feature-and then

sftim · 2020-02-27T13:08:29Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+{{< feature-state for_k8s_version="v1.18" state="alpha" >}}
+
+{{< note >}}
+The Service Account Issuer Discovery feature is __alpha__ in 1.18 and enabled by


This is repeating the feature-state line. I would tell readers how to enable the feature gate (what component?) and omit the repetition.

sftim · 2020-02-27T13:09:16Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+Note that the issuer URL must comply with the
+[OIDC Discovery Spec](https://openid.net/specs/openid-connect-discovery-1_0.html). In
+practice, this means it must use the `https` scheme, and should serve an OpenID
+provider configuration at `{service-account-issuer}/.well-known/openid-configuration`.


I'd start the {{< note >}} here (move the advice about enabling the feature gate to be before the note block).

sftim · 2020-02-27T13:10:44Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+service account tokens issued by a cluster (the _identity provider_) with
+external systems (_relying parties_).
+
+When enabled, the Kubernetes API server will serve an OpenID Provider


Suggested change

When enabled, the Kubernetes API server will serve an OpenID Provider

When enabled, the Kubernetes API server provides a public OpenID Provider

Done. Also added clarification on RBAC, thanks for the reminder with your comment about "public."

sftim · 2020-02-27T13:12:30Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+{{< note >}}
+The responses served at `/.well-known/openid-configuration` and
+`/openid/v1/jwks` are designed to be OIDC compatible, but not strictly OIDC
+compliant. Today they contain only the parameters necessary to perform


Suggested change

compliant. Today they contain only the parameters necessary to perform

compliant. Those documents contain only the parameters necessary to perform

(“today” looks a bit like a statement about the future; see https://kubernetes.io/docs/contribute/style/style-guide/#avoid-statements-about-the-future)

I would definitely remove:

Additional, parameters may be added if it is determined that doing so improves compatibility with common client implementations used by relying parties.

That kind of detail belongs in the KEP.

Yup, already in the KEP. Sounds good. Done.

sftim · 2020-02-27T13:13:06Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+client implementations used by relying parties.
+{{< /note >}}
+
+The JWKS contains public keys that can be used to validate the Kubernetes


Suggested change

The JWKS contains public keys that can be used to validate the Kubernetes

The JWKS response contains public keys that can a relying party can use to validate the Kubernetes

sftim · 2020-02-27T13:13:44Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+For additional technical details, see the
+[Service Account Signing Key Retrieval KEP](https://github.com/kubernetes/enhancements/blob/master/keps/sig-auth/20190730-oidc-discovery.md)
+and
+[OIDC Discovery Spec](https://openid.net/specs/openid-connect-discovery-1_0.html).


These could (I think should) move into the whatsnext capture.

mikedanese · 2020-02-27T15:24:49Z

For tech review.

/lgtm

mtaufen · 2020-03-04T18:59:21Z

This looks like it's pending approval for v1.18 release? If so, @mtaufen, you might want to add a /hold

@sftim The code is merged for 1.18 already. Unless you meant something else?

sftim

/lgtm
One nit which would be nice to fix (I'll re-review)

sftim · 2020-03-04T22:17:44Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+JSON Web Key Set (JWKS) at `/openid/v1/jwks`. The OpenID Provider Configuration
+is sometimes referred to as the _discovery document_.
+
+When enabled, the cluster is also configured with a default RBAC `ClusterRole`


nit:

Suggested change

When enabled, the cluster is also configured with a default RBAC `ClusterRole`

When enabled, the cluster is also configured with a default RBAC ClusterRole

In the docs, API objects don't go inside backticks.

sftim

/lgtm

mtaufen · 2020-03-05T17:28:29Z

Filed the issue to remind us to create a new task webpage: #19496

@sftim do you need to /approve also?

sftim · 2020-03-05T20:17:34Z

@VineethReddy02 is docs lead for the v1.18 release

mtaufen · 2020-03-05T20:30:03Z

/assign @VineethReddy02

VineethReddy02 · 2020-03-07T13:05:21Z

👋 Please rebase this PR on dev-1.18 in order to avoid merge conflicts.

Feel free to /hold cancel after you've rebased.

/hold

sftim

Here's some more feedback on the text @mtaufen

sftim · 2020-03-08T22:24:52Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+and then enabling the Service Account Token Projection feature as described above.
+
+{{< note >}}
+Note that the issuer URL must comply with the


Suggested change

Note that the issuer URL must comply with the

The issuer URL must comply with the

The shortcode {{< note >}} already marks this as a note.

sftim · 2020-03-08T22:25:41Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

-See also the
-[Cluster Admin Guide to Service Accounts](/docs/reference/access-authn-authz/service-accounts-admin/).
+See also:
+- [Cluster Admin Guide to Service Accounts](/docs/reference/access-authn-authz/service-accounts-admin/)


Add a blank line before this list to keep the Markdown parser happy.

sftim · 2020-03-08T22:26:57Z

content/en/docs/tasks/configure-pod-container/configure-service-account.md

+
+The Service Account Issuer Discovery feature is enabled by enabling the
+`ServiceAccountIssuerDiscovery` [feature gate](/docs/reference/command-line-tools-reference/feature)
+and then enabling the Service Account Token Projection feature as described above.


nit:

Suggested change

and then enabling the Service Account Token Projection feature as described above.

and then enabling the Service Account Token Projection feature as described [above](#service-account-token-volume-projection).

VineethReddy02 · 2020-03-09T09:03:12Z

Hi, @mtaufen As today is the deadline for docs placeholder PR to be ready for review state? Can we have all the requested changes to the PR sometime soon?
Thanks!

Extends the documentation on configuring service accounts to include details on the ServiceAccountIssuerDiscovery feature.

mtaufen · 2020-03-09T15:28:00Z

/hold cancel

@VineethReddy02 all requested changes have been made.

sftim

Following on from #19328 (comment)
/lgtm

VineethReddy02 · 2020-03-12T20:16:43Z

/lgtm
/approve

k8s-ci-robot · 2020-03-12T20:17:07Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: VineethReddy02

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~~ [VineethReddy02]

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 requested review from liggitt, mikedanese and VineethReddy02 February 26, 2020 17:21

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Feb 26, 2020

k8s-ci-robot added size/M Denotes a PR that changes 30-99 lines, ignoring generated files. language/en Issues or PRs related to English language sig/docs Categorizes an issue or PR as relevant to SIG Docs. labels Feb 26, 2020

mtaufen mentioned this pull request Feb 26, 2020

Provide OIDC discovery for service account token issuer kubernetes/enhancements#1393

Closed

12 tasks

sftim requested changes Feb 27, 2020

View reviewed changes

k8s-ci-robot assigned mikedanese Feb 27, 2020

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Feb 27, 2020

mtaufen force-pushed the oidc-docs-1.18 branch from 828d08c to fb4fa66 Compare March 4, 2020 19:18

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 4, 2020

sftim reviewed Mar 4, 2020

View reviewed changes

k8s-ci-robot assigned sftim Mar 4, 2020

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 4, 2020

mtaufen force-pushed the oidc-docs-1.18 branch from fb4fa66 to f684fac Compare March 4, 2020 22:37

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 4, 2020

sftim reviewed Mar 4, 2020

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 4, 2020

mtaufen mentioned this pull request Mar 5, 2020

Create a Tasks doc for Service Account Issuer Discovery #19496

Closed

k8s-ci-robot assigned VineethReddy02 Mar 5, 2020

k8s-ci-robot added the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Mar 7, 2020

sftim requested changes Mar 8, 2020

View reviewed changes

ServiceAccountIssuerDiscovery: Add user facing documentation

39a7d4f

Extends the documentation on configuring service accounts to include details on the ServiceAccountIssuerDiscovery feature.

mtaufen force-pushed the oidc-docs-1.18 branch from f684fac to 39a7d4f Compare March 9, 2020 15:27

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 9, 2020

k8s-ci-robot removed the do-not-merge/hold Indicates that a PR should not merge because someone has issued a /hold command. label Mar 9, 2020

sftim reviewed Mar 10, 2020

View reviewed changes

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Mar 10, 2020

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Mar 12, 2020

k8s-ci-robot merged commit e746d34 into kubernetes:dev-1.18 Mar 12, 2020

	setting the `ServiceAccountIssuerDiscovery` feature gate to `true` and then
	enabling the `ServiceAccountIssuerDiscovery` [feature gate](/docs/reference/command-line-tools-reference/feature-and then

	When enabled, the Kubernetes API server will serve an OpenID Provider
	When enabled, the Kubernetes API server provides a public OpenID Provider

	compliant. Today they contain only the parameters necessary to perform
	compliant. Those documents contain only the parameters necessary to perform

	The JWKS contains public keys that can be used to validate the Kubernetes
	The JWKS response contains public keys that can a relying party can use to validate the Kubernetes

	When enabled, the cluster is also configured with a default RBAC `ClusterRole`
	When enabled, the cluster is also configured with a default RBAC ClusterRole

	Note that the issuer URL must comply with the
	The issuer URL must comply with the

	and then enabling the Service Account Token Projection feature as described above.
	and then enabling the Service Account Token Projection feature as described [above](#service-account-token-volume-projection).

ServiceAccountIssuerDiscovery: Add user facing documentation #19328

ServiceAccountIssuerDiscovery: Add user facing documentation #19328

Conversation

mtaufen commented Feb 26, 2020

k8sio-netlify-preview-bot commented Feb 26, 2020 • edited Loading

sftim commented Feb 27, 2020

sftim left a comment

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

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

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mikedanese commented Feb 27, 2020

mtaufen commented Mar 4, 2020

sftim left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sftim left a comment

Choose a reason for hiding this comment

mtaufen commented Mar 5, 2020

sftim commented Mar 5, 2020

mtaufen commented Mar 5, 2020

VineethReddy02 commented Mar 7, 2020

sftim left a comment

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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

VineethReddy02 commented Mar 9, 2020

mtaufen commented Mar 9, 2020

sftim left a comment

Choose a reason for hiding this comment

VineethReddy02 commented Mar 12, 2020

k8s-ci-robot commented Mar 12, 2020

k8sio-netlify-preview-bot commented Feb 26, 2020 •

edited

Loading