diff --git a/content/en/docs/deployment/pad/kubernetes-pad.md b/content/en/docs/deployment/pad/best-practices-k8s/_index.md similarity index 99% rename from content/en/docs/deployment/pad/kubernetes-pad.md rename to content/en/docs/deployment/pad/best-practices-k8s/_index.md index 1c93d78a728..19836231f12 100644 --- a/content/en/docs/deployment/pad/kubernetes-pad.md +++ b/content/en/docs/deployment/pad/best-practices-k8s/_index.md @@ -3,6 +3,8 @@ 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 @@ -444,3 +446,5 @@ If the app cannot connect to the database, check the database credentials in the ```text kubectl get secret mendix-secret -n mendix-app -o yaml ``` + +## Read More 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 new file mode 100644 index 00000000000..317c5b66480 --- /dev/null +++ b/content/en/docs/deployment/pad/best-practices-k8s/deploy-helm-portable.md @@ -0,0 +1,159 @@ +--- +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 + +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 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 uses an operator-driven deployment model where application configuration is managed through Kubernetes Custom Resource Definitions (CRDs). + +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. + +## Prerequisites + +Before starting the migration, ensure that you have the following prerequisites: + +* 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 + +## Migration Overview + +The migration process consists of the following stages: + +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. + +### Configuration Discovery + +The migration utility analyses the existing Kubernetes Deployment resource and identifies dependent resources. + +The utility examines the following resources: + +* 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: + +* `-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 + +#### Application Constants + +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 the `etc/variables.conf` file, which 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 be created in one of the following ways: + +* 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 + +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 + +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: + + ```text + ./migrate \ + --namespace \ + --name \ + --hocon-runtime-ref /etc/variables.conf \ + --hocon-constants-ref /etc/constants/variables.conf \ + --output-dir + ``` + + The tool generates the following files with configuration mapped from the Operator-based deployment: + + * *values.yaml* + * *Configmap-custom-config.yaml* + +2. Create the generated configuration map: + + ```text + kubectl apply -f Configmap-custom-config.yaml + ``` + + This makes the migrated application configuration available to the Portable Runtime deployment. + +3. 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 + ``` + +3. 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 + +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 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..e654210159b --- /dev/null +++ b/content/en/docs/deployment/pad/best-practices-k8s/migrate-portable.md @@ -0,0 +1,269 @@ +--- +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 + +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. + +{{% 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 %}} + +### 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. + +### 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 the following tasks: + +* 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. + +## Prerequisites + +Before deploying a Mendix Portable Runtime application using Helm, ensure that you have the following prerequisites: + +* 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](/developerportal/deploy/portable-app-distribution-deploy/). + +## Obtaining the Helm Chart + +The reference Helm Chart is available from the [Mendix Portable Runtime Helm Charts Repository](https://github.com/mendixlabs/mendix-portable-runtime-helm-charts). + +The repository contains the following artifacts: + +* 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: + +```text +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: + +```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 + +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 +``` + +3. To preview the generated Kubernetes resources before deployment, run the following command: + +```text +helm template myapp . \ + -f examples/dev-simple.yaml +``` + +### Upgrading a Deployment + +To upgrade an existing deployment, run the following command: + +```text +helm upgrade myapp . \ + -f examples/dev-simple.yaml \ + -n +``` + +### 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 and Openshift Route in the following sections: + +* `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: + - name: custom + configMapName: my-config + key: custom-config.conf + filename: custom-config.conf + mountPath: /opt/app/etc +``` + +#### 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. + +### Referencing Existing Secrets + +```text +secretKeyRefs: + - envName: RUNTIME_PARAMS_DATABASEJDBCURL + secretName: my-db-secret + key: DATABASE_URL +``` + +### Importing All Secret Values + +```text +secretEnvFrom: + - name: my-db-secret +``` + +### 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 + +The following commands can be used to manage the deployment. + +### Listing Running Pods + +```text +kubectl get pods -n +``` + +### Viewing Application Logs + +```text +kubectl logs \ + -l app=myapp-mendix-portable-runtime \ + -n +``` + +### Restarting the Deployment after Updating ConfigMaps or Secrets + +```text +kubectl rollout restart deployment \ + myapp-mendix-portable-runtime \ + -n +``` + +### Viewing Configured Ingress Resources + +```text +kubectl get ingress -n +``` + +### Viewing Routes for OpenShift Deployments + +```text +kubectl get route -n +``` + +## Read More + +* [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