Reference Documentation

Design docs, concept definitions, and references for APIs and CLIs.

Edit This Page

Workloads API changes in versions 1.8 and 1.9

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.

Migration

This section contains information to assist users in migrating core Workloads API kinds between group versions.

General

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.

Deprecated Replaced By
Group Version Kind Group Version Kind
apps v1beta1 Deployment apps v1beta2 Deployment
apps v1beta1 ReplicaSet apps v1beta2 ReplicaSet
apps v1beta1 StatefulSet apps v1beta2 StatefulSet
extensions v1beta1 Deployment apps v1beta2 Deployment
extensions v1beta1 DaemonSet apps v1beta2 DaemonSet
extensions v1beta1 StatefulSet apps v1beta2 StatefulSet

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.

Deprecated Replaced By
Group Version Kind Group Version Kind
apps v1beta2 Deployment apps v1 Deployment
apps v1beta2 DaemonSet apps v1 DaemonSet
apps v1beta2 ReplicaSet apps v1 StatefulSet
apps v1beta2 StatefulSet apps v1 StatefulSet

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.

GA Previous
Group Version Kind Group Version Kind
apps v1 Deployment apps v1beta1 Deployment
apps v1beta2 Deployment
extensions v1beta1 Deployment
apps v1 Daemonset apps v1beta2 DaemonSet
extensions v1beta1 DaemonSet
apps v1 ReplicaSet apps v1beta1 ReplicaSet
apps v1beta2 ReplicaSet
extensions v1beta1 ReplicaSet
apps v1 StatefulSet apps v1beta1 StatefulSet
apps v1beta2 StatefulSet

Analytics

Create an Issue Edit this Page