1 Introduction
This document describes how an existing installation of Mendix for Private Cloud can be upgraded to the latest version.
Both the Mendix Operator and Mendix Agent should be upgraded at the same time.
2 Upgrading to Mendix Operator 1.8.0
2.1 Preparation
Open a Bash-compatible terminal and set the target namespace where the Operator is currently installed:
OPERATOR_NAMESPACE={namespace where the Mendix Operator is installed}
All the following commands require the OPERATOR_NAMESPACE
variable to be set. When opening a new terminal, re-run this command again.
Check the current version of the Operator by running the following command:
kubectl -n $OPERATOR_NAMESPACE get deployment mendix-operator -o=jsonpath='{.spec.template.spec.containers[].image}'
The image name will look similar to private-cloud.registry.mendix.com/mendix-operator:{VERSION}
or quay.io/digital_ecosystems/mendix-operator:{VERSION}
.
Only follow the steps applicable to your currently installed version of the Mendix Operator.
For example, if the image name is quay.io/digital_ecosystems/mendix-operator:1.3.0
, follow only the steps for upgrading from Mendix Operator 1.3.*.
This process will take:
- about 15 to 30 minutes when upgrading from Mendix Operator 1.0.*
- about 15 minutes when upgrading from Mendix Operator 1.1.* to 1.7.*.
Some upgrade steps are only required when upgrading from older versions of the Mendix Operator. There is a notice on these steps indicating which upgrade paths they apply to and for which paths the step should be skipped.
During the upgrade process, the Mendix Operator will have to be stopped and will not process any changes. Apps and Environments managed by the Operator will keep running during this process and will be restarted in the cleanup step.
2.2.1 Stop the Operator
Stop the Operator, by running the following command:
kubectl -n $OPERATOR_NAMESPACE scale deployment mendix-operator --replicas=0
2.2.2 Upgrading the Custom Resource Definitions
Follow this step when upgrading from Mendix Operator versions 1.0.* to 1.7.* only.
Run the following command to upgrade to the latest version of the Custom Resource Definitions for the Mendix Operator:
kubectl apply -f https://installergen.private-cloud.api.mendix.com/privatecloud/crds/v1
Custom Resource Definitions allow Mendix applications to be managed with Kubernetes APIs and tools such as kubectl
and oc
.
2.2.3 Upgrading the dependency versions
Follow this step when upgrading from Mendix Operator versions 1.0.* to 1.7.* only.
Run the following command to upgrade to the latest version of the Custom Resource Definitions for the Mendix Operator:
kubectl -n $OPERATOR_NAMESPACE apply -f https://installergen.private-cloud.api.mendix.com/privatecloud/ocf/v1/versions
Custom Resource Definitions allow Mendix applications to be managed with Kubernetes APIs and tools such as kubectl
and oc
.
2.2.4 Upgrading the Mendix Operator Deployment
Run the following command to switch to Mendix Operator version 1.8.0:
kubectl -n $OPERATOR_NAMESPACE patch deployment mendix-operator -p \
'{"spec":{"template":{"spec":{"containers":[{"name":"mendix-operator","image":"private-cloud.registry.mendix.com/mendix-operator:1.8.0"}]}}}}'
2.2.5 Updating the Mendix Operator Configuration
2.2.5.1 Updating the Mendix Operator Configuration (from version 1.0.*)
Follow this step when upgrading from Mendix Operator version 1.0.* only. If you’re running a later version of the Mendix Operator, proceed to the next step.
Run the following commands to switch to the latest component versions:
kubectl -n $OPERATOR_NAMESPACE patch operatorconfiguration mendix-operator-configuration --type merge -p \
'{"spec":{
"sidecarImage":null,
"metricsSidecarImage":null,
"builderImage":null,
"buildRuntimeBaseImage":"private-cloud.registry.mendix.com/runtime-base:{{.MxRuntimeVersion}}-rhel",
"dockerfile":null
}}'
Set the default requests and limits for the Mendix Runtime pods:
kubectl -n $OPERATOR_NAMESPACE patch operatorconfiguration mendix-operator-configuration --type merge -p \
'{"spec":{
"runtimeResources":{"limits":{"cpu":"1000m","memory":"512Mi"},"requests":{"cpu":"100m","memory":"512Mi"}}
}}'
Set the configuration for the readiness and liveness probes:
kubectl -n $OPERATOR_NAMESPACE patch operatorconfiguration mendix-operator-configuration --type merge -p \
'{"spec":{
"runtimeLivenessProbe":{"initialDelaySeconds":60,"periodSeconds":15},
"runtimeReadinessProbe":{"initialDelaySeconds":5,"periodSeconds":1}
}}'
Set the type for all Storage Plans to on-demand
:
kubectl -n $OPERATOR_NAMESPACE get storageplan --no-headers=true -o name | sed -e 's/.*\///g' | \
xargs -I {} kubectl -n $OPERATOR_NAMESPACE patch storageplan {} --type=merge -p '{"spec":{"type":"on-demand"}}'
2.2.5.2 Updating the Mendix Operator Configuration (from versions 1.1.* to 1.7.*)
Follow this step only when upgrading from Mendix Operator 1.1.* to 1.7.* only.
Run the following commands to switch to the latest component versions:
kubectl -n $OPERATOR_NAMESPACE patch operatorconfiguration mendix-operator-configuration --type merge -p \
'{"spec":{
"sidecarImage":null,
"metricsSidecarImage":null,
"builderImage":null,
"buildRuntimeBaseImage":"private-cloud.registry.mendix.com/runtime-base:{{.MxRuntimeVersion}}-rhel"
}}'
2.2.6 Update the Kubernetes Role
2.2.6.1 Update the Kubernetes Role for OpenShift routes
Follow this step when upgrading from Mendix Operator versions 1.0.*, 1.1.*, and 1.2.*.
It can be skipped if the Mendix Operator is not configured to use OpenShift Routes for incoming network traffic.
To allow you to change the App URL in OpenShift Routes, you need to perform this step to add the update
permission to the mendix-operator
role.
Search for the mendix-operator
Role in the OpenShift web console and open if for editing, or run the following command to start editing the mendix-operator
Role:
oc -n $OPERATOR_NAMESPACE edit role mendix-operator
Find the following resource (containing apiGroups
: route.openshift.io
and resources
: routes
):
- apiGroups:
- route.openshift.io
resources:
- routes
verbs:
- get
- create
- list
- watch
and add an update
verb to the list of verbs:
- apiGroups:
- route.openshift.io
resources:
- routes
verbs:
- get
- create
- list
- watch
- update # add this line
Save the role to apply the changes.
2.2.6.2 Update the Kubernetes Role for OperatorVersions CRD
Follow this step when upgrading from Mendix Operator versions 1.0.* to 1.7.*.
To allow the Operator to manage its dependency versions, add the operatorversions
resource to the mendix-operator
role.
Search for the mendix-operator
Role in the OpenShift web console and open it for editing, or run the following command to start editing the mendix-operator
Role:
kubectl -n $OPERATOR_NAMESPACE edit role mendix-operator
Find the following resource (containing apiGroups
: privatecloud.mendix.com
):
- apiGroups:
- privatecloud.mendix.com
resources:
- '*'
- builds
- runtimes
- mendixapps
- operatorconfigurations
- endpoints
- storageplans
- storageinstances
verbs:
- '*'
and add an operatorversions
resource to the list of resources:
- apiGroups:
- privatecloud.mendix.com
resources:
- '*'
- builds
- runtimes
- mendixapps
- operatorconfigurations
- endpoints
- storageplans
- storageinstances
- operatorversions # add this line
verbs:
- '*'
Save the role to apply the changes.
2.2.7 Update the Storage Plan provisioners
Only follow this step when upgrading from Mendix Operator versions 1.0.* to 1.7.*.
Run the following command:
for PROVISIONER in basic postgres96 minio s3 sqlserver2017 cos
do
echo "Upgrading $PROVISIONER Storage Plans..."
kubectl -n $OPERATOR_NAMESPACE get storageplan -o=jsonpath="{range .items[*]}{.metadata.name}{' '}{.spec.create.image}{'\n'}{end}" | \
grep ":${PROVISIONER}-rhel" | while read -r STORAGEPLAN
do
UPGRADE_STORAGEPLAN=$(echo $STORAGEPLAN | cut -d " " -f1)
echo "Upgrading $UPGRADE_STORAGEPLAN Storage Plan"
kubectl -n $OPERATOR_NAMESPACE patch storageplan $UPGRADE_STORAGEPLAN --type=merge -p \
"{\"spec\":{\"provisioner\":\"$PROVISIONER\",\"create\":{\"image\":\"\"},\"delete\":{\"image\":\"\"}}}"
done
done
2.2.8 Start the Mendix Operator
To start the updated version of the Mendix Operator, run:
kubectl -n $OPERATOR_NAMESPACE scale deployment mendix-operator --replicas=1
Starting the Operator will create or update deployments for all your apps.
All network traffic will be routed to the new deployments - causing a restart of all your apps managed by that Operator.
When upgrading from Mendix Operator 1.0.* to the latest version, Deployments will be created in addition to StatefulSets created by the previous version of the Operator.
The StatefulSets should be cleaned up manually as documented in the Cleanup phase section.
2.2.9 Cleanup Phase
Follow this step when upgrading from Mendix Operator version 1.0.* only.
Delete StatefulSets from the Namespace where the Operator was installed:
kubectl -n $OPERATOR_NAMESPACE delete --all statefulsets
These StatefulSets were replaced with deployments when the new version of the Operator was started.
3 Upgrading to Mendix Gateway Agent 1.7.0
If the cluster was installed in Standalone mode, the Mendix Gateway Agent is not included in the installation and doesn’t need to be upgraded.
Upgrading the Mendix Gateway Agent is only possible if the cluster was originally installed in Connected mode.
3.1 Preparation
Before upgrading to Mendix Gateway Agent version 1.7.0, first upgrade the Mendix Operator to the latest version
and set the OPERATOR_NAMESPACE
variable in your Bash terminal as described above.
Check the current version of the Agent by running the following command:
kubectl -n $OPERATOR_NAMESPACE get deployment mendix-agent -o=jsonpath='{.spec.template.spec.containers[].image}'
The image name will look similar to private-cloud.registry.mendix.com/mendix-agent:{VERSION}
or quay.io/digital_ecosystems/mendix-agent:{VERSION}
.
Only follow the steps applicable to your currently installed version of the Mendix Agent.
For example, if the image name is quay.io/digital_ecosystems/mendix-agent:1.6.0
, follow only the steps for upgrading from Mendix Agent 1.6.*.
Some upgrade steps are only required when upgrading from older versions of the Mendix Gateway Agent. There is a notice on these steps indicating which upgrade paths they apply to and for which paths the step should be skipped.
3.2 Update the Kubernetes Role
3.2.1 Update the Kubernetes Role for OperatorVersions CRD
Follow this step when upgrading from Mendix Gateway Agent versions 1.0.* to 1.6.* only.
To allow the Mendix Gateway Agent to report and manage dependency versions for the Mendix Operator, add the operatorversions
resource to the mendix-agent
role.
Search for the mendix-agent
Role in the OpenShift web console and open if for editing, or run the following command to start editing the mendix-agent
Role:
kubectl -n $OPERATOR_NAMESPACE edit role mendix-agent
Find the following resource (containing apiGroups
: privatecloud.mendix.com
):
- apiGroups:
- privatecloud.mendix.com
resources:
- mendixapps
verbs:
- '*'
and add an operatorversions
resource to the list of resources:
- apiGroups:
- privatecloud.mendix.com
resources:
- mendixapps
- operatorversions # add this line
verbs:
- '*'
Save the role to apply the changes.
3.3 Upgrading the Mendix Gateway Agent Deployment
Run the following command to switch to the Mendix Agent version 1.7.0:
kubectl -n $OPERATOR_NAMESPACE patch deployment mendix-agent -p \
'{"spec":{"template":{"spec":{"containers":[{"name":"mendix-agent","image":"private-cloud.registry.mendix.com/kubernetes-agent:1.7.0"}]}}}}'