KEP-3962: Mutating admission policy documentation #48467
Conversation
k8s-ci-robot
added
cncf-cla: yes
|
[APPROVALNOTIFIER] This PR is NOT APPROVED This pull-request has been approved by: The full list of commands accepted by this bot can be found here.
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
k8s-ci-robot
added
the
sig/docs
✅ Pull request preview available for checkingBuilt without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify site configuration. |
There was a problem hiding this comment.
@jpbetz, we should consider setting the dev-1.32 branch as the target branch rather than the main branch for this pull request. Since the change is related to the feature targeting alpha in 1.32.
|
Link to KEP: kubernetes/enhancements#3962 |
|
Hi. Please rebase this against dev-1.32, squashing to a small number of commits, and set the base branch for this PR to dev-1.32. The main branch is our live documentation. |
|
/milestone 1.32 |
|
|
||
| {{< feature-state state="alpha" for_k8s_version="v1.32" >}} | ||
|
|
||
| This page provides an overview of Mutating Admission Policy. |
There was a problem hiding this comment.
| This page provides an overview of Mutating Admission Policy. | |
| This page provides an overview of _MutatingAdmissionPolicies_ in Kubernetes. |
Extra credit: update the ValidatingAdmissionPolicies page to align that one with this (and, more importantly, align both with our style guide).
|
|
||
| <!-- overview --> | ||
|
|
||
| {{< feature-state state="alpha" for_k8s_version="v1.32" >}} |
There was a problem hiding this comment.
Please refer to a feature gate by name. Also see https://kubernetes.io/docs/contribute/new-content/new-features/#ready-for-review-feature-gates for how to add the associated feature gate description and metadata.
{{< feature-state feature_gate_name="ExampleFeatureGate" >}}something like this.
|
|
||
| <!-- body --> | ||
|
|
||
| ## What is Mutating Admission Policy? |
There was a problem hiding this comment.
| ## What is Mutating Admission Policy? | |
| ## What are MutatingAdmissionPolicies? |
|
|
||
| ## What is Mutating Admission Policy? | ||
|
|
||
| Mutating admission policies offer a declarative, in-process alternative to mutating admission webhooks. |
There was a problem hiding this comment.
Rather than compare them to another feature, at beta and beyond these docs should explain what MutatingAdmissionPolicies are and do. The docs we write should make sense even if we were to deprecate or even remove admission webhooks (we won't, but please use that thought experiment as a guide).
|
|
||
| Mutating admission policies use the Common Expression Language (CEL) to declare mutations to resources. | ||
| Mutations can be defined either with an *apply configuration* that is merged using the | ||
| [server side apply merge strategy](https://kubernetes.io/docs/reference/using-api/server-side-apply/#merge-strategy) |
There was a problem hiding this comment.
Per the style guide, use site relative hyperlinks.
| Mutating admission policies are highly configurable, enabling policy authors to define policies | ||
| that can be parameterized and scoped to resources as needed by cluster administrators. | ||
|
|
||
| ## What Resources Make a Policy |
There was a problem hiding this comment.
Per the style guide, write headings in sentence case.
| - A `MutatingAdmissionPolicyBinding` links the above resources together and provides scoping. | ||
| If you only want to set an `owner` label for `Pods`, the binding is where you would | ||
| specify this mutation. |
There was a problem hiding this comment.
Per the style guide, drop the backticks on MutatingAdmissionPolicyBinding and Pods.
| specify this mutation. | ||
|
|
||
| - A parameter resource provides information to a `MutatingAdmissionPolicy` to make it a concrete | ||
| statement (think "set the `owner` label to something that ends in `.company.com`"). |
There was a problem hiding this comment.
Use an example domain, such as company.example.
|
|
||
| ## Getting Started with Mutating Admission Policy | ||
|
|
||
| TODO |
There was a problem hiding this comment.
Write this. You can also shift this part to a post-release blog article.
| reviewers: | ||
| - deads2k | ||
| - sttts | ||
| - cici37 | ||
| title: Mutating Admission Policy | ||
| content_type: concept |
There was a problem hiding this comment.
Ideally (will have to happen post release) we also add the metadata to place API reference links here. Have a look at the concept page for Deployment to get an idea of what I mean (both source code and the rendered page).
Nice to have for alpha, but not required until beta.
k8s-ci-robot
added
size/M
|
@Jefftree: Closed this PR. In response to this:
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. |
Description
This documents KEP-3962 for the alpha release of the enhancement in 1.32.