Generate schema for CRD v1

[kazk]

Schema is generated with schemars.

Also fixed the location of subresources and additionalPrinterColumns.

Closes #264

---

For deriving CRD v1, the spec struct must include schemars::JsonSchema. The schemas for subresources are currently not generated, but it should be possible to add the status subresource by requiring the status struct to have schemars::JsonSchema and extracting the generated schema similar to the spec. If there is a status subresource, its struct must include JsonSchema as well.

I'm not sure how to handle the new schemars dependency.

[nightkr]

IIRC Kubernetes requires its own weird dialect of JSON Schemas. In particular, it has some weird requirements around tagged unions (which we'd generally use rich enums for in Rust).

Can schemars generate schemas that are compliant with that? If so, what special options are required for that?

[kazk]

@teozkr Thanks for reviewing. I just pushed a fix to support nested struct/enums and that also includes the status subresource automatically if present.

IIRC Kubernetes requires its own weird dialect of JSON Schemas. In particular, it has some weird requirements around tagged unions (which we'd generally use rich enums for in Rust).

Yes, they use Open API v3 (dialect of JSON Schemas) with additional restrictions.

I wasn't aware of the requirements around tagged unions. I'll try adding some.

Can schemars generate schemas that are compliant with that? If so, what special options are required for that?

schemars support Open API v3 through a setting and this uses that. Also, Kubernetes disallows definitions so I'm using an option to inline all the schemas. Usually schemars defines schema to reference under definitions for each type. The original implementation was extracting the schema of the spec struct with schema.definitions.get("FooSpec").unwrap(), but I found the option to inline all.

[kazk]

2. for each field in an object and each item in an array which is specified within any of allOf, anyOf, oneOf or not, the schema also specifies the field/item outside of those logical junctors (compare example 1 and 2).

BAD

allOf:
- properties:
    foo:
      ...

GOOD

properties:
  foo:
    ...
allOf:
- properties:
    foo:
      ...

😕

---

For the following spec (attributes omitted for brevity):

pub struct FooSpec {
    value: FooEnum,
}
#[serde(untagged)]
pub enum FooEnum {
    Foo { foo: String },
    Bar { bar: String },
}

The generated schema currently looks like the following:

openAPIV3Schema:
  type: object
  properties:
    spec:
      properties:
        value:
          anyOf:
            - properties:
                foo:
                  type: string
              required:
                - foo
              type: object
            - properties:
                bar:
                  type: string
              required:
                - bar
              type: object
      required:
        - value
      type: object
  required:
    - spec

Can schemars generate schemas that are compliant with that? If so, what special options are required for that?

I'm not sure what's valid in this case, but I think we can transform the schema by implementing a Visitor and using with_visitor:

let gen = schemars::gen::SchemaSettings::openapi3()
    .with(|s| {
        s.inline_subschemas = true;
    })
    .with_visitor(KubeVisitor::new())
    .into_generator();

[kazk]

• Vanilla CRD OpenAPI subset: structural schemas
• apiextensions: implement structural schema condition (original implementation PR)
  • k8s.io/apiextensions-apiserver/pkg/apiserver/schema current package
  • NewStructural function converts an OpenAPI v3 schema into a structural schema.
    • The input is apiextensions.JSONSchemaProps, so maybe we can port this. Seems unrelated to producing structural schema.

[clux]

This is huge @kazk . Thank you so much for doing this. 🥳

Using schemars here is a very sensible solution that avoids homebrewing this too much, and the library has sensible serde re-use policies for attributes. As a tiny negative it does look like this prevents us from doing validation constraints such as minimum and maximum, but starting to think it's maybe more transparent for rust to control the validation fully where possible.

There are a couple of things I would like to have tests for and clarify before we release this though:

• default and default_with serde attrs should correspond with crd defaulting rules
• if Optional fields are nullable, do they require explicit serialization of the null value for k8s to null them out? If so, we ought to at least document that it's a bit scary to put #[serde(skip_serializing_if = "Option::is_none")] on them.
• if a user puts a timestamp in a struct (timestamp: DateTime<Utc>,) requiring chrono with serde feature, how would this interact with kube-derive (which pulls in schemars without the chrono feature), maybe we should just pull in chrono feature always (it's always in k8s-openapi's dependency tree anyway)

Of course; I am happy to take this into master without further changes right now. This is a massive improvement, so thank you again. But if you are able to help a little bit with the general user experience, that would be super helpful :-)

[kazk]

@clux Thanks for reviewing. Yeah, this definitely need more polishing. Also, we need to ensure generating a structural schema for more complex specs (should be a separate PR). But api.create(&PostParams::default(), &Foo::crd()).await? for simple FooSpec should work now and I'm happy to be able to give something back :)

As a tiny negative it does look like this prevents us from doing validation constraints such as minimum and maximum

There's an issue open and the author wrote:

Alternatively, I could just add more options to #[schemars(...)] attributes to allow setting more properties on the generated schema

GREsau/schemars#12 (comment)

So maybe it can be supported relatively easily.

---

I'll look into the points you brought up later. It's getting late here.

[kazk]

I did some research on generating more complex schemas and it turns out controller-gen (used by kubebuilder) doesn't support it either yet.

• Support more complex validations (oneOf/anyOf/allOf/etc)
• Support for oneOf Groups for Discriminate Types (PR for oneOf open since 2019-08-06)

So, it might not be limiting as I thought. (But I also think that Rust code is more likely to need this.)

---

I'll finish the examples/tests either tonight or tomorrow.

[kazk]

@clux I cleaned up the commits and it should be ready for merge. Please let me know if I missed anything or if there's something you'd like to be fixed.

[clux]

This is absolutely awesome. Tests seem to cover things well, I'll add them to the circleci config so that it sticks around.

Left a small request for chrono feature, I think it will "just work", but if it's in any way complicated, just say so, and I'll merge this as is!

[clux]

Looking good. Ready to merge? :-)

[kazk]

Yeah :)

[clux]

Thanks again for all of this. I'm planning to get a release out on Wednesday with some release notes for this. I'll post when it's done.