305-998-7702 | 415-800-2922 info@rx-m.com

Understand API Deprecations

Learn how to put the latest open source technology into practice with hands-on training, delivered by industry experts, aligned to your desired business outcomes

As an ongoing project, new features will move through various stages of maturity as Kubernetes continues to grow. Every feature is served by a new API that is registered to the Kubernetes API server. There are 3 stages of maturity for these APIs:

  • Alpha – These APIs serve features that are highly experimental and not recommended for any production use. Kubernetes includes these Alpha APIs but they must be enabled by setting the appropriate feature gate on the API server. Alpha APIs can either move to beta status or get removed depending on how well the feature is received and used.
  • Beta – These APIs serve features that are still in highly active development but considered ready for production use. Beta APIs and features are enabled by default. Depending on their development cycles, Beta APIs can move up through multiple versions between Kubernetes releases or regress back to Alpha for further development.
  • Stable – These APIs are highly mature and do not see too many changes between versions. Stable APIs are enabled by default. At this point, stable APIs can only be retired if their feature is no longer necessary or if a new version of the API supplants its use.

You can view all of the APIs registered with your Kubernetes API server using the kubectl api-versions command:

$ kubectl api-versions

admissionregistration.k8s.io/v1
apiextensions.k8s.io/v1
apiregistration.k8s.io/v1
apps/v1
authentication.k8s.io/v1
authorization.k8s.io/v1
autoscaling/v1
autoscaling/v2
autoscaling/v2beta1
autoscaling/v2beta2

...

$

API deprecations are a major event in the Kubernetes development cycle and come with many announcements. After a deprecation announcement, the affected features and/or APIs that get deprecated will:

  • Begin generating warnings in the CLI when invoked or submitted to the Kubernetes API server
  • Have their functionality disabled while continuing to generate warnings
  • Eventually get removed from the codebase all together, usually within 2-3 releases
$ kubectl run -o yaml --dry-run=client pod-with-reqs-limits --requests cpu=64m,memory=256Mi --limits cpu=256m,memory=512Mi --image nginx

Flag --requests has been deprecated, has no effect and will be removed in 1.24.
Flag --limits has been deprecated, has no effect and will be removed in 1.24.
apiVersion: v1
kind: Pod
metadata:
  creationTimestamp: null
  labels:
    run: pod-with-reqs-limits
  name: pod-with-reqs-limits
spec:
  containers:
  - image: nginx
    name: pod-with-reqs-limits
    resources: {}
  dnsPolicy: ClusterFirst
  restartPolicy: Always
status: {}

$

For existing manifests, the apiVersion line must be changed to a non-deprecated API version. This can be done with kubectl-convert, an optional kubectl plugin that examines older manifests and updates them to reflect the latest API versions.

The kubectl-convert plugin must be installed separate, with instructions found here.

$ curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl-convert"

$ sudo install -o root -g root -m 0755 kubectl-convert /usr/local/bin/kubectl-convert

$

Given the following file, which describes a deployment from v1.16 (when deployments were under the old extensions API):

$ cat old-deploy.yaml

apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: old-deploy
spec:
  replicas: 3
  selector:
    matchLabels:
      app: old-deploy
  template:
    metadata:
      labels:
        app: old-deploy
    spec:
      containers:
      - image: nginx
        name: nginx

$

kubectl-convert can read the file and automatically make the necessary changes to update it to the latest api (apps/v1 in 1.23):

$ kubectl-convert -f old-deploy.yaml --output-version apps/v1

apiVersion: apps/v1
kind: Deployment
metadata:
  creationTimestamp: null
  labels:
    app: old-deploy
  name: old-deploy
spec:
  progressDeadlineSeconds: 2147483647
  replicas: 3
  revisionHistoryLimit: 2147483647
  selector:
    matchLabels:
      app: old-deploy
  strategy:
    rollingUpdate:
      maxSurge: 1
      maxUnavailable: 1
    type: RollingUpdate
  template:
    metadata:
      creationTimestamp: null
      labels:
        app: old-deploy
    spec:
      containers:
      - image: nginx
        imagePullPolicy: Always
        name: nginx
        resources: {}
        terminationMessagePath: /dev/termination-log
        terminationMessagePolicy: File
      dnsPolicy: ClusterFirst
      restartPolicy: Always
      schedulerName: default-scheduler
      securityContext: {}
      terminationGracePeriodSeconds: 30
status: {}

$

There are usually about 2-3 minor versions between a deprecation notice and the removal of a feature, so users typically have at least 6 months.

Learn more about and keep track of the API Deprecation process and how to use kubectl-convert.