Official 1.13 Release Docs (#11401)

* Update metadata.generation behaviour for custom resources (#10705) * update docs promoting plugins to beta (#10796) * docs update to promote TaintBasedEvictions to beta (#10765) * First Korean l10n work for dev-1.13 (#10719) * Update outdated l10n(ko) contents (#10689) fixes #10686 * Translate concepts/overview/what-is-kubernetes in Korean (#10690) * Translate concepts/overview/what-is-kubernetes in Korean * Feedback from ClaudiaJKang * Translate concepts/overview/components in Korean (#10882) * Translate concepts/overview/components in Korean #10717 * Translate concepts/overview/components in Korean * Translate concepts/overview/components in Korean * Apply Korean glossary: 서비스 어카운트 * Translate concepts/overview/kubernetes-api in Korean (#10773) * Translate concepts/overview/kubernetes-api in Korean * Applied feedback from ianychoi * kubeadm: update the configuration docs to v1beta1 (#10959) * kubeadm: add small v1beta1 related updates (#10988) * ADD content/zh/docs/reference/setup-tools/kubeadm/kubeadm.md (#11031) * ADD content/zh/docs/reference/setup-tools/kubeadm/kubeadm.md * ADD content/zh/docs/reference/setup-tools/kubeadm/generated/kubeadm_init.md * Update content/zh/docs/reference/setup-tools/kubeadm/kubeadm.md Accepted Co-Authored-By: YouthLab <tsui@highyouth.com> * do not change 'master' or 'worker' nodes to '主从' * Doc updates for volume scheduling GA (#10743) * Doc updates for volume scheduling GA * Make trivial change to kick build * Document nodelease feature (#10699) * advanced audit doc for ModeBlockingStrict (#10203) * Rename EncryptionConfig to EncryptionConfiguration (#11080) EncryptionConfig was renamed to EncryptedConfiguration and added to the `apiserver.config.k8s.io` API group in Kubernetes 1.13. The feature was previously in alpha and was not handling versions properly, which lead to an originally unnoticed `v1` in the docs. * content/zh/docs/reference/setup-tools/kubeadm/kubeadm-init.md * trsanlate create-cluster-kubeadm.md to chinese (#11041) * trsanlate create-cluster-kubeadm.md to chinese * Update create-cluster-kubeadm.md * update the feature stage in v1.13 (#11307) * update new feature gates to document (#11295) * refresh controller role list on rbac description page (#11290) * node labeling restriction docs (#10944) * Update 1.13 docs for CSI GA (#10893) * dynamic audit documentation (#9947) * adds dynamic audit documentation * Copyedit for clarity See also inline question/s * Fix feature state shortcode * Update feature state * changes wording for dynamic audit flag behavior * Minor copyedit * fix dynamic audit yaml * adds api enablement command to dynamic audit docs * change ordering dynamic audit appears in * add references to dynamic audit in webhook backend * reword dynamic audit reference * updates stages field for audit sink object * changes audit sink api definition; rewords policy * kubeadm: remove kube-proxy workaround (#11162) * zh-trans content/en/docs/setup/independent/install-kubeadm.md (#11338) * zh-trans content/en/docs/setup/independent/install-kubeadm.md * Update install-kubeadm.md * Update dry run feature to beta (#11140) * vSphere volume raw block support doc update (#10932) * Add docs for Windows DNS configurations (#10036) * Update docs for fields allowed at root of CRD schema (#9973) * Add docs for Windows DNS configurations * add device monitoring documentation (#9945) * kubeadm: adds upgrade instructions for 1.13 (#11138) * kubeadm: adds upgrade instructions for 1.13 Signed-off-by: Chuck Ha <ha.chuck@gmail.com> * add minor copyedits Addressed a couple of copyedit comments a bit more cleanly. * kubeadm: add improvements to HA docs (#11094) * kubeadm: add information and diagrams for HA topologies * kubeadm: update HA doc with simplified steps * kubeadm: update HA doc with simplified steps * edit ha, add new topology topic, reorder by weight * troubleshoot markdown * fix more markdown, fix links * more markdown * more markdown * more markdown * changes after reviewer comments * add steps about Weave * update note about stacked topology * kubeadm external etcd HA upgrade 1.13 (#11364) * kubeadm external etcd HA upgrade 1.13 Signed-off-by: Ruben Orduz <rubenoz@gmail.com> * Update stacked controlplane steps * kubeadm cert documentation (#11093) * kubeadm certificate API and CSR documentation * copyedits * fix typo * PR for diff docs (#10789) * Empty commit against dev-1.13 for diff documentation * Complete Declarative maangement with diff commands * Second Korean l10n work for dev-1.13. (#11030) * Update outdated l10n(ko) contents (#10915) * Translate main menu for l10n(ko) docs (#10916) * Translate tasks/run-application/horizontal-pod-autoscale-walkthrough (#10980) * Translate content/ko/docs/concepts/overview/working-with-objects/kubernetes-object in Korean #11104 (#11332) * Pick-right-solution page translates into Korean. (#11340) * ko-trans: add jd/..., sap/..., ebay/..., homeoffice/... (#11336) * Translate concept/workloads/pods/pod-overview.md (#11092) Co-authored-by: June Yi <june.yi@samsung.com> Co-authored-by: Jesang Myung <jesang.myung@gmail.com> Co-authored-by: zerobig <38598117+zer0big@users.noreply.github.com> Co-authored-by: Claudia J.Kang <claudiajkang@gmail.com> Co-authored-by: lIuDuI <1693291525@qq.com> Co-authored-by: Woojin Na(Eddie) <cheapluv@gmail.com> * Rename encryption-at-rest related objects (#11059) EncryptionConfig was renamed to EncryptedConfiguration and added to the `apiserver.config.k8s.io` API group in Kubernetes 1.13. The feature was previously in alpha and was not handling versions properly, which lead to an originally unnoticed `v1` in the docs. Also, the `--experimental-encryption-provider-config` flag is now called just `--encryption-provider-config`. * Documenting FlexVolume Resize alpha feature. (#10097) * CR webhook conversion documentation (#10986) * CR Conversion * Addressing comments * Addressing more comments * Addressing even more comments * Addressing even^2 more comments * Remove references to etcd2 in v1.13 since support has been removed (#11414) * Remove etcd2 references as etcd2 is deprecated Link back to the v1.12 version of the etcd3 doc for the etcd2->etcd3 migration instructions. I updated the kube-apiserver reference manually, unsure if that is auto-generated somehow. The federation-apiserver can still potentially support etcd2 so I didn't touch that. * Remove outdated {master,node}.yaml files There are master/node yaml files that reference etcd2.service that are likely highly out of date. I couldn't find any docs that actually reference these templates so I removed them * Address review comments * Final Korean l10n work for dev-1.13 (#11440) * Update outdated l10n(ko) contents (#11425) fixes #11424 * Remove references to etcd2 in content/ko (#11416) * Resolve conflicts against master for /ko contents (#11438) * Fix unopened caution shortcode * kubeadm: update the reference docs for 1.13 (#10960) * docs update to promote TaintBasedEvictions to beta (#10765) * First Korean l10n work for dev-1.13 (#10719) * Update outdated l10n(ko) contents (#10689) fixes #10686 * Translate concepts/overview/what-is-kubernetes in Korean (#10690) * Translate concepts/overview/what-is-kubernetes in Korean * Feedback from ClaudiaJKang * Translate concepts/overview/components in Korean (#10882) * Translate concepts/overview/components in Korean #10717 * Translate concepts/overview/components in Korean * Translate concepts/overview/components in Korean * Apply Korean glossary: 서비스 어카운트 * Translate concepts/overview/kubernetes-api in Korean (#10773) * Translate concepts/overview/kubernetes-api in Korean * Applied feedback from ianychoi * kubeadm: update the configuration docs to v1beta1 (#10959) * kubeadm: add small v1beta1 related updates (#10988) * update new feature gates to document (#11295) * Update dry run feature to beta (#11140) * kubeadm: add improvements to HA docs (#11094) * kubeadm: add information and diagrams for HA topologies * kubeadm: update HA doc with simplified steps * kubeadm: update HA doc with simplified steps * edit ha, add new topology topic, reorder by weight * troubleshoot markdown * fix more markdown, fix links * more markdown * more markdown * more markdown * changes after reviewer comments * add steps about Weave * update note about stacked topology * kubeadm: update reference docs - add section about working with phases under kubeadm-init.md - update GA / beta status of features - kubeadm alpha phase was moved to kubeadm init phase - new commands were added under kubeadm alpha - included new CoreDNS usage examples * Generate components and tools reference * Add generated federation API Reference (#11491) * Add generated federation API Reference * Add front matter to federation reference * Remove whitespace from federation front matter * Remove more whitespace from federation front matter * Remove superfluous kubefed reference * Add frontmatter to generated kubefed reference * Fix kubefed reference page frontmatter * Generate kubectl reference docs 1.13 (#11487) * Generate kubectl reference docs 1.13 * Fix links in kubectl reference * Add 1.13 API reference (#11489) * Update config.toml (#11486) * Update config.toml Preparing for 1.13 release, updating the config.toml and dropping the 1.8 docs reference. * update dot releases and docsbranch typo * adding .Site. to Params.currentUrl (#11503) see https://github.com/kubernetes/website/pull/11502 for context * Add 1.13 Release notes (#11499)
2018-12-03 19:21:11 -06:00
parent b1dde5578c
commit 27b7b453a9
347 changed files with 69250 additions and 4447 deletions
@@ -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 >}}
-All specified versions must use the same schema. There 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 @@ 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
@@ -146,10 +146,8 @@ items:
 - apiVersion: stable.example.com/v1
  kind: CronTab
  metadata:
-    clusterName: ""
    creationTimestamp: 2017-05-31T12:56:35Z
-    deletionGracePeriodSeconds: null
-    deletionTimestamp: null
+    generation: 1
    name: my-new-cron-object
    namespace: default
    resourceVersion: "285"
@@ -175,7 +173,7 @@ kubectl get crontabs
 ```

 ```console
-Error from server (NotFound): Unable to list "crontabs": the server could not find the requested resource (get crontabs.stable.example.com)
+Error from server (NotFound): Unable to list {"stable.example.com" "v1" "crontabs"}: the server could not find the requested resource (get crontabs.stable.example.com)
 ```

 If you later recreate the same CustomResourceDefinition, it will start out empty.
@@ -470,7 +468,7 @@ When the status subresource is enabled, the `/status` subresource for the custom
 - `PUT` requests to the `/status` subresource take a custom resource object and ignore changes to anything except the status stanza.
 - `PUT` requests to the `/status` subresource only validate the status stanza of the custom resource.
 - `PUT`/`POST`/`PATCH` requests to the custom resource ignore changes to the status stanza.
- Any changes to the spec stanza increments the value at `.metadata.generation`.
+- The `.metadata.generation` value is incremented for all changes, except for changes to `.metadata` or `.status`.
 - Only the following constructs are allowed at the root of the CRD OpenAPI validation schema:

  - Description