Upgrading IBM Cloud Private-CE

You can upgrade IBM Cloud Private-CE from specific previous versions.

Supported upgrade paths

You can upgrade only the following supported paths:

• IBM Cloud Private-CE version 3.2.0 to 3.2.1
• IBM Cloud Private-CE version 3.1.2 to 3.2.1
• IBM Cloud Private-CE version 3.1.1 to 3.2.1
• IBM Cloud Private-CE version 3.1.0 to 3.2.1

If you use an earlier version of IBM Cloud Private-CE, you must upgrade to version 3.1.0 first.

You can upgrade only from one version of IBM Cloud Private-CE to another version of IBM Cloud Private-CE. You cannot upgrade IBM Cloud Private-CE to IBM Cloud Private Cloud Native or Enterprise editions.

During the upgrade process, you can't access the IBM Cloud Private management console. You also can't set cloud provider options, such as configuring a vSphere Cloud Provider, or choose to use NSX-T.

Upgrading

1. Log in to the boot node as a user with root permissions. The boot node is usually your master node. For more information about node types, see Architecture. During installation, you specify the IP addresses for each node type.

2. Pull the IBM Cloud Private-CE installer image from Docker Hub.

   sudo docker pull ibmcom/icp-inception:3.2.1
   

3. Create an installation directory and copy the cluster directories from the previous installation directory to the new IBM Cloud Private cluster folder. Use a different installation directory than you used for the previous version. For example, to store the configuration files in /opt/ibm-cloud-private-3.2.1, run the following commands:

   mkdir -p /opt/ibm-cloud-private-3.2.0
   cd /opt/ibm-cloud-private-3.2.0
   cp -r /<installation_directory>/cluster .
   sudo rm -rf .upgrade upgrade_version
   

   Note: /<installation_directory> is the full path to your version 3.2.0 installation directory, and /<new_installation_directory> is the full path to your version 3.2.1 installation directory.

4. Check the calico_ipip_enabled parameter value in the version that you are upgrading from.

   • If the parameter was set as calico_ipip_enabled: true, replace the parameter in the /<new_installation_directory>/cluster/config.yaml with calico_ipip_mode: Always.
   • If the parameter was set as calico_ipip_enabled: false, replace the parameter in the /<new_installation_directory>/cluster/config.yaml with calico_ipip_mode: Never.

5. Deploy your environment by completing the following steps:

   1. If you enabled single sign-on (SSO) in a previous release, you must disable it before you upgrade your cluster. For more information about disabling SSO, see Configuring single sign-on. If you do not disable SSO before upgrade, or if the platform-auth container fails to start after you upgrade your cluster, see platform-auth container fails to start.
   2. Change to the cluster folder in your installation directory.

      cd /<new_installation_directory>/cluster
      

   3. Prepare the cluster for upgrade.

      sudo docker run -e LICENSE=accept --net=host --rm -t -v "$(pwd)":/installer/cluster \
      ibmcom/icp-inception:3.2.1 upgrade-prepare
      

      If the cluster preparation fails, review the error message and resolve any issues. Then, run the upgrade-prepare command again.

   4. Upgrade Kubernetes.

      sudo docker run -e LICENSE=accept --net=host --rm -t -v "$(pwd)":/installer/cluster \
      ibmcom/icp-inception:3.2.1 upgrade-k8s
      

      • If the Kubernetes upgrade fails with a different message, review the error message and resolve any issues. Then, roll back the Kubernetes services and run the upgrade Kubernetes services command again.

   5. Upgrade chart.

      sudo docker run -e LICENSE=accept --net=host --rm -t -v "$(pwd)":/installer/cluster \
      ibmcom/icp-inception:3.2.1 upgrade-chart
      

      • If the chart upgrade fails with a different message, review the error message and resolve any issues. Then, rerun the upgrade chart command again.
   6. If GlusterFS is installed in your cluster, you must upgrade the GlusterFS client to version 4.1.5.
   7. Update NGINX ingress rewrite-target annotation. For more information, see NGINX ingress rewrite-target annotation fails when you upgrade to IBM Cloud Private Version 3.2.1.

6. Verify the status of your upgrade.

   • If the upgrade succeeded, the access information for your cluster is displayed. The <Cluster Master Host> is defined in Master endpoint.

     UI URL is https://<Cluster Master Host>:<Cluster Master API Port>
     

     Where, <Cluster Master Host>:<Cluster Master API Port> is defined in Master endpoint.

   • If you encounter errors, you can add the argument v after any subcommand and then rerun. For example, if upgrade-prepare failed, add -v after upgrade-prepare and rerun this command:

      sudo docker run -e LICENSE=accept --net=host --rm -t -v "$(pwd)":/installer/cluster \
      ibmcom/icp-inception-s390x:3.2.0.1907-ee upgrade-prepare -vsee [Troubleshooting](../troubleshoot/troubleshoot.html).
     

     You can also check Troubleshooting for details.

7. Clear your browser cache.

8. If you have either applications that use GPU resources or a resource quota for GPU resources, you need to manually update the application or resource quota with the new GPU resource name nvidia.com/gpu.

   • For applications that use GPU resources, follow the steps in Creating a deployment with attached GPU resources to run a sample GPU application. For your own GPU application, you need to update the application to use the new GPU resource name nvidia.com/gpu. For example, to update the deployment properties, you can use either the management console (see Modifying a deployment) or the kubectl CLI.
   • To update the resource quota for GPU resources, follow the steps in Setting resource quota to set a resource quota for your namespace. For upgrading, you need to update the resource quota to use the GPU resource name nvidia.com/gpu. For example, you can set the GPU quota to requests.nvidia.com/gpu: "2".

9. Access your cluster. From a web browser, browse to the URL for your cluster. For a list of supported browsers, see Supported browsers.

   • For more information about accessing your cluster by using the IBM Cloud Private management console from a web browser, see Accessing your IBM Cloud Private cluster by using the management console.
   • For more information about accessing your cluster by using the Kubernetes command line (kubectl), see Accessing your IBM Cloud Private cluster by using the kubectl CLI. Note: After your upgrade the pod security policy for your clusters is automatically enabled, but set to the least restrictive setting to avoid access problems. See Pod security for information about how to manage the pod security policy settings.

10. Ensure that all the IBM Cloud Private default ports are open. For more information about the default IBM Cloud Private ports, see Default ports.

11. Back up the boot node. Copy your /<new_installation_directory>/cluster directory to a secure location.