Improve the ValidationAdmissionPolicy docs

[samos123]

This is a Feature Request

What would you like to be added

• End-to-end example: Add example of adding a label environment=test to one of the namespace
• Add explanation to the examples
• Add a note about how to enable the admissionregistration.k8s.io/v1alpha1 API or link to another doc that talks about runtimeConfig
• remove all the example.com parts since it was mostly confusing
• Link to API docs for the various objects mentioned in the doc
• Move all examples to separate files and ensure they are tested, this would prevent issues like ValidationAdmissionPolicy binding example is incorrect #38495 from occurring again, see comment from @tengqm below

comment from @tengqm:
Issues like this would be easy to detect if we make the manifest an example YAML.
For example:

1. move the YAML snippet into a separate file content/en/examples/policy/validating-admission-ex.yaml and,
2. reference it as {{< codenew file="policy/validating-admission-ex.yaml" >}} in the markdown page,
3. (optionally) amend content/en/examples/examples_test.go so that it can be validated against current and future k8s releases.

Why is this needed
Current docs was hard to follow for a new user like myself

[jimmyraywv]

So, more documentation about what the admission controller receives from the API would also be helpful. Is it the customary AdmissionReview object?

[sftim]

more documentation about what the admission controller receives from the API would also be helpful. Is it the customary AdmissionReview object?

We typically don't document internal details like that. Maybe that's something we could document within eg https://k8s.dev/docs/

Kubernetes is free to change its internal implementation and end users shouldn't need to know how that's done.

[sftim]

/sig api-machinery

Improvements are welcome

This is an alpha feature; we should aim to make the docs better before this graduates to beta.
/priority backlog

[sftim]

/language en

If we wanted to, we could add a new tutorial that shows how to do admission-time validation. First with a webhook and then with CEL.

[jimmyraywv]

@sftim The issue is that we need to know what data is sent in the api server request to the ValidatingAdmissionPolicy, so that we can understand what capabilities this solution has.

If you look at the docs for Webhook Mode, you can see that the API server request is documented there: https://kubernetes.io/docs/reference/access-authn-authz/webhook/

The AdmissionReview object is also documented in the Dynamic Admission Control docs: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#webhook-request-and-response

[tengqm]

PR #38522 is adding a reference to the admission config API where AdmissionReview, AdmissionRequest are documented. Is that what you want, @jimmyraywv ?

[jimmyraywv]

@tengqm I think that will work. However for UserInfo v1 authentication.k8s.io, for the groups []string, are those k8s RBAC groups or are those AuthN IDP groups, like group claims from OIDC?

What I am driving towards is that will this feature allow us to write policies with CEL that blur the lines between traditional validating admission webhooks, and the AuthZ Webhook Mode?

[tengqm]

@tengqm I think that will work. However for UserInfo v1 authentication.k8s.io, for the groups []string, are those k8s RBAC groups or are those AuthN IDP groups, like group claims from OIDC?

AFAICT, k8s doesn't have an abstraction for users or an abstraction for groups. All those information are extracted from the authentication input.

What I am driving towards is that will this feature allow us to write policies with CEL that blur the lines between traditional validating admission webhooks, and the AuthZ Webhook Mode?

I believe CEL was not designed for authn or authz's purpose. It is a mechanism for you to leverage, to impose constraints that are difficult or impossible to express using OpenAPI schemas. You can mix these admission plugins in any way to meet your requirements.

[sftim]

AFAICT, k8s doesn't have an abstraction for users or an abstraction for groups. All those information are extracted from the authentication input.

You can extend Kubernetes to add those things - this isn't just theoretical, there's a User API in OpenShift 4.8 for example.

Core Kubernetes doesn't have User or Group APIs. If your container platform does have extension APIs for users and groups, this alpha feature lets you use CEL to validate changes at admission time.

You asked about the (also alpha) SelfSubjectReview API.

https://kubernetes.io/docs/reference/kubernetes-api/authorization-resources/self-subject-review-v1alpha1/#SelfSubjectReviewStatus is filled in after you create a SelfSubjectReview. Here's what you might submit, as YAML, if you wanted to find out who the Kubernetes cluster thinks you are:

apiVersion: authentication.k8s.io/v1alpha1
kind: SelfSubjectReview

At HTTP level, the body of response might look like:

{
  "apiVersion": "authentication.k8s.io/v1alpha1",
  "kind": "SelfSubjectReview",
  "status": {
    "userInfo": {
      "username": "sftim",
      "uid": "71d99f8d-5b1b-4625-9149-037dc46fdc83",
      "groups": [
        "en-reviewers",
        "en-approvers",
        "system:authenticated"
      ],
      "extra": {
        "emoji": [
          "true"
        ]
      }
    }
  }
}

but a ValidatingAdmissionPolicy constrains what you send there, not what you get back.

---

In a couple of days, we'll have a blog article about this. I'm afraid it's not yet live. Please check back on the 20th of December.

We don't have anything to document here that I can see. Is there a page that needs to be more clear?