How to enum poorly documented

[erictune]

There are quite a few ways a user might try to make an enum. Only one or two ways are "right".

Suggested Fix:

• Specifically have a section in the KubeBuilder book called "Enums" and show a generic example.
• Explain that the validation and how you chose to define types in Go are not related. (This is not obvious because some aspect of go syntax do generate OpenAPI, like scalar types.)

All the ways

The Right Way

The documentation example for CronJob does an enum like this:

// +kubebuilder:validation:Enum=A,B,C
type MyEnum string
const (
    MyEnumA MyEnum = "A"
    MyEnumB MyEnum = "B"
    MyEnumB MyEnum = "C"
)
type MyObjectSpec {
  // 
   Mode MyEnum
}

This works right, in that the OpenAPI enum= validation is generated in the CRD.
However, a reasonable user might also try to do many other ways, only some of which work right.

Alternative One

kubebuilder comment on the field in the Object.
Works right

type MyEnum string
const (
    MyEnumA MyEnum = "A"
    MyEnumB MyEnum = "B"
    MyEnumB MyEnum = "C"
)
type MyObjectSpec {
  // 
   // +kubebuilder:validation:Enum=A,B,C
   Mode MyEnum
}

Alternative Two

kubebuilder comment on the field in the Object and on the EnumType.
Does not work. They seem to cancel out

// +kubebuilder:validation:Enum=A,B,C
type MyEnum string
const (
    MyEnumA MyEnum = "A"
    MyEnumB MyEnum = "B"
    MyEnumB MyEnum = "C"
)
type MyObjectSpec {
  // 
   // +kubebuilder:validation:Enum=A,B,C
   Mode MyEnum
}

Alternative Three

No kubebuilder comment.
does not work
User might assume that when you use the Go idiom for an enum that the OpenAPI is inferred. It isn't.

type MyEnum string
const (
    MyEnumA MyEnum = "A"
    MyEnumB MyEnum = "B"
    MyEnumB MyEnum = "C"
)
type MyObjectSpec {
   Mode MyEnum
}

Alternative Four

Kubebuilder comment and no Go enum idiom
works but no static checking in go

type MyObjectSpec {
  // 
   // +kubebuilder:validation:Enum=A,B,C
   Mode string
}

/kind documentation

[erictune]

/remove-kind bug

[DirectXMan12]

Does not work. They seem to cancel out

Err... that's a bug

/kind bug

[DirectXMan12]

/good-first-issue

on the docs

help wanted on the cancelling out bug. I'm guessing that our allof resolution logic has a bug. Start by adding a unit test (It("should preserve validation when both the field and the type have the same validation")) and go from there.

[k8s-ci-robot]

@DirectXMan12:
This request has been marked as suitable for new contributors.

Please ensure the request meets the requirements listed here.

If this request no longer meets these requirements, the label can be removed
by commenting with the /remove-good-first-issue command.

In response to this:

/good-first-issue

on the docs

help wanted on the cancelling out bug. I'm guessing that our allof resolution logic has a bug. Start by adding a unit test (It("should preserve validation when both the field and the type have the same validation")) and go from there.

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/test-infra repository.

[camilamacedo86]

/assign @camilamacedo86

[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

[djzager]

/assign @djzager

[djzager]

Looking into the doc portion of this issue it appears that this is already laid out in Generating CRDs. Specifically, the section concerning validation shows the correct way to do this (shortened for simplicity):

type ToySpec struct {
...
	Alias   Alias   `json:"alias,omitempty"`
	Rank    Rank    `json:"rank"`
}

// +kubebuilder:validation:Enum=Lion;Wolf;Dragon
type Alias string

[djzager]

help wanted on the cancelling out bug. I'm guessing that our allof resolution logic has a bug. Start by adding a unit test (It("should preserve validation when both the field and the type have the same validation")) and go from there.

Maybe this hsould be an issue against https://github.com/kubernetes-sigs/controller-tools ? I don't see anything in kubebuilder related to that, but searching for allof in controller-tools leads me to believe this should be addressed there.

@DirectXMan12 what do you think?

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

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 rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

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

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

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

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/test-infra repository.