From 2f56f12a7d67c06f8e64edabdaef6c96a99ba5af Mon Sep 17 00:00:00 2001 From: Jennifer Rondeau Date: Thu, 28 Sep 2017 13:24:56 -0700 Subject: [PATCH] add draft workloads api content for 1.8 (#5650) * add draft workloads api content for 1.8 * edits per review, add tables, for 1.8 workloads api doc * fix typo --- _data/reference.yml | 1 + docs/reference/workloads-18-19.md | 261 ++++++++++++++++++++++++++++++ 2 files changed, 262 insertions(+) create mode 100644 docs/reference/workloads-18-19.md diff --git a/_data/reference.yml b/_data/reference.yml index cb8812844bd08..fa403d8e44fbf 100644 --- a/_data/reference.yml +++ b/_data/reference.yml @@ -23,6 +23,7 @@ toc: - docs/admin/authorization/node.md - docs/admin/authorization/webhook.md - docs/reference/deprecation-policy.md + - docs/reference/workloads-18-19.md - title: API Reference section: diff --git a/docs/reference/workloads-18-19.md b/docs/reference/workloads-18-19.md new file mode 100644 index 0000000000000..e57b95adb2217 --- /dev/null +++ b/docs/reference/workloads-18-19.md @@ -0,0 +1,261 @@ +--- +title: Workloads API changes in versions 1.8 and 1.9 +approvers: +- steveperry-53 +- kow3ns +--- + +## Overview + +The Kubernetes core Workloads API includes the Deployment, DaemonSet, ReplicaSet, and StatefulSet kinds. To provide a stable API for users to orchestrate their workloads, we are prioritizing promoting these kinds to GA. The batch Workloads API (Job and CronJob), while also important, is not part of this effort, and it will have a separate path to GA stability. + +- In the 1.8 release, we introduce the apps/v1beta2 API group and version. This beta version of the core Workloads API contains the Deployment, DaemonSet, ReplicaSet, and StatefulSet kinds, and it is the version we plan to promote to GA in the 1.9 release provided the feedback is positive. + +- In the 1.9 release, we plan to introduce the apps/v1 group version. We intend to promote the apps/v1beta2 group version in its entirety to apps/v1 and to deprecate apps/v1beta2 at that time. + +- We realize that even after the release of apps/v1, users will need time to migrate their code from extensions/v1beta1, apps/v1beta1, and apps/v1beta2. It is important to remember that the minimum support durations listed in the deprecations guidelines are minimums. We will continue to support conversion between groups and versions until users have had sufficient time to migrate. + +## Migration + +This section contains information to assist users in migrating core Workloads API kinds between group versions. + +### General + +- If you are using kinds from the extensions/v1beta1 or apps/v1beta1 group versions, you can wait to migrate existing code until after the release of the apps/v1 group version. + +- If your deployment requires features that are available in the apps/v1beta2 group version, you can migrate to this group version before the apps/v1 release. + +- You should develop all new code against the latest stable release. + +- You can run `kubectl convert` to convert manifests between group versions. + +### Migrating to apps/v1beta2 + +This section provides information on migrating to the apps/v1beta2 group version. It covers general changes to the core Workloads API kinds. For changes that affect a specific kind (for example, default values), consult the reference documentation for the kind. + +#### Default selectors are deprecated + +In earlier versions of the apps and extensions groups, the spec.selectors of the core Workloads API kinds were, when left unspecified, defaulted to a LabelSelector generated from the spec.template.metadata.labels. + +User feedback led us to determine that, as it is incompatible with strategic merge patch and kubectl apply, defaulting the value of a field from the value of another field of the same object is an anti-pattern. + +#### Immutable selectors + +We have always cautioned users against selector mutation. The core Workloads API controller does not, in the general case, handle selector mutation gracefully. + +To provide a consistent, usable, and stable API, selectors are immutable for all kinds in the apps/v1beta2 group and version. + +We believe that there are better ways to support features like promotable canaries and orchestrated Pod relabeling, but if restricted selector mutation is a necessary feature for our users, we can relax immutability before GA without breaking backward compatibility. + +The development of features like promotable canaries, orchestrated Pod relabeling, and restricted selector mutability is driven by demand signals from our users. If you are currently modifying the selectors of your core Workloads API objects, please tell us about your use case in a GitHub issue or by participating in SIG-apps. + +#### Default rolling updates + +Before apps/v1beta2, some kinds defaulted the spec.updateStrategy to a strategy other than RollingUpdate. For example, apps/v1beta1 StatefulSet specifies OnDelete by default. In apps/v1beta2 the spec.updateStrategy for all kinds defaults to RollingUpdate. + +#### Created-by annotation is deprecated + +"kubernetes.io/created-by" is deprecated in version 1.8. Instead, you should specify an object’s ControllerRef from its ownerReferences to determine object ownership. + +## Timeline + +This section details the timeline for promotion and deprecation of kinds in the core Workloads API. + +### Release 1.8 + +In Kubernetes 1.8, we unify the core Workloads API kinds in a single group and version. We address consistency, usability, and stability issues across the API surface. We have deprecated portions of the apps/v1beta1 group version and the extension/v1beta1 group version and replaced them with the apps/v1beta2 group version. The table below shows the kinds that are deprecated and the kinds that replace them. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DeprecatedReplaced By
GroupVersionKindGroupVersionKind
appsv1beta1Deploymentappsv1beta2Deployment
appsv1beta1ReplicaSetappsv1beta2ReplicaSet
appsv1beta1StatefulSetappsv1beta2StatefulSet
extensionsv1beta1Deploymentappsv1beta2Deployment
extensionsv1beta1DaemonSetappsv1beta2DaemonSet
extensionsv1beta1StatefulSetappsv1beta2StatefulSet
+ +### Release 1.9 + +In Kubernetes 1.9, our goal is to address any feedback on the apps/v1beta2 group version and to promote the group version to GA. The table below shows the kinds that we plan to deprecate and the kinds that will replace them. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
DeprecatedReplaced By
GroupVersionKindGroupVersionKind
appsv1beta2Deploymentappsv1Deployment
appsv1beta2DaemonSetappsv1DaemonSet
appsv1beta2ReplicaSetappsv1StatefulSet
appsv1beta2StatefulSetappsv1StatefulSet
+ +### Post 1.9 + +Because users will continue to depend on extensions/v1beta1, apps/v1beta1, and apps/v1beta2, we will not completely remove deprecated kinds in these group versions upon GA promotion. Instead, we will provide auto-conversion between the deprecated portions of the API surface and the GA version. The table below shows the bidirectional conversion that we will support. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
GAPrevious
GroupVersionKindGroupVersionKind
appsv1Deploymentappsv1beta1Deployment
appsv1beta2Deployment
extensionsv1beta1Deployment
appsv1Daemonsetappsv1beta2DaemonSet
extensionsv1beta1DaemonSet
appsv1ReplicaSetappsv1beta1ReplicaSet
appsv1beta2ReplicaSet
extensionsv1beta1ReplicaSet
appsv1StatefulSetappsv1beta1StatefulSet
appsv1beta2StatefulSet
\ No newline at end of file