|
1 | 1 | # KEP-5073: Declarative Validation of Kubernetes Native Types With validation-gen |
2 | 2 | <!-- toc --> |
3 | | -- [KEP-5073: Declarative Validation of Kubernetes Native Types With validation-gen](#kep-5073-declarative-validation-of-kubernetes-native-types-with-validation-gen) |
4 | | - - [Summary](#summary) |
5 | | - - [Motivation](#motivation) |
6 | | - - [Goals](#goals) |
7 | | - - [Non-Goals](#non-goals) |
8 | | - - [Proposal](#proposal) |
9 | | - - [Overview](#overview) |
10 | | - - [Introduce <code>validation-gen</code>](#introduce-validation-gen) |
11 | | - - [<code>validation-gen</code> Has No Plans To Use CEL Validation Directly](#validation-gen-has-no-plans-to-use-cel-validation-directly) |
12 | | - - [IDL Tag Authoring DevEx and User Error Messaging](#idl-tag-authoring-devex-and-user-error-messaging) |
13 | | - - [Introduce new validation tests and test framework](#introduce-new-validation-tests-and-test-framework) |
14 | | - - [New Validations Vs Migrating Validations](#new-validations-vs-migrating-validations) |
15 | | - - [New Validation Tests](#new-validation-tests) |
16 | | - - [Ensuring Validation Equivalence With Testing](#ensuring-validation-equivalence-with-testing) |
17 | | - - [Introduce Feature Gates: <code>DeclarativeValidation</code> & <code>DeclarativeValidationMismatchMetrics</code>](#introduce-feature-gates-declarativevalidation--declarativevalidationmismatchmetrics) |
18 | | - - [<code>DeclarativeValidation</code> & <code>DeclarativeValidationMismatchMetrics</code> Will Target Beta From The Beginning](#declarativevalidation--declarativevalidationmismatchmetrics-will-target-beta-from-the-beginning) |
19 | | - - [Linter](#linter) |
20 | | - - [Documentation Generation](#documentation-generation) |
21 | | - - [Analysis of existing validation rules](#analysis-of-existing-validation-rules) |
22 | | - - [User Stories (Optional)](#user-stories-optional) |
23 | | - - [Kubernetes developer wishes to add a field to an existing API version](#kubernetes-developer-wishes-to-add-a-field-to-an-existing-api-version) |
24 | | - - [Kubernetes developer adds a new version (v1beta2) of an API](#kubernetes-developer-adds-a-new-version-v1beta2-of-an-api) |
25 | | - - [Kubernetes Developer Using an Aggregated API and/or KRM Server Is Adding a New Field To Their Custom API Type](#kubernetes-developer-using-an-aggregated-api-andor-krm-server-is-adding-a-new-field-to-their-custom--api-type) |
26 | | - - [Kubernetes API reviewer is reviewing API changes for a PR for a new Kubernetes Native Type](#kubernetes-api-reviewer-is-reviewing-api-changes-for-a-pr-for-a-new-kubernetes-native-type) |
27 | | - - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional) |
28 | | - - [Risks and Mitigations](#risks-and-mitigations) |
29 | | - - [Risk: The Migration Project Loses Steam And Work Is Abandoned](#risk-the-migration-project-loses-steam-and-work-is-abandoned) |
30 | | - - [Mitigation: Roll Back All Migrated Fields](#mitigation-roll-back-all-migrated-fields) |
31 | | - - [Risk: we get hundreds of PRs from people migrating fields and can't review them all.](#risk-we-get-hundreds-of-prs-from-people-migrating-fields-and-cant-review-them-all) |
32 | | - - [Mitigation: These are not urgent and we will have patterns which can be reviewed by more people.](#mitigation-these-are-not-urgent-and-we-will-have-patterns-which-can-be-reviewed-by-more-people) |
33 | | - - [Risk: Versioned validation drifts between versions.](#risk-versioned-validation-drifts-between-versions) |
34 | | - - [Mitigation: round-trip testing + fuzzing + equivalence tests + linting.](#mitigation-round-trip-testing--fuzzing--equivalence-tests--linting) |
35 | | - - [Risk: Migration to Declarative Validation introduces breaking change to API validation](#risk-migration-to-declarative-validation-introduces-breaking-change-to-api-validation) |
36 | | - - [Mitigation: Ensure Invalid Objects Still Invalid](#mitigation-ensure-invalid-objects-still-invalid) |
37 | | - - [Mitigation: Ensure Valid Old Objects Still Valid](#mitigation-ensure-valid-old-objects-still-valid) |
38 | | - - [Risk: Added latency to API request handling.](#risk-added-latency-to-api-request-handling) |
39 | | - - [Mitigation: Resolve Known "Low Hanging Fruit" of Performance Improvements In Current Validation Code](#mitigation-resolve-known-low-hanging-fruit-of-performance-improvements-in-current-validation-code) |
40 | | - - [Mitigation: Avoid Conversion to Internal Type](#mitigation-avoid-conversion-to-internal-type) |
41 | | - - [Design Details](#design-details) |
42 | | - - [Summary of Declarative Validation Components](#summary-of-declarative-validation-components) |
43 | | - - [<code>validation-gen</code> Implementation Plan](#validation-gen-implementation-plan) |
44 | | - - [Catalog of Supported Validation Rules & Associated IDL Tags](#catalog-of-supported-validation-rules--associated-idl-tags) |
45 | | - - [Supporting Declarative Validation IDL tags On Shared Struct Fields](#supporting-declarative-validation-idl-tags-on-shared-struct-fields) |
46 | | - - [<code>subfield</code> IDL Tag](#subfield-idl-tag) |
47 | | - - [<code>validation-gen</code> One-deep typedef Issue And Solution](#validation-gen-one-deep-typedef-issue-and-solution) |
48 | | - - [Solution](#solution) |
49 | | - - [Migration Plan](#migration-plan) |
50 | | - - [Phase1: Initialization (Responsibility of Contributors Implementing the KEP)](#phase1-initialization-responsibility-of-contributors-implementing-the-kep) |
51 | | - - [Phase2: Scaling the Migration (Responsibility of Contributors Implementing the KEP and broader community)](#phase2-scaling-the-migration-responsibility-of-contributors-implementing-the-kep-and-broader-community) |
52 | | - - [Phase3: Finalization and GA (Core Team and community)](#phase3-finalization-and-ga-core-team-and-community) |
53 | | - - [Tagging and Validating Against Versioned Types](#tagging-and-validating-against-versioned-types) |
54 | | - - [Handling Zero Values in Declarative Validation](#handling-zero-values-in-declarative-validation) |
55 | | - - [Difficulties with <code>+k8s:required</code> and <code>+k8s:default</code>](#difficulties-with-k8srequired-and-k8sdefault) |
56 | | - - [Proposed Solutions](#proposed-solutions) |
57 | | - - [Addressing the Problem with Valid Zero Values Using the Linter](#addressing-the-problem-with-valid-zero-values-using-the-linter) |
58 | | - - [Ratcheting](#ratcheting) |
59 | | - - [Test Plan](#test-plan) |
60 | | - - [Prerequisite testing updates](#prerequisite-testing-updates) |
61 | | - - [Unit tests](#unit-tests) |
62 | | - - [Runtime verification testing](#runtime-verification-testing) |
63 | | - - [Integration tests](#integration-tests) |
64 | | - - [e2e tests](#e2e-tests) |
65 | | - - [Graduation Criteria](#graduation-criteria) |
66 | | - - [Beta](#beta) |
67 | | - - [DeclarativeValidation](#declarativevalidation) |
68 | | - - [GA](#ga) |
69 | | - - [DeclarativeValidation](#declarativevalidation-1) |
70 | | - - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) |
71 | | - - [Version Skew Strategy](#version-skew-strategy) |
72 | | - - [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire) |
73 | | - - [Feature Enablement and Rollback](#feature-enablement-and-rollback) |
74 | | - - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning) |
75 | | - - [Monitoring Requirements](#monitoring-requirements) |
76 | | - - [Dependencies](#dependencies) |
77 | | - - [Scalability](#scalability) |
78 | | - - [Troubleshooting](#troubleshooting) |
79 | | - - [Implementation History](#implementation-history) |
80 | | - - [Drawbacks](#drawbacks) |
81 | | - - [Alternatives](#alternatives) |
82 | | - - [Use CEL and OpenAPI libraries directly for K8s Native Types (<a href="https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/4153-declarative-validation">KEP-4153</a>)](#use-cel-and-openapi-libraries-directly-for-k8s-native-types-kep-4153) |
83 | | - - [Infrastructure Needed (Optional)](#infrastructure-needed-optional) |
84 | | - - [Future Work](#future-work) |
85 | | - - ["New K8s Native APIs" Design Partner For Declarative Validation in 1.34](#new-k8s-native-apis-design-partner-for-declarative-validation-in-134) |
| 3 | +- [Release Signoff Checklist](#release-signoff-checklist) |
| 4 | +- [Summary](#summary) |
| 5 | +- [Motivation](#motivation) |
| 6 | + - [Goals](#goals) |
| 7 | + - [Non-Goals](#non-goals) |
| 8 | +- [Proposal](#proposal) |
| 9 | + - [Overview](#overview) |
| 10 | + - [Introduce <code>validation-gen</code>](#introduce-validation-gen) |
| 11 | + - [<code>validation-gen</code> Has No Plans To Use CEL Validation Directly](#validation-gen-has-no-plans-to-use-cel-validation-directly) |
| 12 | + - [IDL Tag Authoring DevEx and User Error Messaging](#idl-tag-authoring-devex-and-user-error-messaging) |
| 13 | + - [Introduce new validation tests and test framework](#introduce-new-validation-tests-and-test-framework) |
| 14 | + - [New Validations Vs Migrating Validations](#new-validations-vs-migrating-validations) |
| 15 | + - [New Validation Tests](#new-validation-tests) |
| 16 | + - [Ensuring Validation Equivalence With Testing](#ensuring-validation-equivalence-with-testing) |
| 17 | + - [Introduce Feature Gates: <code>DeclarativeValidation</code> & <code>DeclarativeValidationMismatchMetrics</code>](#introduce-feature-gates-declarativevalidation--declarativevalidationmismatchmetrics) |
| 18 | + - [<code>DeclarativeValidation</code> & <code>DeclarativeValidationMismatchMetrics</code> Will Target Beta From The Beginning](#declarativevalidation--declarativevalidationmismatchmetrics-will-target-beta-from-the-beginning) |
| 19 | + - [Linter](#linter) |
| 20 | + - [Documentation Generation](#documentation-generation) |
| 21 | +- [Analysis of existing validation rules](#analysis-of-existing-validation-rules) |
| 22 | + - [User Stories (Optional)](#user-stories-optional) |
| 23 | + - [Kubernetes developer wishes to add a field to an existing API version](#kubernetes-developer-wishes-to-add-a-field-to-an-existing-api-version) |
| 24 | + - [Kubernetes developer adds a new version (v1beta2) of an API](#kubernetes-developer-adds-a-new-version-v1beta2-of-an-api) |
| 25 | + - [Kubernetes Developer Using an Aggregated API and/or KRM Server Is Adding a New Field To Their Custom API Type](#kubernetes-developer-using-an-aggregated-api-andor-krm-server-is-adding-a-new-field-to-their-custom--api-type) |
| 26 | + - [Kubernetes API reviewer is reviewing API changes for a PR for a new Kubernetes Native Type](#kubernetes-api-reviewer-is-reviewing-api-changes-for-a-pr-for-a-new-kubernetes-native-type) |
| 27 | + - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional) |
| 28 | + - [Risks and Mitigations](#risks-and-mitigations) |
| 29 | + - [Risk: The Migration Project Loses Steam And Work Is Abandoned](#risk-the-migration-project-loses-steam-and-work-is-abandoned) |
| 30 | + - [Mitigation: Roll Back All Migrated Fields](#mitigation-roll-back-all-migrated-fields) |
| 31 | + - [Risk: we get hundreds of PRs from people migrating fields and can't review them all.](#risk-we-get-hundreds-of-prs-from-people-migrating-fields-and-cant-review-them-all) |
| 32 | + - [Mitigation: These are not urgent and we will have patterns which can be reviewed by more people.](#mitigation-these-are-not-urgent-and-we-will-have-patterns-which-can-be-reviewed-by-more-people) |
| 33 | + - [Risk: Versioned validation drifts between versions.](#risk-versioned-validation-drifts-between-versions) |
| 34 | + - [Mitigation: round-trip testing + fuzzing + equivalence tests + linting.](#mitigation-round-trip-testing--fuzzing--equivalence-tests--linting) |
| 35 | + - [Risk: Migration to Declarative Validation introduces breaking change to API validation](#risk-migration-to-declarative-validation-introduces-breaking-change-to-api-validation) |
| 36 | + - [Mitigation: Ensure Invalid Objects Still Invalid](#mitigation-ensure-invalid-objects-still-invalid) |
| 37 | + - [Mitigation: Ensure Valid Old Objects Still Valid](#mitigation-ensure-valid-old-objects-still-valid) |
| 38 | + - [Risk: Added latency to API request handling.](#risk-added-latency-to-api-request-handling) |
| 39 | + - [Mitigation: Resolve Known "Low Hanging Fruit" of Performance Improvements In Current Validation Code](#mitigation-resolve-known-low-hanging-fruit-of-performance-improvements-in-current-validation-code) |
| 40 | + - [Mitigation: Avoid Conversion to Internal Type](#mitigation-avoid-conversion-to-internal-type) |
| 41 | +- [Design Details](#design-details) |
| 42 | + - [Summary of Declarative Validation Components](#summary-of-declarative-validation-components) |
| 43 | + - [<code>validation-gen</code> Implementation Plan](#validation-gen-implementation-plan) |
| 44 | + - [Catalog of Supported Validation Rules & Associated IDL Tags](#catalog-of-supported-validation-rules--associated-idl-tags) |
| 45 | + - [Supporting Declarative Validation IDL tags On Shared Struct Fields](#supporting-declarative-validation-idl-tags-on-shared-struct-fields) |
| 46 | + - [<code>subfield</code> IDL Tag](#subfield-idl-tag) |
| 47 | + - [<code>validation-gen</code> One-deep typedef Issue And Solution](#validation-gen-one-deep-typedef-issue-and-solution) |
| 48 | + - [Solution](#solution) |
| 49 | + - [Migration Plan](#migration-plan) |
| 50 | + - [Phase1: Initialization (Responsibility of Contributors Implementing the KEP)](#phase1-initialization-responsibility-of-contributors-implementing-the-kep) |
| 51 | + - [Phase2: Scaling the Migration (Responsibility of Contributors Implementing the KEP and broader community)](#phase2-scaling-the-migration-responsibility-of-contributors-implementing-the-kep-and-broader-community) |
| 52 | + - [Phase3: Finalization and GA (Core Team and community)](#phase3-finalization-and-ga-core-team-and-community) |
| 53 | + - [Tagging and Validating Against Versioned Types](#tagging-and-validating-against-versioned-types) |
| 54 | + - [Handling Zero Values in Declarative Validation](#handling-zero-values-in-declarative-validation) |
| 55 | + - [Difficulties with <code>+k8s:required</code> and <code>+k8s:default</code>](#difficulties-with-k8srequired-and-k8sdefault) |
| 56 | + - [Proposed Solutions](#proposed-solutions) |
| 57 | + - [Addressing the Problem with Valid Zero Values Using the Linter](#addressing-the-problem-with-valid-zero-values-using-the-linter) |
| 58 | + - [Ratcheting](#ratcheting) |
| 59 | + - [Test Plan](#test-plan) |
| 60 | + - [Prerequisite testing updates](#prerequisite-testing-updates) |
| 61 | + - [Unit tests](#unit-tests) |
| 62 | + - [Runtime verification testing](#runtime-verification-testing) |
| 63 | + - [Integration tests](#integration-tests) |
| 64 | + - [e2e tests](#e2e-tests) |
| 65 | + - [Graduation Criteria](#graduation-criteria) |
| 66 | + - [Beta](#beta) |
| 67 | + - [DeclarativeValidation](#declarativevalidation) |
| 68 | + - [GA](#ga) |
| 69 | + - [DeclarativeValidation](#declarativevalidation-1) |
| 70 | + - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) |
| 71 | + - [Version Skew Strategy](#version-skew-strategy) |
| 72 | +- [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire) |
| 73 | + - [Feature Enablement and Rollback](#feature-enablement-and-rollback) |
| 74 | + - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning) |
| 75 | + - [Monitoring Requirements](#monitoring-requirements) |
| 76 | + - [Dependencies](#dependencies) |
| 77 | + - [Scalability](#scalability) |
| 78 | + - [Troubleshooting](#troubleshooting) |
| 79 | +- [Implementation History](#implementation-history) |
| 80 | +- [Drawbacks](#drawbacks) |
| 81 | +- [Alternatives](#alternatives) |
| 82 | + - [Use CEL and OpenAPI libraries directly for K8s Native Types (<a href="https://github.com/kubernetes/enhancements/tree/master/keps/sig-api-machinery/4153-declarative-validation">KEP-4153</a>)](#use-cel-and-openapi-libraries-directly-for-k8s-native-types-kep-4153) |
| 83 | +- [Infrastructure Needed (Optional)](#infrastructure-needed-optional) |
| 84 | +- [Future Work](#future-work) |
| 85 | + - ["New K8s Native APIs" Design Partner For Declarative Validation in 1.34](#new-k8s-native-apis-design-partner-for-declarative-validation-in-134) |
86 | 86 | <!-- /toc --> |
87 | 87 |
|
88 | | -# KEP-5073: Declarative Validation of Kubernetes Native Types With validation-gen |
| 88 | + |
| 89 | +## Release Signoff Checklist |
| 90 | + |
| 91 | +<!-- |
| 92 | +**ACTION REQUIRED:** In order to merge code into a release, there must be an |
| 93 | +issue in [kubernetes/enhancements] referencing this KEP and targeting a release |
| 94 | +milestone **before the [Enhancement Freeze](https://git.k8s.io/sig-release/releases) |
| 95 | +of the targeted release**. |
| 96 | +
|
| 97 | +For enhancements that make changes to code or processes/procedures in core |
| 98 | +Kubernetes—i.e., [kubernetes/kubernetes], we require the following Release |
| 99 | +Signoff checklist to be completed. |
| 100 | +
|
| 101 | +Check these off as they are completed for the Release Team to track. These |
| 102 | +checklist items _must_ be updated for the enhancement to be released. |
| 103 | +--> |
| 104 | + |
| 105 | +Items marked with (R) are required *prior to targeting to a milestone / release*. |
| 106 | + |
| 107 | +- [x] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR) |
| 108 | +- [x] (R) KEP approvers have approved the KEP status as `implementable` |
| 109 | +- [x] (R) Design details are appropriately documented |
| 110 | +- [x] (R) Test plan is in place, giving consideration to SIG Architecture and SIG Testing input (including test refactors) |
| 111 | + - [ ] e2e Tests for all Beta API Operations (endpoints) |
| 112 | + - [ ] (R) Ensure GA e2e tests meet requirements for [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md) |
| 113 | + - [ ] (R) Minimum Two Week Window for GA e2e tests to prove flake free |
| 114 | +- [x] (R) Graduation criteria is in place |
| 115 | + - [ ] (R) [all GA Endpoints](https://github.com/kubernetes/community/pull/1806) must be hit by [Conformance Tests](https://github.com/kubernetes/community/blob/master/contributors/devel/sig-architecture/conformance-tests.md) |
| 116 | +- [x] (R) Production readiness review completed |
| 117 | +- [x] (R) Production readiness review approved |
| 118 | +- [ ] "Implementation History" section is up-to-date for milestone |
| 119 | +- [x] User-facing documentation has been created in [kubernetes/website], for publication to [kubernetes.io] |
| 120 | +- [ ] Supporting documentation—e.g., additional design documents, links to mailing list discussions/SIG meetings, relevant PRs/issues, release notes |
| 121 | + |
| 122 | +<!-- |
| 123 | +**Note:** This checklist is iterative and should be reviewed and updated every time this enhancement is being considered for a milestone. |
| 124 | +--> |
89 | 125 |
|
90 | 126 | ## Summary |
91 | 127 |
|
|
0 commit comments