From 282109cf0ccc207405871cb650a14721158cff1d Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 7 Oct 2026 16:44:26 +0200 Subject: [PATCH 1/7] Two new Portable documents --- .../pad/best-practices-k8s/_index.md | 450 ++++++++++++++++++ .../deploy-helm-portable.md} | 0 .../best-practices-k8s/migrate-portable.md | 446 +++++++++++++++++ 3 files changed, 896 insertions(+) create mode 100644 content/en/docs/deployment/pad/best-practices-k8s/_index.md rename content/en/docs/deployment/pad/{kubernetes-pad.md => best-practices-k8s/deploy-helm-portable.md} (100%) create mode 100644 content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md diff --git a/content/en/docs/deployment/pad/best-practices-k8s/_index.md b/content/en/docs/deployment/pad/best-practices-k8s/_index.md new file mode 100644 index 00000000000..19836231f12 --- /dev/null +++ b/content/en/docs/deployment/pad/best-practices-k8s/_index.md @@ -0,0 +1,450 @@ +--- +title: "Best practices for Kubernetes" +url: /developerportal/deploy/docker-deploy-k8s/ +weight: 60 +description: "Describes how to use Mendix Portable Runtime to deploy on Kubernetes without installing the Mendix Operator." +no_list: false +description_list: true +--- + +## Introduction + +This guide provides a walkthrough for deploying your Mendix application using [Mendix Portable Runtime](/developerportal/deploy/portable-app-distribution-deploy/) with Kubernetes, but without relying on the Mendix Operator. This is particularly useful for air-gapped environments, private cloud deployments, or scenarios where you need full control over the deployment process. + +{{% alert color="info" %}} +This document is not an official Mendix implementation, or a substitute for recommended production deployment strategies. For more features, such as app management or governance, we suggest using [Mendix on Kubernetes](/developerportal/deploy/private-cloud/) or [Mendix on Azure](/developerportal/deploy/mendix-on-azure/), which offer a structured, tested experience with cloud infrastructure. + +For information about the scope of support, see [Support for Different Deployment Strategies](/support/deployment-strategy-support/). +{{% /alert %}} + +## Benefits of Mendix Portable Runtime + +Mendix Portable Runtime revolutionizes the way in which Mendix applications are packaged and delivered. This innovative approach bundles your application code with all its necessary dependencies into a single, self-contained, and runnable artifact. This greatly simplifies the deployment of Mendix applications, whether you are targeting on-premise infrastructure or modern containerized environments like Docker, making the entire process more efficient and seamless. + +The ability to generate a Mendix Portable Runtime with a single build command means that creating a Docker-ready artifact becomes a streamlined process, making the overall integration into existing Docker-based CI/CD pipelines more efficient and less prone to errors. + +The Mendix Portable Runtime feature allows you to package and deploy Mendix apps without relying on the Mendix Cloud or a Mendix Operator. This is particularly useful for the following use cases: + +* Air-gapped environments where internet access is restricted or unavailable +* Private cloud deployments where you manage your own infrastructure +* Full control scenarios where you need complete ownership of the deployment pipeline + +Docker provides a consistent and reproducible environment for running Mendix apps, making it ideal for cloud-native and containerized deployments. + +Mendix Portable Runtime offers a more agile, user-centric, and efficient deployment ecosystem, empowering customers with greater control over their Docker deployments and simplifying the internal deployment processes. + +## Prerequisites + +Before you begin, ensure you have the following: + +* A Portable Package [created from your Mendix app](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file) +* Docker installed on your system +* Access to a container registry +* Kubernetes cluster (if deploying to Kubernetes) +* `kubectl` configured to connect to your Kubernetes cluster + +## Deploying an App with Mendix Portable Runtime + +The Mendix Portable Runtime feature in Mendix Studio Pro provides you with the necessary application files to build a Docker image. It packages your Mendix application as a self-contained distribution, ready for integration into your Docker environment. + +To deploy your app to Docker, you must [create a Mendix Portable Runtime Package](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file), build a Docker image, and then deploy the Docker image (including pushing it to a container registry). For more information, refer to the sections below. + +### Building a Docker Image + +To build a Docker image from the Portable Package, perform the following steps: + +1. Extract the Portable Package to a directory of your choice. +2. Create a Dockerfile in the extracted directory. For more information, see [Building a Docker Image](/developerportal/deploy/docker-deploy-pad/#building-a-docker-image). +3. Build the Docker image by using the following command: `docker build -t : .`, where `` and `` indicate your required image name and version tag (for example, `my-mendix-app:1.0.0`). + +### Pushing the Docker Image + +To push the Docker image to a container registry, perform the following steps: + +1. Log in to your container registry by running the following command: `docker login `. +2. Tag the Docker image with the registry URL by running the following command: `docker tag : /:`. +3. Push the Docker image to the registry by running the following command: `docker push /:`. + +### Deploying the Docker Image + +Once the Docker image is available in your container registry, you can deploy it to Kubernetes by applying the following .yaml files. The .yaml files must be organized in a folder, for example, *k8s/*. You must apply them in the same order as below. + +#### Creating a Namespace + +Create a namespace by performing the following steps: + +1. Create a file named, for example, *namespace.yaml*, with contents like the following: + + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: mendix-app + ``` + +2. Apply the file by running the following command: `kubectl apply -f namespace.yaml`. + + Replace the name and path of the file as required. + +#### Creating a Kubernetes Secret + +Store all sensitive values in a Kubernetes Secret by performing the following steps: + +1. Create a file named, for example, *secret.yaml*, with the contents like the following: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: mendix-secret + namespace: mendix-app + type: Opaque + stringData: + RUNTIME_PARAMS_DATABASEJDBCURL: "postgresql://mendix:mendix@postgres:5432/mendix" # Defines the JDBC URL to use for the database connection (which overrides the other database connection settings). + RUNTIME_PARAMS_DATABASETYPE: "PostgreSQL" + RUNTIME_PARAMS_DATABASEHOST: "postgresEndpointURL" #This will be overridden if you supply DatabaseJdbcUrl. + RUNTIME_PARAMS_DATABASENAME: "" + RUNTIME_PARAMS_DATABASEUSERNAME: "" + RUNTIME_PARAMS_DATABASEPASSWORD: "" + RUNTIME_ADMINUSER_PASSWORD: "" + RUNTIME_PARAMS_LICENSE_LICENSE_ID: "" + RUNTIME_PARAMS_LICENSE_LICENSE_KEY: "" + ``` + +2. Apply the file by running the following command: `kubectl apply -f secret.yaml`. + + Replace the name and path of the file as required. + +##### Security Recommendations + +By default, Kubernetes secrets are stored in the cluster's datastore (`etcd`). Although secret values are Base64-encoded, they are not encrypted by default and anyone with sufficient access to `etcd` or the Kubernetes API can read them. + +For production deployments, configure Encryption at Rest for Kubernetes Secrets. This ensures that sensitive information such as database credentials, license keys, and administrator passwords is encrypted before it is stored in `etcd`. + +Common approaches include the following: + +* AWS EKS - Use AWS KMS for envelope encryption of Kubernetes Secrets. +* Azure AKS - Enable Secret encryption using Azure Key Vault and a customer-managed key (CMK) or the AKS Secret encryption feature. +* Google GKE - Configure Application-layer Secrets Encryption using Cloud KMS. +* Self-managed Kubernetes clusters - Configure an `EncryptionConfiguration` file for the API server and use a supported provider such as AES-CBC, Secretbox, or an external KMS provider. + +In addition, consider storing highly sensitive credentials in an external secrets management solution such as the followings: + +* AWS Secrets Manager +* Azure Key Vault +* Google Secret Manager +* HashiCorp Vault + +These solutions can be integrated with Kubernetes using the External Secrets Operator or the Secrets Store CSI Driver, reducing the need to store long-lived credentials directly in Kubernetes Secrets. For environments that require strict security or compliance controls, Mendix recommends enabling secret encryption at rest and following your organization's key management policies. + +#### Using a ConfigMap + +The previous section showed how to load secrets as environment variables. For other properties that need to be changed and are not defined in a secret, you can pass constants and variables using a ConfigMap by mounting them as files (similar to mounting files in Docker) and by passing them directly as environment variables. + +The following is a sample command to create a ConfigMap: `kubectl create configmap my-config --from-file=default.conf --from-file=custom.conf --from-file=variables.conf -n mendix-app`. + +Configuration values such as the admin user password, license key, and custom runtime settings are provided in the *custom.conf* and *variables.conf* files. These files must be included in the [Configuration File](/developerportal/deploy/portable-app-distribution-deploy/best-practices/). + +#### Configuring Deployment + +Create a Kubernetes Deployment for your Mendix app by performing the following steps: + +1. Create a file named, for example, *deployment.yaml*, with the contents like the following: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: mendix-app + namespace: mendix-app + spec: + replicas: 1 + selector: + matchLabels: + app: mendix-app + template: + metadata: + labels: + app: mendix-app + spec: + containers: + - name: mendix-app + image: /: + ports: + - containerPort: 8080 + - containerPort: 8090 + envFrom: + - secretRef: + name: mendix-secret + resources: + requests: + memory: "512Mi" + cpu: "250m" + limits: + memory: "1Gi" + cpu: "500m" + # Use this if you have health checks enabled. + # livenessProbe: + # httpGet: + # path: /health/live + # port: 8080 + # initialDelaySeconds: 60 + # periodSeconds: 10 + #readinessProbe: + # httpGet: + # path: /health/ready + # port: 8080 + # initialDelaySeconds: 30 + # periodSeconds: 10 + + # If passing a ConfigMap + # volumeMounts: + # - name: config-volume + # mountPath: /opt/app/etc/ + # readOnly: true + # volumes: + # - name: config-volume + # configMap: + # name: my-config + ``` + +2. Apply the file by running the following command: `kubectl apply -f deployment.yaml`. + + Replace the name and path of the file as required. + +#### Configuring the Service + +Create a Kubernetes Service to expose your Mendix app by performing the following steps: + +1. Create a file named, for example, *service.yaml*, with the contents like the following: + + ```yaml + apiVersion: v1 + kind: Service + metadata: + name: mendix-app-service + namespace: mendix-app + spec: + selector: + app: mendix-app + ports: + - name: http + protocol: TCP + port: 80 + targetPort: 8080 + - name: admin + protocol: TCP + port: 8090 + targetPort: 8090 + type: ClusterIP + ``` + +2. Apply the file by running the following command: `kubectl apply -f service.yaml`. + + Replace the name and path of the file as required. + +#### Configuring the Ingress + +Create a Kubernetes Ingress to expose your Mendix app to the outside world by performing the following steps: + +1. Create a file named, for example, *ingress.yaml*, with the contents like the following: + + ```yaml + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: mendix-app-ingress + namespace: mendix-app + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / + spec: + rules: + - host: + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: mendix-app-service + port: + number: 80 + ``` + +2. Apply the file by running the following command: `kubectl apply -f ingress.yaml`. + + Replace the name and path of the file as required. + +### Configuring Storage + +The following sections explain how to configure storage for your Mendix app on Kubernetes. + +#### Local Storage + +By default, the Mendix Runtime uses local storage. However, in a Kubernetes environment, local storage is not persistent. To use persistent storage, you can use a Persistent Volume Claim (PVC). + +1. Create a file named, for example, *k8s/pvc.yaml*, with the contents like the following: + + ```yaml + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: mendix-storage + namespace: mendix-app + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + ``` + +2. Apply the file by running the following command: `kubectl apply -f k8s/pvc.yaml`. + + Replace the name and path of the file as required. + +3. Update the Deployment to mount the PVC: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: mendix-app + namespace: mendix-app + spec: + replicas: 1 + selector: + matchLabels: + app: mendix-app + template: + metadata: + labels: + app: mendix-app + spec: + containers: + - name: mendix-app + image: /: + ports: + - containerPort: 8080 + - containerPort: 8090 + envFrom: + - secretRef: + name: mendix-secret + env: + - name: MENDIX_STORAGE_TYPE + value: "local" + - name: MENDIX_STORAGE_PATH + value: "/data" + volumeMounts: + - name: mendix-storage + mountPath: /data + resources: + requests: + memory: "512Mi" + cpu: "250m" + limits: + memory: "1Gi" + cpu: "500m" + livenessProbe: + httpGet: + path: /health/live + port: 8080 + initialDelaySeconds: 60 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /health/ready + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + volumes: + - name: mendix-storage + persistentVolumeClaim: + claimName: mendix-storage + ``` + +#### S3 Storage + +To use S3-compatible storage, set the following environment variables: + +```text +env: + - name: RUNTIME_COM_PARAMS_MENDIX_CORE_STORAGESERVICE + value: "com.mendix.storage.s3" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ENDPOINT + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_BUCKETNAME + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION + value: "" + ... + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY +``` + +#### Azure Blob Storage + +To use Azure BlobStorage, set the following environment variables: + +```text +env: + - name: RUNTIME_PARAMS_COM_MENDIX_CORE_STORAGESERVICE + value: "com.mendix.storage.azure" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_BLOBENDPOINT + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_CONTAINER + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION + value: "" + ... + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY +``` + +## Troubleshooting + +If you encounter issues, use the following troubleshooting tips to help you solve them. + +### App Does Not Start + +If the app does not start, check the logs of the pod: + +```text +kubectl logs -n mendix-app +``` + +### App Is Not Accessible + +If the app is not accessible, check the status of the pod, service, and ingress: + +```text +kubectl get pods -n mendix-app +kubectl get services -n mendix-app +kubectl get ingress -n mendix-app +``` + +### Database Connection Issues + +If the app cannot connect to the database, check the database credentials in the secret: + +```text +kubectl get secret mendix-secret -n mendix-app -o yaml +``` + +## Read More diff --git a/content/en/docs/deployment/pad/kubernetes-pad.md b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md similarity index 100% rename from content/en/docs/deployment/pad/kubernetes-pad.md rename to content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md diff --git a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md new file mode 100644 index 00000000000..1c93d78a728 --- /dev/null +++ b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md @@ -0,0 +1,446 @@ +--- +title: "Best practices for Kubernetes" +url: /developerportal/deploy/docker-deploy-k8s/ +weight: 60 +description: "Describes how to use Mendix Portable Runtime to deploy on Kubernetes without installing the Mendix Operator." +--- + +## Introduction + +This guide provides a walkthrough for deploying your Mendix application using [Mendix Portable Runtime](/developerportal/deploy/portable-app-distribution-deploy/) with Kubernetes, but without relying on the Mendix Operator. This is particularly useful for air-gapped environments, private cloud deployments, or scenarios where you need full control over the deployment process. + +{{% alert color="info" %}} +This document is not an official Mendix implementation, or a substitute for recommended production deployment strategies. For more features, such as app management or governance, we suggest using [Mendix on Kubernetes](/developerportal/deploy/private-cloud/) or [Mendix on Azure](/developerportal/deploy/mendix-on-azure/), which offer a structured, tested experience with cloud infrastructure. + +For information about the scope of support, see [Support for Different Deployment Strategies](/support/deployment-strategy-support/). +{{% /alert %}} + +## Benefits of Mendix Portable Runtime + +Mendix Portable Runtime revolutionizes the way in which Mendix applications are packaged and delivered. This innovative approach bundles your application code with all its necessary dependencies into a single, self-contained, and runnable artifact. This greatly simplifies the deployment of Mendix applications, whether you are targeting on-premise infrastructure or modern containerized environments like Docker, making the entire process more efficient and seamless. + +The ability to generate a Mendix Portable Runtime with a single build command means that creating a Docker-ready artifact becomes a streamlined process, making the overall integration into existing Docker-based CI/CD pipelines more efficient and less prone to errors. + +The Mendix Portable Runtime feature allows you to package and deploy Mendix apps without relying on the Mendix Cloud or a Mendix Operator. This is particularly useful for the following use cases: + +* Air-gapped environments where internet access is restricted or unavailable +* Private cloud deployments where you manage your own infrastructure +* Full control scenarios where you need complete ownership of the deployment pipeline + +Docker provides a consistent and reproducible environment for running Mendix apps, making it ideal for cloud-native and containerized deployments. + +Mendix Portable Runtime offers a more agile, user-centric, and efficient deployment ecosystem, empowering customers with greater control over their Docker deployments and simplifying the internal deployment processes. + +## Prerequisites + +Before you begin, ensure you have the following: + +* A Portable Package [created from your Mendix app](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file) +* Docker installed on your system +* Access to a container registry +* Kubernetes cluster (if deploying to Kubernetes) +* `kubectl` configured to connect to your Kubernetes cluster + +## Deploying an App with Mendix Portable Runtime + +The Mendix Portable Runtime feature in Mendix Studio Pro provides you with the necessary application files to build a Docker image. It packages your Mendix application as a self-contained distribution, ready for integration into your Docker environment. + +To deploy your app to Docker, you must [create a Mendix Portable Runtime Package](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file), build a Docker image, and then deploy the Docker image (including pushing it to a container registry). For more information, refer to the sections below. + +### Building a Docker Image + +To build a Docker image from the Portable Package, perform the following steps: + +1. Extract the Portable Package to a directory of your choice. +2. Create a Dockerfile in the extracted directory. For more information, see [Building a Docker Image](/developerportal/deploy/docker-deploy-pad/#building-a-docker-image). +3. Build the Docker image by using the following command: `docker build -t : .`, where `` and `` indicate your required image name and version tag (for example, `my-mendix-app:1.0.0`). + +### Pushing the Docker Image + +To push the Docker image to a container registry, perform the following steps: + +1. Log in to your container registry by running the following command: `docker login `. +2. Tag the Docker image with the registry URL by running the following command: `docker tag : /:`. +3. Push the Docker image to the registry by running the following command: `docker push /:`. + +### Deploying the Docker Image + +Once the Docker image is available in your container registry, you can deploy it to Kubernetes by applying the following .yaml files. The .yaml files must be organized in a folder, for example, *k8s/*. You must apply them in the same order as below. + +#### Creating a Namespace + +Create a namespace by performing the following steps: + +1. Create a file named, for example, *namespace.yaml*, with contents like the following: + + ```yaml + apiVersion: v1 + kind: Namespace + metadata: + name: mendix-app + ``` + +2. Apply the file by running the following command: `kubectl apply -f namespace.yaml`. + + Replace the name and path of the file as required. + +#### Creating a Kubernetes Secret + +Store all sensitive values in a Kubernetes Secret by performing the following steps: + +1. Create a file named, for example, *secret.yaml*, with the contents like the following: + + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: mendix-secret + namespace: mendix-app + type: Opaque + stringData: + RUNTIME_PARAMS_DATABASEJDBCURL: "postgresql://mendix:mendix@postgres:5432/mendix" # Defines the JDBC URL to use for the database connection (which overrides the other database connection settings). + RUNTIME_PARAMS_DATABASETYPE: "PostgreSQL" + RUNTIME_PARAMS_DATABASEHOST: "postgresEndpointURL" #This will be overridden if you supply DatabaseJdbcUrl. + RUNTIME_PARAMS_DATABASENAME: "" + RUNTIME_PARAMS_DATABASEUSERNAME: "" + RUNTIME_PARAMS_DATABASEPASSWORD: "" + RUNTIME_ADMINUSER_PASSWORD: "" + RUNTIME_PARAMS_LICENSE_LICENSE_ID: "" + RUNTIME_PARAMS_LICENSE_LICENSE_KEY: "" + ``` + +2. Apply the file by running the following command: `kubectl apply -f secret.yaml`. + + Replace the name and path of the file as required. + +##### Security Recommendations + +By default, Kubernetes secrets are stored in the cluster's datastore (`etcd`). Although secret values are Base64-encoded, they are not encrypted by default and anyone with sufficient access to `etcd` or the Kubernetes API can read them. + +For production deployments, configure Encryption at Rest for Kubernetes Secrets. This ensures that sensitive information such as database credentials, license keys, and administrator passwords is encrypted before it is stored in `etcd`. + +Common approaches include the following: + +* AWS EKS - Use AWS KMS for envelope encryption of Kubernetes Secrets. +* Azure AKS - Enable Secret encryption using Azure Key Vault and a customer-managed key (CMK) or the AKS Secret encryption feature. +* Google GKE - Configure Application-layer Secrets Encryption using Cloud KMS. +* Self-managed Kubernetes clusters - Configure an `EncryptionConfiguration` file for the API server and use a supported provider such as AES-CBC, Secretbox, or an external KMS provider. + +In addition, consider storing highly sensitive credentials in an external secrets management solution such as the followings: + +* AWS Secrets Manager +* Azure Key Vault +* Google Secret Manager +* HashiCorp Vault + +These solutions can be integrated with Kubernetes using the External Secrets Operator or the Secrets Store CSI Driver, reducing the need to store long-lived credentials directly in Kubernetes Secrets. For environments that require strict security or compliance controls, Mendix recommends enabling secret encryption at rest and following your organization's key management policies. + +#### Using a ConfigMap + +The previous section showed how to load secrets as environment variables. For other properties that need to be changed and are not defined in a secret, you can pass constants and variables using a ConfigMap by mounting them as files (similar to mounting files in Docker) and by passing them directly as environment variables. + +The following is a sample command to create a ConfigMap: `kubectl create configmap my-config --from-file=default.conf --from-file=custom.conf --from-file=variables.conf -n mendix-app`. + +Configuration values such as the admin user password, license key, and custom runtime settings are provided in the *custom.conf* and *variables.conf* files. These files must be included in the [Configuration File](/developerportal/deploy/portable-app-distribution-deploy/best-practices/). + +#### Configuring Deployment + +Create a Kubernetes Deployment for your Mendix app by performing the following steps: + +1. Create a file named, for example, *deployment.yaml*, with the contents like the following: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: mendix-app + namespace: mendix-app + spec: + replicas: 1 + selector: + matchLabels: + app: mendix-app + template: + metadata: + labels: + app: mendix-app + spec: + containers: + - name: mendix-app + image: /: + ports: + - containerPort: 8080 + - containerPort: 8090 + envFrom: + - secretRef: + name: mendix-secret + resources: + requests: + memory: "512Mi" + cpu: "250m" + limits: + memory: "1Gi" + cpu: "500m" + # Use this if you have health checks enabled. + # livenessProbe: + # httpGet: + # path: /health/live + # port: 8080 + # initialDelaySeconds: 60 + # periodSeconds: 10 + #readinessProbe: + # httpGet: + # path: /health/ready + # port: 8080 + # initialDelaySeconds: 30 + # periodSeconds: 10 + + # If passing a ConfigMap + # volumeMounts: + # - name: config-volume + # mountPath: /opt/app/etc/ + # readOnly: true + # volumes: + # - name: config-volume + # configMap: + # name: my-config + ``` + +2. Apply the file by running the following command: `kubectl apply -f deployment.yaml`. + + Replace the name and path of the file as required. + +#### Configuring the Service + +Create a Kubernetes Service to expose your Mendix app by performing the following steps: + +1. Create a file named, for example, *service.yaml*, with the contents like the following: + + ```yaml + apiVersion: v1 + kind: Service + metadata: + name: mendix-app-service + namespace: mendix-app + spec: + selector: + app: mendix-app + ports: + - name: http + protocol: TCP + port: 80 + targetPort: 8080 + - name: admin + protocol: TCP + port: 8090 + targetPort: 8090 + type: ClusterIP + ``` + +2. Apply the file by running the following command: `kubectl apply -f service.yaml`. + + Replace the name and path of the file as required. + +#### Configuring the Ingress + +Create a Kubernetes Ingress to expose your Mendix app to the outside world by performing the following steps: + +1. Create a file named, for example, *ingress.yaml*, with the contents like the following: + + ```yaml + apiVersion: networking.k8s.io/v1 + kind: Ingress + metadata: + name: mendix-app-ingress + namespace: mendix-app + annotations: + nginx.ingress.kubernetes.io/rewrite-target: / + spec: + rules: + - host: + http: + paths: + - path: / + pathType: Prefix + backend: + service: + name: mendix-app-service + port: + number: 80 + ``` + +2. Apply the file by running the following command: `kubectl apply -f ingress.yaml`. + + Replace the name and path of the file as required. + +### Configuring Storage + +The following sections explain how to configure storage for your Mendix app on Kubernetes. + +#### Local Storage + +By default, the Mendix Runtime uses local storage. However, in a Kubernetes environment, local storage is not persistent. To use persistent storage, you can use a Persistent Volume Claim (PVC). + +1. Create a file named, for example, *k8s/pvc.yaml*, with the contents like the following: + + ```yaml + apiVersion: v1 + kind: PersistentVolumeClaim + metadata: + name: mendix-storage + namespace: mendix-app + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi + ``` + +2. Apply the file by running the following command: `kubectl apply -f k8s/pvc.yaml`. + + Replace the name and path of the file as required. + +3. Update the Deployment to mount the PVC: + + ```yaml + apiVersion: apps/v1 + kind: Deployment + metadata: + name: mendix-app + namespace: mendix-app + spec: + replicas: 1 + selector: + matchLabels: + app: mendix-app + template: + metadata: + labels: + app: mendix-app + spec: + containers: + - name: mendix-app + image: /: + ports: + - containerPort: 8080 + - containerPort: 8090 + envFrom: + - secretRef: + name: mendix-secret + env: + - name: MENDIX_STORAGE_TYPE + value: "local" + - name: MENDIX_STORAGE_PATH + value: "/data" + volumeMounts: + - name: mendix-storage + mountPath: /data + resources: + requests: + memory: "512Mi" + cpu: "250m" + limits: + memory: "1Gi" + cpu: "500m" + livenessProbe: + httpGet: + path: /health/live + port: 8080 + initialDelaySeconds: 60 + periodSeconds: 10 + readinessProbe: + httpGet: + path: /health/ready + port: 8080 + initialDelaySeconds: 30 + periodSeconds: 10 + volumes: + - name: mendix-storage + persistentVolumeClaim: + claimName: mendix-storage + ``` + +#### S3 Storage + +To use S3-compatible storage, set the following environment variables: + +```text +env: + - name: RUNTIME_COM_PARAMS_MENDIX_CORE_STORAGESERVICE + value: "com.mendix.storage.s3" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ENDPOINT + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_BUCKETNAME + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION + value: "" + ... + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY +``` + +#### Azure Blob Storage + +To use Azure BlobStorage, set the following environment variables: + +```text +env: + - name: RUNTIME_PARAMS_COM_MENDIX_CORE_STORAGESERVICE + value: "com.mendix.storage.azure" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_BLOBENDPOINT + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_CONTAINER + value: "" + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION + value: "" + ... + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT + - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY + valueFrom: + secretKeyRef: + name: mendix-secret + key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY +``` + +## Troubleshooting + +If you encounter issues, use the following troubleshooting tips to help you solve them. + +### App Does Not Start + +If the app does not start, check the logs of the pod: + +```text +kubectl logs -n mendix-app +``` + +### App Is Not Accessible + +If the app is not accessible, check the status of the pod, service, and ingress: + +```text +kubectl get pods -n mendix-app +kubectl get services -n mendix-app +kubectl get ingress -n mendix-app +``` + +### Database Connection Issues + +If the app cannot connect to the database, check the database credentials in the secret: + +```text +kubectl get secret mendix-secret -n mendix-app -o yaml +``` From 184745801363cd09d112110695067f7af0bfe89e Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 7 Oct 2026 16:50:27 +0200 Subject: [PATCH 2/7] draft --- .../deploy-helm-portable.md | 446 +----------------- .../best-practices-k8s/migrate-portable.md | 446 +----------------- 2 files changed, 10 insertions(+), 882 deletions(-) diff --git a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md index 1c93d78a728..ed96b8f9c25 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md @@ -1,446 +1,10 @@ --- -title: "Best practices for Kubernetes" -url: /developerportal/deploy/docker-deploy-k8s/ -weight: 60 -description: "Describes how to use Mendix Portable Runtime to deploy on Kubernetes without installing the Mendix Operator." +title: "Deploying Mendix Portable Runtime Using Helm Charts" +linktitle: "Helm Chart Deployment" +url: /developerportal/deploy/deploy-helm-portable/ +weight: 30 +description: "Describes how to deploy Mendix Portable Runtime with Helm charts." --- ## Introduction -This guide provides a walkthrough for deploying your Mendix application using [Mendix Portable Runtime](/developerportal/deploy/portable-app-distribution-deploy/) with Kubernetes, but without relying on the Mendix Operator. This is particularly useful for air-gapped environments, private cloud deployments, or scenarios where you need full control over the deployment process. - -{{% alert color="info" %}} -This document is not an official Mendix implementation, or a substitute for recommended production deployment strategies. For more features, such as app management or governance, we suggest using [Mendix on Kubernetes](/developerportal/deploy/private-cloud/) or [Mendix on Azure](/developerportal/deploy/mendix-on-azure/), which offer a structured, tested experience with cloud infrastructure. - -For information about the scope of support, see [Support for Different Deployment Strategies](/support/deployment-strategy-support/). -{{% /alert %}} - -## Benefits of Mendix Portable Runtime - -Mendix Portable Runtime revolutionizes the way in which Mendix applications are packaged and delivered. This innovative approach bundles your application code with all its necessary dependencies into a single, self-contained, and runnable artifact. This greatly simplifies the deployment of Mendix applications, whether you are targeting on-premise infrastructure or modern containerized environments like Docker, making the entire process more efficient and seamless. - -The ability to generate a Mendix Portable Runtime with a single build command means that creating a Docker-ready artifact becomes a streamlined process, making the overall integration into existing Docker-based CI/CD pipelines more efficient and less prone to errors. - -The Mendix Portable Runtime feature allows you to package and deploy Mendix apps without relying on the Mendix Cloud or a Mendix Operator. This is particularly useful for the following use cases: - -* Air-gapped environments where internet access is restricted or unavailable -* Private cloud deployments where you manage your own infrastructure -* Full control scenarios where you need complete ownership of the deployment pipeline - -Docker provides a consistent and reproducible environment for running Mendix apps, making it ideal for cloud-native and containerized deployments. - -Mendix Portable Runtime offers a more agile, user-centric, and efficient deployment ecosystem, empowering customers with greater control over their Docker deployments and simplifying the internal deployment processes. - -## Prerequisites - -Before you begin, ensure you have the following: - -* A Portable Package [created from your Mendix app](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file) -* Docker installed on your system -* Access to a container registry -* Kubernetes cluster (if deploying to Kubernetes) -* `kubectl` configured to connect to your Kubernetes cluster - -## Deploying an App with Mendix Portable Runtime - -The Mendix Portable Runtime feature in Mendix Studio Pro provides you with the necessary application files to build a Docker image. It packages your Mendix application as a self-contained distribution, ready for integration into your Docker environment. - -To deploy your app to Docker, you must [create a Mendix Portable Runtime Package](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file), build a Docker image, and then deploy the Docker image (including pushing it to a container registry). For more information, refer to the sections below. - -### Building a Docker Image - -To build a Docker image from the Portable Package, perform the following steps: - -1. Extract the Portable Package to a directory of your choice. -2. Create a Dockerfile in the extracted directory. For more information, see [Building a Docker Image](/developerportal/deploy/docker-deploy-pad/#building-a-docker-image). -3. Build the Docker image by using the following command: `docker build -t : .`, where `` and `` indicate your required image name and version tag (for example, `my-mendix-app:1.0.0`). - -### Pushing the Docker Image - -To push the Docker image to a container registry, perform the following steps: - -1. Log in to your container registry by running the following command: `docker login `. -2. Tag the Docker image with the registry URL by running the following command: `docker tag : /:`. -3. Push the Docker image to the registry by running the following command: `docker push /:`. - -### Deploying the Docker Image - -Once the Docker image is available in your container registry, you can deploy it to Kubernetes by applying the following .yaml files. The .yaml files must be organized in a folder, for example, *k8s/*. You must apply them in the same order as below. - -#### Creating a Namespace - -Create a namespace by performing the following steps: - -1. Create a file named, for example, *namespace.yaml*, with contents like the following: - - ```yaml - apiVersion: v1 - kind: Namespace - metadata: - name: mendix-app - ``` - -2. Apply the file by running the following command: `kubectl apply -f namespace.yaml`. - - Replace the name and path of the file as required. - -#### Creating a Kubernetes Secret - -Store all sensitive values in a Kubernetes Secret by performing the following steps: - -1. Create a file named, for example, *secret.yaml*, with the contents like the following: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: mendix-secret - namespace: mendix-app - type: Opaque - stringData: - RUNTIME_PARAMS_DATABASEJDBCURL: "postgresql://mendix:mendix@postgres:5432/mendix" # Defines the JDBC URL to use for the database connection (which overrides the other database connection settings). - RUNTIME_PARAMS_DATABASETYPE: "PostgreSQL" - RUNTIME_PARAMS_DATABASEHOST: "postgresEndpointURL" #This will be overridden if you supply DatabaseJdbcUrl. - RUNTIME_PARAMS_DATABASENAME: "" - RUNTIME_PARAMS_DATABASEUSERNAME: "" - RUNTIME_PARAMS_DATABASEPASSWORD: "" - RUNTIME_ADMINUSER_PASSWORD: "" - RUNTIME_PARAMS_LICENSE_LICENSE_ID: "" - RUNTIME_PARAMS_LICENSE_LICENSE_KEY: "" - ``` - -2. Apply the file by running the following command: `kubectl apply -f secret.yaml`. - - Replace the name and path of the file as required. - -##### Security Recommendations - -By default, Kubernetes secrets are stored in the cluster's datastore (`etcd`). Although secret values are Base64-encoded, they are not encrypted by default and anyone with sufficient access to `etcd` or the Kubernetes API can read them. - -For production deployments, configure Encryption at Rest for Kubernetes Secrets. This ensures that sensitive information such as database credentials, license keys, and administrator passwords is encrypted before it is stored in `etcd`. - -Common approaches include the following: - -* AWS EKS - Use AWS KMS for envelope encryption of Kubernetes Secrets. -* Azure AKS - Enable Secret encryption using Azure Key Vault and a customer-managed key (CMK) or the AKS Secret encryption feature. -* Google GKE - Configure Application-layer Secrets Encryption using Cloud KMS. -* Self-managed Kubernetes clusters - Configure an `EncryptionConfiguration` file for the API server and use a supported provider such as AES-CBC, Secretbox, or an external KMS provider. - -In addition, consider storing highly sensitive credentials in an external secrets management solution such as the followings: - -* AWS Secrets Manager -* Azure Key Vault -* Google Secret Manager -* HashiCorp Vault - -These solutions can be integrated with Kubernetes using the External Secrets Operator or the Secrets Store CSI Driver, reducing the need to store long-lived credentials directly in Kubernetes Secrets. For environments that require strict security or compliance controls, Mendix recommends enabling secret encryption at rest and following your organization's key management policies. - -#### Using a ConfigMap - -The previous section showed how to load secrets as environment variables. For other properties that need to be changed and are not defined in a secret, you can pass constants and variables using a ConfigMap by mounting them as files (similar to mounting files in Docker) and by passing them directly as environment variables. - -The following is a sample command to create a ConfigMap: `kubectl create configmap my-config --from-file=default.conf --from-file=custom.conf --from-file=variables.conf -n mendix-app`. - -Configuration values such as the admin user password, license key, and custom runtime settings are provided in the *custom.conf* and *variables.conf* files. These files must be included in the [Configuration File](/developerportal/deploy/portable-app-distribution-deploy/best-practices/). - -#### Configuring Deployment - -Create a Kubernetes Deployment for your Mendix app by performing the following steps: - -1. Create a file named, for example, *deployment.yaml*, with the contents like the following: - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: mendix-app - namespace: mendix-app - spec: - replicas: 1 - selector: - matchLabels: - app: mendix-app - template: - metadata: - labels: - app: mendix-app - spec: - containers: - - name: mendix-app - image: /: - ports: - - containerPort: 8080 - - containerPort: 8090 - envFrom: - - secretRef: - name: mendix-secret - resources: - requests: - memory: "512Mi" - cpu: "250m" - limits: - memory: "1Gi" - cpu: "500m" - # Use this if you have health checks enabled. - # livenessProbe: - # httpGet: - # path: /health/live - # port: 8080 - # initialDelaySeconds: 60 - # periodSeconds: 10 - #readinessProbe: - # httpGet: - # path: /health/ready - # port: 8080 - # initialDelaySeconds: 30 - # periodSeconds: 10 - - # If passing a ConfigMap - # volumeMounts: - # - name: config-volume - # mountPath: /opt/app/etc/ - # readOnly: true - # volumes: - # - name: config-volume - # configMap: - # name: my-config - ``` - -2. Apply the file by running the following command: `kubectl apply -f deployment.yaml`. - - Replace the name and path of the file as required. - -#### Configuring the Service - -Create a Kubernetes Service to expose your Mendix app by performing the following steps: - -1. Create a file named, for example, *service.yaml*, with the contents like the following: - - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: mendix-app-service - namespace: mendix-app - spec: - selector: - app: mendix-app - ports: - - name: http - protocol: TCP - port: 80 - targetPort: 8080 - - name: admin - protocol: TCP - port: 8090 - targetPort: 8090 - type: ClusterIP - ``` - -2. Apply the file by running the following command: `kubectl apply -f service.yaml`. - - Replace the name and path of the file as required. - -#### Configuring the Ingress - -Create a Kubernetes Ingress to expose your Mendix app to the outside world by performing the following steps: - -1. Create a file named, for example, *ingress.yaml*, with the contents like the following: - - ```yaml - apiVersion: networking.k8s.io/v1 - kind: Ingress - metadata: - name: mendix-app-ingress - namespace: mendix-app - annotations: - nginx.ingress.kubernetes.io/rewrite-target: / - spec: - rules: - - host: - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: mendix-app-service - port: - number: 80 - ``` - -2. Apply the file by running the following command: `kubectl apply -f ingress.yaml`. - - Replace the name and path of the file as required. - -### Configuring Storage - -The following sections explain how to configure storage for your Mendix app on Kubernetes. - -#### Local Storage - -By default, the Mendix Runtime uses local storage. However, in a Kubernetes environment, local storage is not persistent. To use persistent storage, you can use a Persistent Volume Claim (PVC). - -1. Create a file named, for example, *k8s/pvc.yaml*, with the contents like the following: - - ```yaml - apiVersion: v1 - kind: PersistentVolumeClaim - metadata: - name: mendix-storage - namespace: mendix-app - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi - ``` - -2. Apply the file by running the following command: `kubectl apply -f k8s/pvc.yaml`. - - Replace the name and path of the file as required. - -3. Update the Deployment to mount the PVC: - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: mendix-app - namespace: mendix-app - spec: - replicas: 1 - selector: - matchLabels: - app: mendix-app - template: - metadata: - labels: - app: mendix-app - spec: - containers: - - name: mendix-app - image: /: - ports: - - containerPort: 8080 - - containerPort: 8090 - envFrom: - - secretRef: - name: mendix-secret - env: - - name: MENDIX_STORAGE_TYPE - value: "local" - - name: MENDIX_STORAGE_PATH - value: "/data" - volumeMounts: - - name: mendix-storage - mountPath: /data - resources: - requests: - memory: "512Mi" - cpu: "250m" - limits: - memory: "1Gi" - cpu: "500m" - livenessProbe: - httpGet: - path: /health/live - port: 8080 - initialDelaySeconds: 60 - periodSeconds: 10 - readinessProbe: - httpGet: - path: /health/ready - port: 8080 - initialDelaySeconds: 30 - periodSeconds: 10 - volumes: - - name: mendix-storage - persistentVolumeClaim: - claimName: mendix-storage - ``` - -#### S3 Storage - -To use S3-compatible storage, set the following environment variables: - -```text -env: - - name: RUNTIME_COM_PARAMS_MENDIX_CORE_STORAGESERVICE - value: "com.mendix.storage.s3" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ENDPOINT - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_BUCKETNAME - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION - value: "" - ... - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY -``` - -#### Azure Blob Storage - -To use Azure BlobStorage, set the following environment variables: - -```text -env: - - name: RUNTIME_PARAMS_COM_MENDIX_CORE_STORAGESERVICE - value: "com.mendix.storage.azure" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_BLOBENDPOINT - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_CONTAINER - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION - value: "" - ... - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY -``` - -## Troubleshooting - -If you encounter issues, use the following troubleshooting tips to help you solve them. - -### App Does Not Start - -If the app does not start, check the logs of the pod: - -```text -kubectl logs -n mendix-app -``` - -### App Is Not Accessible - -If the app is not accessible, check the status of the pod, service, and ingress: - -```text -kubectl get pods -n mendix-app -kubectl get services -n mendix-app -kubectl get ingress -n mendix-app -``` - -### Database Connection Issues - -If the app cannot connect to the database, check the database credentials in the secret: - -```text -kubectl get secret mendix-secret -n mendix-app -o yaml -``` diff --git a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md index 1c93d78a728..0cf27a8f5f9 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md @@ -1,446 +1,10 @@ --- -title: "Best practices for Kubernetes" -url: /developerportal/deploy/docker-deploy-k8s/ -weight: 60 -description: "Describes how to use Mendix Portable Runtime to deploy on Kubernetes without installing the Mendix Operator." +title: "Migrate from Mendix on Kubernetes Standalone to Mendix Portable Runtime" +linktitle: "Migrate from Mendix on Kubernetes Standalone" +url: /developerportal/deploy/migrate-portable/ +weight: 20 +description: "Describes how you can migrate from Standalone Mendix on Kubernetes to Mendix Portable Runtime." --- ## Introduction -This guide provides a walkthrough for deploying your Mendix application using [Mendix Portable Runtime](/developerportal/deploy/portable-app-distribution-deploy/) with Kubernetes, but without relying on the Mendix Operator. This is particularly useful for air-gapped environments, private cloud deployments, or scenarios where you need full control over the deployment process. - -{{% alert color="info" %}} -This document is not an official Mendix implementation, or a substitute for recommended production deployment strategies. For more features, such as app management or governance, we suggest using [Mendix on Kubernetes](/developerportal/deploy/private-cloud/) or [Mendix on Azure](/developerportal/deploy/mendix-on-azure/), which offer a structured, tested experience with cloud infrastructure. - -For information about the scope of support, see [Support for Different Deployment Strategies](/support/deployment-strategy-support/). -{{% /alert %}} - -## Benefits of Mendix Portable Runtime - -Mendix Portable Runtime revolutionizes the way in which Mendix applications are packaged and delivered. This innovative approach bundles your application code with all its necessary dependencies into a single, self-contained, and runnable artifact. This greatly simplifies the deployment of Mendix applications, whether you are targeting on-premise infrastructure or modern containerized environments like Docker, making the entire process more efficient and seamless. - -The ability to generate a Mendix Portable Runtime with a single build command means that creating a Docker-ready artifact becomes a streamlined process, making the overall integration into existing Docker-based CI/CD pipelines more efficient and less prone to errors. - -The Mendix Portable Runtime feature allows you to package and deploy Mendix apps without relying on the Mendix Cloud or a Mendix Operator. This is particularly useful for the following use cases: - -* Air-gapped environments where internet access is restricted or unavailable -* Private cloud deployments where you manage your own infrastructure -* Full control scenarios where you need complete ownership of the deployment pipeline - -Docker provides a consistent and reproducible environment for running Mendix apps, making it ideal for cloud-native and containerized deployments. - -Mendix Portable Runtime offers a more agile, user-centric, and efficient deployment ecosystem, empowering customers with greater control over their Docker deployments and simplifying the internal deployment processes. - -## Prerequisites - -Before you begin, ensure you have the following: - -* A Portable Package [created from your Mendix app](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file) -* Docker installed on your system -* Access to a container registry -* Kubernetes cluster (if deploying to Kubernetes) -* `kubectl` configured to connect to your Kubernetes cluster - -## Deploying an App with Mendix Portable Runtime - -The Mendix Portable Runtime feature in Mendix Studio Pro provides you with the necessary application files to build a Docker image. It packages your Mendix application as a self-contained distribution, ready for integration into your Docker environment. - -To deploy your app to Docker, you must [create a Mendix Portable Runtime Package](/developerportal/deploy/portable-app-distribution-deploy/#creating-a-portable-app-distribution-file), build a Docker image, and then deploy the Docker image (including pushing it to a container registry). For more information, refer to the sections below. - -### Building a Docker Image - -To build a Docker image from the Portable Package, perform the following steps: - -1. Extract the Portable Package to a directory of your choice. -2. Create a Dockerfile in the extracted directory. For more information, see [Building a Docker Image](/developerportal/deploy/docker-deploy-pad/#building-a-docker-image). -3. Build the Docker image by using the following command: `docker build -t : .`, where `` and `` indicate your required image name and version tag (for example, `my-mendix-app:1.0.0`). - -### Pushing the Docker Image - -To push the Docker image to a container registry, perform the following steps: - -1. Log in to your container registry by running the following command: `docker login `. -2. Tag the Docker image with the registry URL by running the following command: `docker tag : /:`. -3. Push the Docker image to the registry by running the following command: `docker push /:`. - -### Deploying the Docker Image - -Once the Docker image is available in your container registry, you can deploy it to Kubernetes by applying the following .yaml files. The .yaml files must be organized in a folder, for example, *k8s/*. You must apply them in the same order as below. - -#### Creating a Namespace - -Create a namespace by performing the following steps: - -1. Create a file named, for example, *namespace.yaml*, with contents like the following: - - ```yaml - apiVersion: v1 - kind: Namespace - metadata: - name: mendix-app - ``` - -2. Apply the file by running the following command: `kubectl apply -f namespace.yaml`. - - Replace the name and path of the file as required. - -#### Creating a Kubernetes Secret - -Store all sensitive values in a Kubernetes Secret by performing the following steps: - -1. Create a file named, for example, *secret.yaml*, with the contents like the following: - - ```yaml - apiVersion: v1 - kind: Secret - metadata: - name: mendix-secret - namespace: mendix-app - type: Opaque - stringData: - RUNTIME_PARAMS_DATABASEJDBCURL: "postgresql://mendix:mendix@postgres:5432/mendix" # Defines the JDBC URL to use for the database connection (which overrides the other database connection settings). - RUNTIME_PARAMS_DATABASETYPE: "PostgreSQL" - RUNTIME_PARAMS_DATABASEHOST: "postgresEndpointURL" #This will be overridden if you supply DatabaseJdbcUrl. - RUNTIME_PARAMS_DATABASENAME: "" - RUNTIME_PARAMS_DATABASEUSERNAME: "" - RUNTIME_PARAMS_DATABASEPASSWORD: "" - RUNTIME_ADMINUSER_PASSWORD: "" - RUNTIME_PARAMS_LICENSE_LICENSE_ID: "" - RUNTIME_PARAMS_LICENSE_LICENSE_KEY: "" - ``` - -2. Apply the file by running the following command: `kubectl apply -f secret.yaml`. - - Replace the name and path of the file as required. - -##### Security Recommendations - -By default, Kubernetes secrets are stored in the cluster's datastore (`etcd`). Although secret values are Base64-encoded, they are not encrypted by default and anyone with sufficient access to `etcd` or the Kubernetes API can read them. - -For production deployments, configure Encryption at Rest for Kubernetes Secrets. This ensures that sensitive information such as database credentials, license keys, and administrator passwords is encrypted before it is stored in `etcd`. - -Common approaches include the following: - -* AWS EKS - Use AWS KMS for envelope encryption of Kubernetes Secrets. -* Azure AKS - Enable Secret encryption using Azure Key Vault and a customer-managed key (CMK) or the AKS Secret encryption feature. -* Google GKE - Configure Application-layer Secrets Encryption using Cloud KMS. -* Self-managed Kubernetes clusters - Configure an `EncryptionConfiguration` file for the API server and use a supported provider such as AES-CBC, Secretbox, or an external KMS provider. - -In addition, consider storing highly sensitive credentials in an external secrets management solution such as the followings: - -* AWS Secrets Manager -* Azure Key Vault -* Google Secret Manager -* HashiCorp Vault - -These solutions can be integrated with Kubernetes using the External Secrets Operator or the Secrets Store CSI Driver, reducing the need to store long-lived credentials directly in Kubernetes Secrets. For environments that require strict security or compliance controls, Mendix recommends enabling secret encryption at rest and following your organization's key management policies. - -#### Using a ConfigMap - -The previous section showed how to load secrets as environment variables. For other properties that need to be changed and are not defined in a secret, you can pass constants and variables using a ConfigMap by mounting them as files (similar to mounting files in Docker) and by passing them directly as environment variables. - -The following is a sample command to create a ConfigMap: `kubectl create configmap my-config --from-file=default.conf --from-file=custom.conf --from-file=variables.conf -n mendix-app`. - -Configuration values such as the admin user password, license key, and custom runtime settings are provided in the *custom.conf* and *variables.conf* files. These files must be included in the [Configuration File](/developerportal/deploy/portable-app-distribution-deploy/best-practices/). - -#### Configuring Deployment - -Create a Kubernetes Deployment for your Mendix app by performing the following steps: - -1. Create a file named, for example, *deployment.yaml*, with the contents like the following: - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: mendix-app - namespace: mendix-app - spec: - replicas: 1 - selector: - matchLabels: - app: mendix-app - template: - metadata: - labels: - app: mendix-app - spec: - containers: - - name: mendix-app - image: /: - ports: - - containerPort: 8080 - - containerPort: 8090 - envFrom: - - secretRef: - name: mendix-secret - resources: - requests: - memory: "512Mi" - cpu: "250m" - limits: - memory: "1Gi" - cpu: "500m" - # Use this if you have health checks enabled. - # livenessProbe: - # httpGet: - # path: /health/live - # port: 8080 - # initialDelaySeconds: 60 - # periodSeconds: 10 - #readinessProbe: - # httpGet: - # path: /health/ready - # port: 8080 - # initialDelaySeconds: 30 - # periodSeconds: 10 - - # If passing a ConfigMap - # volumeMounts: - # - name: config-volume - # mountPath: /opt/app/etc/ - # readOnly: true - # volumes: - # - name: config-volume - # configMap: - # name: my-config - ``` - -2. Apply the file by running the following command: `kubectl apply -f deployment.yaml`. - - Replace the name and path of the file as required. - -#### Configuring the Service - -Create a Kubernetes Service to expose your Mendix app by performing the following steps: - -1. Create a file named, for example, *service.yaml*, with the contents like the following: - - ```yaml - apiVersion: v1 - kind: Service - metadata: - name: mendix-app-service - namespace: mendix-app - spec: - selector: - app: mendix-app - ports: - - name: http - protocol: TCP - port: 80 - targetPort: 8080 - - name: admin - protocol: TCP - port: 8090 - targetPort: 8090 - type: ClusterIP - ``` - -2. Apply the file by running the following command: `kubectl apply -f service.yaml`. - - Replace the name and path of the file as required. - -#### Configuring the Ingress - -Create a Kubernetes Ingress to expose your Mendix app to the outside world by performing the following steps: - -1. Create a file named, for example, *ingress.yaml*, with the contents like the following: - - ```yaml - apiVersion: networking.k8s.io/v1 - kind: Ingress - metadata: - name: mendix-app-ingress - namespace: mendix-app - annotations: - nginx.ingress.kubernetes.io/rewrite-target: / - spec: - rules: - - host: - http: - paths: - - path: / - pathType: Prefix - backend: - service: - name: mendix-app-service - port: - number: 80 - ``` - -2. Apply the file by running the following command: `kubectl apply -f ingress.yaml`. - - Replace the name and path of the file as required. - -### Configuring Storage - -The following sections explain how to configure storage for your Mendix app on Kubernetes. - -#### Local Storage - -By default, the Mendix Runtime uses local storage. However, in a Kubernetes environment, local storage is not persistent. To use persistent storage, you can use a Persistent Volume Claim (PVC). - -1. Create a file named, for example, *k8s/pvc.yaml*, with the contents like the following: - - ```yaml - apiVersion: v1 - kind: PersistentVolumeClaim - metadata: - name: mendix-storage - namespace: mendix-app - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi - ``` - -2. Apply the file by running the following command: `kubectl apply -f k8s/pvc.yaml`. - - Replace the name and path of the file as required. - -3. Update the Deployment to mount the PVC: - - ```yaml - apiVersion: apps/v1 - kind: Deployment - metadata: - name: mendix-app - namespace: mendix-app - spec: - replicas: 1 - selector: - matchLabels: - app: mendix-app - template: - metadata: - labels: - app: mendix-app - spec: - containers: - - name: mendix-app - image: /: - ports: - - containerPort: 8080 - - containerPort: 8090 - envFrom: - - secretRef: - name: mendix-secret - env: - - name: MENDIX_STORAGE_TYPE - value: "local" - - name: MENDIX_STORAGE_PATH - value: "/data" - volumeMounts: - - name: mendix-storage - mountPath: /data - resources: - requests: - memory: "512Mi" - cpu: "250m" - limits: - memory: "1Gi" - cpu: "500m" - livenessProbe: - httpGet: - path: /health/live - port: 8080 - initialDelaySeconds: 60 - periodSeconds: 10 - readinessProbe: - httpGet: - path: /health/ready - port: 8080 - initialDelaySeconds: 30 - periodSeconds: 10 - volumes: - - name: mendix-storage - persistentVolumeClaim: - claimName: mendix-storage - ``` - -#### S3 Storage - -To use S3-compatible storage, set the following environment variables: - -```text -env: - - name: RUNTIME_COM_PARAMS_MENDIX_CORE_STORAGESERVICE - value: "com.mendix.storage.s3" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ENDPOINT - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_BUCKETNAME - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION - value: "" - ... - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_ACCESS_KEYID - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_SECRETACCESSKEY -``` - -#### Azure Blob Storage - -To use Azure BlobStorage, set the following environment variables: - -```text -env: - - name: RUNTIME_PARAMS_COM_MENDIX_CORE_STORAGESERVICE - value: "com.mendix.storage.azure" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_BLOBENDPOINT - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_CONTAINER - value: "" - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_S3_REGION - value: "" - ... - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNT - - name: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY - valueFrom: - secretKeyRef: - name: mendix-secret - key: RUNTIME_PARAMS_COM_MENDIX_STORAGE_AZURE_ACCOUNTKEY -``` - -## Troubleshooting - -If you encounter issues, use the following troubleshooting tips to help you solve them. - -### App Does Not Start - -If the app does not start, check the logs of the pod: - -```text -kubectl logs -n mendix-app -``` - -### App Is Not Accessible - -If the app is not accessible, check the status of the pod, service, and ingress: - -```text -kubectl get pods -n mendix-app -kubectl get services -n mendix-app -kubectl get ingress -n mendix-app -``` - -### Database Connection Issues - -If the app cannot connect to the database, check the database credentials in the secret: - -```text -kubectl get secret mendix-secret -n mendix-app -o yaml -``` From f248379d60af0b97eaf06ccf59f6d8f69d63a58a Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Wed, 7 Oct 2026 17:26:21 +0200 Subject: [PATCH 3/7] draft --- .../deploy-helm-portable.md | 191 ++++++++++++++++++ 1 file changed, 191 insertions(+) diff --git a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md index ed96b8f9c25..e8886f0a6e8 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md @@ -8,3 +8,194 @@ description: "Describes how to deploy Mendix Portable Runtime with Helm charts." ## Introduction +Starting with Mendix 12, Mendix on Kubernetes Standalone is deprecated. Customers running applications in private or disconnected Kubernetes environments should migrate to Mendix Portable Runtime as the recommended deployment model. This document provides guidance for migrating a Mendix application deployed using Mendix on Kubernetes Standalone to Mendix Portable Runtime deployed with Helm charts. + +Migrating from Mendix on Kubernetes Standalone to Mendix Portable Runtime primarily involves translating operator-managed configuration into Helm-based configuration. You can simplify this process by using an open-source migration utility to generate the initial Portable Runtime configuration, allowing organizations to accelerate adoption while retaining existing databases, storage, and application URLs where appropriate. + +{{% alert color="info" %}} +This migration approach is based on an open-source migration utility and Helm chart templates provided through the Mendix Labs GitHub repositories. These tools are intended as guidance and reference implementations and are not officially supported Mendix Platform features. Customers should validate the generated configuration before using it in production environments. +{{% /alert %}} + +## Differences Between Deployment Models +Mendix on Kubernetes Standalone +MxOnK8S uses an operator-driven deployment model where application configuration is managed through Kubernetes Custom Resource Definitions (CRDs). + +Mendix Portable Runtime +Mendix Portable Runtime uses a packaging-based deployment model. Applications are deployed using Kubernetes manifests and Helm charts, without requiring the Mendix Operator. Configuration, infrastructure resources, and secrets must be provided through the deployment package and Helm values. + +Migration Overview +The migration process consists of: + +Extracting application configuration from the existing MxOnK8S deployment. + +Mapping configuration to Mendix Portable Runtime settings. + +Generating a Helm values file. + +Creating required Kubernetes configuration resources. + +Deploying the application using the Portable Runtime Helm chart. + +The migration utility uses the existing Kubernetes Deployment resource as the source of truth and derives configuration from referenced resources such as ConfigMaps, Secrets, Services, and Ingress definitions. + +Prerequisites +Before starting the migration: + +Access to the existing Kubernetes cluster + +Permissions to read Kubernetes Deployments, Secrets, ConfigMaps, and related resources + +A generated Mendix Portable Runtime package for the target application + +Go installed if using the migration utility + +Helm installed for deployment + +Configuration Discovery +The migration utility analyses the existing deployment and identifies dependent resources. + +The following resource types are typically examined: + +ConfigMaps + +Secrets + +Persistent Volume Claims (PVCs) + +Service Accounts + +Services + +Ingresses or Routes + +Horizontal Pod Autoscalers (if applicable) + +Pod Disruption Budgets (if applicable) + +Resource Mapping +The following configuration mappings are commonly used during migration. + +Existing MxOnK8S Resource + +Portable Runtime Configuration + +-m2ee secret + +M2EE password secret reference + +-database secret + +Database secret reference + +-file secret + +Storage secret reference + +runtime-config/custom.json + +Application constants and custom settings + +runtime-config/runtime.json + +Runtime settings + +Existing Route/Ingress + +Recreated using same application URL + +Application Constants +Application constants are extracted from the existing runtime configuration and converted into the Portable Runtime custom configuration format. The migration references: + +etc/constants/variables.conf + +This file contains application-specific constants and settings. + +Runtime Settings +Runtime settings are mapped using: + +etc/variables.conf + +This file contains the runtime property definitions used by Portable Runtime. + +Database and Storage Credentials +Database and storage credentials are typically sourced from Kubernetes Secrets referenced by the existing deployment. + +These credentials can either: + +Be created directly through the Helm chart + +Be created separately and referenced from the generated values file + +Portable Runtime should continue to use the same database and storage location whenever possible. + +Application URL +To minimize changes for end users, reuse the same ingress or route URL that was used by the previous deployment. + +Before activating the new deployment, remove or update the existing ingress or route resource to avoid conflicts. + +Unsupported Configuration +Some runtime behaviours available through the Mendix Operator are not directly portable. + +For example: + +Liveness probes provided by the M2EE sidecar + +Readiness probes provided by the M2EE sidecar + +Portable Runtime deployments may require alternative probe definitions depending on the deployment environment. + +Using the Migration Utility +[!NOTE] The migration utility is an open-source reference tool distributed through a Mendix Labs GitHub repository. It serves as a migration accelerator and is not part of the Mendix Platform lifecycle or support policy. + +Generate Migration Artifacts +Run the migration utility against the existing deployment: + + + +./migrate \ + --namespace \ + --name \ + --hocon-runtime-ref /etc/variables.conf \ + --hocon-constants-ref /etc/constants/variables.conf \ + --output-dir +The tool generates: + +values.yaml + +Configmap-custom-config.yaml + +These files contain the generated configuration mapped from the operator-based deployment. + +Create Configuration Resources +Create the generated configuration map: + +kubectl apply -f Configmap-custom-config.yaml + +This makes the migrated application configuration available to the Portable Runtime deployment. + +Deploy Using Helm +Clone or download the Portable Runtime Helm chart: + +git clone GitHub - mendixlabs/mendix-portable-runtime-helm-charts: Contains helm chart to deploy Mendix portable runtime app on Kubernetes cluster + +Deploy the application using the generated values file: + + + +helm install . \ + -f /values.yaml \ + --namespace +Show more lines + +The deployment uses the generated configuration and existing application settings extracted from the previous MxOnK8S deployment. + +Known Limitations +The reference migration implementation currently requires validation for some advanced deployment scenarios, including: + +AWS IRSA integrations + +Azure Managed Identity integrations + +External secret providers such as Key Vault or Secret Manager + +Support for these scenarios depends on the capabilities provided by the selected Helm chart version and target Kubernetes environment. \ No newline at end of file From c74dc0675ae7c2ef0bb28a8f9322c60f5a51eddc Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 8 Oct 2026 11:18:18 +0200 Subject: [PATCH 4/7] portable updates --- .../deployment/pad/best-practices-k8s/deploy-helm-portable.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md index e8886f0a6e8..48da3be907f 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md @@ -10,7 +10,8 @@ description: "Describes how to deploy Mendix Portable Runtime with Helm charts." Starting with Mendix 12, Mendix on Kubernetes Standalone is deprecated. Customers running applications in private or disconnected Kubernetes environments should migrate to Mendix Portable Runtime as the recommended deployment model. This document provides guidance for migrating a Mendix application deployed using Mendix on Kubernetes Standalone to Mendix Portable Runtime deployed with Helm charts. -Migrating from Mendix on Kubernetes Standalone to Mendix Portable Runtime primarily involves translating operator-managed configuration into Helm-based configuration. You can simplify this process by using an open-source migration utility to generate the initial Portable Runtime configuration, allowing organizations to accelerate adoption while retaining existing databases, storage, and application URLs where appropriate. +Migrating from Mendix on Kubernetes Standalone to Mendix Portable Runtime primarily involves translating +operator-managed configuration into Helm-based configuration. You can simplify this process by using an open-source migration utility to generate the initial Portable Runtime configuration, accelerating adoption while retaining existing databases, storage, and application URLs where appropriate. {{% alert color="info" %}} This migration approach is based on an open-source migration utility and Helm chart templates provided through the Mendix Labs GitHub repositories. These tools are intended as guidance and reference implementations and are not officially supported Mendix Platform features. Customers should validate the generated configuration before using it in production environments. From 2958fec7517bb3c6d7305f6d0a76519f270e11f1 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 9 Oct 2026 17:59:44 +0200 Subject: [PATCH 5/7] draft --- .../deploy-helm-portable.md | 215 +++++++----------- 1 file changed, 86 insertions(+), 129 deletions(-) diff --git a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md index 48da3be907f..317c5b66480 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md @@ -10,193 +10,150 @@ description: "Describes how to deploy Mendix Portable Runtime with Helm charts." Starting with Mendix 12, Mendix on Kubernetes Standalone is deprecated. Customers running applications in private or disconnected Kubernetes environments should migrate to Mendix Portable Runtime as the recommended deployment model. This document provides guidance for migrating a Mendix application deployed using Mendix on Kubernetes Standalone to Mendix Portable Runtime deployed with Helm charts. -Migrating from Mendix on Kubernetes Standalone to Mendix Portable Runtime primarily involves translating -operator-managed configuration into Helm-based configuration. You can simplify this process by using an open-source migration utility to generate the initial Portable Runtime configuration, accelerating adoption while retaining existing databases, storage, and application URLs where appropriate. +Migrating from Mendix on Kubernetes Standalone to Mendix Portable Runtime involves translating operator-managed configuration into Helm-based configuration. You can simplify this process by using an open-source migration utility to generate the initial Portable Runtime configuration, accelerating adoption while retaining existing databases, storage, and application URLs where appropriate. {{% alert color="info" %}} This migration approach is based on an open-source migration utility and Helm chart templates provided through the Mendix Labs GitHub repositories. These tools are intended as guidance and reference implementations and are not officially supported Mendix Platform features. Customers should validate the generated configuration before using it in production environments. {{% /alert %}} -## Differences Between Deployment Models -Mendix on Kubernetes Standalone -MxOnK8S uses an operator-driven deployment model where application configuration is managed through Kubernetes Custom Resource Definitions (CRDs). +### Differences Between Deployment Models -Mendix Portable Runtime -Mendix Portable Runtime uses a packaging-based deployment model. Applications are deployed using Kubernetes manifests and Helm charts, without requiring the Mendix Operator. Configuration, infrastructure resources, and secrets must be provided through the deployment package and Helm values. - -Migration Overview -The migration process consists of: - -Extracting application configuration from the existing MxOnK8S deployment. - -Mapping configuration to Mendix Portable Runtime settings. - -Generating a Helm values file. - -Creating required Kubernetes configuration resources. - -Deploying the application using the Portable Runtime Helm chart. - -The migration utility uses the existing Kubernetes Deployment resource as the source of truth and derives configuration from referenced resources such as ConfigMaps, Secrets, Services, and Ingress definitions. - -Prerequisites -Before starting the migration: - -Access to the existing Kubernetes cluster - -Permissions to read Kubernetes Deployments, Secrets, ConfigMaps, and related resources - -A generated Mendix Portable Runtime package for the target application - -Go installed if using the migration utility - -Helm installed for deployment - -Configuration Discovery -The migration utility analyses the existing deployment and identifies dependent resources. - -The following resource types are typically examined: - -ConfigMaps +Mendix on Kubernetes Standalone uses an operator-driven deployment model where application configuration is managed through Kubernetes Custom Resource Definitions (CRDs). -Secrets - -Persistent Volume Claims (PVCs) - -Service Accounts - -Services - -Ingresses or Routes - -Horizontal Pod Autoscalers (if applicable) - -Pod Disruption Budgets (if applicable) - -Resource Mapping -The following configuration mappings are commonly used during migration. - -Existing MxOnK8S Resource - -Portable Runtime Configuration +Mendix Portable Runtime uses a packaging-based deployment model. Applications are deployed using Kubernetes manifests and Helm charts, without requiring the Mendix Operator. Configuration, infrastructure resources, and secrets must be provided through the deployment package and Helm values. --m2ee secret +## Prerequisites -M2EE password secret reference +Before starting the migration, ensure that you have the following prerequisites: --database secret +* Access to the existing Kubernetes cluster +* Permissions to read Kubernetes Deployments, Secrets, ConfigMaps, and related resources +* A generated Mendix Portable Runtime package for the target application +* Go installed if using the migration utility +* Helm installed for deployment -Database secret reference +## Migration Overview --file secret +The migration process consists of the following stages: -Storage secret reference +1. Extracting application configuration from the existing Mendix on Kubernetes Standalone deployment. +2. Mapping configuration to Mendix Portable Runtime settings. +3. Generating a Helm values file. +4. Creating required Kubernetes configuration resources. +5. Deploying the application using the Portable Runtime Helm chart. -runtime-config/custom.json +### Configuration Discovery -Application constants and custom settings +The migration utility analyses the existing Kubernetes Deployment resource and identifies dependent resources. -runtime-config/runtime.json +The utility examines the following resources: -Runtime settings +* ConfigMaps +* Secrets +* Persistent Volume Claims (PVCs) +* Service Accounts +* Services +* Ingresses or Routes +* Horizontal Pod Autoscalers (if applicable) +* Pod Disruption Budgets (if applicable) -Existing Route/Ingress +### Resource Mapping -Recreated using same application URL +The following configuration mappings are commonly used during migration: -Application Constants -Application constants are extracted from the existing runtime configuration and converted into the Portable Runtime custom configuration format. The migration references: +* `-m2ee` secret - M2EE password secret reference +* `-database` secret - Database secret reference +* `-file secret` - Storage secret reference +* `runtime-config/custom.json` - Application constants and custom settings +* `runtime-config/runtime.json` - Runtime settings +* Existing route and ingress - Recreated using the same application URL -etc/constants/variables.conf +#### Application Constants -This file contains application-specific constants and settings. +Application constants are extracted from the existing runtime configuration and converted into the Portable Runtime custom configuration format. The migration references the `etc/constants/variables.conf` file, which contains application-specific constants and settings. -Runtime Settings -Runtime settings are mapped using: +#### Runtime Settings -etc/variables.conf +Runtime settings are mapped using the `etc/variables.conf` file, which contains the runtime property definitions used by Portable Runtime. -This file contains the runtime property definitions used by Portable Runtime. +#### Database and Storage Credentials -Database and Storage Credentials Database and storage credentials are typically sourced from Kubernetes Secrets referenced by the existing deployment. -These credentials can either: - -Be created directly through the Helm chart +These credentials be created in one of the following ways: -Be created separately and referenced from the generated values file +* Directly through the Helm chart +* Separately, referenced from the generated values file Portable Runtime should continue to use the same database and storage location whenever possible. -Application URL +#### Application URL + To minimize changes for end users, reuse the same ingress or route URL that was used by the previous deployment. Before activating the new deployment, remove or update the existing ingress or route resource to avoid conflicts. -Unsupported Configuration -Some runtime behaviours available through the Mendix Operator are not directly portable. - -For example: +### Unsupported Configuration -Liveness probes provided by the M2EE sidecar +Some runtime behaviours available through the Mendix Operator are not directly portable, for example: -Readiness probes provided by the M2EE sidecar +* Liveness probes provided by the M2EE sidecar +* Readiness probes provided by the M2EE sidecar Portable Runtime deployments may require alternative probe definitions depending on the deployment environment. -Using the Migration Utility -[!NOTE] The migration utility is an open-source reference tool distributed through a Mendix Labs GitHub repository. It serves as a migration accelerator and is not part of the Mendix Platform lifecycle or support policy. +## Using the Migration Utility -Generate Migration Artifacts -Run the migration utility against the existing deployment: +The migration utility is an open-source reference tool distributed through a Mendix Labs GitHub repository. It serves as a migration accelerator and is not part of the Mendix Platform lifecycle or support policy. +To use the utility, perform the following steps: +1. Generate migration artifacts by running the migration utility against the existing deployment: -./migrate \ - --namespace \ - --name \ - --hocon-runtime-ref /etc/variables.conf \ - --hocon-constants-ref /etc/constants/variables.conf \ - --output-dir -The tool generates: + ```text + ./migrate \ + --namespace \ + --name \ + --hocon-runtime-ref /etc/variables.conf \ + --hocon-constants-ref /etc/constants/variables.conf \ + --output-dir + ``` -values.yaml + The tool generates the following files with configuration mapped from the Operator-based deployment: -Configmap-custom-config.yaml + * *values.yaml* + * *Configmap-custom-config.yaml* -These files contain the generated configuration mapped from the operator-based deployment. +2. Create the generated configuration map: -Create Configuration Resources -Create the generated configuration map: + ```text + kubectl apply -f Configmap-custom-config.yaml + ``` -kubectl apply -f Configmap-custom-config.yaml + This makes the migrated application configuration available to the Portable Runtime deployment. -This makes the migrated application configuration available to the Portable Runtime deployment. +3. Clone or download the Portable Runtime Helm chart: -Deploy Using Helm -Clone or download the Portable Runtime Helm chart: + ```text + git clone GitHub - mendixlabs/mendix-portable-runtime-helm-charts: Contains helm chart to deploy Mendix portable runtime app on Kubernetes cluster + ``` -git clone GitHub - mendixlabs/mendix-portable-runtime-helm-charts: Contains helm chart to deploy Mendix portable runtime app on Kubernetes cluster +3. Deploy the application using the generated values file: -Deploy the application using the generated values file: + ```text + helm install . \ + -f /values.yaml \ + --namespace + ``` +The deployment uses the generated configuration and existing application settings extracted from the previous Mendix on Kubernetes Standalone deployment. +## Known Limitations -helm install . \ - -f /values.yaml \ - --namespace -Show more lines - -The deployment uses the generated configuration and existing application settings extracted from the previous MxOnK8S deployment. - -Known Limitations The reference migration implementation currently requires validation for some advanced deployment scenarios, including: -AWS IRSA integrations - -Azure Managed Identity integrations - -External secret providers such as Key Vault or Secret Manager +* AWS IRSA integrations +* Azure Managed Identity integrations +* External secret providers such as Key Vault or Secret Manager Support for these scenarios depends on the capabilities provided by the selected Helm chart version and target Kubernetes environment. \ No newline at end of file From aa99269b20924593f1780519b3c9128677278618 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 9 Oct 2026 18:00:54 +0200 Subject: [PATCH 6/7] draft --- .../best-practices-k8s/migrate-portable.md | 305 ++++++++++++++++++ 1 file changed, 305 insertions(+) diff --git a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md index 0cf27a8f5f9..c13b0446709 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md @@ -8,3 +8,308 @@ description: "Describes how you can migrate from Standalone Mendix on Kubernetes ## Introduction +The Mendix Portable Runtime Helm Chart provides a reference deployment template for running Mendix Portable Runtime applications on Kubernetes and OpenShift platforms. The Helm Chart simplifies the deployment of Portable Runtime container images by providing pre-configured Kubernetes resources for application runtime, networking, configuration management, secrets, and storage. + +This deployment approach is intended for customers who want to run Mendix Portable Runtime in self-managed Kubernetes environments without using the Mendix Operator. The chart can serve as a starting point for production deployments and can be extended to meet organisation-specific requirements. + +Note + +The Helm Chart is provided as an open-source Mendix Labs project and should be considered a reference implementation and deployment template. Customers are responsible for validating, maintaining, and adapting the chart to their infrastructure, security, and operational standards. Mendix supports the Mendix Portable Runtime package itself, but not the open-source Helm Chart implementation. + +Prerequisites +Before deploying a Mendix Portable Runtime application using Helm, ensure that you have: + +A Mendix Portable Runtime deployment package + +A container image containing your Mendix application + +Helm 3.x installed + +Kubernetes 1.34+ or OpenShift 4.x + +Access to a Kubernetes or OpenShift cluster + +Database and storage services provisioned for your application requirements + +For information on creating Portable Runtime deployment packages, see Mendix Portable Runtime. + +Obtaining the Helm Chart +The reference Helm Chart is available from the Mendix Labs GitHub repository: + +Mendix Portable Runtime Helm Charts Repository + +The repository contains: + +Helm chart templates + +Example deployment configurations + +Sample configuration files + +Kubernetes and OpenShift deployment examples + +Documentation and usage guidance + +Helm Chart Structure +The chart follows a standard Helm layout: + + + + + +mendix-portable-runtime/ +├── Chart.yaml +├── values.yaml +├── templates/ +│ ├── deployment.yaml +│ ├── service.yaml +│ ├── ingress.yaml +│ ├── route.yaml +│ ├── configmap.yaml +│ ├── secret.yaml +│ ├── serviceaccount.yaml +│ ├── namespace.yaml +│ └── storage.yaml +└── examples/ + ├── dev-simple.yaml + └── custom-config.conf +The templates directory contains Kubernetes resource definitions, while values.yaml provides the deployment configuration used during chart installation. + +How the Helm Chart Works +The Helm Chart deploys a container image containing a Mendix Portable Runtime application. During startup, the application is launched using the standard Portable Runtime startup mechanism: + + + + + +./bin/start [customConfigFile...] +` + + +Configuration is applied using the Portable Runtime layered configuration model: + + + + + +Base Configuration + ↓ +Environment Variables + ↓ +Custom Configuration Files +` +This model enables common settings to be maintained in a base configuration while environment-specific overrides are supplied through mounted configuration files or environment variables. + +Installing the Chart +Clone or download the Helm Chart repository and navigate to the chart directory. + +Install the application using: + + + + + +helm install myapp . \ + -f examples/dev-simple.yaml \ + -n +To preview the generated Kubernetes resources before deployment, run: + + + +helm template myapp . \ + -f examples/dev-simple.yaml +To upgrade an existing deployment: + + + +helm upgrade myapp . \ + -f examples/dev-simple.yaml \ + -n +To uninstall the deployment: + + + +helm uninstall myapp \ + -n + + +Configuring the Deployment +The primary deployment configuration is stored in: + +values.yaml + +The chart exposes configuration options for ingress / Openshift Route. + +Section + +Description + +image + +Container image repository and tag or digest + +runtime + +Portable Runtime configuration + +env + +Environment variables + +secrets + +Secret creation + +secretKeyRefs + +References to external Kubernetes secrets + +configMaps + +ConfigMap creation and mounting + +ingress + +Kubernetes Ingress configuration + +route + +OpenShift Route configuration + +storage + +Persistent storage configuration + +resources + +CPU and memory requests and limits + +livenessProbe + +Runtime health monitoring + +readinessProbe + +Traffic readiness validation + +Using Custom Configuration Files +Portable Runtime supports layered configuration through external configuration files. + +The Helm Chart allows configuration files to be mounted through Kubernetes ConfigMaps: + + + +runtime: + baseConfig: "etc/Default" + customConfigFiles: + - name: custom + configMapName: my-config + key: custom-config.conf + filename: custom-config.conf + mountPath: /opt/app/etc +Example configuration file: + + + +runtime { + params { + "DTAPMode" = "D" + "SessionTimeout" = 2 minutes + } +} +Configuration values supplied through environment variables take precedence over configuration file settings. + +Managing Secrets +Database credentials and application secrets can be supplied through Kubernetes Secrets. + +Referencing Existing Secrets + + +secretKeyRefs: + - envName: RUNTIME_PARAMS_DATABASEJDBCURL + secretName: my-db-secret + key: DATABASE_URL +Importing All Secret Values + + + + +secretEnvFrom: + - name: my-db-secret +Creating Secrets Through the Chart + + +secrets: + - name: db-credentials + stringData: + DATABASE_URL: jdbc:postgresql://host:5432/db + + +For production environments, it is recommended to use externally managed Kubernetes secrets. + +Operations and Monitoring +The following commands can be used to manage the deployment. + +List running pods: + +kubectl get pods -n + +View application logs: + + + + + +kubectl logs \ + -l app=myapp-mendix-portable-runtime \ + -n +Restart the deployment after updating ConfigMaps or Secrets: + + + +kubectl rollout restart deployment \ + myapp-mendix-portable-runtime \ + -n +View configured Ingress resources: + +kubectl get ingress -n + +For OpenShift deployments, view Routes: + +kubectl get route -n + + + +Support Considerations +The Helm Chart provides deployment automation for Kubernetes resources but does not change the Mendix Portable Runtime support model. + +Mendix supports the Portable Runtime package and runtime capabilities. Customers remain responsible for: + +Kubernetes cluster management + +Container image management + +Security hardening + +Networking and ingress configuration + +Storage configuration + +Backup and disaster recovery procedures + +Operational monitoring and alerting + +The Helm Chart should therefore be treated as a deployment accelerator rather than a fully supported deployment product. + +Related Documentation +Mendix Portable Runtime + +Best practices for Kubernetes + +Reference Guide for Docker Deployment + +Mendix Portable Runtime Helm Charts Repository + +Open Source Disclaimer + +The Mendix Portable Runtime Helm Chart is an open-source Mendix Labs project provided for guidance purposes. The repository serves as a deployment template demonstrating one possible approach for running Mendix Portable Runtime applications on Kubernetes and OpenShift environments. Customers should review and adapt the implementation to align with their platform standards and operational requirements. \ No newline at end of file From 915665c5c35dd07f2b18688f8f0d103bdcd9761a Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Mon, 12 Oct 2026 16:12:06 +0200 Subject: [PATCH 7/7] updates --- .../best-practices-k8s/migrate-portable.md | 280 ++++++++---------- 1 file changed, 117 insertions(+), 163 deletions(-) diff --git a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md index c13b0446709..e654210159b 100644 --- a/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md @@ -12,51 +12,60 @@ The Mendix Portable Runtime Helm Chart provides a reference deployment template This deployment approach is intended for customers who want to run Mendix Portable Runtime in self-managed Kubernetes environments without using the Mendix Operator. The chart can serve as a starting point for production deployments and can be extended to meet organisation-specific requirements. -Note - +{{% alert color="info" %}} The Helm Chart is provided as an open-source Mendix Labs project and should be considered a reference implementation and deployment template. Customers are responsible for validating, maintaining, and adapting the chart to their infrastructure, security, and operational standards. Mendix supports the Mendix Portable Runtime package itself, but not the open-source Helm Chart implementation. +{{% /alert %}} -Prerequisites -Before deploying a Mendix Portable Runtime application using Helm, ensure that you have: +### Open Source Disclaimer -A Mendix Portable Runtime deployment package +The Mendix Portable Runtime Helm Chart is an open-source Mendix Labs project provided for guidance purposes. The repository serves as a deployment template demonstrating one possible approach for running Mendix Portable Runtime applications on Kubernetes and OpenShift environments. Customers should review and adapt the implementation to align with their platform standards and operational requirements. -A container image containing your Mendix application +### Support Considerations -Helm 3.x installed +The Helm Chart provides deployment automation for Kubernetes resources but does not change the Mendix Portable Runtime support model. -Kubernetes 1.34+ or OpenShift 4.x +Mendix supports the Portable Runtime package and runtime capabilities. Customers remain responsible for the following tasks: -Access to a Kubernetes or OpenShift cluster +* Kubernetes cluster management +* Container image management +* Security hardening +* Networking and ingress configuration +* Storage configuration +* Backup and disaster recovery procedures +* Operational monitoring and alerting -Database and storage services provisioned for your application requirements +The Helm Chart should therefore be treated as a deployment accelerator rather than a fully supported deployment product. -For information on creating Portable Runtime deployment packages, see Mendix Portable Runtime. +## Prerequisites -Obtaining the Helm Chart -The reference Helm Chart is available from the Mendix Labs GitHub repository: +Before deploying a Mendix Portable Runtime application using Helm, ensure that you have the following prerequisites: -Mendix Portable Runtime Helm Charts Repository +* A Mendix Portable Runtime deployment package +* A container image containing your Mendix application +* Helm 3.x installed +* Kubernetes 1.34+ or OpenShift 4.x +* Access to a Kubernetes or OpenShift cluster +* Database and storage services provisioned for your application requirements -The repository contains: +For information on creating Portable Runtime deployment packages, see [Mendix Portable Runtime](/developerportal/deploy/portable-app-distribution-deploy/). -Helm chart templates +## Obtaining the Helm Chart -Example deployment configurations +The reference Helm Chart is available from the [Mendix Portable Runtime Helm Charts Repository](https://github.com/mendixlabs/mendix-portable-runtime-helm-charts). -Sample configuration files +The repository contains the following artifacts: -Kubernetes and OpenShift deployment examples +* Helm chart templates +* Example deployment configurations +* Sample configuration files +* Kubernetes and OpenShift deployment examples +* Documentation and usage guidance -Documentation and usage guidance +## Helm Chart Structure -Helm Chart Structure The chart follows a standard Helm layout: - - - - +```text mendix-portable-runtime/ ├── Chart.yaml ├── values.yaml @@ -73,132 +82,93 @@ mendix-portable-runtime/ └── examples/ ├── dev-simple.yaml └── custom-config.conf -The templates directory contains Kubernetes resource definitions, while values.yaml provides the deployment configuration used during chart installation. +``` -How the Helm Chart Works -The Helm Chart deploys a container image containing a Mendix Portable Runtime application. During startup, the application is launched using the standard Portable Runtime startup mechanism: - - +The templates directory contains Kubernetes resource definitions, while *values.yaml* provides the deployment configuration used during chart installation. +### How the Helm Chart Works +The Helm Chart deploys a container image containing a Mendix Portable Runtime application. During startup, the application is launched using the standard Portable Runtime startup mechanism: +```text ./bin/start [customConfigFile...] ` - +``` Configuration is applied using the Portable Runtime layered configuration model: - - - - +```text Base Configuration ↓ Environment Variables ↓ Custom Configuration Files ` -This model enables common settings to be maintained in a base configuration while environment-specific overrides are supplied through mounted configuration files or environment variables. +``` -Installing the Chart -Clone or download the Helm Chart repository and navigate to the chart directory. - -Install the application using: +This model enables common settings to be maintained in a base configuration while environment-specific overrides are supplied through mounted configuration files or environment variables. - +## Installing the Chart +To install the Helm Chart, perform the following steps: +1. Clone or download the Helm Chart repository and navigate to the chart directory. +2. Install the application by running the following command: +```text helm install myapp . \ -f examples/dev-simple.yaml \ -n -To preview the generated Kubernetes resources before deployment, run: - +``` +3. To preview the generated Kubernetes resources before deployment, run the following command: +```text helm template myapp . \ -f examples/dev-simple.yaml -To upgrade an existing deployment: +``` +### Upgrading a Deployment +To upgrade an existing deployment, run the following command: +```text helm upgrade myapp . \ -f examples/dev-simple.yaml \ -n -To uninstall the deployment: +``` +### Uninstalling a Deployment +To uninstall the deployment, run the following command: +```text helm uninstall myapp \ -n - - -Configuring the Deployment -The primary deployment configuration is stored in: - -values.yaml - -The chart exposes configuration options for ingress / Openshift Route. - -Section - -Description - -image - -Container image repository and tag or digest - -runtime - -Portable Runtime configuration - -env - -Environment variables - -secrets - -Secret creation - -secretKeyRefs - -References to external Kubernetes secrets - -configMaps - -ConfigMap creation and mounting - -ingress - -Kubernetes Ingress configuration - -route +``` -OpenShift Route configuration +## Configuring the Deployment -storage +The primary deployment configuration is stored in *values.yaml*. The chart exposes configuration options for ingress and Openshift Route in the following sections: -Persistent storage configuration - -resources - -CPU and memory requests and limits - -livenessProbe - -Runtime health monitoring - -readinessProbe - -Traffic readiness validation - -Using Custom Configuration Files -Portable Runtime supports layered configuration through external configuration files. - -The Helm Chart allows configuration files to be mounted through Kubernetes ConfigMaps: +* `image` - Container image repository and tag or digest +* `runtime` - Portable Runtime configuration +* `env` - Environment variables +* `secrets` - Secret creation +* `secretKeyRefs` - References to external Kubernetes secrets +* `configMaps` - ConfigMap creation and mounting +* `ingress` - Kubernetes Ingress configuration +* `route` - OpenShift Route configuration +* `storage` - Persistent storage configuration +* `resources` - CPU and memory requests and limits +* `livenessProbe` - Runtime health monitoring +* `readinessProbe` - Traffic readiness validation +### Using Custom Configuration Files +Portable Runtime supports layered configuration through external configuration files. The Helm Chart allows configuration files to be mounted through Kubernetes ConfigMaps: +```text runtime: baseConfig: "etc/Default" customConfigFiles: @@ -207,109 +177,93 @@ runtime: key: custom-config.conf filename: custom-config.conf mountPath: /opt/app/etc -Example configuration file: - +``` +#### Example Configuration File +```text runtime { params { "DTAPMode" = "D" "SessionTimeout" = 2 minutes } } +``` + Configuration values supplied through environment variables take precedence over configuration file settings. -Managing Secrets -Database credentials and application secrets can be supplied through Kubernetes Secrets. +## Managing Secrets -Referencing Existing Secrets +Database credentials and application secrets can be supplied through Kubernetes Secrets. +### Referencing Existing Secrets +```text secretKeyRefs: - envName: RUNTIME_PARAMS_DATABASEJDBCURL secretName: my-db-secret key: DATABASE_URL -Importing All Secret Values - - - +``` +### Importing All Secret Values + +```text secretEnvFrom: - name: my-db-secret -Creating Secrets Through the Chart +``` +### Creating Secrets Through the Chart +```text secrets: - name: db-credentials stringData: DATABASE_URL: jdbc:postgresql://host:5432/db - +``` For production environments, it is recommended to use externally managed Kubernetes secrets. -Operations and Monitoring +## Operations and Monitoring + The following commands can be used to manage the deployment. -List running pods: +### Listing Running Pods +```text kubectl get pods -n +``` -View application logs: - - - - +### Viewing Application Logs +```text kubectl logs \ -l app=myapp-mendix-portable-runtime \ -n -Restart the deployment after updating ConfigMaps or Secrets: - +``` +### Restarting the Deployment after Updating ConfigMaps or Secrets +```text kubectl rollout restart deployment \ myapp-mendix-portable-runtime \ -n -View configured Ingress resources: +``` + +### Viewing Configured Ingress Resources +```text kubectl get ingress -n +``` -For OpenShift deployments, view Routes: +### Viewing Routes for OpenShift Deployments +```text kubectl get route -n - +``` +## Read More -Support Considerations -The Helm Chart provides deployment automation for Kubernetes resources but does not change the Mendix Portable Runtime support model. - -Mendix supports the Portable Runtime package and runtime capabilities. Customers remain responsible for: - -Kubernetes cluster management - -Container image management - -Security hardening - -Networking and ingress configuration - -Storage configuration - -Backup and disaster recovery procedures - -Operational monitoring and alerting - -The Helm Chart should therefore be treated as a deployment accelerator rather than a fully supported deployment product. - -Related Documentation -Mendix Portable Runtime - -Best practices for Kubernetes - -Reference Guide for Docker Deployment - -Mendix Portable Runtime Helm Charts Repository - -Open Source Disclaimer - -The Mendix Portable Runtime Helm Chart is an open-source Mendix Labs project provided for guidance purposes. The repository serves as a deployment template demonstrating one possible approach for running Mendix Portable Runtime applications on Kubernetes and OpenShift environments. Customers should review and adapt the implementation to align with their platform standards and operational requirements. \ No newline at end of file +* [Mendix Portable Runtime](/developerportal/deploy/portable-app-distribution-deploy/) +* [Best practices for Kubernetes](/developerportal/deploy/docker-deploy-k8s/) +* [Reference Guide for Docker Deployment](/developerportal/deploy/docker-deploy-pad/) +* [Mendix Portable Runtime Helm Charts Repository](https://github.com/mendixlabs/mendix-portable-runtime-helm-charts) \ No newline at end of file