|
| 1 | +# WG API Expression Charter |
| 2 | + |
| 3 | +This charter adheres to the conventions described in the [Kubernetes Charter README] and uses |
| 4 | +the Roles and Organization Management outlined in [sig-governance]. |
| 5 | + |
| 6 | +## Scope |
| 7 | + |
| 8 | +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. |
| 9 | + |
| 10 | +### In scope |
| 11 | + |
| 12 | +#### Code, Binaries and Services |
| 13 | + |
| 14 | +- Declarative validation code generator (validation-gen) that generates Go validation code from declarative tags in API type definitions |
| 15 | +- Kube API Linter (KAL) for checking API types against Kubernetes API Conventions and best practices |
| 16 | +- Integration frameworks between declarative tools (validation-gen, kubebuilder, KAL, and other API tools) |
| 17 | +- Libraries and components for type discovery and declarative API expression that can be reused across code generators |
| 18 | +- Tools and processes for generating CEL or OpenAPI validation rules from declarative tags |
| 19 | +- Documentation generation tools that create API documentation from declarative expressions |
| 20 | + |
| 21 | +#### Cross-cutting and Externally Facing Processes |
| 22 | + |
| 23 | +- Development and maintenance of KEPs for declarative API expression features (eg: KEP-5073 Declarative Validation) |
| 24 | +- Migration strategies and guides for SIGs to adopt the declarative framework |
| 25 | +- Establishing patterns for ratcheting, validation, defaulting, and immutability expressed declaratively |
| 26 | +- Ensuring consistency between Kubernetes native types and CRD validation experiences |
| 27 | +- Automated API quality checks and linting processes integrated into the standard API review workflow |
| 28 | + |
| 29 | +### Out of scope |
| 30 | + |
| 31 | +- General API design decisions unrelated to declarative expression |
| 32 | +- Runtime validation logic that cannot be expressed declaratively |
| 33 | + |
| 34 | +## Deliverables |
| 35 | + |
| 36 | +The working group will deliver: |
| 37 | + |
| 38 | +- **validation-gen code generator**: Core tool for generating Go validation code from declarative tags |
| 39 | +- **Kube API Linter (KAL)**: Automated API convention checker integrated into the review process |
| 40 | +- **Integration strategy**: Cohesive approach for integrating validation-gen, kubebuilder, KAL, and other tools |
| 41 | +- **KEPs**: Series of enhancement proposals introducing and evolving the framework |
| 42 | +- **CRD equivalence strategy**: Plan to bridge the gap between native types and CRDs |
| 43 | +- **Documentation generation strategy**: Automated documentation from declarative API expressions |
| 44 | +- **Migration guides**: Documentation for SIGs to adopt the framework and migrate existing APIs |
| 45 | + |
| 46 | +## Stakeholders |
| 47 | + |
| 48 | +- **SIG API Machinery**: Owner of API server, gengo, kube-openapi, and validation-gen tool |
| 49 | +- **SIG Architecture**: Owner of Kubernetes API conventions and architectural decisions |
| 50 | +- **SIG CLI**: Consumer of more expressive APIs, providing feedback on kubectl interaction and user experience |
| 51 | + |
| 52 | +## Roles and Organization Management |
| 53 | + |
| 54 | +This sig adheres to the Roles and Organization Management outlined in [sig-governance] |
| 55 | +and opts-in to updates and modifications to [sig-governance]. |
| 56 | + |
| 57 | +### Meeting Mechanics |
| 58 | + |
| 59 | +- **Frequency**: Bi-weekly (every 2 weeks) |
| 60 | +- **Duration**: 60 minutes |
| 61 | +- **Communication**: |
| 62 | + - Slack: #wg-api-expression |
| 63 | + |
| 64 | + |
| 65 | +### Chairs |
| 66 | + |
| 67 | +- Aaron Prindle (@aaron-prindle) |
| 68 | +- Joel Speed (@JoelSpeed) |
| 69 | + |
| 70 | +## Exit Criteria |
| 71 | + |
| 72 | +The working group will have fulfilled its charter and can be disbanded when: |
| 73 | + |
| 74 | +1. The core framework, including validation-gen and associated libraries, is stable and integrated into the main Kubernetes development workflow |
| 75 | +2. Foundational KEPs (e.g., Declarative Validation) are implemented and graduated to GA |
| 76 | +3. Kube API Linter (KAL) is mature, widely adopted, and integrated into the standard API development and review process |
| 77 | +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 |
| 78 | +5. Ongoing maintenance of the framework has been successfully transitioned to owner SIGs, primarily SIG API Machinery |
| 79 | + |
| 80 | +[sig-governance]: https://github.com/kubernetes/community/blob/master/committee-steering/governance/sig-governance.md |
| 81 | +[sig-subprojects]: https://github.com/kubernetes/community/blob/master/sig-YOURSIG/README.md#subprojects |
| 82 | +[Kubernetes Charter README]: https://github.com/kubernetes/community/blob/master/committee-steering/governance/README.md |
0 commit comments