KEP-3962: Mutating admission policy documentation

[Jefftree]

Description

This documents KEP-3962 for the alpha release of the enhancement in 1.32

Supersedes #48467

Comments still outstanding from that PR are addressed.

[netlify]

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

Name	Link
🔨 Latest commit	d58a4e5
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-vnext-staging/deploys/674607b0ca6f640008a5f084

[netlify]

✅ Pull request preview available for checking

Built without sensitive environment variables

Name	Link
🔨 Latest commit	d58a4e5
🔍 Latest deploy log	https://app.netlify.com/sites/kubernetes-io-main-staging/deploys/674607b088ce7f0008587d95
😎 Deploy Preview	https://deploy-preview-48646--kubernetes-io-main-staging.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[sftim]

Comments still outstanding from that PR that need to be addressed here.

/retitle [WIP] KEP-3962: Mutating admission policy documentation

Sounds like this is not yet ready for review, so I'll mark it as a draft. @Jefftree if you can get it ready, that's helpful.

[Jefftree]

/assign @jpbetz @cici37

[jpbetz]

/approve
/lgtm
For technical content for alpha

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: fa93e23869f2228fea584e83482f736326d923c0

[Jefftree]

Comments addressed @tengqm

[sftim]

Thanks. It's good to have this doc ready for review on schedule.

We try to avoid putting tutorials and conceptual explanations into the docs reference section, so I'd love to see changes to this PR.

Please consider rewording https://kubernetes.io/docs/concepts/policy/#apply-policies-using-validatingadmissionpolicy to mention mutating admission policies too. This change is important.

For beta (and ideally even for alpha), we should (as in could, not must) turn this guide-style explanation into:

• a tutorial that helps people try out VAP and MAP in their toy cluster
  • yes, I mean one combined tutorial that teaches both kinds of admission policies
  • yes, I know that ValidatingAdmissionPolicy is GA and MutatingAdmissionPolicy is alpha; that's OK
• a shorter reference explanation of MutatingAdmissionPolicy, to live within the reference pages

Please consider doing or supporting that work eventually, @Jefftree. "Supporting" need not mean you do the work; it could be more around putting out a call for help.
As an opinion, but also the opinion of a former tech lead, that refactoring to a tutorial would really help people learn about K8s admission.

I've added some inline feedback too. See what you think.

---

Here's the part of the page I'd keep for the reference section (perhaps slightly expanded):

CEL expressions have access to the types needed to create JSON patches and objects:

• JSONPatch - CEL type of JSON Patch operations. JSONPatch has the fields op, from, path and value.
  See JSON patch for more details. The value field may be set to any of: string,
  integer, array, map or object. If set, the path and from fields must be set to a
  JSON pointer string, where the jsonpatch.escapeKey() CEL
  function may be used to escape path keys containing / and ~.
• Object - CEL type of the resource object.
• Object.<fieldName> - CEL type of object field (such as Object.spec)
• Object.<fieldName1>.<fieldName2>...<fieldNameN> - CEL type of nested field (such as Object.spec.containers)

CEL expressions have access to the contents of the API request, organized into CEL variables as well as some other useful variables:

• object - The object from the incoming request. The value is null for DELETE requests.
• oldObject - The existing object. The value is null for CREATE requests.
• request - Attributes of the API request.
• params - Parameter resource referred to by the policy binding being evaluated. Only populated if the policy has a ParamKind.
• namespaceObject - The namespace object that the incoming object belongs to. The value is null for cluster-scoped resources.
• variables - Map of composited variables, from its name to its lazily evaluated value.
  For example, a variable named foo can be accessed as variables.foo.
• authorizer - A CEL Authorizer. May be used to perform authorization checks for the principal (user or service account) of the request.
  See https://pkg.go.dev/k8s.io/apiserver/pkg/cel/library#Authz
• authorizer.requestResource - A CEL ResourceCheck constructed from the authorizer and configured with the
  request resource.

[sftim]

Overall: I'm wary to approve this as-is, but @Jefftree once you have read the feedback, please feel free to make the minimum set of changes you feel are right for alpha stage. Then request a new review (you could consider the auto-assigned reviewers, @natalisucks and @reylejano).

[AnshumanTripathi]

Hi @jpbetz 👋 !
I'm reaching out from the Docs team. Just checking in as we approach Docs Freeze on Tuesday November 26th 18:00 PDT. This documentation appears to still be under review. To meet the Docs Freeze, this PR must have a technical review as well as lgtm and approve labels applied, without any unaddressed comments or concerns from SIG Docs. Thank you!

[Jefftree]

@sftim comments addressed. Tried to put together a minimal set of references with a single example for applyconfiguration and json patch without too many examples making this into a tutorial. As a follow up (after docs freeze), will create a new page as a tutorial for VAP and MAP.

[tengqm]

Is it able to check the labels of an object?
I don't mean I want to change it.

[Jefftree]

yes, thanks for catching!

[sftim]

OK, also: annotations?

[sftim]

/label tide/merge-method-squash

[Jefftree]

@sftim comments addressed, thanks!

[sftim]

/lgtm

with a quibble

[k8s-ci-robot]

LGTM label has been added.

Git tree hash: ff4ae603d81471439400e990fb183b4543a463ed

[chanieljdan]

Docs and Tech LGTM provided above

/approve

[k8s-ci-robot]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: chanieljdan, jpbetz

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 [chanieljdan]

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