cs_versions.md

copyright	lastupdated
years 2014, 2018	2018-04-09

{:new_window: target="_blank"} {:shortdesc: .shortdesc} {:screen: .screen} {:pre: .pre} {:table: .aria-labeledby="caption"} {:codeblock: .codeblock} {:tip: .tip} {:download: .download}

Kubernetes versions for {{site.data.keyword.containerlong_notm}}

{: #cs_versions}

{{site.data.keyword.containerlong}} concurrently supports multiple versions of Kubernetes. When a latest version (n) is released, versions up to 2 behind (n-2) are supported. Versions more than 2 behind the latest (n-3) are first deprecated and then unsupported. {:shortdesc}

The current supported Kubernetes versions are:

• Latest: 1.9.3
• Default: 1.8.8
• Supported: 1.7.4

Deprecated Versions: When clusters are running on a deprecated Kubernetes, you have 30 days to review and update to a supported Kubernetes version before the version becomes unsupported. During the deprecation period, you can run limited commands in your clusters to add workers, reload workers, and update the cluster. You cannot create new clusters in the deprecated version.

Unsupported Versions: If you are running clusters on a Kubernetes version that is not supported, review potential impacts for updates and then immediately update your cluster to continue receiving important security updates and support.

To check the server version, run the following command.

kubectl version  --short | grep -i server

{: pre}

Example output:

Server Version: 1.8.8

{: screen}

Update types

{: #version_types}

Your Kubernetes cluster has three types of updates: major, minor, and patch. {:shortdesc}

Update type	Examples of version labels	Updated by	Impact
Major	1.x.x	You	Operation changes for clusters, including scripts or deployments.
Minor	x.9.x	You	Operation changes for clusters, including scripts or deployments.
Patch	x.x.4_1510	IBM and you	Security and operating system patches. IBM updates masters automatically, but you apply patches to worker nodes.
{: caption="Impacts of Kubernetes updates" caption-side="top"}

For major and minor updates, first update your master node and then update the worker nodes. For patch updates, check monthly to see if an update is available, and use the bx cs worker-update command to apply these security and operating system patches. As updates become available, you are notified when you view information about the worker nodes, such as with the bx cs workers <cluster> or bx cs worker-get <cluster> <worker> commands.

By default, you cannot update a Kubernetes master more than two minor versions ahead. For example, if your current master is version 1.5 and you want to update to 1.8, you must update to 1.7 first. You can force the update to continue, but updating more than two minor versions might cause unexpected results. {: tip}

The following information summarizes updates that are likely to have impact on deployed apps when you update a cluster to a new version from the previous version. Review the Kubernetes changelog for a complete list of changes in Kubernetes versions.

If you use a kubectl CLI version that does match at least the major.minor version of your clusters, you might experience unexpected results. Make sure to keep your Kubernetes cluster and CLI versions up-to-date. {:tip}

Version 1.9

{: #cs_v19}

{{site.data.keyword.containerlong_notm}} is a Certified Kubernetes product for version 1.9 under the CNCF Kubernetes Software Conformance Certification program. _Kubernetes® is a registered trademark of The Linux Foundation in the United States and other countries, and is used pursuant to a license from The Linux Foundation._

Review changes that you might need to make when you are updating from the previous Kubernetes version to 1.9.

Update before master

{: #19_before}

Changes to make before you update the master to Kubernetes 1.9

Type	Description
Webhook admission API	The admission API, which is used when the API server calls admission control webhooks, is moved from admission.v1alpha1 to admission.v1beta1. You must delete any existing webhooks before you upgrade your cluster, and update the webhook configuration files to use the latest API. This change is not backward compatible.

Update after master

{: #19_after}

Changes to make after you update the master to Kubernetes 1.9

Type	Description
`kubectl` output	Now, when you use the `kubectl` command to specify `-o custom-columns` and the column is not found in the object, you see an output of ``. Previously, the operation failed and you saw the error message `xxx is not found`. If your scripts rely on the previous behavior, update them.
`kubectl patch`	Now, when no changes are made to the resource that is patched, the `kubectl patch` command fails with `exit code 1`. If your scripts rely on the previous behavior, update them.
Kubernetes dashboard permissions	Users are required to log in to the Kubernetes dashboard with their credentials to view cluster resources. The default Kubernetes dashboard `ClusterRoleBinding` RBAC authorization is removed. For instructions, see [Launching the Kubernetes dashboard](cs_app.html#cli_dashboard).
Taints and tolerations	The `node.alpha.kubernetes.io/notReady` and `node.alpha.kubernetes.io/unreachable` taints were changed to `node.kubernetes.io/not-ready` and `node.kubernetes.io/unreachable` respectively. Although the taints are updated automatically, you must manually update the tolerations for these taints. For each namespace except `ibm-system` and `kube-system`, determine whether you need to change tolerations: kubectl get pods -n <namespace> -o yaml | grep "node.alpha.kubernetes.io/notReady" && echo "Action required" kubectl get pods -n <namespace> -o yaml | grep "node.alpha.kubernetes.io/unreachable" && echo "Action required" If `Action required` is returned, modify the pod tolerations accordingly.
Webhook admission API	If you deleted existing webhooks before you updated the cluster, create new webhooks.

Version 1.8

{: #cs_v18}

{{site.data.keyword.containerlong_notm}} is a Certified Kubernetes product for version 1.8 under the CNCF Kubernetes Software Conformance Certification program. _Kubernetes® is a registered trademark of The Linux Foundation in the United States and other countries, and is used pursuant to a license from The Linux Foundation._

Review changes that you might need to make when you are updating from the previous Kubernetes version to 1.8.

Update before master

{: #18_before}

Changes to make before you update the master to Kubernetes 1.8

Type	Description
None	No changes are required before you update the master

Update after master

{: #18_after}

Changes to make after you update the master to Kubernetes 1.8

Type	Description
Kubernetes dashboard login	The URL for accessing the Kubernetes dashboard in version 1.8 changed, and the login process includes a new authentication step. See [accessing the Kubernetes dashboard](cs_app.html#cli_dashboard) for more information.
Kubernetes dashboard permissions	To force users to log in with their credentials to view cluster resources in version 1.8, remove the 1.7 ClusterRoleBinding RBAC authorization. Run `kubectl delete clusterrolebinding -n kube-system kubernetes-dashboard`.
`kubectl delete`	The `kubectl delete` command no longer scales down workload API objects, like pods, before the object is deleted. If you require the object to scale down, use [`kubectl scale` ](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#scale) before you delete the object.
`kubectl run`	The `kubectl run` command must use multiple flags for `--env` instead of comma-separated arguments. For example, run kubectl run --env <x>=<y> --env <z>=<a> and not kubectl run --env <x>=<y>,<z>=<a>.
`kubectl stop`	The `kubectl stop` command is no longer available.

Version 1.7

{: #cs_v17}

{{site.data.keyword.containerlong_notm}} is a Certified Kubernetes product for version 1.7 under the CNCF Kubernetes Software Conformance Certification program.

Review changes that you might need to make when you are updating from the previous Kubernetes version to 1.7.

Update before master

{: #17_before}

Changes to make before you update the master to Kubernetes 1.7

Type

Description

Storage

Configuration scripts with `hostPath` and `mountPath` with parent directory references like `../to/dir` are not allowed. Change paths to simple absolute paths, for example, `/path/to/dir`. Determine whether you need to change storage paths: ``` kubectl get pods --all-namespaces -o yaml | grep "\.\." && echo "Action required" ``` If `Action required` is returned, change the pods to reference the absolute path before you update all of your worker nodes. If the pod is owned by another resource, such as a deployment, change the [_PodSpec_ ](https://kubernetes.io/docs/api-reference/v1.7/#podspec-v1-core) within that resource.

Update after master

{: #17_after}

Changes to make after you update the master to Kubernetes 1.7

Type	Description
Deployment `apiVersion`	After you update the cluster from Kubernetes 1.5, use `apps/v1beta1` for the `apiVersion` field in new `Deployment` YAML files. Continue to use `extensions/v1beta1` for other resources, such as `Ingress`.
kubectl	After the `kubectl` CLI update, these `kubectl create` commands must use multiple flags instead of comma-separated arguments: `role` `clusterrole` `rolebinding` `clusterrolebinding` `secret` For example, run `kubectl create role --resource-name --resource-name ` and not `kubectl create role --resource-name ,`.
Network Policy	The `net.beta.kubernetes.io/network-policy` annotation is no longer available. Determine whether you need to change policies: ``` kubectl get ns -o yaml | grep "net.beta.kubernetes.io/network-policy" | grep "DefaultDeny" && echo "Action required" ``` If `"Action required"` is returned, add the following network policy to each Kubernetes namespace that was listed: kubectl create -n <namespace> -f - <<EOF kind: NetworkPolicy apiVersion: networking.k8s.io/v1 metadata: name: default-deny namespace: <namespace> spec: podSelector: {} EOF After adding the networking policy, remove the `net.beta.kubernetes.io/network-policy` annotation: ``` kubectl annotate ns --overwrite "net.beta.kubernetes.io/network-policy-" ```
Pod Affinity Scheduling	The `scheduler.alpha.kubernetes.io/affinity` annotation is deprecated. For each namespace except `ibm-system` and `kube-system`, determine whether you need to update pod affinity scheduling: ``` kubectl get pods -n -o yaml | grep "scheduler.alpha.kubernetes.io/affinity" && echo "Action required" ``` If `"Action required"` is returned, use the [_PodSpec_ ](https://kubernetes.io/docs/api-reference/v1.7/#podspec-v1-core) _affinity_ field instead of the `scheduler.alpha.kubernetes.io/affinity` annotation.
RBAC for `default` `ServiceAccount`	The administrator `ClusterRoleBinding` for the `default` `ServiceAccount` in the `default` namespace is removed to improve cluster security. Applications that run in the `default` namespace no longer have cluster administrator privileges to the Kubernetes API, and might encounter `RBAC DENY` permission errors. Check your app and its `.yaml` file to see whether it runs in the `default` namespace, uses the `default ServiceAccount`, and accesses the Kubernetes API. If your applications rely on these privileges, [create RBAC authorization resources](https://kubernetes.io/docs/admin/authorization/rbac/#api-overview) for your apps. As you update your app RBAC policies, you might want to revert temporarily to the previous `default`. Copy, save, and apply the following files with the `kubectl apply -f FILENAME` command. Note: Revert to give yourself time to update all your application resources, and not as a long-term solution. kind: ClusterRoleBinding apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: admin-binding-nonResourceURLSs-default subjects: - kind: ServiceAccount name: default namespace: default roleRef: kind: ClusterRole name: admin-role-nonResourceURLSs apiGroup: rbac.authorization.k8s.io --- kind: ClusterRoleBinding apiVersion: rbac.authorization.k8s.io/v1beta1 metadata: name: admin-binding-resourceURLSs-default subjects: - kind: ServiceAccount name: default namespace: default roleRef: kind: ClusterRole name: admin-role-resourceURLSs apiGroup: rbac.authorization.k8s.io
StatefulSet pod DNS	StatefulSet pods lose their Kubernetes DNS entries after updating the master. To restore the DNS entries, delete the StatefulSet pods. Kubernetes re-creates the pods and automatically restores the DNS entries. For more information, see the [Kubernetes issue ](kubernetes/kubernetes#48327).
Tolerations	The `scheduler.alpha.kubernetes.io/tolerations` annotation is no longer available. For each namespace except `ibm-system` and `kube-system`, determine whether you need to change tolerations: ``` kubectl get pods -n -o yaml | grep "scheduler.alpha.kubernetes.io/tolerations" && echo "Action required" ``` If `"Action required"` is returned, use the [_PodSpec_ ](https://kubernetes.io/docs/api-reference/v1.7/#podspec-v1-core) _tolerations_ field instead of the `scheduler.alpha.kubernetes.io/tolerations` annotation
Taints	The `scheduler.alpha.kubernetes.io/taints` annotation is no longer available. Determine whether you need to change taints: ``` kubectl get nodes -o yaml | grep "scheduler.alpha.kubernetes.io/taints" && echo "Action required" ``` If `"Action required"` is returned, remove the `scheduler.alpha.kubernetes.io/taints` annotation for each node: `kubectl annotate nodes scheduler.alpha.kubernetes.io/taints-` Add a taint to each node: `kubectl taint node `

Archive

{: #k8s_version_archive}

Version 1.5 (Unsupported)

{: #cs_v1-5}

As of 4 April 2018, {{site.data.keyword.containershort_notm}} clusters that run Kubernetes version 1.5 are unsupported. Version 1.5 clusters cannot receive security updates or support unless they are updated to the next most recent version (Kubernetes 1.7).

Review potential impact of each Kubernetes version update, and then update your clusters immediately. Note that you update from one version to the next most recent, such as 1.5 to 1.7 or 1.8 to 1.9.