Upgrading Private Cloud

Last modified: August 27, 2024

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.

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.

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.

Manual upgrade is an alternative to automatic upgrade mode. If you have already performed an automatic upgrade, you don’t need to follow the instructions in this section.

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
Stop Deployments
Apply the Upgrade Patches
Start Deployments

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=0

If 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=0

Apply the Upgrade Patches

Run the following command to upgrade Custom Resource Definitions for the Mendix Operator:

kubectl apply -f crds.manifest.yaml

Custom 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.yaml

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

The 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=1

If 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