Hello Kubernetes Community,
This is a formal proposal to reinstate the previously archived Working Group for API Expression (WG-API-Expression). This proposal is submitted on behalf of contributors currently working on declarative API improvements, including the "Declarative Validation" project, and represents a broader vision for API expression in Kubernetes.
We believe this work is important for the long-term health and velocity of the project and are seeking community feedback and sponsorship from our stakeholder SIGs (primarily SIG API Machinery).
Thanks,
Aaron Prindle
===
Following the process outlined in the Working Group Governance document, this proposal outlines the charter for the working group.
1. What is the exact problem this group is trying to solve?
Imperative, handwritten logic in Kubernetes APIs (esp. for validation and defaulting) is difficult to write, difficult to review, and has a high consequence of failure. This slows down development and requires additional time for review by a small pool of API reviewers.
The Kubernetes API lacks a declarative language for expressing information about the API. This leads to several problems:
Fragmented Sources of Truth for API Fields: Critical metadata about API fields such as ratcheting, validation rules, defaulting logic, immutability, etc. is not expressed declaratively currently. This information is fragmented across hand-written Go code, comments, and documentation, preventing programmatic consumption and creating toil for both humans and tools.
Complex Logic is Opaque: Logic for patterns like ratcheting, validation, defaulting, etc. currently are represented in hand-written Go code, making it difficult to understand, review, document, and reuse.
Inconsistent K8s Native Types vs. CRD Experience: CRD authors use CEL or webhooks to implement validations that are handwritten for native types, leading to a divergence in capability and authoring experience.
This working group will solve these problems by developing and promoting a framework for declaring API rules as part of the schema itself.
2. What is the artifact that this group will deliver, and to whom?
The working group will deliver a complete framework for declarative API expressions, aimed at stakeholder SIGs and the broader contributor community. The key deliverables are:
A code generator (validation-gen): This code generator and its components are core to the work here. It will generate Go validation code directly from declarative tags in API type definitions. The goal is that pieces of the code generator (type discovery, etc) can be reused in other similar code generators to enable additional declarative API expression usages.
A series of Kubernetes Enhancement Proposals (KEPs): To introduce and evolve the framework. The group is currently working on the KEP Declarative Validation (KEP-5073) which includes features like ratcheting, etc. Future KEPs will cover new capabilities such as OpenAPI integration, etc.
A clear strategy for CRD equivalence: A plan to bridge the gap between Kubernetes native types and CRDs, potentially through integration with kube-openapi, openapi-gen, and/or kubebuilder to generate CEL or OpenAPI validation rules from the same declarative tags.
A clear strategy for documentation generation: A plan to automatically generate documentation for Kubernetes native types from declarative API expressions.
Onboarding documentation and migration guides: To make it easy for new contributors to join the effort and for other SIGs to adopt the framework and migrate their existing APIs.
3. How does the group know when the problem-solving process is completed, and it is time for the Working Group to dissolve?
The working group will have fulfilled its charter and can be disbanded when its work has transitioned from incubation to being a standard, maintained part of Kubernetes development. The specific exit criteria are:
The core framework, including validation-gen and its associated libraries, is stable and integrated into the main Kubernetes development workflow.
The foundational KEPs (eg: Declarative Validation, etc.) are implemented and Declarative Validation has graduated to GA.
A clear, documented process exists for SIGs to migrate existing types and for new APIs to use the framework, with successful migrations of key types (PodSpec, etc.) demonstrating the process.
The ongoing maintenance of the framework has been successfully transitioned to its owner SIGs, primarily SIG API Machinery.
4. Who are all of the stakeholder SIGs involved in this problem this group is trying to solve?
The key stakeholders are:
SIG API Machinery (Primary): As the owner of the API server, gengo, kube-openapi, and the validation-gen tool itself, this SIG is the primary owner and implementer of the framework.
SIG CLI: Consumer of a more declarative API, providing feedback on interaction w/ kubectl, etc. and associated user experience.
5. What are the meeting mechanics (frequency, duration, roles)?
Meetings: The group will use the pre-existing cadence of bi-weekly meetings for 60 minutes. Meeting time will be set to accommodate participants across time zones.
Communication:
Slack: A new #wg-api-expression channel will be established for discussions.
Mailing List: The existing kubernetes-wg-...@googlegroups.com list will be used for official announcements and design discussions.
Roles:
Aaron Prindle (@aaron-prindle) will facilitate the meeting
6. Does the goal of the Working Group represent the needs of the project as a whole, or is it focused on the interests of a narrow set of contributors or companies?
The goal of the Working Group represents the needs of the project as a whole. The benefits are project-wide:
For API Reviewers: Drastically reduces the time required to review API changes, freeing up a critical project resource.
For SIG Contributors: Simplifies the process of adding and validating new API fields, documenting APIs, etc.
For CRD/Controller Authors: Goal of future work is to create a consistent, powerful mechanism for validation, defaulting, etc. making it easier to build on top of Kubernetes.
For End Users: Leads to more consistent, predictable, and better-documented API behavior.
This effort directly addresses review bottlenecking and project velocity, which are core concerns for the health of Kubernetes as a whole.
7. Who will chair the group, and ensure it continues to meet these requirements?
The proposed initial chair for this working group is:
Aaron Prindle (@aaron-prindle)
8. Is diversity well-represented in the Working Group?
We are strongly committed to making this a fully open Kubernetes community effort. A key motivation for formalizing this WG is to transition the work from a small, informal group to a public project that welcomes all contributors.
We have a concrete plan to foster diversity in the Working Group:
Open Contribution: We are actively seeking contributors from different backgrounds, companies, etc.
Clear Onboarding: We will create a "getting started" guide and document the process for contributing as well as aiding in adding declarative tags, etc. to current types.