YAML AdmissionReview example in Dynamic Admission Control page is misleading and does not match wire format

[eram]

example requests on this page should be in json format. not in yaml. ref: https://kubernetes.io/docs/reference/access-authn-authz/extensible-admission-controllers/#request

[AmarNathChary]

/language en /sig docs

[dipesh-rawat]

/retitle Specify JSON format instead of YAML for example requests on Dynamic Admission Control page

[sftim]

If you mean the example following This example shows the data contained in an AdmissionReview object for a request to update the scale subresource of an apps/v1 Deployment:, then it's IMO much more readable expressed as YAML.

If we switch it to JSON, we'll need to delete all the comments.

However, we should make it very clear that the example is not the wire format.

[rukundob451]

Hey @sftim, how would you want to make it very clear that the example is not the wire format?

[sftim]

Try this:

## This shows an example AdmissionReview request.
## The example is encoded as YAML so that there can be explanatory comments.
## However, this is not the format you should expect for your own webhook.
## The HTTP body of an AdmissionReview request to an admission webhook is typically encoded as JSON.

apiVersion: admission.k8s.io/v1
kind: AdmissionReview
request:
  # Random uid uniquely identifying this admission call
  uid: 705ab4f5-6393-11e8-b7cc-42010a800002

[sftim]

There are two ways to fix this:

• switch the example to JSON (and find another way to explain what field does what)
• very clearly explain that the commented YAML document is not the wire format

Either is fine!

[eram]

The whole point in giving an example is that it looks like the real thing. Otherwise, just write some text about what you expect. Adding 5 lines of explanation into the example code??? Better write it in Json5 (aka with comments inline) or set placeholders like "<< comment >>" in the example body.

[sftim]

@eram, the best way to boost that view - from https://github.com/kubernetes/website/issues/41542#issuecomment-1675730251 - is to open a pull request. However, if someone opens a pull request that takes the other approach, we'll consider that too.

[sftim]

This is a valid fix (per the issue ~title~ description); please also see https://github.com/kubernetes/website/issues/41542#issuecomment-1675119823

/triage accepted

[sftim]

/retitle YAML AdmissionReview example in Dynamic Admission Control page is misleading and does not match wire format

[k8s-triage-robot]

This issue has not been updated in over 1 year, and should be re-triaged.

You can:

• Confirm that this issue is still relevant with /triage accepted (org members only)
• Close this issue with /close

For more details on the triage process, see https://www.kubernetes.dev/docs/guide/issue-triage/

/remove-triage accepted