From 78e80acea729f349fbbb8f6d218c29bdfdd87902 Mon Sep 17 00:00:00 2001 From: Jefftree Date: Tue, 31 Aug 2021 19:37:58 -0700 Subject: [PATCH] Address comments --- .../2896-openapi-v3/README.md | 92 ++++--------------- 1 file changed, 19 insertions(+), 73 deletions(-) diff --git a/keps/sig-api-machinery/2896-openapi-v3/README.md b/keps/sig-api-machinery/2896-openapi-v3/README.md index 319b10f8ad2e..ec61387936ab 100644 --- a/keps/sig-api-machinery/2896-openapi-v3/README.md +++ b/keps/sig-api-machinery/2896-openapi-v3/README.md @@ -60,68 +60,41 @@ SIG Architecture for cross-cutting KEPs). --> # KEP-2896: OpenAPI V3 - - - - - [Release Signoff Checklist](#release-signoff-checklist) - [Summary](#summary) - [Motivation](#motivation) - [Goals](#goals) + - [Transparency in the OpenAPI](#transparency-in-the-openapi) - [Non-Goals](#non-goals) - [Proposal](#proposal) - - [User Stories (Optional)](#user-stories-optional) - - [Story 1](#story-1) - - [Story 2](#story-2) - [Notes/Constraints/Caveats (Optional)](#notesconstraintscaveats-optional) + - [Future Work](#future-work) - [Risks and Mitigations](#risks-and-mitigations) - [Design Details](#design-details) + - [Paths](#paths) + - [Controllers](#controllers) + - [OpenAPI Builder](#openapi-builder) + - [Proto Models & ETags](#proto-models--etags) + - [Aggregator](#aggregator) + - [OpenAPI](#openapi) + - [Version Skew](#version-skew) - [Test Plan](#test-plan) - [Graduation Criteria](#graduation-criteria) + - [Alpha](#alpha) + - [Beta](#beta) - [Upgrade / Downgrade Strategy](#upgrade--downgrade-strategy) - [Version Skew Strategy](#version-skew-strategy) - [Production Readiness Review Questionnaire](#production-readiness-review-questionnaire) - [Feature Enablement and Rollback](#feature-enablement-and-rollback) - - [Rollout, Upgrade and Rollback Planning](#rollout-upgrade-and-rollback-planning) - - [Monitoring Requirements](#monitoring-requirements) - - [Dependencies](#dependencies) - [Scalability](#scalability) - - [Troubleshooting](#troubleshooting) - [Implementation History](#implementation-history) - [Drawbacks](#drawbacks) - [Alternatives](#alternatives) -- [Infrastructure Needed (Optional)](#infrastructure-needed-optional) ## Release Signoff Checklist - - Items marked with (R) are required *prior to targeting to a milestone / release*. - [ ] (R) Enhancement issue in release milestone, which links to KEP dir in [kubernetes/enhancements] (not the initial KEP PR) @@ -150,48 +123,16 @@ Items marked with (R) are required *prior to targeting to a milestone / release* ## Summary - - This KEP proposes a new endpoint to publish the [OpenAPI v3 specification](https://swagger.io/specification/) for Kubernetes types. This solves our problem of stripping fields when publishing the OpenAPI v2 and improves the transparency and accuracy of the published OpenAPI. ## Motivation - - Kubernetes resources and types can be described through their OpenAPI definitions, currently served as OpenAPI v2 at the $cluster/openapi/v2 cluster endpoint. With the introduction of CRDs, users provide an OpenAPI v3 spec to describe the resource. Since kubernetes only publishes OpenAPI v2, these definitions are converted into an OpenAPI v2 definition before being aggregated and served at the /openapi/v2 endpoint. OpenAPI v3 is more expressive than v2, and the conversion results in the loss of some information. Some of the type definitions are just transformed into “accept anything” definitions because of our lack of ability to perform a better conversion and limitations in kubectl. Some efforts at improving the OpenAPI (eg: enum support) are targeted to bo bundled with OpenAPI v3. Additionally, since kubernetes aggregate the OpenAPI v2 spec for all specs into one endpoint, whenever a spec is modified the entire spec is updated and all clients will need to redownload the spec. Depending on the size and number of CRDs, this is not an inexpensive operation. ### Goals - - Support publishing and aggregating OpenAPI v3 for all kubernetes types - Published v3 spec should be a lossless representation of the data and no fields should be stripped for both built-in types and CRDs @@ -265,7 +206,7 @@ The overarching `/openapi/v3` endpoint will contain the list of paths (groups) a } ``` -Based on the provided group, clients can then request `openapi/v3/apis/apps`, `/openapi/v3/apis/networking.k8s.io` and etc. These leaf node specs are self contained OpenAPI v3 specs and include all referenced types. +Based on the provided group, clients can then request `openapi/v3/apis/apps/v1`, `/openapi/v3/apis/networking.k8s.io/v1` and etc. These leaf node specs are self contained OpenAPI v3 specs and include all referenced types. ### Controllers @@ -311,6 +252,10 @@ type OpenAPIv3 struct { There is a potential version skew between old aggregated apiservers and a new kube-apiserver. All new aggregated apiservers will publish v3 which will be discovered and published by the aggregator for v3. Old aggregated apiservers will not publish v3, and the aggregator cannot discover the v3 schema for the corresponding aggregated apiservers. The v3 schema for the old apiservers will not be published by the aggregator until they are upgraded to support v3. Regardless of version skew, v2 aggregation will continue for all aggregated apiservers. +It is technically possible for the aggregator handling OpenAPI v3 to download from the OpenAPI v2 schema, but there are a few tradeoffs that I believe make this not worthwhile. The OpenAPI v3 aggregator must publish OpenAPI v3, and OpenAPI v2 will need to be converted if it is intended to be used. The v3 schema is designed to be a lossless representation of a user's spec, but by going through OpenAPI v2, critical information may have already been lost. Publishing an inaccurate v3 schema is not desirable and is not in line with the primary goal of this KEP. Converting from OpenAPI v2 to v3 via the Swagger/OpenAPI structs after publishing is also much more complicated than modifying the OpenAPI generation before publishing. + +By not publishing the v3 spec for old aggregated apiservers, the v3 spec is not a full representation of all the resources and endpoints available within the cluster. However, the scope of this is limited to select group-versions claimed by the select aggregated apiservers. A group-version in v3 will either have a fully lossless OpenAPI v3 or be non-existent (old aggregated apiserver), preventing a partial lossy spec from being published. This should also serve as a good incentive for users to upgrade their aggregated apiservers to the latest version and publish OpenAPI v3. + ### Test Plan -For alpha, unit tests will be included to ensure that v3 schemas are properly generated and published. +For alpha, unit tests will be included to ensure that v3 schemas are properly generated and published. A validator will also be used to ensure that the spec generated is valid OpenAPI v3. ### Graduation Criteria @@ -343,7 +288,8 @@ For alpha, unit tests will be included to ensure that v3 schemas are properly ge #### Beta - Native types are updated to capture capabilities introduced with v3 - +- Definition names of native resources are updated to omit their package paths +- Parameters are reused as components ### Upgrade / Downgrade Strategy