Skip to content

Latest commit

 

History

History
443 lines (345 loc) · 25.7 KB

cs_versions.md

File metadata and controls

443 lines (345 loc) · 25.7 KB
Raw
copyright lastupdated
years
2014, 2018
2018-09-25

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

Version information and update actions

{: #cs_versions}

Kubernetes version types

{: #version_types}

{{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}

Supported Kubernetes versions:

  • Latest: 1.11.3
  • Default: 1.10.7
  • Other: 1.9.10

Deprecated versions: When clusters are running on a deprecated Kubernetes version, you have 30 days to review and update to a supported Kubernetes version before the version becomes unsupported. During the deprecation period, your cluster is still fully supported. However, you cannot create new clusters that use 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 the cluster to continue receiving important security updates and support.

  • Attention: If you wait until your cluster is three or more minor versions behind a supported version, you must force the update, which might cause unexpected results or failure.
  • Unsupported clusters cannot add or reload existing worker nodes.
  • After you update the cluster to a supported version, your cluster can resume normal operations and continue receiving support.

To check the server version of a cluster, run the following command.

kubectl version  --short | grep -i server

{: pre}

Example output:

Server Version: v1.10.7+IKS

{: screen}

Update types

{: #update_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 Kubernetes patches, as well as other {{site.data.keyword.Bluemix_notm}} Provider component updates such as security and operating system patches. IBM updates masters automatically, but you apply patches to worker nodes.
{: caption="Impacts of Kubernetes updates" caption-side="top"}

As updates become available, you are notified when you view information about the worker nodes, such as with the ibmcloud ks workers <cluster> or ibmcloud ks worker-get <cluster> <worker> commands.

  • Major and minor updates: First, update your master node and then update the worker nodes.
    • By default, you cannot update a Kubernetes master three or more minor versions ahead. For example, if your current master is version 1.7 and you want to update to 1.10, you must update to 1.9 first. You can force the update to continue, but updating more than two minor versions might cause unexpected results or failure.
    • 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.
  • Patch updates: Check monthly to see whether an update is available, and use the ibmcloud ks worker-update command or the ibmcloud ks worker-reload command to apply these security and operating system patches. For more information, see Version changelog.

This 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.


For a complete list of changes, review the following information:


Version 1.11

{: #cs_v111}

This badge indicates Kubernetes version 1.11 certification for IBM Cloud Container Service. {{site.data.keyword.containerlong_notm}} is a Certified Kubernetes product for version 1.11 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.11.

Important: Before you can successfully update a cluster from Kubernetes version 1.9 or earlier to version 1.11, you must follow the steps listed in Preparing to update to Calico v3.

Update before master

{: #111_before}

Changes to make before you update the master to Kubernetes 1.11
Type Description
`containerd` new Kubernetes container runtime Important: `containerd` replaces Docker as the new container runtime for Kubernetes. For actions that you must take, see [Migrating to `containerd` as the container runtime](#containerd).
Kubernetes container volume mount propagation The default value for the [`mountPropagation` field ![External link icon](../icons/launch-glyph.svg "External link icon")](https://kubernetes.io/docs/concepts/storage/volumes/#mount-propagation) for a container `VolumeMount` changed from `HostToContainer` to `None`. This change restores the behavior that existed in Kubernetes version 1.9 and earlier. If your pod specs rely on `HostToContainer` being the default, update them.
Kubernetes API server JSON deserializer The Kubernetes API server JSON deserializer is now case-sensitive. This change restores the behavior that existed in Kubernetes version 1.7 and earlier. If your JSON resource definitions use the incorrect case, update them.

**Note**: Only direct Kubernetes API server requests are impacted. The `kubectl` CLI continued to enforce case-sensitive keys in Kubernetes version 1.7 and later, so if you strictly manage your resources with `kubectl`, you are not impacted.

Update after master

{: #111_after}

Changes to make after you update the master to Kubernetes 1.11
Type Description
Cluster logging configuration The `fluentd` cluster add-on is automatically updated with version 1.11, even when `logging-autoupdate` is disabled.

The container log directory changed from `/var/lib/docker/` to `/var/log/pods/`. If you use your own logging solution that monitors the previous directory, update accordingly.
Refresh Kubernetes configuration The OpenID Connect configuration for the cluster's Kubernetes API server is updated to support {{site.data.keyword.Bluemix_notm}} Identity Access and Management (IAM) access groups. As a result, you must refresh your cluster's Kubernetes configuration after the master Kubernetes v1.11 update by running `ibmcloud ks cluster-config --cluster `.

If you do not refresh the configuration, cluster actions fail with the following error message: `You must be logged in to the server (Unauthorized).`
`kubectl` CLI The `kubectl` CLI for Kubernetes version 1.11 requires the `apps/v1` APIs. As a result, the v1.11 `kubectl` CLI does not work for clusters that run Kubernetes version 1.8 or earlier. Use the version of the `kubectl` CLI that matches the Kubernetes API server version of your cluster.
`kubectl auth can-i` Now, when a user is not authorized, the `kubectl auth can-i` command fails with `exit code 1`. If your scripts rely on the previous behavior, update them.
`kubectl delete` Now, when deleting resources by using selection criteria such as labels, the `kubectl delete` command ignores `not found` errors by default. If your scripts rely on the previous behavior, update them.
Kubernetes `sysctls` feature The `security.alpha.kubernetes.io/sysctls` annotation is now ignored. Instead, Kubernetes added fields to the `PodSecurityPolicy` and `Pod` objects for specifying and controlling `sysctls`. For more information, see [Using sysctls in Kubernetes ![External link icon](../icons/launch-glyph.svg "External link icon")](https://kubernetes.io/docs/tasks/administer-cluster/sysctl-cluster/).

After you update the cluster master and workers, update your `PodSecurityPolicy` and `Pod` objects to use the new `sysctls` fields.

Migrating to containerd as the container runtime

{: #containerd}

For clusters that run Kubernetes version 1.11 or later, containerd replaces Docker as the new container runtime for Kubernetes to enhance performance. If your pods rely on Docker as the Kubernetes container runtime, you must update them to handle containerd as the container runtime. For more information, see the Kubernetes containerd announcement External link icon. {: shortdesc}

How do I know if my apps rely on docker instead of containerd?
Examples of times that you might rely on Docker as the container runtime:

  • If you access the Docker engine or API directly by using privileged containers, update your pods to support containerd as the runtime.
  • Some third-party add-ons, such as logging and monitoring tools, that you install in your cluster might rely on the Docker engine. Check with your provider to make sure the tools are compatible with containerd.

Besides reliance on the runtime, do I need to take other migration actions?

Manifest tool: If you have multi-platform images that are built with the experimental docker manifest tool External link icon before Docker version 18.06, you cannot pull the image from DockerHub by using containerd.

When you check the pod events, you might see an error such as the following.

failed size validation

{: screen}

To use an image that is built by using the manifest tool with containerd, choose from the following options.

  • Rebuild the image with the manifest tool External link icon.
  • Rebuild the image with the docker-manifest tool after you update to Docker version 18.06 or later.

What is not affected? Do I need to change how I deploy my containers?
In general, your container deployment processes do not change. You can still use a Dockerfile to define a Docker image and build a Docker container for your apps. If you use docker commands to build and push images to a registry, you can continue to use docker or use ibmcloud cr commands instead.

Preparing to update to Calico v3

{: #111_calicov3}

Important: If you are updating a cluster from Kubernetes version 1.9 or earlier to version 1.11, prepare for the Calico v3 update before you update the master. During the master upgrade to Kubernetes v1.11, new pods and new Kubernetes or Calico network policies are not scheduled. The amount of time that the update prevents new scheduling varies. Small clusters can take a few minutes, with a few extra minutes for every 10 nodes. Existing network policies and pods continue to run.

Note: If you are updating a cluster from Kubernetes version 1.10 to version 1.11, skip these steps because you completed these steps when you updated to 1.10.

Before you begin, your cluster master and all worker nodes must be running Kubernetes version 1.8 or 1.9, and must have at least one worker node.

  1. Verify that your Calico pods are healthy.

    kubectl get pods -n kube-system -l k8s-app=calico-node -o wide

    {: pre}

  2. If any pod is not in a Running state, delete the pod and wait until it is in a Running state before you continue.

  3. If you auto-generate Calico policies or other Calico resources, update your automation tooling to generate these resources with Calico v3 syntax External link icon.

  4. If you use strongSwan for VPN connectivity, the strongSwan 2.0.0 Helm chart does not work with Calico v3 or Kubernetes 1.11. Update strongSwan to the 2.1.0 Helm chart, which is backward compatible with Calico 2.6, and Kubernetes 1.7, 1.8, and 1.9.

  5. Update your cluster master to Kubernetes v1.11.


Version 1.10

{: #cs_v110}

This badge indicates Kubernetes version 1.10 certification for IBM Cloud Container Service. {{site.data.keyword.containerlong_notm}} is a Certified Kubernetes product for version 1.10 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.10.

Important: Before you can successfully update to Kubernetes 1.10, you must follow the steps listed in Preparing to update to Calico v3.


Update before master

{: #110_before}

Changes to make before you update the master to Kubernetes 1.10
Type Description
Calico v3 Updating to Kubernetes version 1.10 also updates Calico from v2.6.5 to v3.1.1. Important: Before you can successfully update to Kubernetes v1.10, you must follow the steps listed in [Preparing to update to Calico v3](#110_calicov3).
Kubernetes Dashboard network policy In Kubernetes 1.10, the kubernetes-dashboard network policy in the kube-system namespace blocks all pods from accessing the Kubernetes dashboard. However, this does not impact the ability to access the dashboard from the {{site.data.keyword.Bluemix_notm}} console or by using kubectl proxy. If a pod requires access to the dashboard, you can add a kubernetes-dashboard-policy: allow label to a namespace and then deploy the pod to the namespace.
Kubelet API access Kubelet API authorization is now delegated to the Kubernetes API server. Access to the Kubelet API is based on ClusterRoles that grant permission to access node subresources. By default, Kubernetes Heapster has ClusterRole and ClusterRoleBinding. However, if the Kubelet API is used by other users or apps, you must grant them permission to use the API. Refer to the Kubernetes documentation on [Kubelet authorization![External link icon](../icons/launch-glyph.svg "External link icon")](https://kubernetes.io/docs/reference/command-line-tools-reference/kubelet-authentication-authorization/).
Cipher suites The supported cipher suites to the Kubernetes API server and Kubelet API are now restricted to a subset with high strength encryption (128 bits or more). If you have existing automation or resources that use weaker ciphers and rely on communicating with the Kubernetes API server or Kubelet API, enable stronger cipher support before you update the master.
strongSwan VPN If you use [strongSwan](cs_vpn.html#vpn-setup) for VPN connectivity, you must remove the chart before you update the cluster by running `helm delete --purge `. After the cluster update is complete, reinstall the strongSwan Helm chart.

Update after master

{: #110_after}

Changes to make after you update the master to Kubernetes 1.10
Type Description
Calico v3 When the cluster is updated, all existing Calico data that is applied to the cluster is automatically migrated to use Calico v3 syntax. To view, add, or modify Calico resources with Calico v3 syntax, update your [Calico CLI configuration to version 3.1.1](#110_calicov3).
Node ExternalIP address The ExternalIP field of a node is now set to the public IP address value of the node. Review and update any resources that depend on this value.
kubectl port-forward Now when you use the kubectl port-forward command, it no longer supports the -p flag. If your scripts rely on the previous behavior, update them to replace the -p flag with the pod name.
Read-only API data volumes Now `secret`, `configMap`, `downwardAPI`, and projected volumes are mounted read-only. Previously, apps were allowed to write data to these volumes that might be reverted automatically by the system. This migration action is required to fix security vulnerability [CVE-2017-1002102![External link icon](../icons/launch-glyph.svg "External link icon")](https://cve.mitre.org/cgi-bin/cvename.cgi?name=2017-1002102). If your apps rely on the previous insecure behavior, modify them accordingly.
strongSwan VPN If you use [strongSwan](cs_vpn.html#vpn-setup) for VPN connectivity and deleted your chart before updating your cluster, you can now re-install your strongSwan Helm chart.

Preparing to update to Calico v3

{: #110_calicov3}

Before you begin, your cluster master and all worker nodes must be running Kubernetes version 1.8 or later, and must have at least one worker node.

Important: Prepare for the Calico v3 update before you update the master. During the master upgrade to Kubernetes v1.10, new pods and new Kubernetes or Calico network policies are not scheduled. The amount of time that the update prevents new scheduling varies. Small clusters can take a few minutes, with a few extra minutes for every 10 nodes. Existing network policies and pods continue to run.

  1. Verify that your Calico pods are healthy.

    kubectl get pods -n kube-system -l k8s-app=calico-node -o wide

    {: pre}

  2. If any pod is not in a Running state, delete the pod and wait until it is in a Running state before you continue.

  3. If you auto-generate Calico policies or other Calico resources, update your automation tooling to generate these resources with Calico v3 syntax External link icon.

  4. If you use strongSwan for VPN connectivity, the strongSwan 2.0.0 Helm chart does not work with Calico v3 or Kubernetes 1.10. Update strongSwan to the 2.1.0 Helm chart, which is backward compatible with Calico 2.6, and Kubernetes 1.7, 1.8, and 1.9.

  5. Update your cluster master to Kubernetes v1.10.


Version 1.9

{: #cs_v19}

This badge indicates Kubernetes version 1.9 certification for IBM Cloud Container Service. {{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).
Read-only API data volumes Now `secret`, `configMap`, `downwardAPI`, and projected volumes are mounted read-only. Previously, apps were allowed to write data to these volumes that might be reverted automatically by the system. This migration action is required to fix security vulnerability [CVE-2017-1002102](https://cve.mitre.org/cgi-bin/cvename.cgi?name=2017-1002102). If your apps rely on the previous insecure behavior, modify them accordingly.
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.

Archive

{: #k8s_version_archive}

Version 1.8 (Unsupported)

{: #cs_v18}

As of 22 September 2018, {{site.data.keyword.containerlong_notm}} clusters that run Kubernetes version 1.8 are unsupported. Version 1.8 clusters cannot receive security updates or support unless they are updated to the next most recent version (Kubernetes 1.9).

Review potential impact of each Kubernetes version update, and then update your clusters immediately to at least 1.9.

Version 1.7 (Unsupported)

{: #cs_v17}

As of 21 June 2018, {{site.data.keyword.containerlong_notm}} clusters that run Kubernetes version 1.7 are unsupported. Version 1.7 clusters cannot receive security updates or support unless they are updated to the next most recently supported version (Kubernetes 1.9).

Review potential impact of each Kubernetes version update, and then update your clusters immediately to at least 1.9.

Version 1.5 (Unsupported)

{: #cs_v1-5}

As of 4 April 2018, {{site.data.keyword.containerlong_notm}} clusters that run Kubernetes version 1.5 are unsupported. Version 1.5 clusters cannot receive security updates or support.

To continue running your apps in {{site.data.keyword.containerlong_notm}}, create a new cluster and migrate your apps to the cluster.