CRD Conversion API Changes #67795

mbohlool · 2018-08-24T03:56:50Z

This is the API changes section of Custom Resource Conversion feature (kubernetes/community#2420) extracted from main implementation PR #67006 for the purpose of a separate API review.

@deads2k @lavalamp @sttts @kubernetes/sig-api-machinery-api-reviews

NONE

mbohlool · 2018-08-26T14:14:49Z

/retest

mbohlool · 2018-08-26T23:53:58Z

@sttts @deads2k Please take a look

dims · 2018-08-27T00:05:02Z

/sig architecture

we need sign off from them too, right?

sttts · 2018-08-27T08:49:52Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/types.go

+	// - `Webhook`: API Server will call to an external webhook to do the conversion. Additional information is needed for this option.
+	Strategy ConversionStrategyType
+
+	// Additional information for external conversion if strategy is set to external


is set to "Webhook"

sttts · 2018-08-27T08:53:55Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// - `Webhook`: API Server will call to an external webhook to do the conversion. Additional information is needed for this option.
+	Strategy ConversionStrategyType `json:"strategy" protobuf:"bytes,1,name=strategy"`
+
+	// Additional information for external conversion if strategy is set to external


is set to "Webhook"

If strategy is Webhook, must contain instructions for how to call the webhook.

sttts · 2018-08-27T08:55:07Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// ConvertedObject is the converted version of request.Object if the Result is nil.
+	// +optional
+	ConvertedObject runtime.RawExtension `json:"convertedObject" protobuf:"bytes,2,name=convertedObject"`
+	// Result contains extra details into why a conversion request was failed. If it is not nil, it means


it's not a pointer. It can't be nil.

please make it a pointer & optional

runtime.RawExtension can be nil (having nil value). The optional runtime.RawExtension is not a pointer in other APIs (at least the ones I checked like WatchEvent or AdmissionRequest)

lavalamp

Some API suggestions.

lavalamp · 2018-08-27T16:45:41Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+
+const (
+	// NopConverter is a converter that only sets apiversion of the CR and leave everything else unchanged.
+	NopConverter     ConversionStrategyType = "None"


RenameConverter? "Nop" is maybe a little obscure, and anyway, no abbreviations in the API with few exceptions.

NoChangeConverter? RepackageConverter? NullConverter?

ah I see the name isn't going to be in the docs, so it matters less. In that case, let's make it match "None" even though NoneConverter sounds a bit weird?

lavalamp · 2018-08-27T16:47:47Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+
+// CustomResourceConversion describes how to convert different versions of a CR.
+type CustomResourceConversion struct {
+	// Strategy specifies the conversion strategy. Allowed values are:


strategy -- match json field name.

lavalamp · 2018-08-27T16:48:37Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// - `Webhook`: API Server will call to an external webhook to do the conversion. Additional information is needed for this option.
+	Strategy ConversionStrategyType `json:"strategy" protobuf:"bytes,1,name=strategy"`
+
+	// Additional information for external conversion if strategy is set to external


If strategy is Webhook, must contain instructions for how to call the webhook.

lavalamp · 2018-08-27T16:49:20Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+}
+
+// CustomResourceConversionWebhook describes how to call a conversion webhook.
+type CustomResourceConversionWebhook struct {


What is the purpose of this layer of indirection?

lavalamp · 2018-08-27T16:51:01Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	Response *ConversionResponse `json:"response,omitempty" protobuf:"bytes,2,opt,name=response"`
+}
+
+// ConversionRequest describes a conversion request parameters.


lavalamp · 2018-08-27T16:52:36Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// +optional
+	UID types.UID `json:"uid,omitempty" protobuf:"bytes,1,opt,name=uid"`
+	// The version to convert given object to. E.g. "stable.example.com/v1"
+	APIVersion string `json:"apiVersion" protobuf:"bytes,2,name=apiVersion"`


Please separate it out into separate group and kind fields--friends don't make friends parse strings ;)

Please name it so it's clear it's the desired version, not the version of the thing that is being sent.

There is no need to parse the string (as an example, look at my example converter webhook in the main PR test/images folder). I find it more clear to use the whole APIVersion in switch cases of the conversion.

Also the field in the CR is APIVersion in the same form (e.g. stable.example.com/v1). If we separate it out then our friends need to merge strings which is not horrible but why? :)

Probably looking at these two code samples make it easier to argue that APIVersion make more sense:

https://github.com/mbohlool/kubernetes/blob/b31503af5365263544ad36e73abbd268085d65c5/test/images/crd-conversion-webhook/converter/example_converter.go#L40

https://github.com/mbohlool/kubernetes/blob/b31503af5365263544ad36e73abbd268085d65c5/test/images/crd-conversion-webhook/converter/framework.go#L102

OK, no need to split it if it is always used together (I still think in an absolute sense it's better for it to be passed around as a pair, but fixing only one spot is maybe worse than leaving it like this).

However I still think it should be named more clearly, like "DesiredAPIVersion", "DestinationAPIVersion", or something like that. ("Target" is not good as it's ambiguous.)

lavalamp · 2018-08-27T16:54:24Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// Object is the CRD object to be converted.
+	Object runtime.RawExtension `json:"object" protobuf:"bytes,3,name=object"`
+	// IsList indicates that this is a List operation and Object contains a list of items.
+	IsList bool `json:"isList" protobuf:"varint,4,name=isList"`


I haven't looked back at the KEP, so maybe you answered this there, but why not just make Object into Objects []runtime.RawExtension? Then the webhook always gets a list, and apiserver can pack as many or few objects into the list as it wants.

I have a more detailed answer for this in the main PR, but briefly, this will allow the webhook to change list metas.

why do we want the conversion webhook to inspect/change anything under listmeta? I can't think of a reason conversion of individual objects should care about resourceVersion or continue tokens for the containing list

Agreed. Will make this a array.

lavalamp · 2018-08-27T16:54:50Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// ConvertedObject is the converted version of request.Object if the Result is nil.
+	// +optional
+	ConvertedObject runtime.RawExtension `json:"convertedObject" protobuf:"bytes,2,name=convertedObject"`
+	// Result contains extra details into why a conversion request was failed. If it is not nil, it means


please make it a pointer & optional

mbohlool · 2018-08-29T04:18:17Z

@sttts @lavalamp PTAL

mbohlool · 2018-08-29T06:20:34Z

/retest

mbohlool · 2018-08-29T10:32:50Z

/retest

mbohlool · 2018-08-30T04:38:29Z

/retest

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

lavalamp · 2018-08-30T21:10:46Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	UID types.UID `json:"uid,omitempty" protobuf:"bytes,1,opt,name=uid"`
+	// ConvertedObjects is the list of converted version of request.Objects if the Result is successful otherwise empty.
+	ConvertedObjects []runtime.RawExtension `json:"convertedObjects" protobuf:"bytes,2,rep,name=convertedObjects"`
+	// Result contains the result of conversion with extra details if the conversion failed. Result.Status determines if


Is this field optional? What should it be set to for successful conversions? Unsuccessful ones? What will happen with the reason / message fields?

Added comment to explain that.

lavalamp · 2018-08-30T21:12:53Z

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

+	// otherwise identical (parallel requests, requests when earlier requests did not modify etc)
+	// The UID is meant to track the round trip (request/response) between the KAS and the WebHook, not the user request.
+	// It is suitable for correlating log entries between the webhook and apiserver, for either auditing or debugging.
+	// +optional


Is this actually optional?

lavalamp · 2018-08-30T21:16:47Z

This LGTM with the few minor changes I mentioned.

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go

staging/src/k8s.io/apiserver/pkg/util/webhook/validation.go

pkg/apis/admissionregistration/validation/validation.go

…ration

liggitt · 2018-10-31T20:18:35Z

/approve
/lgtm

looks like verify script is failing on generated file

liggitt · 2018-10-31T20:22:38Z

cc @sttts @lavalamp for k8s.io/apiextensions-apiserver approval

liggitt · 2018-10-31T20:30:58Z

/lgtm

lavalamp · 2018-10-31T20:34:46Z

/approve

We should get the api types here owned by the api reviewers/approvers.

k8s-ci-robot · 2018-10-31T20:34:55Z

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: lavalamp, liggitt, mbohlool

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:

~~api/OWNERS~~ [lavalamp,liggitt]
~~docs/api-reference/OWNERS~~ [lavalamp,liggitt]
~~pkg/apis/OWNERS~~ [lavalamp,liggitt]
~~pkg/features/OWNERS~~ [lavalamp,liggitt]
~~staging/src/k8s.io/api/OWNERS~~ [lavalamp,liggitt]
~~staging/src/k8s.io/apiextensions-apiserver/OWNERS~~ [lavalamp]
~~staging/src/k8s.io/apiserver/OWNERS~~ [lavalamp,liggitt]

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

liggitt · 2018-10-31T20:35:52Z

We should get the api types here owned by the api reviewers/approvers.

#70453

k8s-ci-robot · 2018-10-31T21:47:31Z

New changes are detected. LGTM label has been removed.

mbohlool · 2018-11-01T01:58:30Z

/test pull-kubernetes-e2e-gce-100-performance

liggitt · 2018-11-01T04:45:18Z

set an empty release note, make sure we include release notes in the implementation PR

k8s-ci-robot requested review from justinsb and sttts August 24, 2018 03:56

k8s-ci-robot added the area/custom-resources label Aug 24, 2018

mbohlool changed the title ~~Crd Conversion Api Changes~~ Crd Conversion API Changes Aug 24, 2018

mbohlool changed the title ~~Crd Conversion API Changes~~ CRD Conversion API Changes Aug 24, 2018

mbohlool mentioned this pull request Aug 24, 2018

CRD webhook conversion #67006

Merged

k8s-ci-robot added the sig/architecture Categorizes an issue or PR as relevant to SIG Architecture. label Aug 27, 2018

sttts reviewed Aug 27, 2018

View reviewed changes

lavalamp reviewed Aug 27, 2018

View reviewed changes

mbohlool force-pushed the crd_conversion_api_changes branch from 1f6a9a2 to d337746 Compare August 29, 2018 04:18

lavalamp reviewed Aug 30, 2018

View reviewed changes

staging/src/k8s.io/apiextensions-apiserver/pkg/apis/apiextensions/v1beta1/types.go Show resolved Hide resolved

lavalamp reviewed Aug 30, 2018

View reviewed changes

mbohlool force-pushed the crd_conversion_api_changes branch 2 times, most recently from 2422154 to 1a8aae1 Compare August 30, 2018 23:21

liggitt reviewed Oct 31, 2018

View reviewed changes

mbohlool force-pushed the crd_conversion_api_changes branch 2 times, most recently from 5ae3346 to f77fd9f Compare October 31, 2018 18:10

mbohlool added 3 commits October 31, 2018 11:14

API Types for CRD conversion

530c799

Refactor webhookclientConfig validation of admission and audit regist…

1587d18

…ration

FeatureGate and API Validation for CRD Webhook Conversion

998e22d

mbohlool force-pushed the crd_conversion_api_changes branch from f77fd9f to 0e2024f Compare October 31, 2018 18:15

k8s-ci-robot assigned liggitt Oct 31, 2018

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 31, 2018

mbohlool force-pushed the crd_conversion_api_changes branch from 0e2024f to 96241de Compare October 31, 2018 20:29

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 31, 2018

k8s-ci-robot added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 31, 2018

k8s-ci-robot added the approved Indicates a PR has been approved by an approver from all required OWNERS files. label Oct 31, 2018

Update generated files

e27096c

mbohlool force-pushed the crd_conversion_api_changes branch from 96241de to e27096c Compare October 31, 2018 21:47

k8s-ci-robot removed the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Oct 31, 2018

mbohlool added the lgtm "Looks good to me", indicates that a PR is ready to be merged. label Nov 1, 2018

k8s-ci-robot added release-note-none Denotes a PR that doesn't merit a release note. and removed do-not-merge/release-note-label-needed Indicates that a PR should not merge because it's missing one of the release note labels. labels Nov 1, 2018

k8s-ci-robot merged commit 11706d3 into kubernetes:master Nov 1, 2018

liggitt mentioned this pull request Jan 24, 2019

Extensibility features - Path to GA #73185

Closed

12 tasks

CRD Conversion API Changes #67795

CRD Conversion API Changes #67795

Conversation

mbohlool commented Aug 24, 2018 • edited by liggitt Loading

mbohlool commented Aug 26, 2018

mbohlool commented Aug 26, 2018

dims commented Aug 27, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lavalamp left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mbohlool commented Aug 29, 2018

mbohlool commented Aug 29, 2018

mbohlool commented Aug 29, 2018

mbohlool commented Aug 30, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

lavalamp commented Aug 30, 2018

liggitt commented Oct 31, 2018

liggitt commented Oct 31, 2018 • edited Loading

liggitt commented Oct 31, 2018

lavalamp commented Oct 31, 2018

k8s-ci-robot commented Oct 31, 2018

liggitt commented Oct 31, 2018

k8s-ci-robot commented Oct 31, 2018

mbohlool commented Nov 1, 2018

liggitt commented Nov 1, 2018

mbohlool commented Aug 24, 2018 •

edited by liggitt

Loading

liggitt commented Oct 31, 2018 •

edited

Loading