Epic: Kpt OpenAPI roadmap

[natasha41575]

This is an umbrella issue describing the tasks that @mengqiy outlined, for OpenAPI features in kpt

• Define a scheme to use OpenAPI extension mechanisms Define a scheme to use OpenAPI extension mechanisms for kpt functions #1505
  • Use the scheme to define the augment for k8s builtin types (depends on Define a scheme to use OpenAPI extension mechanisms for kpt functions #1505)
  • Use the scheme to define the augment for KCC types (depends on Define a scheme to use OpenAPI extension mechanisms for kpt functions #1505)
• Kpt should have one or more compiled-in OpenAPI docs that matches the minor versions supported by GKE fleet
• Kpt should allow users to provide OpenAPI docs
• Kpt should be able to load the OpenAPI from the APIServer
• Ensure “kpt pkg update” can access the merge strategy and merge keys from the OpenAPI doc
• No matter what language a function is written in, kpt should have a mechanism to inject the OpenAPI document to a function when it is executed Design a mechanism to inject OpenAPI schema into kpt functions #1608

Why do we need to do this?

We want our tools to work well with custom resources. We want our functions to have a good UX and custom resources work like builtin types, so that users don't have to provide their own hardcoded fieldspecs for their CRDs (see this example). Instead of having to provide their own fieldspecs, we would like to see if they can be inferred from OpenAPI instead, and make CRDs work like builtins. For this to work, we need to build OpenAPI extensions so that the necessary metadata is available for kpt and kpt functions.

We also want users to have a good UX including a separation between CRD authors and function consumers. In an ideal workflow, the CRD author would provide the OpenAPI specification and extensions needed to use their CRD, and function users would be able to use them seamlessly. These users would only need to provide their desired fields without including the fieldspec metadata that can be provided by the author.

Not only does this affect functions, but kpt uses OpenAPI data for merging packages. 3-way merge requires metadata from OpenAPI (to get merge key and patch strategy information). 3-way merge is necessary for kpt package update. If a user can provide their own OpenAPI doc, then they can also control how kpt merges resources.

Why do this now?

Because this work may take a few months, and ideally this would be available for kpt functions in the function catalog when they are ready. It is better to start now rather than start when the need arises. This will impact every function that needs metadata from OpenAPI which will affect most functions in the function catalog.

[natasha41575]

@mengqiy umbrella issue for the openapi work

[natasha41575]

we may also want to look into kubernetes-sigs/kustomize#3670

[mikebz]

I'd consider moving this into "In Progress" if it's actively being worked on.

[mikebz]

Could we link some questions or issues that were filed because this feature didn't exist? It would be great to get back to those users and see if we are addressing their needs and also could be early design partners.

[natasha41575]

I will link issues if they arise. The main goal here is to make sure the UX for functions is good, so we are welcoming any input from users on that.

[mikebz]

I have rarely seen a feature well received if it wasn't addressing a problem that customers already knew they had.

[frankfarzan]

This is a cross-cutting and critical part of having good UX when manipulating KRM resources. Even most basic functions like name-prefix require augmented OpenAPI semantics to work properly. Kustomize has done this for core k8s native types based on a real need, we need to generalize and extend this.

[natasha41575]

Another note: because kustomize had only been built with OpenAPI for native types, issues have come up regarding the lack of OpenAPI support for CRDs (see kubernetes-sigs/kustomize#2825, kubernetes-sigs/kustomize#1689, kubernetes-sigs/kustomize#3677). It will be good if kpt can learn from this and support it early on.