OpenAPI definition for AdmissionReview

[reegnz]

What would you like to be added:

I would like an OpenAPI schema definition for admission controllers for the purposes of generating the API types (and potentially servers or server stubs) in multiple languages.

Why is this needed:

Now that AdmissionReview is promoted to v1, it would be welcome if we could get an OpenAPI schema on how such an API would look like.

Currently we have a nice OpenAPI schema that is used to programmatically generate API server clients in a multitude of languages. This is great for writing components that interact directly with the API Server.

We do however have the AdmissionReview API where one does not communicate with the component indirectly by watching API resources, but instead the component is called synchronously on API resource changes.

For such use-cases it would be nice to have a separate OpenAPI schema as well, where the types can also be generated for a multitude of languages, and maybe even generate servers from them, where you only need to pass in a request handler for example.

Right now it would be sufficient to simply generate the OpenAPI spec for the AdmissionReview types though.

[reegnz]

/sig api-machinery

[yue9944882]

/assign

great to hear you're implementing webhooks in other language. @liggitt is that intended? the last api group disable openapi generation :-/

[liggitt]

@liggitt is that intended?

sure, there's no requirement for webhooks to be written in go

the last api group disable openapi generation

Can you clarify what you mean by that?

[yue9944882]

Can you clarify what you mean by that?

sry to be ambiguous, by scanning all the api groups in k/k, i found only admission.k8s.io/{v1,v1beta1} marked w/ package-level // +k8s:openapi-gen=false

kubernetes/staging/src/k8s.io/api/admission/v1/doc.go

Line 19 in c634276

// +k8s:openapi-gen=false

@liggitt is that intended?

reading that as a yes to enable the openapi generation for the group.

[fedebongio]

/cc @apelisse @jennybuckley

[jennybuckley]

Generally the openapi should contain every resource served by the kube-apiserver, but AdmissionReview is different in that, it's a request made by the apiserver to a webhook servers. It probably doesn't belong in the main openapi spec served by the apiserver, but generating openapi for it and putting it somewhere could be useful.

[yue9944882]

UPDATE: i tried toggle on the openapi generation for these groups but it doesnt work. i see the admission{request,response} types are already present in the pkg/generated/zz_generated_openapi.go but in the published doc from the apiserver, the types are gone.. or they can probably be filtered on aggregating/merging the openapi specs..

[apelisse]

There seems to be a mechanism in OpenAPI to describe "callbacks": https://swagger.io/docs/specification/callbacks/
I think we should just describe webhooks through that mechanism, along with the types it uses of course.

[yue9944882]

yes! however the callbacks only applies to v3 spec https://swagger.io/blog/news/whats-new-in-openapi-3-0/, we can consider include this in this KEP kubernetes/enhancements#1263 @p0lyn0mial

[aespinosa]

@yue9944882 did you fetch the openapi.json using the /openapi/v2 endpoint in the api-server or did you regenerate https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/swagger.json ?

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[aespinosa]

@yue9944882 did you fetch the openapi.json using the /openapi/v2 endpoint in the api-server or did you regenerate https://github.com/kubernetes/kubernetes/tree/master/api/openapi-spec/swagger.json ?

was looking at the shellscripts again the swagger.json file is actually generated by spinning up an apiserver and then getting the spec from there.

[aespinosa]

/remove-lifecycle stale

[brendandburns]

/lifecycle frozen

[marqc]

Any plans for further work on this issue? Currently best option is to use unofficial clients like fabric8 for java, that has model for AdmissionReview class https://github.com/fabric8io/kubernetes-client/

[bergeron]

In case it's useful for others, here are the swagger 2.0 specs I generated from k8s.io/api/admission. I used these swagger specs to generate models for my controller's webhook callbacks:

• k8s.io.api.admission.v1beta1.swagger.json
• k8s.io.api.admission.v1.swagger.json

I generated them with kubernetes/kube-openapi after changing k8s:openapi-gen=false to k8s:openapi-gen=true in api/admission/{v1,v1beta1}/doc.go.

Source code for the generator: https://gist.github.com/bergeron/70ca86cf31762e16f18b2be3c549a074?permalink_comment_id=3504827#gistcomment-3504827