How Should We Model Versions, Schemas, and Conversions?

[stevekuznetsov]

@ncdc @vincepri and I were chatting about APIResourceSchema and the associated machinery and a thought came up - we want API rollout to be explicit and deterministic, so we require that APIResourceSchema be immutable. This means that if an API has N versions, and I update just one of them to have a new field, I create an entirely new APIResourceSchema and copy lots of data. Similarly, the proposed APIConversion resource is also immutable has all the mappings required for an APIResourceSchema, so any minor change requires a lot of copying into a new object.

What if we model things at a more granular level?

1. each APIExport references a set of APIResourceSchema
2. each APIResourceSchema references a set of APIResourceVersions
3. each APIResourceVersion provides the information necessary for a specific semantic version, at a particular point in time - e.g. v1, from November 22nd

Then, we can also have APIConversion objects that are uniquely identified by the two APIResourceVersion objects they operate between - so each APIConversion resource only provides the (bi)directional conversions between two specific versions.

This would allow us to reduce the amount of noise and duplication in our API objects, as well as give us much more fine grained control over e.g. garbage collection, without changing the nice guarantees we have at the APIExport level.

[vincepri]

re:APIResourceSchema immutability.

Could we consider an option where we have the APIResourceSchema object be mutable? Some pre-requisites/assumptions:

• Changes to existing APIs (updates) should be strictly validated with warnings or errors in an admission controller.
  • These can be super-strict at first, for example: "existing versions can only add new fields", "an optional field cannot become required", "cannot change type of a field if already set" and so on.
  • Over time, we can relax some (where it makes sense) of these requirements to allow safe in place changes.
• We can provide flags for developers and authors to force override the checks and just store the schema changes; these would be useful in development, testing, and in scenarios where APIs are not being used or the scope is limited; the decision is left ultimately to the API author which can opt in into world-breaking changes.

Immutability today is required to control the rollout of an APIResourceSchema revision, if we allow APIResourceSchema objects to be mutable, the system could potentially offer revisions as part of an admission process. For example,

Let's say that we have this schema (copied from test/e2e):

[...]
  - name: v1alpha1
    schema:
      description: Cowboy is part of the wild west
      properties:
        apiVersion:
          description: 'APIVersion defines the versioned schema of this representation
            of an object. Servers should convert recognized schemas to the latest
            internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
          type: string
        kind:
          description: 'Kind is a string value representing the REST resource this
            object represents. Servers may infer this from the endpoint the client
            submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
          type: string
        metadata:
          type: object
        spec:
          description: CowboySpec holds the desired state of the Cowboy.
          properties:
            intent:
              type: string
          type: object
        status:
          description: CowboyStatus communicates the observed state of the Cowboy.
          properties:
            result:
              type: string
          type: object
      type: object
[...]

After the object is accepted:

[...]
  - name: v1alpha1
    schema:
      description: Cowboy is part of the wild west
      properties:
        apiVersion:
>         revision: 1
          description: 'APIVersion defines the versioned schema of this representation
            of an object. Servers should convert recognized schemas to the latest
            internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
          type: string
        kind:
>        revision: 1
          description: 'Kind is a string value representing the REST resource this
            object represents. Servers may infer this from the endpoint the client
            submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
          type: string
        metadata:
>         revision: 1
          type: object
        spec:
>         revision: 1
          description: CowboySpec holds the desired state of the Cowboy.
          properties:
            intent:
>             revision: 1
              type: string
          type: object
        status:
>         revision: 1
          description: CowboyStatus communicates the observed state of the Cowboy.
          properties:
            result:
>             revision: 1
              type: string
          type: object
      type: object
[...]

Let's say now, we add a new field to the existing v1alpha1 version, the system after processing it would look like:

[...]
  - name: v1alpha1
    schema:
      description: Cowboy is part of the wild west
      properties:
       [...]
        spec:
          revision: 1
          description: CowboySpec holds the desired state of the Cowboy.
          properties:
            fedora:
>             revision: 2
              type: bool
            intent:
              revision: 1
              type: string
          type: object
[...]

In addition, the APIResourceSchema type could get a new field under Status (maybe?) outlining for users which versions are available to be exposed.