Manual In-place Upgrades - Upgrading a Cluster | Installation and Configuration

Overview
Preparing for a Manual Upgrade
Upgrading Master Components
Updating Policy Definitions
Upgrading Nodes
Upgrading the Router
Upgrading the Registry
- Updating Custom Registry Configuration Files
- Enforcing quota in the Registry
Updating the Default Image Streams and Templates
Importing the Latest Images
Upgrading the EFK Logging Stack
Upgrading Cluster Metrics
Additional Manual Steps Per Release
Verifying the Upgrade

Overview

As an alternative to performing an automated upgrade, you can manually upgrade your OpenShift cluster. To manually upgrade without disruption, it is important to upgrade each component as documented in this topic.

Before you begin your upgrade, familiarize yourself now with the entire procedure. Specific releases may require additional steps to be performed at key points before or during the standard upgrade process.

Ensure that you have met all prerequisites before proceeding with an upgrade. Failure to do so can result in a failed upgrade.

Preparing for a Manual Upgrade

Before upgrading your cluster to OpenShift Container Platform 3.3, the cluster must be already upgraded to the latest asynchronous release of version 3.2. Cluster upgrades cannot span more than one minor version at a time, so if your cluster is at version 3.0 or 3.1, you must first upgrade incrementally (e.g., 3.0 to 3.1, then 3.1 or 3.2).

To prepare for a manual upgrade, follow these steps:

If you are upgrading from version 3.2 to 3.3, manually disable the 3.2 channel and enable the 3.3 channel on each host:

# subscription-manager repos --disable="rhel-7-server-ose-3.2-rpms" \
    --enable="rhel-7-server-ose-3.3-rpms" \
    --enable="rhel-7-server-extras-rpms"

On RHEL 7 systems, also clear the yum cache:

# yum clean all

Install or update to the latest available version of the atomic-openshift-utils package on each RHEL 7 system, which provides files that will be used in later sections:
```
# yum install atomic-openshift-utils
```
Install or update to the following latest available *-excluder packages on each RHEL 7 system, which helps ensure your systems stay on the correct versions of atomic-openshift and docker packages when you are not trying to upgrade, according to the OpenShift Container Platform version:
```
# yum install atomic-openshift-excluder atomic-openshift-docker-excluder
```
These packages add entries to the exclude directive in the host’s /etc/yum.conf file.

Create an etcd backup on each master. The etcd package is required, even if using embedded etcd, for access to the etcdctl command to make the backup. The package is installed by default for RHEL Atomic Host 7 systems. If the master is a RHEL 7 system, ensure the package is installed:

# yum install etcd

Then, create the backup:

# ETCD_DATA_DIR=/var/lib/origin/openshift.local.etcd (1)
# etcdctl backup \
    --data-dir $ETCD_DATA_DIR \
    --backup-dir $ETCD_DATA_DIR.bak.<date> (2)

1	This directory is for embedded etcd. If you use a separate etcd cluster, use */var/lib/etcd* instead.
2	Use the date of the backup, or some unique identifier, for `<date>`. The command will not make a backup if the `--backup-dir` location already exists.

For any upgrade path, ensure that you are running the latest kernel on each RHEL 7 system:
```
# yum update kernel
```

Upgrading Master Components

Upgrade your master hosts first:

Run the following command on each master to remove the atomic-openshift packages from the list of yum excludes on the host:
```
# atomic-openshift-excluder unexclude
```
Upgrade the atomic-openshift packages or related images.
1. For masters using the RPM-based method on a RHEL 7 system, upgrade all installed atomic-openshift packages:
  # yum upgrade atomic-openshift\*
2. For masters using the containerized method on a RHEL 7 or RHEL Atomic Host 7 system, set the IMAGE_VERSION parameter to the version you are upgrading to in the following files:
  - /etc/sysconfig/atomic-openshift-master (single master clusters only)
  - /etc/sysconfig/atomic-openshift-master-controllers (multi-master clusters only)
  - /etc/sysconfig/atomic-openshift-master-api (multi-master clusters only)
  - /etc/sysconfig/atomic-openshift-node
  - /etc/sysconfig/atomic-openshift-openvswitch
    
    For example:
    
    IMAGE_VERSION=<tag>
    
    Replace <tag> with v3.3 for the latest version.

In OpenShift Container Platform 3.3, protocol buffers are used by default for internal communications between node, masters, and controllers. To configure this, the following stanzas must be altered in the /etc/origin/master-config.yaml file on each master:

masterClients:
  externalKubernetesClientConnectionOverrides:
    acceptContentTypes: application/vnd.kubernetes.protobuf,application/json
    contentType: application/vnd.kubernetes.protobuf
    burst: 400
    qps: 200
  externalKubernetesKubeConfig: ""
  openshiftLoopbackClientConnectionOverrides:
    acceptContentTypes: application/vnd.kubernetes.protobuf,application/json
    contentType: application/vnd.kubernetes.protobuf
    burst: 600
    qps: 300
  openshiftLoopbackKubeConfig: openshift-master.kubeconfig

For more information on protocol buffers, see https://developers.google.com/protocol-buffers/docs/overview.

In OpenShift Container Platform 3.3, the kubernetesMasterConfig.admissionConfig.pluginConfig parameter in the /etc/origin/master-config.yaml file is being deprecated. If you are upgrading from version 3.2 to 3.3 and this parameter is in use, see General Admission Rules for guidance on moving and merging into admissionConfig.pluginConfig.

Restart the master service(s) on each master and review logs to ensure they restart successfully.

For single master clusters:

# systemctl restart atomic-openshift-master
# journalctl -r -u atomic-openshift-master

For multi-master clusters:

# systemctl restart atomic-openshift-master-controllers
# systemctl restart atomic-openshift-master-api
# journalctl -r -u atomic-openshift-master-controllers
# journalctl -r -u atomic-openshift-master-api

Because masters also have node components running on them in order to be configured as part of the OpenShift SDN, restart the atomic-openshift-node and openvswitch services:
```
# systemctl restart atomic-openshift-node
# systemctl restart openvswitch
# journalctl -r -u openvswitch
# journalctl -r -u atomic-openshift-node
```
Run the following command on each master to add the atomic-openshift packages back to the list of yum excludes on the host:
```
# atomic-openshift-excluder exclude
```

Upgrade any external etcd hosts using the RPM-based method on a RHEL 7 system:

Upgrade the etcd package:
```
# yum update etcd
```
Restart the etcd service and review the logs to ensure it restarts successfully:
```
# systemctl restart etcd
# journalctl -r -u etcd
```

During the cluster upgrade, it can sometimes be useful to take a master out of rotation since some DNS client libraries will not properly to the other masters for cluster DNS. In addition to stopping the master and controller services, you can remove the EndPoint from the Kubernetes service’s subsets.addresses.

$ oc edit ep/kubernetes -n default

When the master is restarted, the Kubernetes service will be automatically updated.

Updating Policy Definitions

After a cluster upgrade, the recommended default cluster roles may be updated. To check if an update is recommended for your environment, you can run:

# oadm policy reconcile-cluster-roles

If you have customized default cluster roles and want to ensure a role reconciliation does not modify those customized roles, annotate them with openshift.io/reconcile-protect set to true. Doing so means you are responsible for manually updating those roles with any new or required permissions during upgrades.

This command outputs a list of roles that are out of date and their new proposed values. For example:

# oadm policy reconcile-cluster-roles
apiVersion: v1
items:
- apiVersion: v1
  kind: ClusterRole
  metadata:
    creationTimestamp: null
    name: admin
  rules:
  - attributeRestrictions: null
    resources:
    - builds/custom
...

Your output will vary based on the OpenShift version and any local customizations you have made. Review the proposed policy carefully.

You can either modify this output to re-apply any local policy changes you have made, or you can automatically apply the new policy using the following process:

Reconcile the cluster roles:

# oadm policy reconcile-cluster-roles \
    --additive-only=true \
    --confirm

Reconcile the cluster role bindings:

# oadm policy reconcile-cluster-role-bindings \
    --exclude-groups=system:authenticated \
    --exclude-groups=system:authenticated:oauth \
    --exclude-groups=system:unauthenticated \
    --exclude-users=system:anonymous \
    --additive-only=true \
    --confirm

Reconcile security context constraints:

# oadm policy reconcile-sccs \
    --additive-only=true \
    --confirm

Upgrading Nodes

After upgrading your masters, you can upgrade your nodes. When restarting the atomic-openshift-node service, there will be a brief disruption of outbound network connectivity from running pods to services while the service proxy is restarted. The length of this disruption should be very short and scales based on the number of services in the entire cluster.

Blue-green deployments are another proven approach to reducing downtime caused while updating an environment.

One at at time for each node that is not also a master, you must disable scheduling and evacuate its pods to other nodes, then upgrade packages and restart services.

Run the following command on each node to remove the atomic-openshift packages from the list of yum excludes on the host:
```
# atomic-openshift-excluder unexclude
```
As a user with cluster-admin privileges, disable scheduling for the node:
```
# oadm manage-node <node> --schedulable=false
```
Evacuate pods on the node to other nodes:

The --force option deletes any pods that are not backed by a replication controller.
```
# oadm manage-node <node> --evacuate --force
```
Upgrade the node component packages or related images.
1. For nodes using the RPM-based method on a RHEL 7 system, upgrade all installed atomic-openshift packages:
  # yum upgrade atomic-openshift\*
2. For nodes using the containerized method on a RHEL 7 or RHEL Atomic Host 7 system, set the IMAGE_VERSION parameter in the /etc/sysconfig/atomic-openshift-node and /etc/sysconfig/openvswitch files to the version you are upgrading to. For example:
  IMAGE_VERSION=<tag>
  Replace <tag> with v3.3 for the latest version.
In OpenShift Container Platform 3.3, protocol buffers are used by default for internal communications between node, masters, and controllers. To configure this, the following stanzas must be altered in the /etc/origin/node-config.yaml file on each node:
```
masterClientConnectionOverrides:
  acceptContentTypes: application/vnd.kubernetes.protobuf,application/json
  contentType: application/vnd.kubernetes.protobuf
  burst: 200
  qps: 100
```
For more information on protocol buffers, see https://developers.google.com/protocol-buffers/docs/overview.

Restart the atomic-openshift-node and openvswitch services and review the logs to ensure they restart successfully:

# systemctl restart atomic-openshift-node
# systemctl restart openvswitch
# journalctl -r -u atomic-openshift-node
# journalctl -r -u openvswitch

Re-enable scheduling for the node:
```
# oadm manage-node <node> --schedulable
```
Run the following command on the node to add the atomic-openshift packages back to the list of yum excludes on the host:
```
# atomic-openshift-excluder exclude
```
Repeat these steps on the next node, and continue repeating these steps until all nodes have been upgraded.

After all nodes have been upgraded, as a user with cluster-admin privileges, verify that all nodes are showing as Ready:

# oc get nodes
NAME                        STATUS                     AGE
master.example.com          Ready,SchedulingDisabled   165d
node1.example.com           Ready                      165d
node2.example.com           Ready                      165d

Upgrading the Router

If you have previously deployed a router, the router deployment configuration must be upgraded to apply updates contained in the router image. To upgrade your router without disrupting services, you must have previously deployed a highly-available routing service.

If you previously customized your HAProxy routing template, then, depending on the changes, additional steps may be required due to changes in the routing data structure starting in OpenShift Container Platform 3.3. See Routing Data Structure Changes in the OpenShift Container Platform 3.3 Release Notes for details.

Edit your router’s deployment configuration. For example, if it has the default router name:

# oc edit dc/router

Apply the following changes:

...
spec:
 template:
    spec:
      containers:
      - env:
        ...
        image: registry.access.redhat.com/openshift3/ose-haproxy-router:<tag> (1)
        imagePullPolicy: IfNotPresent
        ...

1	Adjust `<tag>` to match the version you are upgrading to (use `v3.3` for the latest version).

You should see one router pod updated and then the next.

Upgrading the Registry

The registry must also be upgraded for changes to take effect in the registry image. If you have used a PersistentVolumeClaim or a host mount point, you may restart the registry without losing the contents of your registry. Storage for the Registry details how to configure persistent storage for the registry.

Edit your registry’s deployment configuration:

# oc edit dc/docker-registry

Apply the following changes:

...
spec:
 template:
    spec:
      containers:
      - env:
        ...
        image: registry.access.redhat.com/openshift3/ose-docker-registry:<tag> (1)
        imagePullPolicy: IfNotPresent
        ...

1	Adjust `<tag>` to match the version you are upgrading to (use `v3.3` for the latest version).

Images that are being pushed or pulled from the internal registry at the time of upgrade will fail and should be restarted automatically. This will not disrupt pods that are already running.

Updating Custom Registry Configuration Files

You may safely skip this part if you do not use a custom registry configuration file.

The internal Docker registry version 3.3.0 and higher requires following entries in the middleware section of the configuration file:

middleware:
  registry:
    - name: openshift
  repository:
    - name: openshift
  storage:
    - name: openshift

Edit your custom configuration file, adding the missing entries.
Deploy your updated configuration.
Append the --overwrite flag to oc volume dc/docker-registry --add to replace a volume mount of your previous secret.
You can safely remove the old secret.

Enforcing quota in the Registry

quota must be enforced to prevent layer blobs that exceed the size limit from being written to the registry’s storage. This can be achieved via a configuration file:

...
middleware:
  repository:
    - name: openshift
      options:
        enforcequota: true
...

Alternatively, use the REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_ENFORCEquota environment variable, which is set to true for the new registry deployments by default. Existing deployments need to be modified using:

# oc set env dc/docker-registry REGISTRY_MIDDLEWARE_REPOSITORY_OPENSHIFT_ENFORCEquota=true

Updating the Default Image Streams and Templates

By default, the quick and advanced installation methods automatically create default image streams, InstantApp templates, and database service templates in the openshift project, which is a default project to which all users have view access. These objects were created during installation from the JSON files located under the /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/ directory.

Because RHEL Atomic Host 7 cannot use yum to update packages, the following steps must take place on a RHEL 7 system.

Update the packages that provide the example JSON files. On a subscribed Red Hat Enterprise Linux 7 system where you can run the CLI as a user with cluster-admin permissions, install or update to the latest version of the atomic-openshift-utils package, which should also update the openshift-ansible- packages:
```
# yum update atomic-openshift-utils
```
The openshift-ansible-roles package provides the latest example JSON files.
After a manual upgrade, get the latest templates from openshift-ansible-roles:
rpm -ql openshift-ansible-roles | grep examples | grep v1.3
In this example, /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/image-streams/image-streams-rhel7.json is the latest file that you want in the latest openshift-ansible-roles package.

/usr/share/openshift/examples/image-streams/image-streams-rhel7.json is not owned by a package, but is updated by Ansible. If you are upgrading outside of Ansible. you need to get the latest .json files on the system where you are running oc, which can run anywhere that has access to the master.

Install atomic-openshift-utils and its dependencies to install the new content into /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/.:

$ oc create -n openshift -f  /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/image-streams/image-streams-rhel7.json
$ oc create -n openshift -f  /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/image-streams/dotnet_imagestreams.json
$ oc replace -n openshift -f  /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/image-streams/image-streams-rhel7.json
$ oc replace -n openshift -f  /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/image-streams/dotnet_imagestreams.json

Update the templates:

$ oc create -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/
$ oc create -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/db-templates/
$ oc create -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/infrastructure-templates/
$ oc create -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/xpaas-templates/
$ oc create -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/xpaas-streams/
$ oc replace -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/
$ oc replace -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/db-templates/
$ oc replace -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/infrastructure-templates/
$ oc replace -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/xpaas-templates/
$ oc replace -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/xpaas-streams/

Errors are generated for items that already exist. This is expected behavior:

# oc create -n openshift -f /usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/
Error from server: error when creating "/usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/cakephp-mysql.json": templates "cakephp-mysql-example" already exists
Error from server: error when creating "/usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/cakephp.json": templates "cakephp-example" already exists
Error from server: error when creating "/usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/dancer-mysql.json": templates "dancer-mysql-example" already exists
Error from server: error when creating "/usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/dancer.json": templates "dancer-example" already exists
Error from server: error when creating "/usr/share/ansible/openshift-ansible/roles/openshift_examples/files/examples/v1.3/quickstart-templates/django-postgresql.json": templates "django-psql-example" already exists

Now, content can be updated. Without running the automated upgrade playbooks, the content is not updated in /usr/share/openshift/.

Importing the Latest Images

After updating the default image streams, you may also want to ensure that the images within those streams are updated. For each image stream in the default openshift project, you can run:

# oc import-image -n openshift <imagestream>

For example, get the list of all image streams in the default openshift project:

# oc get is -n openshift
NAME     DOCKER REPO                                                      TAGS                   UPDATED
mongodb  registry.access.redhat.com/openshift3/mongodb-24-rhel7           2.4,latest,v3.1.1.6    16 hours ago
mysql    registry.access.redhat.com/openshift3/mysql-55-rhel7             5.5,latest,v3.1.1.6    16 hours ago
nodejs   registry.access.redhat.com/openshift3/nodejs-010-rhel7           0.10,latest,v3.1.1.6   16 hours ago
...

Update each image stream one at a time:

# oc import-image -n openshift nodejs
The import completed successfully.

Name:			nodejs
Created:		10 seconds ago
Labels:			<none>
Annotations:		openshift.io/image.dockerRepositoryCheck=2016-07-05T19:20:30Z
Docker Pull Spec:	172.30.204.22:5000/openshift/nodejs

Tag	Spec								Created		PullSpec						Image
latest	4								9 seconds ago	registry.access.redhat.com/rhscl/nodejs-4-rhel7:latest	570ad8ed927fd5c2c9554ef4d9534cef808dfa05df31ec491c0969c3bd372b05
4	registry.access.redhat.com/rhscl/nodejs-4-rhel7:latest		9 seconds ago	<same>							570ad8ed927fd5c2c9554ef4d9534cef808dfa05df31ec491c0969c3bd372b05
0.10	registry.access.redhat.com/openshift3/nodejs-010-rhel7:latest	9 seconds ago	<same>							a1ef33be788a28ec2bdd48a9a5d174ebcfbe11c8e986d2996b77f5bccaaa4774

In order to update your S2I-based applications, you must manually trigger a new build of those applications after importing the new images using oc start-build <app-name>.

Upgrading the EFK Logging Stack

Use the following to upgrade an already-deployed EFK logging stack.

The following steps apply when upgrading to OpenShift Container Platform 3.3+.

Ensure you are working in the project where the EFK stack was previously deployed. For example, if the project is named logging:
```
$ oc project logging
```

Recreate the deployer templates for service accounts and running the deployer:

$ oc apply -n openshift -f \
    usr/share/ansible/openshift-ansible/roles/openshift_hosted_templates/files/v1.3/enterprise/metrics-deployer.yaml

Generate any missing service accounts and roles:

$ oc process logging-deployer-account-template | oc apply -f -

Ensure that the cluster role oauth-editor is assigned to the logging-deployer service account:

$ oadm policy add-cluster-role-to-user oauth-editor \
       system:serviceaccount:logging:logging-deployer

In preparation for running the deployer, ensure that you have the configurations for your current deployment in the logging-deployer ConfigMap.

Ensure that your image version is the latest version, not the currently installed version.

Run the deployer with the parameter in upgrade mode:

$ oc new-app logging-deployer-template -p MODE=upgrade

Running the deployer in this mode handles scaling down the components to minimize loss of logs, patching configurations, generating missing secrets and keys, and scaling the components back up to their previous replica count.

Due to the privileges needed to label and unlabel a node for controlling the deployment of Fluentd pods, the deployer does delete the logging-fluentd Daemonset and recreates it from the logging-fluentd-template template.

Upgrading Cluster Metrics

After upgrading an already-deployed Cluster Metrics install, you must update to a newer version of the metrics components.

The update process stops all the metrics containers, updates the metrics configuration files, and redeploys the newer components.
It does not change the metrics route.
It does not delete the metrics persistent volume claim. Metrics stored to persistent volumes before the update are available after the update completes.

The update deletes all non-persisted metric values and overwrites local changes to the metrics configurations. For example, the number of instances in a replica set is not saved.

To update, follow the same steps as when the metrics components were first deployed, using the correct template, except this time, specify the MODE=refresh option:

$ oc new-app -f metrics-deployer.yaml \
    -p HAWKULAR_METRICS_HOSTNAME=hm.example.com,MODE=refresh (1)

1	In the original deployment command, there was no `MODE=refresh`.

During the update, the metrics components do not run. Because of this, they cannot collect data and a gap normally appears in the graphs.

Additional Manual Steps Per Release

Some OpenShift Container Platform releases may have additional instructions specific to that release that must be performed to fully apply the updates across the cluster. This section will be updated over time as new asynchronous updates are released for OpenShift Container Platform 3.3.

As of the latest 3.3 release (v3.3), there are no 3.3 asynchronous releases that require additional instructions during upgrade. See the OpenShift Container Platform 3.3 Release Notes to review the latest release notes.

Verifying the Upgrade

To verify the upgrade, first check that all nodes are marked as Ready:

# oc get nodes
NAME                        STATUS                     AGE
master.example.com          Ready,SchedulingDisabled   165d
node1.example.com           Ready                      165d
node2.example.com           Ready                      165d

Then, verify that you are running the expected versions of the docker-registry and router images, if deployed. Replace <tag> with v3.3 for the latest version.

# oc get -n default dc/docker-registry -o json | grep \"image\"
    "image": "openshift3/ose-docker-registry:<tag>",
# oc get -n default dc/router -o json | grep \"image\"
    "image": "openshift3/ose-haproxy-router:<tag>",

After upgrading, you can use the diagnostics tool on the master to look for common issues:

# oadm diagnostics
...
[Note] Summary of diagnostics execution:
[Note] Completed with no errors or warnings seen.

Performing Manual In-place Cluster Upgrades