Merge pull request #25151 from Jefftree/defaults

Add section on Built-in Defaulting

content/en/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definitions.md

@@ -761,6 +761,48 @@ Default values must be pruned (with the exception of defaults for `metadata` fie
 
 Default values for `metadata` fields of `x-kubernetes-embedded-resources: true` nodes (or parts of a default value covering `metadata`) are not pruned during CustomResourceDefinition creation, but through the pruning step during handling of requests.
 
+#### Defaulting and Nullable
+
+**New in 1.20:** null values for fields that either don't specify the nullable flag, or give it a `false` value, will be pruned before defaulting happens. If a default is present, it will be applied. When nullable is `true`, null values will be conserved and won't be defaulted.
+
+For example, given the OpenAPI schema below:
+
+```yaml
+type: object
+properties:
+  spec:
+    type: object
+    properties:
+      foo:
+        type: string
+        nullable: false
+        default: "default"
+      bar:
+        type: string
+        nullable: true
+      baz:
+        type: string
+```
+
+creating an object with null values for `foo` and `bar` and `baz`
+
+```yaml
+spec:
+  foo: null
+  bar: null
+  baz: null
+```
+
+leads to
+
+```yaml
+spec:
+  foo: "default"
+  bar: null
+```
+
+with `foo` pruned and defaulted because the field is non-nullable, `bar` maintaining the null value due to `nullable: true`, and `baz` pruned because the field is non-nullable and has no default.
+
 ### Publish Validation Schema in OpenAPI v2
 
 CustomResourceDefinition [OpenAPI v3 validation schemas](#validation) which are [structural](#specifying-a-structural-schema) and [enable pruning](#field-pruning) are published as part of the [OpenAPI v2 spec](/docs/concepts/overview/kubernetes-api/#openapi-and-swagger-definitions) from Kubernetes API server.