WG API Expression Proposal #8503

aaron-prindle · 2025-06-25T02:32:45Z

Which issue(s) this PR fixes:

See the thread for context: https://groups.google.com/a/kubernetes.io/g/dev/c/VYRaUdf0Arc

/sig api-machinery
/sig architecture
/sig cli

k8s-ci-robot · 2025-06-25T02:32:52Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: aaron-prindle
Once this PR has been reviewed and has the lgtm label, please assign jberkus for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

OWNERS_ALIASES

soltysh · 2025-07-28T11:25:06Z

/committee steering

BenTheElder · 2025-07-31T16:25:28Z

sigs.yaml

+  contact:
+    slack: wg-api-expression
+    mailing_list: https://groups.google.com/forum/#!forum/kubernetes-wg-api-expression
+    liaison:


TODO: steering will loadbalance a liason

[still todo, raised this again with steering-private]

I can be the liaison for this WG.

I believe this will be @pohly

Great, thanks @pohly! I have updated the liaison information here now.

BenTheElder

Missing charter.md to outline scope and exit criteria.

Also curious, is this a permanent problem space like Code Organization Subproject of SIG Arch, or a scoped effort that will conclude? If it's the former a SIG API Machinery Subproject + subproject meeting might be a better fit. If the latter, we need a charter to clarify it.

Pushing charter.md should auto-assign steering for review and label the PR etc.

e.g. https://github.com/kubernetes/community/blob/master/wg-device-management/charter.md

aaron-prindle · 2025-08-12T22:05:23Z

Missing charter.md to outline scope and exit criteria.

Oof, my mistake thanks for pointing this out. I've updated the PR here to have the completed charter.md file now for WG API Expression

wg-api-expression/charter.md

BenTheElder · 2025-08-20T00:12:31Z

wg-api-expression/charter.md

+#### 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


This is an ongoing subproject, not a workgroup deliverable?

IIUC the declarative validation code generator is also ongoing work right?

BenTheElder · 2025-08-20T00:13:30Z

wg-api-expression/charter.md

+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


These first two don't seem like workgroup deliverables, they're existing subprojects, and there's no specific targeted improvements to them.

soltysh · 2025-08-20T12:10:25Z

sig-cli/README.md

@@ -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)


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.

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.

soltysh · 2025-08-20T12:12:50Z

sigs.yaml

+    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


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.

wg-api-expression/charter.md

soltysh · 2025-08-20T12:31:18Z

wg-api-expression/charter.md

+#### 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


IIUC the declarative validation code generator is also ongoing work right?

wg-api-expression/charter.md

soltysh · 2025-08-20T12:37:30Z

wg-api-expression/charter.md

+- **Kube API Linter (KAL)**: Automated API convention checker integrated into the review process
+- **Integration strategy**: Cohesive approach for integrating validation-gen, kubebuilder, KAL, and other tools
+- **KEPs**: Series of enhancement proposals introducing and evolving the framework
+- **CRD equivalence strategy**: Plan to bridge the gap between native types and CRDs


What is the gap that you're planning to bridge?

I've updated the text here to explain the gap we are hoping to bridge:

Native Type and CRD Validation Parity: Bridge the gap between how validation is implemented for native Kubernetes types and CRDs to unify the developer experience and improve APIs. This strategy includes:

Establishing a declarative source of truth (eg: Go struct tags) for validation rules that can generate the validation methods needed for native types and the OpenAPI/CEL rules used by CRDs.

Enable easier inheritance of validation logic when a CRD embeds a native type. For example, a CRD that includes a corev1.PodSpec should allow reuse of PodSpec's validation.

wg-api-expression/charter.md

soltysh · 2025-08-20T12:38:32Z

wg-api-expression/charter.md

+
+- **SIG API Machinery**: Owner of API server, gengo, kube-openapi, and validation-gen tool
+- **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


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?

wg-api-expression/charter.md

soltysh · 2025-08-20T12:41:29Z

sigs.yaml

@@ -3602,6 +3602,43 @@ workinggroups:
    liaison:
      github: pacoxu
      name: Paco Xu 徐俊杰
+- dir: wg-api-expression
+  name: API Expression
+  mission_statement: >


I'm inclined to suggest to move certain elements from the attached mission statement into the WG charter.

Co-authored-by: Maciej Szulik <[email protected]>

pohly · 2025-08-21T10:30:21Z

sig-cli/README.md

@@ -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)


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.

pohly · 2025-08-21T10:46:15Z

sigs.yaml

+  mission_statement: >
+    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).


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.

This still holds.

soltysh

The remaining bits are:

several unresolved/unanswered questions
SIG sponsorship

soltysh · 2025-08-27T11:33:45Z

sigs.yaml

+  mission_statement: >
+    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).


This still holds.

soltysh · 2025-08-27T11:34:05Z

sigs.yaml

+    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


soltysh · 2025-08-27T11:37:42Z

wg-api-expression/charter.md

+
+- **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
+- **Integration strategy**: Cohesive approach for integrating validation-gen, kubebuilder, KAL, and other tools


So this is just re-using existing sig-apimachnery sub-project, expanding its functionality with this single feature, do I understand that correctly?

aaron-prindle · 2025-08-27T18:47:50Z

Also curious, is this a permanent problem space like Code Organization Subproject of SIG Arch, or a scoped effort that will conclude? If it's the former a SIG API Machinery Subproject + subproject meeting might be a better fit. If the latter, we need a charter to clarify it.

From the conversations here I believe that SIG API Machinery Subproject + subproject meeting would be a better fit. I will close this proposal for now and work on setting up the SIG API Machinery Subproject + subproject meeting. Thanks for your time.

k8s-ci-robot requested a review from jpbetz June 25, 2025 02:32

k8s-ci-robot added the size/M Denotes a PR that changes 30-99 lines, ignoring generated files. label Jun 25, 2025

aaron-prindle force-pushed the wg-api-expression branch from 1dac944 to 6005bf5 Compare June 25, 2025 02:42

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 25, 2025

aaron-prindle force-pushed the wg-api-expression branch from 6005bf5 to 5a1417a Compare June 25, 2025 02:44

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jun 25, 2025

aaron-prindle force-pushed the wg-api-expression branch 2 times, most recently from d2690f9 to 57bcdc5 Compare June 25, 2025 17:01

BenTheElder reviewed Jul 17, 2025

View reviewed changes

OWNERS_ALIASES Show resolved Hide resolved

k8s-ci-robot added committee/steering Denotes an issue or PR intended to be handled by the steering committee. needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. labels Jul 28, 2025

aaron-prindle force-pushed the wg-api-expression branch from 57bcdc5 to 5fb01df Compare July 29, 2025 23:04

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Jul 29, 2025

aaron-prindle force-pushed the wg-api-expression branch from 5fb01df to 10a3afe Compare July 30, 2025 17:14

BenTheElder reviewed Jul 31, 2025

View reviewed changes

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 5, 2025

aaron-prindle force-pushed the wg-api-expression branch from 10a3afe to 8ce24be Compare August 6, 2025 19:32

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 6, 2025

BenTheElder reviewed Aug 12, 2025

View reviewed changes

aaron-prindle force-pushed the wg-api-expression branch from 8ce24be to 8504677 Compare August 12, 2025 22:04

k8s-ci-robot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/M Denotes a PR that changes 30-99 lines, ignoring generated files. labels Aug 12, 2025

k8s-ci-robot added the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 13, 2025

chore: update sigs.yaml to have entry for wg-api-expression

6cf3a43

aaron-prindle force-pushed the wg-api-expression branch from 8504677 to 6cf3a43 Compare August 13, 2025 16:42

k8s-ci-robot removed the needs-rebase Indicates a PR cannot be merged because it has merge conflicts with HEAD. label Aug 13, 2025

pacoxu reviewed Aug 19, 2025

View reviewed changes

wg-api-expression/charter.md Outdated Show resolved Hide resolved

BenTheElder reviewed Aug 20, 2025

View reviewed changes

soltysh reviewed Aug 20, 2025

View reviewed changes

aaron-prindle and others added 3 commits August 20, 2025 18:30

Update wg-api-expression/charter.md

5f4e6d6

Co-authored-by: Maciej Szulik <[email protected]>

Update wg-api-expression/charter.md

ca3877e

Co-authored-by: Maciej Szulik <[email protected]>

Update wg-api-expression/charter.md

f9d7db7

Co-authored-by: Maciej Szulik <[email protected]>

aaron-prindle force-pushed the wg-api-expression branch from 4f58902 to bb8d470 Compare August 21, 2025 02:42

address feedback - round 1

7443dd5

aaron-prindle force-pushed the wg-api-expression branch from bb8d470 to 7443dd5 Compare August 21, 2025 02:59

pohly reviewed Aug 22, 2025

View reviewed changes

soltysh reviewed Aug 27, 2025

View reviewed changes

aaron-prindle closed this Aug 27, 2025

WG API Expression Proposal #8503

WG API Expression Proposal #8503

Conversation

aaron-prindle commented Jun 25, 2025

Uh oh!

k8s-ci-robot commented Jun 25, 2025

Uh oh!

Uh oh!

soltysh commented Jul 28, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

BenTheElder left a comment

Choose a reason for hiding this comment

Uh oh!

aaron-prindle commented Aug 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

soltysh left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aaron-prindle commented Aug 27, 2025

Uh oh!

Uh oh!

aaron-prindle commented Aug 12, 2025 •

edited

Loading