Running the Mendix Operator in Standard Mode

Last modified: April 18, 2024

1 Introduction

When running the Mendix Operator in Standard mode, you must install it separately for every namespace where a Mendix app is deployed. However, the Custom Resource Definitions (CRDs) are global and installed at the cluster level - shared and visible among all namespaces in a given Kubernetes/OpenShift cluster. This can potentially lead to redundancies and conflicts, as well as issues when upgrading a single Mendix Operator installation.

To avoid these potential issues, you can run the Mendix Operator in Global mode. However, the Standard mode is still available for existing customers, and to support use cases that require having a separate Operator instance for every namespace.

2 Downloading the Configuration Tool

Before you can use the Mendix Operator in your namespace you need to install it and configure the services your app will use. Mendix provides you with a Configuration Tool which guides you through the process.

If you are not already on the installation tab for your namespace, go to it by following these instructions:

  1. Go to the Cluster Manager page by clicking Cluster Manager in the top menu of the Clouds page of the Developer Portal.

  2. Click the Details icon next to the namespace you want to use.

  3. Select Installation from the navigation bar to the left of the page.

Now you can download the Configuration Tool by doing the following:

  1. Choose the Operating System for your local computer.

  2. Click Download Executable.

  3. Choose the Mendix Operator Version that you would like to install. If you have already installed the Mendix Operator, your currently installed version will be highlighted.

  4. Click the Download icon to download the installation and configuration tool. Make sure that it is stored somewhere on your path.

3 Signing in to the Platform

You will need to have administrator rights to your private cloud platform. This means you will have to log in before you run the Configuration Tool.

These instructions are for the OpenShift platform; a similar process will be required for other platforms.

You can do this as follows:

  1. Sign in to the OpenShift Console.

  2. Click Copy Login Command in the user drop-down.

  3. Choose your IdP (Identity Provider).

  4. Click Display Token.

  5. Copy the command under Log in with this token.

  6. Paste the command into your command line terminal and press Enter.

4 Running the Configuration Tool

Once you are signed in to your cluster you can run the Configuration Tool.

To install in non-interactive mode please see: Install and Configure Mendix for Private Cloud Non-interactive Mode

  1. Copy the Installation Command by clicking Copy to clipboard.

  2. Paste the command into your command line terminal and press Enter

    You will see the configuration options on the screen and will be guided through filling in the information needed.

4.1 Base Installation

If the Mendix Operator and the Mendix Gateway Agent have not been installed in your cluster, you will need to install them.

  1. Click Base Installation.

  2. Select the required Cluster Mode – connected or standalone.

    For more information, see Connected and Standalone Clusters in the Private Cloud documentation.

  3. Select the required Cluster Type – openshift or generic.

  4. Click Run Installer to install the Mendix Operator and Mendix Gateway Agent in your cluster. You will see the screen below.

  5. Click Save Installer if you want to save these settings to be used later.

  6. Click Exit Installer to finish.

The Mendix operator and Mendix Gateway Agent are now installed on your platform.

4.2 Configure Namespace

You can now configure the resources required for your namespace.

The first time you configure the namespace, you should select all the items under Select items to configure except Proxy and Custom TLS. Only select Proxy if you want to configure a proxy for your namespace. Select Custom TLS only if you want to configure custom CAs for your namespace.

After pressing the Configure namespace button, you will see a prompt to resume a previous session. Clicking the OK button will load form field values from a locally saved previous session file. For example, if you’d like to change the database hostname, or if you exited without saving or applying changes.

  • Press OK to restore all filled forms to their valued values from the previous session.
  • Press Cancel to start with empty form fields (for example, to create an additional database plan).

The options do the following:

  • Database Plan – will create a new database plan for your cluster — you must have at least one database plan in your namespace, but you can have more than one
  • Storage Plan – will create a new storage plan for your cluster — you must have at least one storage plan in your namespace, but you can have more than one
  • Ingress – will configure the ingress for your namespace — if there is already an ingress, this will replace it with new settings
  • Registry – will configure a registry for your namespace — if there is already a registry, this will replace it with new settings
  • Proxy – will configure a proxy for your namespace — if there is already a proxy, this will replace it with new settings
  • Custom TLS – will configure custom CA trust for your namespace — if there is already a custom CA trust configuration, this will replace it with new settings

  1. Select the options you need to configure – the first time you configure your namespace you must check all the first four options. Proxy is optional.

  2. Click Configure Namespace.

    You will be shown the Installation wizard landing page.

  3. Click the appropriate button at the bottom of the page to navigate to the setup page for each resource which you need to configure. Alternatively, use the allocated function keys (for example F2 for the Database Plan).

  4. Each page will lead you through the information you need to supply.

    These are described in the following sections:

4.2.1 Database Plan

Every Mendix app environment needs its own dedicated database. Create a database plan to configure how the Mendix Operator will manage databases.

See the Database plans document for a list and instructions for all options.

4.2.2 Storage Plan

Every Mendix app environment needs a file (blob) storage bucket to store System.FileDocument entities, such as AWS S3, Azure Blob Storage or MinIO. Create a storage plan to configure how the Mendix Operator will manage file storage.

See the Blob storage plans document for a list and instructions for all options.

4.2.3 Ingress

openshift-route will configure an OpenShift Route. This can only be used for OpenShift clusters. This option allows you to enable or disable TLS.

kubernetes-ingress will configure ingress according to the additional domain name you supply. This option allows you to configure the ingress path and custom ingress class (dependent on the Ingress controller) and enable or disable TLS.

service-only will create just a Kubernetes Service, without an Ingress or OpenShift route. This option enables you to use a Load Balancer without an Ingress, or to manually create and manage the Ingress object (an Ingress that is not managed by Mendix for Private Cloud).

4.2.4 Registry

To run an app in Kubernetes, it needs to be converted (packaged) into a container image and pushed to an OCI registry.

The Mendix Operator automatically builds and pushes images into a private OCI registry; to push an image to the target registry, the Mendix Operator needs to be configured.

See the Image registry document for a list of supported registries and instructions how to configure each one.

4.3 Proxy

Check the Enable Proxy checkbox if a proxy is required to access the public internet from the namespace; you will be asked for the proxy configuration details.

List all local (including cluster-local) IP addresses and domains in the No proxy for field. The format is listed below:

Hosts which should be excluded from proxying are specified as:

  • A string containing comma-separated values, where each value is one of the following:

    • An IP address prefix (1.2.3.4)
    • An IP address prefix in CIDR notation (1.2.3.4/8)
    • A domain name
    • If you use the special DNS label (*) this indicates that there are no exceptions and everything will be proxied

  • Each IP address prefix or domain name can also include a literal port number (1.2.3.4:80)

  • A domain name matches that name and all subdomains

  • A domain name with a leading “.” matches subdomains only

    For example, “foo.com” matches “foo.com” and “bar.foo.com”; “.y.com” matches “x.y.com” but not “y.com”.

For more information about how to use this field, see the http proxy documentation used by the Configuration Tool.

4.4 Custom TLS

To use encryption and avoid MITM attacks, communication with all external services should be done over TLS. By default, Mendix Operator trusts Certificate Authorities from the Mozilla CA root bundle, as they are provided by default in the container image.

If Mendix for Private Cloud needs to communicate with external services, some of those services might have TLS certificates signed by a custom (private) CA. In order for the Mendix Operator to trust such certificates, you need to add their root CAs to the Mendix Operator configuration.

  1. In another terminal, prepare the Kubernetes secret containing the custom root CAs list:

    1. Create a custom.crt file, containing the public keys of all custom (private) CAs that Mendix for Private Cloud should trust:

      1
2
3
4
5
6
7
8

      # Private CA 1
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----
# Private CA 2
-----BEGIN CERTIFICATE-----
[...]
-----END CERTIFICATE-----

      (concatenate all the public keys from custom CAs into one custom.crt file, separating them with line breaks and optional comments).

    2. Load the file into a Secret (replace {namespace} with the namespace where the Operator is installed, and {secret} with the name of the Secret to create, for example, mendix-custom-ca):

      For OpenShift:

      oc -n {namespace} create secret generic {secret} --from-file=custom.crt=custom.crt

      For Kubernetes:

      kubectl -n {namespace} create secret generic {secret} --from-file=custom.crt=custom.crt

  2. Paste the name of this custom.crt secret (the {secret} used in the commands above) into the CA Certificates Secret Name field (for example, mendix-custom-ca):

    Custom TLS configuration

These custom CAs will be trusted by:

  • The Mendix Operator when communicating with the database and file storage
  • The Mendix Operator when pushing app images to the container registry
  • Mendix apps when communicating with the database, file storage and external web services
  • The Mendix Agent when connecting to Mendix Developer portal

4.5 Review and Apply

When you have configured all the resources, do the following:

  1. Press F7 to Review and Apply.

  2. Click Evaluate Configuration to check the configuration.

    Resources which are correctly configured will have a status Valid configuration. If an resource is incorrectly configured, it will have a status Invalid configuration: … and an explanation of the issue.

  3. Once you have evaluated the configuration, click Write YAML to save a copy of the configuration .yml files on your local machine.

    The Installer output panel will display the locations of the saved files.

  4. Click Apply Configuration to apply the configuration to your namespace.

    Once the configuration has been applied you will see the message Successfully applied all the configuration!.

  5. Click Exit Installer to return to the landing page.

5 Confirming Namespace Configuration

When using a connected cluster, its status will be shown as Connected in the Developer Portal when the namespace is configured correctly. You may need to click the Refresh button if the screen does not update automatically.