Introduction to Upgrading Clusters

When new versions of OpenShift Origin are released, you can upgrade your existing cluster to apply the latest enhancements and bug fixes. For OpenShift Origin, see the Releases page on GitHub to review the latest changes.

Unless noted otherwise, node and masters within a major version are forward and backward compatible across one minor version, so upgrading your cluster should go smoothly. However, you should not run mismatched versions longer than necessary to upgrade the entire cluster.

Before upgrading, ensure that all OpenShift Origin services are running well. Do not upgrade OpenShift Origin directly if first upgrade attempt failed. You must first downgrade.

The OpenShift Origin 3.9 release includes a merge of features and fixes from Kubernetes 1.8 and 1.9. As a result, the upgrade process from OpenShift Origin 3.7 completes with the cluster fully upgraded to OpenShift Origin 3.9, seemingly "skipping" the 3.8 release. Technically, the OpenShift Origin 3.7 cluster is first upgraded to 3.8-versioned packages, and then the process immediately continues upgrading to OpenShift Origin 3.9 automatically. Your cluster should only remain at 3.8-versioned packages for as long as it takes to successfully complete the upgrade to OpenShift Origin 3.9.

Upgrade Methods

There are two methods available for performing OpenShift Origin cluster upgrades: automated or manual.

Automated Method

The automated upgrade method uses Ansible playbooks to automate the tasks needed to upgrade a OpenShift Origin cluster. You should use the inventory file that you used during initial installation or during the last time that the upgrade was successful to run the upgrade playbook. Using this method allows you to choose between either upgrade strategy: in-place upgrades or blue-green deployments.

Manual Method

The manual upgrade method breaks down the steps that happen during an automated Ansible-based upgrade and provides the equivalent commands to run manually. Using this method describes the in-place upgrade strategy.

Upgrade Strategies

When using the automated upgrade method, there are two strategies you can take for performing the OpenShift Origin cluster upgrade: in-place upgrades or blue-green delpoyments. When using the manual upgrade method, an in-place upgrade is described.

In-place Upgrades

With in-place upgrades, the cluster upgrade is performed on all hosts in a single, running cluster: first masters and then nodes. Pods are evacuated off of nodes and recreated on other running nodes before a node upgrade begins; this helps reduce downtime of user applications.

If you installed using the advanced installation and the ~/.config/openshift/installer.cfg.yml or inventory file that was used is available, you can perform an automated in-place upgrade. Alternatively, you can upgrade in-place manually.

Quick Installation is now deprecated in OpenShift Origin 3.9 and will be completely removed in a future release.

Quick installation will only be capable of installing 3.9. It will not be able to upgrade from 3.7 or 3.8 to 3.9.

Blue-green Deployments

The blue-green deployment upgrade method follows a similar flow to the in-place method: masters and etcd servers are still upgraded first, however a parallel environment is created for new nodes instead of upgrading them in-place.

This method allows administrators to switch traffic from the old set of nodes (e.g., the "blue" deployment) to the new set (e.g., the "green" deployment) after the new deployment has been verified. If a problem is detected, it is also then easy to rollback to the old deployment quickly.