WG API Expression Proposal #8503
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -64,6 +64,7 @@ subprojects, and resolve cross-subproject technical issues and decisions. | |
|
|
||
| The following [working groups][working-group-definition] are sponsored by sig-cli: | ||
| * [WG AI Integration](/wg-ai-integration) | ||
| * [WG API Expression](/wg-api-expression) | ||
|
There was a problem hiding this comment. Speaking on behalf of SIG-CLI, I haven't seen anywhere (slack, mailing list, meeting) any information about this particular WG and us being asked to sponsor it. There was a problem hiding this comment. Looking at https://github.com/kubernetes/community/blob/master/committee-steering/governance/wg-governance.md it's not explicitly stated that a WG must have more than one sponsoring SIG. Would it be okay to drop SIG CLI here if there's no clear connection? That then still leave apimachinery and architecture, plus potentially participants from non-Kubernetes projects. |
||
| * [WG Node Lifecycle](/wg-node-lifecycle) | ||
|
|
||
|
|
||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3602,6 +3602,43 @@ workinggroups: | |
| liaison: | ||
| github: pacoxu | ||
| name: Paco Xu 徐俊杰 | ||
| - dir: wg-api-expression | ||
| name: API Expression | ||
| mission_statement: > | ||
|
There was a problem hiding this comment. I'm inclined to suggest to move certain elements from the attached mission statement into the WG charter. |
||
| Enable API authors to better serve API consumers, by improving and documenting | ||
| all aspects of Kubernetes API development. Mission is for Kubernetes APIs to | ||
| be more declarative. [See full Mission Statement in Proposal](https://docs.google.com/document/d/1RxeKII-3ZESSGMKt09meSGhpDW6CyufM2v1SYgAh_uQ). | ||
|
There was a problem hiding this comment. Links to Google Docs are problematic (access permissions, content could change). I agree with @soltysh, if there's content in that doc that is relevant for the WG, then it should be copied into this repo. |
||
|
|
||
| stakeholder_sigs: | ||
| - API Machinery | ||
| - Architecture | ||
| - CLI | ||
| label: api-expression | ||
| leadership: | ||
| chairs: | ||
| - github: JoelSpeed | ||
| name: Joel Speed | ||
| company: Red Hat | ||
| email: [email protected] | ||
| - github: aaron-prindle | ||
| name: Aaron Prindle | ||
| company: Google | ||
| email: [email protected] | ||
| meetings: | ||
| - description: Regular WG Meeting | ||
| day: Tuesday | ||
| time: "9:30" | ||
| tz: PT (Pacific Time) | ||
| frequency: biweekly | ||
| url: https://zoom.us/j/94238112084 | ||
| archive_url: https://docs.google.com/document/d/1CSpNaicbEqKJoW306qaQEBIkwC1mGIcKl3yiB_C0HZk | ||
| recordings_url: https://www.youtube.com/playlist?list=PL69nYSiGNLP0CU9g6-yb1NgZXGAhMxfFE&jct=9Leh8O_yrRTB0Kcv3rMKZHncZq8POg | ||
| contact: | ||
| slack: wg-api-expression | ||
| mailing_list: https://groups.google.com/forum/#!forum/kubernetes-wg-api-expression | ||
|
There was a problem hiding this comment. I know you're reviving this group, but since then we've move to managed google groups. I think it'd be beneficial to start using the new ML address, rather the old one. |
||
| liaison: | ||
|
There was a problem hiding this comment. TODO: steering will loadbalance a liason There was a problem hiding this comment. [still todo, raised this again with steering-private] There was a problem hiding this comment. I can be the liaison for this WG. There was a problem hiding this comment. I believe this will be @pohly There was a problem hiding this comment. Great, thanks @pohly! I have updated the liaison information here now. |
||
| github: BenTheElder | ||
| name: Benjamin Elder | ||
| - dir: wg-batch | ||
| name: Batch | ||
| mission_statement: > | ||
|
|
||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,36 @@ | ||
| <!--- | ||
| This is an autogenerated file! | ||
|
|
||
| Please do not edit this file directly, but instead make changes to the | ||
| sigs.yaml file in the project root. | ||
|
|
||
| To understand how this file is generated, see https://git.k8s.io/community/generator/README.md | ||
| ---> | ||
| # API Expression Working Group | ||
|
|
||
| Enable API authors to better serve API consumers, by improving and documenting all aspects of Kubernetes API development. Mission is for Kubernetes APIs to be more declarative. [See full Mission Statement in Proposal](https://docs.google.com/document/d/1RxeKII-3ZESSGMKt09meSGhpDW6CyufM2v1SYgAh_uQ). | ||
|
|
||
| ## Stakeholder SIGs | ||
| * [SIG API Machinery](/sig-api-machinery) | ||
| * [SIG Architecture](/sig-architecture) | ||
| * [SIG CLI](/sig-cli) | ||
|
|
||
| ## Meetings | ||
| *Joining the [mailing list](https://groups.google.com/forum/#!forum/kubernetes-wg-api-expression) for the group will typically add invites for the following meetings to your calendar.* | ||
| * Regular WG Meeting: [Tuesdays at 9:30 PT (Pacific Time)](https://zoom.us/j/94238112084) (biweekly). [Convert to your timezone](http://www.thetimezoneconverter.com/?t=9%3A30&tz=PT%20%28Pacific%20Time%29). | ||
| * [Meeting notes and Agenda](https://docs.google.com/document/d/1CSpNaicbEqKJoW306qaQEBIkwC1mGIcKl3yiB_C0HZk). | ||
| * [Meeting recordings](https://www.youtube.com/playlist?list=PL69nYSiGNLP0CU9g6-yb1NgZXGAhMxfFE&jct=9Leh8O_yrRTB0Kcv3rMKZHncZq8POg). | ||
|
|
||
| ## Organizers | ||
|
|
||
| * Joel Speed (**[@JoelSpeed](https://github.com/JoelSpeed)**), Red Hat | ||
| * Aaron Prindle (**[@aaron-prindle](https://github.com/aaron-prindle)**), Google | ||
|
|
||
| ## Contact | ||
| - Slack: [#wg-api-expression](https://kubernetes.slack.com/messages/wg-api-expression) | ||
| - [Mailing list](https://groups.google.com/forum/#!forum/kubernetes-wg-api-expression) | ||
| - [Open Community Issues/PRs](https://github.com/kubernetes/community/labels/wg%2Fapi-expression) | ||
| - Steering Committee Liaison: Benjamin Elder (**[@BenTheElder](https://github.com/BenTheElder)**) | ||
| <!-- BEGIN CUSTOM CONTENT --> | ||
|
|
||
| <!-- END CUSTOM CONTENT --> |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| # WG API Expression Charter | ||
|
|
||
| This charter adheres to the conventions described in the [Kubernetes Charter README] and uses | ||
| the Roles and Organization Management outlined in [sig-governance]. | ||
|
|
||
| ## Scope | ||
|
|
||
| Enable declarative expression of Kubernetes APIs (metadata, validation rules, etc.) to replace imperative, handwritten logic. This working group focuses on developing frameworks and tools that allow API authors to express API rules declaratively as part of the schema itself, improving development velocity, consistency, and maintainability across both native Kubernetes types and CRDs. | ||
aaron-prindle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### In scope | ||
|
|
||
| #### Code, Binaries and Services | ||
|
|
||
| - Declarative validation code generator (validation-gen) that generates Go validation code from declarative tags in API type definitions | ||
| - Kube API Linter (KAL) for checking API types against Kubernetes API Conventions and best practices | ||
|
There was a problem hiding this comment. This is an ongoing subproject, not a workgroup deliverable? There was a problem hiding this comment. IIUC the declarative validation code generator is also ongoing work right? |
||
| - Integration frameworks between declarative tools (validation-gen, kubebuilder, KAL, and other API tools) | ||
| - Libraries and components for type discovery and declarative API expression that can be reused across code generators | ||
| - Tools and processes for generating CEL or OpenAPI validation rules from declarative tags | ||
| - Documentation generation tools that create API documentation from declarative expressions | ||
|
|
||
| #### Cross-cutting and Externally Facing Processes | ||
|
|
||
| - Development and maintenance of KEPs for declarative API expression features (eg: KEP-5073 Declarative Validation) | ||
aaron-prindle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Migration strategies and guides for SIGs to adopt the declarative framework | ||
| - Establishing patterns for ratcheting, validation, defaulting, and immutability expressed declaratively | ||
aaron-prindle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - Ensuring consistency between Kubernetes native types and CRD validation experiences | ||
| - Automated API quality checks and linting processes integrated into the standard API review workflow | ||
|
|
||
| ### Out of scope | ||
|
|
||
| - General API design decisions unrelated to declarative expression | ||
| - Runtime validation logic that cannot be expressed declaratively | ||
|
|
||
| ## Deliverables | ||
|
|
||
| The working group will deliver: | ||
|
|
||
| - **validation-gen code generator**: Core tool for generating Go validation code from declarative tags | ||
| - **Kube API Linter (KAL)**: Automated API convention checker integrated into the review process | ||
|
There was a problem hiding this comment. These first two don't seem like workgroup deliverables, they're existing subprojects, and there's no specific targeted improvements to them. |
||
| - **Integration strategy**: Cohesive approach for integrating validation-gen, kubebuilder, KAL, and other tools | ||
|
There was a problem hiding this comment. Where are you planning to integrate kubebuilder and other tools? Because both validation-gen and KAL are actively being worked on to include in current k/k code. There was a problem hiding this comment. The goal of the bullet here was trying to explain that there is an ecosystem of tags and tools currently that are related to API Expression and declarative APIs. This bullet is related to current discussions here:
around a Kubebuilder tags related to conditional field inclusion from a feature gate and a similar tag in declarative validation around conditionally running a validation based on a feature gate. The bullet here attempts to highlight that WG API Expression is to be used as a way of getting consensus, sharing information, and formalizing designs/approaches across these projects which tackle API Expression. There was a problem hiding this comment. So this is just re-using existing sig-apimachnery sub-project, expanding its functionality with this single feature, do I understand that correctly? |
||
| - **KEPs**: Series of enhancement proposals introducing and evolving the framework | ||
|
There was a problem hiding this comment. Not sure I understand this goal. Can you explain this a bit better? |
||
| - **CRD equivalence strategy**: Plan to bridge the gap between native types and CRDs | ||
|
There was a problem hiding this comment. What is the gap that you're planning to bridge? There was a problem hiding this comment. I've updated the text here to explain the gap we are hoping to bridge:
|
||
| - **Documentation generation strategy**: Automated documentation from declarative API expressions | ||
|
There was a problem hiding this comment. What part are we currently missing? There was a problem hiding this comment. The goal would be that the validation documentation for each field of a native API type could be generated from declarative tags and this could be a part of reference information for the type. (ex: https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/). I've updated the text there to explain this in more detail. |
||
| - **Migration guides**: Documentation for SIGs to adopt the framework and migrate existing APIs | ||
|
|
||
| ## Stakeholders | ||
|
|
||
| - **SIG API Machinery**: Owner of API server, gengo, kube-openapi, and validation-gen tool | ||
aaron-prindle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| - **SIG Architecture**: Owner of Kubernetes API conventions and architectural decisions | ||
| - **SIG CLI**: Consumer of more expressive APIs, providing feedback on kubectl interaction and user experience | ||
|
There was a problem hiding this comment. Again, speaking for SIG-CLI, that part is not fully clear. Would you have time to show up on one of our meetings and explain to us better the idea behind it? |
||
|
|
||
| ## Roles and Organization Management | ||
|
|
||
| This sig adheres to the Roles and Organization Management outlined in [sig-governance] | ||
| and opts-in to updates and modifications to [sig-governance]. | ||
|
|
||
| ### Meeting Mechanics | ||
|
|
||
| - **Frequency**: Bi-weekly (every 2 weeks) | ||
| - **Duration**: 60 minutes | ||
| - **Communication**: | ||
| - Slack: #wg-api-expression | ||
| - Mailing List: [email protected] | ||
aaron-prindle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ### Chairs | ||
|
|
||
| - Aaron Prindle (@aaron-prindle) | ||
| - Joel Speed (@JoelSpeed) | ||
aaron-prindle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
|
||
| ## Exit Criteria | ||
|
|
||
| The working group will have fulfilled its charter and can be disbanded when: | ||
|
|
||
| 1. The core framework, including validation-gen and associated libraries, is stable and integrated into the main Kubernetes development workflow | ||
| 2. Foundational KEPs (e.g., Declarative Validation) are implemented and graduated to GA | ||
| 3. Kube API Linter (KAL) is mature, widely adopted, and integrated into the standard API development and review process | ||
| 4. A clear, documented process exists for SIGs to migrate existing types and use the framework, with successful migrations of key types (eg: PodSpec) demonstrating the process | ||
| 5. Ongoing maintenance of the framework has been successfully transitioned to owner SIGs, primarily SIG API Machinery | ||
|
|
||
| [sig-governance]: https://github.com/kubernetes/community/blob/master/committee-steering/governance/sig-governance.md | ||
| [sig-subprojects]: https://github.com/kubernetes/community/blob/master/sig-YOURSIG/README.md#subprojects | ||
| [Kubernetes Charter README]: https://github.com/kubernetes/community/blob/master/committee-steering/governance/README.md | ||
Uh oh!
There was an error while loading. Please reload this page.