Upgrading Private Cloud
Introduction
This document describes how an existing installation of Mendix for Private Cloud can be upgraded.
This procedure allows you to upgrade to any supported (v1.9.0 and later) version of the Mendix for Private Cloud Operator.
There are special considerations that you must be aware of in the following cases:
- when using the
mxpc-cliinstallation and configuration tool version 2.20.1 or earlier. - when manually installing or upgrading CRDs with
kubectl apply.
Upgrading the Mendix for Private Cloud Operator in a namespace will modify global resources such as Mendix Custom Resource Definitions in the cluster.
Custom Resource Definitions allow Mendix applications to be managed with Kubernetes APIs and tools such as kubectl and oc.
Once you have installed a particular version of the Mendix Operator into any namespace in the cluster, you should not install older versions of the Mendix Operator into the same cluster, even if they are in other namespaces. This is because all the CRDs are global resources and operators in all namespaces use the same one, which may not be compatible across versions.
Starting from mxpc-cli version 2.21.0, the installation or upgrade process checks to see if the CRDs in the cluster are newer than the CRDs bundled with mxpc-cli. If the cluster has newer CRDs, mxpc-cli will skip the CRD installation step and avoid downgrading CRDs.
If you are using your own private registry, follow the Migrating to Your Own Registry guide first to migrate new component versions of Mendix for Private Cloud into your private registry.
If you’re using Mendix for Private Cloud Operator v1.*.* and are planning to upgrade to Kubernetes 1.22, follow these steps first:
- Upgrade your cluster to Kubernetes 1.21
- Upgrade all namespaces in your cluster to Mendix for Private Cloud Operator v2.*.*
- Validate that Mendix for Private Cloud is working correctly in all namespaces
Kubernetes 1.22 deprecated multiple APIs; upgrading to Kubernetes 1.21 and Mendix Operator v2.*.* will prepare resources such as ingresses to be compatible with APIs available in Kubernetes 1.22.
Prerequisites
Download the Configuration Tool
Follow the instructions to Download the Configuration Tool. When downloading the Configuration Tool, choose the version you would like to upgrade to (1.9.0 or a later version) - not the version that is currently installed.
If you’re using an OpenShift cluster, follow the Signing in to OpenShift instructions.
CLI Availability
You must have the OpenShift CLI installed for upgrading Mendix for Private Cloud on OpenShift, or the Kubectl CLI installed if you are upgrading Mendix for Private Cloud on another Kubernetes platform. In both cases, ensure that they are connected to the correct cluster.
Upgrade Namespace
-
Follow the instructions to Run the Configuration Tool. You will see the initial screen:
-
Click Upgrade Namespace. You will see the screen below:
Automatic Upgrade Mode
This mode will automatically upgrade components in the namespace.
-
Select your current required Cluster Type – openshift or generic.
-
Click Run Upgrade to upgrade Mendix for Private Cloud components in the namespace.
The upgrade is successful if the Upgrade output ends with Done.
Manual Upgrade Mode
This mode allows you to review and audit any changes the Configuration Tool would need to perform to upgrade Mendix for Private Cloud in your namespace.
To get the current configuration, this tool will need permissions to read resources in the namespace.
A manual upgrade consists of the following steps:
Generate Upgrade Patches
This step will prepare upgrade patches on your local machine in the subfolder .mxpc-cli of your user home directory (for example C:\Users\<User id>\.mxpc-cli in Windows or /home/<User id>/.mxpc-cli for Mac and U*ix).
-
Select your Cluster Type – openshift or generic.
-
Click Save Upgrade script to generate upgrade patches for the namespace.
The patches are successfully generated if the Upgrade output ends with Done.
Stop Deployments
Stop the deployed mendix-operator (replace {namespace} with the namespace where the Mendix Operator is deployed):
kubectl -n {namespace} scale deployment mendix-operator --replicas=0If you have installed the cluster in Connected mode, stop the deployed mendix-agent (replace {namespace} with the namespace where the Mendix Agent is deployed):
kubectl -n {namespace} scale deployment mendix-agent --replicas=0Apply the Upgrade Patches
Run the following command to upgrade Custom Resource Definitions for the Mendix Operator:
kubectl apply -f crds.manifest.yamlCustom Resource Definitions allow Mendix applications to be managed with Kubernetes APIs and tools such as kubectl and oc.
Run the following command to upgrade the dependency versions for the Mendix Operator:
kubectl -n {namespace} apply -f upgrade_manifest.yamlOpen the upgrade_patches.txt file and run the commands printed in that file.
The upgrade_patches.txt file contains a list of kubectl commands (or oc commands for OpenShift) that you will need to execute in a command line terminal to complete the upgrade process.
upgrade_patches.txt file uses Bash escaping rules. If you’re using another terminal such as the Windows command prompt, you will need to adjust the commands so that they are compatible with your command line terminal’s escaping rules.
Start Deployments
Start the mendix-operator deployment (replace {namespace} with the namespace where the Mendix Operator is deployed):
kubectl -n {namespace} scale deployment mendix-operator --replicas=1If you have installed the cluster in Connected mode, start the mendix-agent deployment (replace {namespace} with the namespace where the Mendix Agent is deployed):
kubectl -n {namespace} scale deployment mendix-agent --replicas=1