[Kubernetes tutorial] Generated schema is quite relaxed

[PierreR]

After generating the Kubernetes schema with cue get go k8s.io/api/apps/v1, I wonder why so many validations are commented out such as:

// Protocol defines network protocols supported for things like container ports.
#Protocol: string // #enumProtocol

Another surprise is this snippet:

	// Protocol for port. Must be UDP, TCP, or SCTP.
	// Defaults to "TCP".
	// +optional
	// +default="TCP"
	protocol?: #Protocol @go(Protocol) @protobuf(4,bytes,opt,casttype=Protocol)

Why are so much rules encoded in comment ?

What is the best strategy here ? Remove these comments and add the rules in the cue.mod/usr directory ?

Thanks

[seh]

While it would be nice if CUE could translate more of the Kubernetes code generation hints, in this case it doesn't matter much, at least for the default value. If you don't specify it, CUE won't export the "protocol" field, and the Kubernetes API server will note its lack and supply the default value during admission.

Note the the code generation directive comments do not encode the enumeration values "SCTP," "TCP," and "UDP." Those are noted in prose near the code generation directive comments, but are otherwise ignored.

[verdverm]

I think it goes the other way around, that defines the type for the enum, and the comment is which enum. It's easier to see if you look at containerStatus

https://github.com/hofstadter-io/c8s/blob/7acfe01a47aa3982e370b2f112a3e4eaabc8189c/cue.mod/gen/k8s.io/api/core/v1/types_go_gen.cue#L2700

Also note, when Go code uses custom (in)marshal functions, than CUE cannot know how to make the import and uses 'top' for the value. This shows up in Kubernetes as container and service ports as an example

[myitcv]

Quoting directly from cue help get go:

Constants and Enums

Go does not have an enum or sum type. Conventionally, a type that is supposed
to be an enum is followed by a const block with the allowed values for that
type. However, as that is only a guideline and not a hard rule, these cases
cannot be translated to CUE disjunctions automatically.

Constant values, however, are generated in a way that makes it easy to convert
a type to a proper enum using native CUE constraints. For instance, the Go type

        package foo

        type Switch int

        const (
                Off Switch = iota
                On
        )

translates into the following CUE definitions:

        package foo

        #Switch: int // enumSwitch

        enumSwitch: Off | On

        Off: 0
        On:  1

This definition allows any integer value for Switch, while the enumSwitch value
defines all defined constants for Switch and thus all valid values if Switch
were to be interpreted as an enum type. To turn Switch into an enum,
include the following constraint in, say, enum.cue, in either the original
source directory or the generated directory:

        package foo

        // limit the valid values for Switch to those existing as constants with
        // the same type.
        #Switch: enumSwitch

This tells CUE that only the values enumerated by enumSwitch are valid
values for Switch. Note that there are now two definitions of Switch.
CUE handles this in the usual way by unifying the two definitions, in which case
the more restrictive enum interpretation of Switch remains.

(will fix the obvious error in the docs regarding # now)

[myitcv]

Would appreciate some eyes on https://cue-review.googlesource.com/c/cue/+/9901

[PierreR]

@myitcv Thanks for your detailed explanation. That makes sense (I am a Go noob who has spent too much time with languages that support sum type ;-).

It reminds me of the following discussion where I wonder if it could be possible to import CUE from an openAPI json file. Could it make the import from the Kubernetes API more aligned with my expectations (just want to know if it makes sense, I perfectly understand it is not a priority).

The PR looks good to me.

[myitcv]

The challenge comes when you have a source of truth, like Go, where you cannot conclusively tell what the author intended. If you assume the author of the Go code will also be responsible for distributing a CUE version, this isn't really a problem because the burden of further refining the generated output falls on the author. Where that's not possible, the workaround is hopefully lightweight, as noted in the commentary.

Where the source of truth does have sufficient information, e.g. OpenAPI, protobuf... then we can provide a definitive translation.

There isn't per se a "right" answer here.

In terms of priority, everything has necessarily been defined by those projects which expressed the greatest interest. Istio for example helped to shape the encoding/openapi package. If you have a use case that would help to prioritise new encodings (or completing existing ones) please do raise an issue or comment on the relevant open issue!

[cueckoo]

This discussion has been migrated to cue-lang/cue#947.

For more details about CUE's migration to a new home, please see cue-lang/cue#1078.