Blog post for OpenAPI and Field Validation

content/en/blog/_posts/2023-xx-xx-openapi-v3-field-validation-ga.md

@@ -0,0 +1,107 @@
+---
+layout: blog
+title: "Server Side Field Validation and OpenAPI V3 move to GA"
+date: 2023-xx-xx
+slug: openapi-v3-field-validation-ga
+---
+
+**Author**: Jeffrey Ying (Google), Antoine Pelisse (Google)
+
+Before Kubernetes v1.8 (!), typos, mis-indentations or minor errors in
+YAMLs could have catastrophic consequences (e.g. a typo like
+forgetting the trailing s in `replica: 1000` could cause an outage,
+because the value would be ignored and missing, forcing a reset of
+replicas back to 1). This was solved back then by fetching the OpenAPI
+v2 in kubectl and using it to verify that fields were correct and
+present before applying. Unfortunately, at that time, Custom Resource
+Definitions didn’t exist, and the code was written under that
+assumption. When CRDs were later introduced, the lack of flexibility
+in the validation code forced some hard decisions in the way CRDs
+exposed their schema, leaving us in a cycle of bad validation causing
+bad OpenAPI and vice-versa. With the new OpenAPI v3 and Server Field
+Validation being GA in 1.27, we’ve now solved both of these problems.
+
+Server Side Field Validation offers resource validation on create,
+update and patch requests to the apiserver and was added to Kubernetes
+in v1.25, beta in v1.26 and is now GA in v1.27. It provides all the
+functionality of kubectl validate on the server side.
+
+[OpenAPI](https://swagger.io/specification/) is a standard, language
+agnostic interface for discovering the set of operations and types
+that a Kubernetes cluster supports. OpenAPI V3 is the latest standard
+of the OpenAPI and is an improvement upon [OpenAPI
+V2](https://kubernetes.io/blog/2016/12/kubernetes-supports-openapi/)
+which has been supported since Kubernetes 1.5. OpenAPI V3 support was
+added in Kubernetes in v1.23, moved to beta in v1.24 and is now GA in
+v1.27.
+
+## OpenAPI V3
+
+### What does OpenAPI V3 offer over V2
+
+#### Built-in types
+
+Kubernetes offers certain annotations on fields that are not
+representable in OpenAPI V2, or sometimes not represented in the
+OpenAPI v2 that Kubernetes generate. Most notably, the "default" field
+is published in OpenAPI V3 while omitted in OpenAPI V2. A single type
+that can represent multiple types is also expressed correctly in
+OpenAPI V3 with the oneOf field. This includes proper representations
+for IntOrString and Quantity.
+
+#### Custom Resource Definitions
+
+In Kubernetes, Custom Resource Definitions use a structural OpenAPI V3
+schema that cannot be represented as OpenAPI V2 without a loss of
+certain fields. Some of these include nullable, default, anyOf, oneOf,
+not, etc. OpenAPI V3 is a completely lossless representation of the
+CustomResourceDefinition structural schema.
+
+### How do I use it?
+
+The OpenAPI V3 root discovery can be found at the `/openapi/v3`
+endpoint of a Kubernetes cluster. OpenAPI V3 documents are grouped by
+group-version to reduce the size of the data transported, the separate
+documents can be accessed at `/openapi/v3/apis/<group>/<version>` and
+`/openapi/v3/api/v1` representing the legacy group version. Please
+refer to the [Kubernetes API
+Documentation](https://kubernetes.io/docs/concepts/overview/kubernetes-api/)
+for more information around this endpoint.
+
+Various consumers of the OpenAPI have already been updated to consume v3, including the entirety of kubectl, and server side apply. An OpenAPI V3 Golang client is available in client-go. Please refer to the [interface](https://github.com/kubernetes/client-go/blob/release-1.27/openapi3/root.go) for details on usage.
+
+## Server Side Field Validation
+
+The query parameter `fieldValidation` may be used to indicate the level of field validation the server should perform. If the parameter is not passed, server side field validation is in Warn mode by default.
+
+- Strict: Strict field validation, errors on validation failure
+- Warn: Field validation is performed, but errors are exposed as warnings rather than failing the request
+- Ignore: No server side field validation is performed
+
+kubectl will skip client side validation and will automatically use server side field validation in strict mode. Controllers by default use server side field validation in warn mode.
+
+With client side validation, we had to be extra lenient because some fields were missing from OpenAPI V2 and we didn’t want to reject possibly valid objects. This is all fixed in server side validation. Additional documentation may be found [here](https://kubernetes.io/docs/reference/using-api/api-concepts/#field-validation)
+
+## What's next?
+
+With Server Side Field Validation and OpenAPI V3 released as GA, we introduce more accurate representations of Kubernetes resources. It is recommended to use server side field validation over client side, but with OpenAPI V3, clients are free to implement their own validation if necessary (to “shift things left”) and we guarantee a full lossless schema published by OpenAPI.
+
+Some existing efforts will further improve the information available through OpenAPI including CEL validation and admission, along with OpenAPI annotations on built-in types.
+
+Many other tools can be built for authoring and transforming resources using the type information found in the OpenAPI v3.
+
+## How to get involved?
+
+These two features are driven by the SIG API Machinery community, available on the slack channel \#sig-api-machinery, through the [mailing list](https://groups.google.com/g/kubernetes-sig-api-machinery) and we meet every other Wednesday at 11:00 AM PT on Zoom.
+
+We offer a huge thanks to all the contributors who helped design,
+implement, and review these two features.
+
+- Alex Zielenski
+- Antoine Pelisse
+- Daniel Smith
+- David Eads
+- Jeffrey Ying
+- Jordan Liggitt
+- Kevin Delgado
+- Sean Sullivan