Using Installation and Configuration Scripts

Last update: Edit

1 Introduction

Usually you will install the Mendix Operator and Mendix Gateway Agent in your Kubernetes or OpenShift namespace using the Configuration Tool. However, there might be a reason you need to perform the installation or configuration on your cluster.

Mendix provides you with two scripts that you can use instead of the Configuration Tool and this document explains how to use them.

2 Obtaining the Scripts

View the details of the namespace you want to use for installation and configuration by doing the following:

  1. Go to the Cluster Manager page by clicking Cluster Manager in the Apps menu.

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

  3. Select the Installation tab.

  4. Click Use Old Installation Script.

You will see two scripts which you can run on your cluster to install and configure the Mendix Operator.

The first script is the installation script which will install the Mendix operator and Mendix agent in your namespace. See Running the Installation Script, below for details.

Once that is done, you can run the second script which allows you to configure your namespace. See Running the Configuration Script, below for details.

3 Running the Installation Script

3.1 Signing in to OpenShift

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

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

To run the installation script on OpenShift, you must sign in to OpenShift using the OpenShift CLI, before you run the scripts in Bash.

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 Bash and press Enter.

3.2 Executing the Installation Script

To execute the installation script, do the following:

  1. Copy the Installation Script which has been created for you by clicking Copy to clipboard.

  2. Paste the script into your Bash console and press Enter to run the script.

The response to the script should look like the image below. You can see that the script has installed the following:

  • mendix-agent
  • mendix-operator

The installation is successful if the response ends with Installation Successful.

The Mendix operator and Mendix Gateway Agent are now installed on your platform. If you look at the project resources in the OpenShift console, you can see the mendix-operator resource.

You can always find the installation script again in the Installation tab for your namespace in the cluster manager.

4 Running the Configuration Script

Before you deploy an app to your namespace, you will need to configure a number of resources, namely:

  • database
  • file storage
  • proxy
  • registry
  • ingress (network)

Mendix provides you with a script which will configure these initially, and this can be re-run any time that you want to change how these are configured.

Before you start, you will need to be signed in with administration rights to the namespace.

  1. Copy the Configuration Script which has been created for you by clicking Copy to clipboard.

  2. Press Enter to start the script.

4.1 What Do You Want to Do?

Choose 1 if this is the initial configuration and you will be led through all the items which you need to configure.

Choose 2 if you have a configuration already but want to reconfigure part of it. If you choose this option, you will then be able to navigate directly to the thing you want to configure, namely one of the following:

  • Database
  • Storage
  • Ingress
  • Registry
  • Proxy
  • Custom TLS

When you reconfigure your namespace with databases or storage, you will add new services in addition to any services which are already configured. These plans are then added to the Developer Portal and can be used when creating environments for an app, unless you specifically deactivate them.

You can return to this initial question from any of the other questions by choosing the option Go back to the start where it is available.

4.2 Pick a Database Type

Postgres will enable you to enter the values to configure a PostgreSQL database. You will need to provide all the information about your PostgreSQL database such as plan name, host, port, database, user, and password.

Ephemeral will enable you to quickly set up your environment and deploy your app, but any data you store in the database will be lost when you restart your environment.

SQL Server will enable you to enter the values to configure a Microsoft SQL Server database. You will need to provide all the information about your SQL Server database such as plan name, host, port, user, and password.

Dedicated JDBC will enable you to enter the database configuration parameters for an existing database directly, as supported by the Mendix Runtime.

4.3 Pick a Storage Type

Minio will connect to a MinIO S3-compatible object storage. You will need to provide all the information about your MinIO storage such as endpoint, access key, and secret key. The MinIO server needs to be a full-featured MinIO server, or a MinIO Gateway with configured etcd.

S3 (create on-demand) will connect to an AWS account to create S3 buckets and associated IAM accounts. Each app will receive a dedicated S3 bucket and an IAM account which only has access to that specific S3 bucket. You will need to provide all the information about your Amazon S3 storage such as plan name, region, access key, and secret key. The associated IAM account needs to have the following IAM policy (replace <account_id> with your AWS account number):

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "bucketPermissions",
            "Effect": "Allow",
            "Action": [
                "s3:CreateBucket",
                "s3:DeleteBucket"
            ],
            "Resource": "arn:aws:s3:::mendix-*"
        },
        {
            "Sid": "iamPermissions",
            "Effect": "Allow",
            "Action": [
                "iam:DeleteAccessKey",
                "iam:PutUserPolicy",
                "iam:DeleteUserPolicy",
                "iam:DeleteUser",
                "iam:CreateUser",
                "iam:CreateAccessKey"
            ],
            "Resource": [
                "arn:aws:iam::<account_id>:user/mendix-*"
            ]
        }
    ]
}

S3 (existing bucket) will connect to an existing S3 bucket with the provided IAM account access key and secret keys. All apps will use the same S3 bucket and an IAM account. You will need to provide all the information about your Amazon S3 storage such as plan name, endpoint, access key, and secret key. The associated IAM account needs to have the following IAM policy (replace <bucket_name> with the your S3 bucket name):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:AbortMultipartUpload",
        "s3:DeleteObject",
        "s3:GetObject",
        "s3:ListMultipartUploadParts",
        "s3:PutObject"
      ],
      "Resource": [
        "arn:aws:s3:::<bucket_name>/*"
      ]
    }
  ]
}

Azure Blob storage Container (existing) will connect to an existing Azure Blob storage Container with the provided storage account name and key. All apps will use the same Container bucket and account credentials. You will need to provide all the information about your Azure Blob storage such as plan name, account name, account key, and container name.

Ephemeral will enable you to quickly set up your environment and deploy your app, but any data objects you store will be lost when you restart your environment.

4.4 Pick an Ingress Type

OpenShift Route will configure an OpenShift Route. This can only be used for OpenShift clusters.

Ingress will configure ingress according to the additional domain name you supply.

Both forms of ingress can have TLS enabled or disabled.

4.5 Pick a Registry Type

Selecting a registry type and configuring its credentials will configure the destination registry used by Mendix for Private Cloud to build images. Images are pulled from this registry by Kubernetes, bypassing the Mendix Operator.

You can choose one of the following registry types. OpenShift registries can only be used for clusters on the OpenShift platform. AWS ECR can only be used for AWS EKS clusters. For some of these registries you may need to supply additional information such as the pull URL, push URL, name, and secret.

  • OpenShift 3 Registry
  • OpenShift 4 Registry
  • Amazon Elastic Container Registry (AWS ECR)
  • Generic registry with authentication – this supports most registries, for example Azure Container Registry, quay.io, or Docker Hub
  • Generic registry without authentication – this can be used for basic, self-hosted registries such as the ones included with Minikube and MicroK8s
  • Existing docker-registry secret

Additional Information

For OpenShift 3 and OpenShift 4 registries, the default image pull credentials from the default ServiceAccount will be used. No additional configuration steps are required to enable image pulls in OpenShift.

For Generic registry… options, the configuration script will ask if the credentials should be added to imagePullSecrets in the default ServiceAccount. If you answer Yes, the configuration script will add image pull credentials to the default ServiceAccount - no additional image pull configuration is required. If you want to configure the image pull separately, choose No.

For Amazon Elastic Container Registry, you will need to configure registry authentication separately through IAM roles.

When choosing the Existing docker-registry secret, you will need to add this secret to the default ServiceAccount manually, or provide registry authentication configuration in another way (depending on which registry authentication options the Kubernetes cluster vendor is offering).

4.6 Do You Want to Configure the Proxy?

Choose Yes if a proxy is required to access the public internet from the namespace; you will be asked for the proxy configuration details.

4.7 Do you want to enable or disable custom TLS?

Choose Enable if additional custom CAs should be trusted by Mendix for Private Cloud in the namespace.

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:

      # 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. Use the name of this custom.crt Secret when asked for the custom ca-certificates secret name (for example, mendix-custom-ca).

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
Want to contribute to our documentation? Start here! Copyright © 2021 Mendix Technology B.V., documentation licensed under CC BY 4.0