CR webhook conversion documentation

content/en/docs/tasks/access-kubernetes-api/custom-resources/custom-resource-definition-versioning.md

@@ -11,13 +11,7 @@ weight: 30
 {{% capture overview %}}
 This page explains how to add versioning information to
 [CustomResourceDefinitions](/docs/reference/generated/kubernetes-api/{{< param "version" >}}/#customresourcedefinition-v1beta1-apiextensions), to indicate the stability
-level of your CustomResourceDefinitions. It also describes how to upgrade an
-object from one version to another.
-
-{{< note >}}
-**Note**: All specified versions must use the same schema. The is no schema
-conversion between versions.
-{{< /note >}}
+level of your CustomResourceDefinitions or advance your API to a new version with conversion between API representations. It also describes how to upgrade an object from one version to another.
 
 {{% /capture %}}
 
@@ -36,10 +30,10 @@ conversion between versions.
 ## Overview
 
 The CustomResourceDefinition API supports a `versions` field that you can use to
-support multiple versions of custom resources that you have developed, and
-indicate the stability of a given custom resource. All versions must currently
-use the same schema, so if you need to add a field, you must add it to all
-versions.
+support multiple versions of custom resources that you have developed. Versions
+can have different schemas with a conversion webhook to convert custom resources between versions.
+Webhook conversions should follow the [Kubernetes API conventions](https://github.com/kubernetes/community/blob/master/contributors/devel/api-conventions.md) wherever applicable.
+Specifically, See the [API change documentation](https://github.com/kubernetes/community/blob/master/contributors/devel/api_changes.md) for a set of useful gotchas and suggestions.
 
 {{< note >}}
 Earlier iterations included a `version` field instead of `versions`. The
@@ -49,8 +43,9 @@ match the first item in the `versions` field.
 
 ## Specify multiple versions
 
-This example shows a CustomResourceDefinition with two versions. The comments in
-the YAML provide more context.
+This example shows a CustomResourceDefinition with two versions. For the first
+example, the assumption is all versions share the same schema with no conversion
+between them. The comments in the YAML provide more context.
 
 ```yaml
 apiVersion: apiextensions.k8s.io/v1beta1
@@ -71,6 +66,12 @@ spec:
   - name: v1
     served: true
     storage: false
+  # The conversion section is introduced in Kubernetes 1.13+ with a default value of
+  # None conversion (strategy sub-field set to None).
+  conversion:
+    # None conversion assumes the same schema for all versions and only sets the apiVersion
+    # field of custom resources to the proper value
+    strategy: None
   # either Namespaced or Cluster
   scope: Namespaced
   names:
@@ -144,6 +145,132 @@ version sort order is `v1`, followed by `v1beta1`. This causes the kubectl
 command to use `v1` as the default version unless the provided object specifies
 the version.
 
+## Webhook conversion
+
+{{< note >}}
+Webhook conversion is introduced in Kubernetes 1.13 as an alpha feature. To use it, the
+`CustomResourceWebhookConversion` feature should be enabled. Please refer to the [feature gate](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/) documentation for more information.
+{{< /note >}}
+
+The above example has a None conversion between versions which only sets the `apiVersion` field
+on conversion and does not change the rest of the object. The API server also supports webhook
+conversions that call an external service in case a conversion is required. For example when:
+
+* custom resource is requested in a different version than stored version.
+* Watch is created in one version but the changed object is stored in another version.
+* custom resource PUT request is in a different version than storage version.
+
+To cover all of these cases and to optimize conversion by the API server, the conversion requests may contain multiple objects in order to minimize the external calls. The webhook should perform these conversions independently.
+
+### Write a conversion webhook server
+
+Please refer to the implementation of the [custom resource conversion webhook
+server](https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/main.go)
+that is validated in a Kubernetes e2e test. The webhook handles the
+`ConversionReview` requests sent by the API servers, and sends back conversion
+results wrapped in `ConversionResponse`. Note that the request
+contains a list of custom resources that need to be converted independently without
+changing the order of objects.
+The example server is organized in a way to be reused for other conversions. Most of the common code are located in the [framework file]((https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/converter/framework.go)) that leaves only [one function]((https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/converter/example-converter.go#L29-L80)) to be implemented for different conversions.
+
+{{< note >}}
+The example conversion webhook server leaves the `ClientAuth` field
+[empty](https://github.com/kubernetes/kubernetes/tree/v1.13.0/test/images/crd-conversion-webhook/config.go#L47-L48),
+which defaults to `NoClientCert`. This means that the webhook server does not
+authenticate the identity of the clients, supposedly API servers. If you need
+mutual TLS or other ways to authenticate the clients, see
+how to [authenticate API servers](/docs/reference/access-authn-authz/extensible-admission-controllers/#authenticate-apiservers).
+{{< /note >}}
+
+### Deploy the conversion webhook service
+
+Documentation for deploying the conversion webhook is the same as for the [admission webhook example service](/docs/reference/access-authn-authz/extensible-admission-controllers/#deploy_the_admission_webhook_service).
+The assumption for next sections is that the conversion webhook server is deployed to a service named `example-conversion-webhook-server` in `default` namespace.
+
+{{< note >}}
+When the webhook server is deployed into the Kubernetes cluster as a
+service, it has to be exposed via a service on port 443 (The server
+itself can have an arbitrary port but the service object should map it to port 443).
+The communication between the API server and the webhook service may fail
+if a different port is used for the service.
+{{< /note >}}
+
+### Configure CustomResourceDefinition to use conversion webhooks
+
+The `None` conversion example can be extended to use the conversion webhook by modifying `conversion`
+section of the `spec`:
+
+```yaml
+apiVersion: apiextensions.k8s.io/v1beta1
+kind: CustomResourceDefinition
+metadata:
+  # name must match the spec fields below, and be in the form: <plural>.<group>
+  name: crontabs.example.com
+spec:
+  # group name to use for REST API: /apis/<group>/<version>
+  group: example.com
+  # list of versions supported by this CustomResourceDefinition
+  versions:
+  - name: v1beta1
+    # Each version can be enabled/disabled by Served flag.
+    served: true
+    # One and only one version must be marked as the storage version.
+    storage: true
+    # Each version can define it's own schema when there is no top-level
+    # schema is defined.
+    schema:
+      openAPIV3Schema:
+        properties:
+          hostPort:
+            type: string
+  - name: v1
+    served: true
+    storage: false
+    schema:
+      openAPIV3Schema:
+        properties:
+          host:
+            type: string
+          port:
+            type: string
+  conversion:
+    # a Webhook strategy instruct API server to call an external webhook for any conversion between custom resources.
+    strategy: Webhook
+    # webhookClientConfig is required when strategy is `Webhook` and it configure the webhook endpoint to be
+    # called by API server.
+    webhookClientConfig:
+      service:
+        namespace: default
+        name: example-conversion-webhook-server
+      caBundle: <pem encoded ca cert that signs the server cert used by the webhook>
+  # either Namespaced or Cluster
+  scope: Namespaced
+  names:
+    # plural name to be used in the URL: /apis/<group>/<version>/<plural>
+    plural: crontabs
+    # singular name to be used as an alias on the CLI and for display
+    singular: crontab
+    # kind is normally the CamelCased singular type. Your resource manifests use this.
+    kind: CronTab
+    # shortNames allow shorter string to match your resource on the CLI
+    shortNames:
+    - ct
+```
+
+{{< note >}}
+When using `clientConfig.service`, the server cert must be valid for
+`<svc_name>.<svc_namespace>.svc`.
+{{< /note >}}
+
+You can save the CustomResourceDefinition in a YAML file, then use
+`kubectl apply` to apply it.
+
+```shell
+kubectl apply -f my-versioned-crontab-with-conversion.yaml
+```
+
+Make sure the conversion service is up and running before applying new changes.
+
 ## Writing, reading, and updating versioned CustomResourceDefinition objects
 
 When an object is written, it is persisted at the version designated as the