From d1bef90efaba593368dd76969052155b0e8293d1 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 19 Nov 2026 20:22:26 +0100 Subject: [PATCH 01/18] Updated the Secret store documents --- .../configuration/pmp-configure-k8s.md | 4 +- .../private-platform/quickstart/_index.md | 2 +- .../quickstart/pmp-quickstart-artifacts.md | 90 ++-- .../quickstart/pmp-quickstart-helm.md | 425 +++++++++++++----- .../quickstart/pmp-quickstart.md | 48 +- .../secret-management/_index.md | 2 + 6 files changed, 401 insertions(+), 170 deletions(-) diff --git a/content/en/docs/private-platform/configuration/pmp-configure-k8s.md b/content/en/docs/private-platform/configuration/pmp-configure-k8s.md index 1c9f61c9b65..7e1734887c8 100644 --- a/content/en/docs/private-platform/configuration/pmp-configure-k8s.md +++ b/content/en/docs/private-platform/configuration/pmp-configure-k8s.md @@ -227,7 +227,7 @@ The settings in this section configure the storage for build output artifacts. azure.workload.identity/client-id: {client-id-pmp} ``` - This step is not required if Private Mendix Platform is using a MI from Azure Managed Identity-based storage plans. In that case, the ServiceAccount already has the correct annotation. + This step is not required when a storage plan already annotates the ServiceAccount, or when you install the platform app from the secret store with `azureWorkloadIdentity.enable` set to `true`. The chart then writes the client id annotation itself. See [Using a Secret Store for the Platform App](/private-mendix-platform/helmfile-installation/#disable-provisioners). 4. Add the following role assignments to the Private Mendix Platform Managed Identity: @@ -247,7 +247,7 @@ The settings in this section configure the storage for build output artifacts. azure.workload.identity/use: "true" ``` - This step is not required if Private Mendix Platform is using a MI from Azure Managed Identity-based storage plans. In that case, the customPodLabel is already configured. + This step is not required when a storage plan already sets the label, or when `azureWorkloadIdentity.enable` or `secretProviderclass.azureparameters.useManagedIdentityForBlob` is `true`. The chart then sets `azure.workload.identity/use: "true"` on the platform pod. 6. Restart Private Mendix Platform to ensure that the labels are applied. diff --git a/content/en/docs/private-platform/quickstart/_index.md b/content/en/docs/private-platform/quickstart/_index.md index c05f8c3cdc6..f8e4fbde448 100644 --- a/content/en/docs/private-platform/quickstart/_index.md +++ b/content/en/docs/private-platform/quickstart/_index.md @@ -13,7 +13,7 @@ aliases: This document provides a comprehensive guide for installing Private Mendix Platform, along with its optional components, in your own Kubernetes environment. -Private Mendix Platform supports using secret storage. If required, you can store some configuration in a secret vault (for example, AWS, Azure, or Hashicorp) without setting up a storage plan, database plan, PCLM admin and Mendix admin info in the Private Mendix Platform installer. +Private Mendix Platform can use an external secret store (for example, AWS Secrets Manager, Azure Key Vault, or HashiCorp Vault). This is the setup described in [Retrieve Environment-Sensitive Data from a Secret Store](/developerportal/deploy/secret-store-credentials/). The secret store can be used together with a database plan or a storage plan. The Mendix Operator still provisions a resource that has a plan. When you leave the plan unset, you create the database, the file storage, the identity, and the role assignments yourself, before installation. That is the default once the secret store is enabled. For the steps, see [Using a Secret Store for the Platform App](/private-mendix-platform/helmfile-installation/#disable-provisioners) and [What the Secret Store Does Not Provision](/private-mendix-platform/interactive-installation/#secret-store-no-provisioner). {{% alert color="info" %}} Using a secret storage incorrectly may reduce the security of your app. Consult your secrets store provider to ensure that it is set up securely for your production environment. diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md index b909cc45455..c58fba87cdd 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md @@ -858,7 +858,7 @@ The `mxplatform` component is used for Mendix application platform deployment. | --- | --- | --- | --- | | `enable` | Boolean | Yes | Enables `mxplatform` deployment | | `name` | string | No (default: `mxplatform`) | The name of the MendixApp CR and ServiceAccount, if created | -| `UseStoragePlanwithIRSA` | Boolean | No (default: `false`) | Set to `true` when using StoragePlans with Workload Identity | +| `useStoragePlanwithIRSA` | Boolean | No (default: `false`) | Set to `true` when a storage plan with workload identity creates the ServiceAccount. Leave `false` when the secret store is enabled, so the chart creates the ServiceAccount | #### PCLM Integration (Required) @@ -874,9 +874,19 @@ The `mxplatform` component is used for Mendix application platform deployment. | --- | --- | --- | | `spec.appURL` | Yes | A public domain for the app | | `spec.sourceURL` | Yes | The OCI image path in the following format: `oci-image:///:` | -| `spec.database.servicePlan` | Conditional | The database service plan name; not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | -| `spec.storage.servicePlan` | Conditional | The storage service plan name; not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | -| `spec.runtime.mxAdminPassword` | Conditional | The admin password not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | +| `spec.database.servicePlan` | Conditional | The database service plan name. Required when the secret store is off. Optional when the secret store is on. Leave it unset to create the database yourself and store its settings in the secret store. A plan name makes the operator create the database | +| `spec.storage.servicePlan` | Conditional | The storage service plan name. Required when the secret store is off. Optional when the secret store is on. Leave it unset to create the file storage yourself and store its settings in the secret store. A plan name makes the operator create the file storage | +| `spec.runtime.mxAdminPassword` | Conditional | The MxAdmin password. Leave empty when `secretProviderclass.enable` is `true`. The app reads `mx-admin-password` from the secret store | + +#### Secret Store + +`SecretProviderclass.database.passwordless` and `secretProviderclass.create` are available starting from Private Mendix Platform 2.8.2. They are not included in the `mxplatform` charts shipped with 2.8.0 and 2.8.1. For more information, see [Enabling the Secret Store](/private-mendix-platform/helmfile-installation/#enable-secret-store). + +| Field | Required | Description | +| --- | --- | --- | +| `secretProviderclass.database.passwordless` | Conditional | Available starting from Private Mendix Platform 2.8.2. Set to `true` to leave `database-password` out of the SecretProviderClass. The database is accessed with the pod identity. Requires `azureWorkloadIdentity.enable` or `awsIRSA.enable`, no database plan, and `secretProviderclass.create` left at `true` | +| `secretProviderclass.create` | No (default: `true`) | Available starting from Private Mendix Platform 2.8.2. Set to `false` to supply your own SecretProviderClass, for example to add app constants such as `Encryption.EncryptionKey`. The chart still sets `allowOverrideSecretsWithSecretStoreCSIDriver`. See [Overriding App Constants](/private-mendix-platform/helmfile-installation/#override-constants) | +| `secretProviderclass.azureparameters.useManagedIdentityForBlob` | No (default: `false`) | Set to `true` when Azure Blob Storage uses the workload identity. The chart then omits `storage-azure-account-name` and `storage-azure-account-key` | #### Automatic Integration Detection @@ -929,57 +939,57 @@ mxplatform: ```text mxplatform: enable: true - # PCLM credentials from Secret Provider + useStoragePlanwithIRSA: false + azureWorkloadIdentity: + enable: true + clientID: "" + tenantID: "" pclm: serviceUrl: "http://mx-privatecloud-license-manager" - username: "" # Empty - injected from Secret Provider - password: "" # Empty - injected from Secret Provider secretProviderclass: enable: true provider: "azure" + database: + passwordless: true azureparameters: - clientID: "..." - tenantID: "..." keyvaultName: "my-keyvault" + useManagedIdentityForBlob: true spec: appURL: "app.example.com" sourceURL: "oci-image://registry/app:1.0" - # Leave empty when using Secret Provider - database: - servicePlan: "" - storage: - servicePlan: "" - runtime: - mxAdminPassword: "" # Empty - injected from Secret Provider ``` -When using Azure Key Vault (with `provider` set to `azure`), you must create the following secrets in your Key Vault: +The secret store can be used with a database plan or a storage plan. The operator creates a resource that has a plan. When the plan is left unset, the operator does not create the database, the file container, or the identity. You create them, and the role assignments, before installation. The procedure is in [Using a Secret Store for the Platform App](/private-mendix-platform/helmfile-installation/#disable-provisioners). +When `provider` is set to `azure`, create the following secrets in Key Vault. The chart's SecretProviderClass requests each key in the **When required** column. A missing key causes the volume mount to fail. + | Secret Name | Description | Example Value | When Required | | --- | --- | --- | --- | -| `mx-admin-password` | The Mendix application admin password | `AdminPassword123` | Always | -| `pclm-admin-username` | The PCLM administrator username | `administrator` | Always | -| `pclm-admin-password` | The PCLM administrator password | `PCLMPassword123` | Always | -| `database-type` | Database type | `PostgreSQL` | Database secrets; required when `spec.database.servicePlan` is empty | -| `database-host` | Database host | `postgres.example.com` | Database secrets; required when `spec.database.servicePlan` is empty | -| `database-name` | Database name | `mxplatform` | Database secrets; required when `spec.database.servicePlan` is empty | -| `database-username` | Database username | `mxplatform_user` | Database secrets; required when `spec.database.servicePlan` is empty | -| `database-password` | Database password | `DBPassword123` | Database secrets; required when `spec.database.servicePlan` is empty | -| `database-jdbc-url` | JDBC connection URL | `jdbc:postgresql://postgres.example.com:5432/mxplatform` | Database secrets; required when `spec.database.servicePlan` is empty | -| `storage-service-name` | Storage service name | `azure` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | -| `storage-azure-container` | Azure Blob container name | -`mxplatform-files` | Storage service name | `azure` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | -| `storage-azure-blob-endpoint` | Azure Blob endpoint | `https://mystorageaccount.blob.core.windows.net` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | -| `storage-azure-use-default-azure-credential` | Use Azure Workload Identity | `true` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | -| `storage-perform-delete` | Allow delete operations | `true` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | -| `storage-use-ca-certificates` | Use CA certificates | `false` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | -| `storage-azure-use-https` | Use HTTPS for Blob access | `true` | Azure Blob Storage secrets; required when `spec.storage.servicePlan is empty` | - -Azure Blob Storage Secrets (with static credentials - when useManagedIdentityForBlob: false): - -| `storage-azure-account-name` | Azure Storage account name | `mystorageaccount` | Azure Blob Storage secrets with static credentials; required when `useManagedIdentityForBlob` is set to `false` | -| `storage-azure-account-key` | Azure Storage account key | `base64encodedkey==` | Azure Blob Storage secrets with static credentials; required when `useManagedIdentityForBlob` is set to `false` | - +| `mx-admin-password` | MxAdmin password | A password of 12 or more characters, with uppercase, lowercase, a digit, and a symbol | Always | +| `pclm-admin-username` | License-manager administrator username. Mounted as the constant `Common.PCLM_USERNAME` | `administrator` | Always | +| `pclm-admin-password` | License-manager administrator password. Mounted as the constant `Common.PCLM_PASSWORD` | The password that administrator was created with | Always | +| `database-type` | Database type | `PostgreSQL` | Secret store enabled | +| `database-host` | Database host and port | `postgres.example.com:5432` | Secret store enabled | +| `database-name` | Database name | `mxplatform` | Secret store enabled | +| `database-username` | Database user. For passwordless Azure PostgreSQL this is the role bound to the app identity | `mxplatform` | Secret store enabled | +| `database-password` | Database password | A password | Secret store enabled and `secretProviderclass.database.passwordless` is `false`. Do not create this secret when `passwordless` is `true`. Key Vault rejects an empty value, and any value you store is used instead of an Entra token | +| `database-jdbc-url` | JDBC connection URL | `jdbc:postgresql://postgres.example.com:5432/mxplatform?sslmode=require` | Secret store enabled | +| `storage-service-name` | Storage service name. Use `com.mendix.storage.azure` for Azure Blob Storage | `com.mendix.storage.azure` | Secret store enabled | +| `storage-azure-container` | Blob container for the app's own files | `mxplatform-files` | Secret store enabled | +| `storage-azure-blob-endpoint` | Blob endpoint | `https://mystorageaccount.blob.core.windows.net/` | Secret store enabled | +| `storage-azure-use-default-azure-credential` | Use the workload identity for blob access | `true` | Secret store enabled. Set `true` when `useManagedIdentityForBlob` is `true`, and `false` when you store an account key | +| `storage-perform-delete` | Delete blobs when the app deletes the file | `true` | Secret store enabled | +| `storage-use-ca-certificates` | Use the app trust store for the storage endpoint | `true` | Secret store enabled | +| `storage-azure-use-https` | Use HTTPS for blob access | `true` | Secret store enabled | +| `storage-azure-account-name` | Storage account name | `mystorageaccount` | Secret store enabled and `useManagedIdentityForBlob` is `false` | +| `storage-azure-account-key` | Storage account key | `` | Secret store enabled and `useManagedIdentityForBlob` is `false` | + +For S3 and for HashiCorp Vault, use the same database and admin keys. The S3 storage keys are listed in [SecretProviderClass Keys](/developerportal/deploy/secret-store-credentials/#keys). + +##### App Constants + +To override an app constant, mount an object named `mx-const-`. The chart's SecretProviderClass does not list extra constants. Starting from Private Mendix Platform 2.8.2, set `secretProviderclass.create` to `false` and add the object on a SecretProviderClass you maintain. Azure Key Vault names cannot contain a period or an underscore, so the vault name uses hyphens and `objectAlias` keeps the constant name. For `Encryption.EncryptionKey` the vault name is `encryption-key` and the alias is `mx-const-Encryption.EncryptionKey`. Runtime custom settings use `mx-runtime-`. The steps and a full object are in [Overriding App Constants](/private-mendix-platform/helmfile-installation/#override-constants). + ### Mxplatform-kube-agent Mxplatform-kube-agent is the Build agent for `mxplatform` app deployments. diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index 9bed8b3e3e5..9128e67fcbf 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -540,7 +540,7 @@ global: The SecretProviderClass allows you to store all sensitive credentials (passwords, connection strings, API keys) in a centralized vault (Azure Key Vault, AWS Secrets Manager, or HashiCorp Vault) instead of hardcoding them in configuration files. {{% alert color="warning" %}} -Secret Management for mxplatform is not compatible with Azure Managed Identity-based Storage Plans. +Do not set `secretProviderclass.enable` and `useStoragePlanwithIRSA` to `true` on `mxplatform` at the same time. A storage plan that uses workload identity and the secret store both need to own the app ServiceAccount. You can use a workload identity together with the secret store when `useStoragePlanwithIRSA` is `false`, so the chart creates the ServiceAccount. A database plan or a storage plan still provisions that resource. See [Using a Secret Store for the Platform App](#disable-provisioners). {{% /alert %}} ### Requirements @@ -589,7 +589,7 @@ helm install vault-csi-provider hashicorp/vault-csi-provider --namespace kube-sy | `svix-server` | PostgreSQL and Redis connection strings | | `mxplatform` | PCLM credentials, admin passwords, database credentials, storage credentials | -Secret Management for mxplatform is not compatible with Azure Managed Identity-based Storage Plans. +On `mxplatform`, keep `useStoragePlanwithIRSA` set to `false` when the secret store is enabled. See [Using a Secret Store for the Platform App](#disable-provisioners). #### Configuration Pattern @@ -690,6 +690,277 @@ mxplatform: # Authenticates with clientID: 33333333-3333-3333-3333-333333333333 ``` +#### Using a Secret Store for the Platform App {#disable-provisioners} + +The secret store for the Private Mendix Platform app is the setup described in [Retrieve Environment-Sensitive Data from a Secret Store](/developerportal/deploy/secret-store-credentials/). You can use it together with a [database plan](/developerportal/deploy/private-cloud-storage-plans/#database) or a [storage plan](/developerportal/deploy/private-cloud-storage-plans/#blob-storage). The Mendix Operator still creates each resource that has a plan. The secret store supplies the settings that do not come from a plan, such as the MxAdmin password and the license-manager credentials. + +##### ServicePlan + +Leave `spec.database.servicePlan` or `spec.storage.servicePlan` unset when you want to create that resource yourself. With the secret store enabled, both stay unset unless you set them. The chart requires a plan only when the secret store is off. For each plan you leave unset, the operator does not create that resource and reads its settings from the secret store. + +With a database plan and a storage plan, and with the secret store left off, the operator creates the database, file container, and managed identity while the app is being deployed. A role that the identity needs beyond what the plan grants, such as **Storage Blob Delegator** for MDA downloads, can only be assigned after that deployment has started. + +##### SecretProviderClass + +Set `secretProviderclass.enable` to `true`. The chart sets `allowOverrideSecretsWithSecretStoreCSIDriver` to `true`. A plan you leave unset is left off the MendixApp. A plan you set is written onto the MendixApp, and the operator runs that provisioner. The chart then omits that resource's keys from the SecretProviderClass. + +When a plan is unset, you must create the following yourself, before you install the app: + +* The identity the pod will use (an Azure user-assigned managed identity, or an AWS IAM role), and the federated credential that ties it to the app ServiceAccount. The ServiceAccount name is the MendixApp name. The default is `mxplatform`. The chart creates that ServiceAccount when `useStoragePlanwithIRSA` is `false`. The account does not have to exist before you create the federated credential. +* The database, and a database user that can use that database only. +* The file container for the app's own files, and the permission that lets the identity use that container. +* When the platform stores MDA files in Azure Blob Storage, the MDA container as well. Assign **Storage Blob Data Contributor** on that container and **Storage Blob Delegator** on the storage account. Delegator has no effect below the account, because a user-delegation key is an account operation. In Private Mendix Platform, set **Mda Location** to `https://.blob.core.windows.net/`. For the portal settings, see [Configuring MDA Storage Setting](/private-mendix-platform/configure-k8s/#mda-storage). The chart adds the pod label `azure.workload.identity/use: "true"` when `azureWorkloadIdentity.enable` is `true`, or when the secret store uses Azure and `useManagedIdentityForBlob` is `true`. You do not set that label on the operator. +* The secrets in the vault, under the key names in [Installation Reference](/private-mendix-platform/installation-reference/#secret-provider-key). + +##### PCLM Username and Passwords + +Leave `pclm.username`, `pclm.password`, and `spec.runtime.mxAdminPassword` out of the values file. The chart reads `pclm-admin-username` and `pclm-admin-password` from the vault and mounts them as the constants `Common.PCLM_USERNAME` and `Common.PCLM_PASSWORD`. It reads `mx-admin-password` as the MxAdmin password. + +##### UseStoragePlanwithIRSA + +Keep `useStoragePlanwithIRSA` set to `false`. With `true`, the operator creates the ServiceAccount from the storage plan, and the chart cannot attach the secret store to it. + ++The same identity can still open the database and the blob container without a stored password. That is workload identity on the ServiceAccount the chart creates. It is separate from the operator provisioner. See [Enabling the Secret Store](#enable-secret-store). + +On AWS and with HashiCorp Vault the same rule applies. A plan still provisions that resource. When the plan is unset, you create the database, the file storage, and the identity, and the operator does not. The key names for S3 are listed in [SecretProviderClass Keys](/developerportal/deploy/secret-store-credentials/#keys). + +#### Enabling the Secret Store {#enable-secret-store} + +To enable the secret store for `mxplatform`, install the CSI driver and provider as in [Example - Install CSI Driver](#example), create the resources in [Using a Secret Store for the Platform App](#disable-provisioners), and use values like the following. + +{{% alert color="warning" %}} ++The code samples are intended to show the range of available options. No rights can be derived from them, as they are presented as examples only, and may require significant adaptation to work in your own environment. It is your responsibility to interpret and adjust them to fit real-world scenarios. +{{% /alert %}} + +```text ++mxplatform: + enable: true + name: mxplatform + # The chart creates the ServiceAccount. The operator does not. + useStoragePlanwithIRSA: false + azureWorkloadIdentity: + enable: true + clientID: "" + tenantID: "" + secretProviderclass: + enable: true + provider: "azure" + # Omit database-password. The sidecar requests an Entra token instead. + database: + passwordless: true + azureparameters: + keyvaultName: "" + # Omit the storage account name and key. Blob access uses the workload identity. + useManagedIdentityForBlob: true + pclm: + serviceUrl: "http://mx-privatecloud-license-manager." + spec: + appURL: "mxplatform.example.com" + sourceURL: "oci-image:///mendix-private-platform:" + # Set this to the runtime version of the platform image. + mendixRuntimeVersion: "" + runtime: + applicationRootUrl: "https://mxplatform.example.com" +``` + +##### Explanation of the Values + +* `secretProviderclass.enable` sets `allowOverrideSecretsWithSecretStoreCSIDriver` to `true` and, when `secretProviderclass.create` is left at its default `true`, renders a SecretProviderClass with the same name as the app. The chart adds the annotation `privatecloud.mendix.com/environment-class: "true"`. +* `spec.database.servicePlan` and `spec.storage.servicePlan` stay empty unless you set them. An empty plan means the operator takes that resource's settings from the vault. A plan name means the operator provisions that resource. +* `secretProviderclass.database.passwordless` keeps `database-password` out of the SecretProviderClass. It requires `azureWorkloadIdentity.enable` or `awsIRSA.enable`, no database plan, and `secretProviderclass.create` left at `true`. For a SecretProviderClass you write yourself, leave `database-password` out of that object instead. The flag has no effect when `create` is `false`. +* `useManagedIdentityForBlob` adds the pod label `azure.workload.identity/use: "true"` and leaves out `storage-azure-account-name` and `storage-azure-account-key`. +* `useStoragePlanwithIRSA: false` makes the chart create the ServiceAccount and annotate it with `privatecloud.mendix.com/environment-account: "true"`. With `azureWorkloadIdentity.enable` set to `true`, it also annotates the client id and tenant id. The operator requires that ServiceAccount when a SecretProviderClass is used. + +{{% alert color="info" %}} +`SecretProviderclass.database.passwordless` is available starting from Private Mendix Platform 2.8.2. With `passwordless` set to `true`, that chart leaves `database-password` out of the SecretProviderClass. + +The `mxplatform` charts shipped with Private Mendix Platform 2.8.0 and 2.8.1 do not include this value. Those charts always request `database-password`. Helm ignores `passwordless` on those versions, so the key stays in the object. Remove that object from the SecretProviderClass after installation and after every upgrade that rewrites the object, and do not create the secret. + +`SecretProviderclass.create` is available in the same 2.8.2 release. See [Overriding App Constants](#override-constants). +{{% /alert %}} + +For AWS, set `awsIRSA.enable` and `awsIRSA.roleArn`, set `secretProviderclass.provider` to `aws`, and set `awsparameters.secretName`. For HashiCorp Vault, set `secretProviderclass.provider` to `vault` and fill in `vaultparameters`. + +##### Creating Azure Resources {#azure-resources} + +You must create the resources listed in [Using a Secret Store for the Platform App](#disable-provisioners) before you install the app. On Azure that is a Key Vault, one user-assigned managed identity, the platform database, and the file container. + +1. Provide an OIDC issuer and workload identity for the cluster. On AKS, the Key Vault CSI add-on does not enable them. + + 1. Add a federated credential for the app identity with the subject `system:serviceaccount::`, and the audience `api://AzureADTokenExchange`. + 2. Put the client ID and tenant ID in `azureWorkloadIdentity`. + +2. Give the *Key Vault Secrets User* Vault role for the app identity, and the *Key Vault Secrets Officer* for the account which writes the secrets. + + {{% alert color="warning" %}} + Do not register the app identity as a Microsoft Entra administrator of the PostgreSQL server. That role is an administrator of every database on the server. If the license manager uses the same server, the platform app can read and change its data. Create an ordinary role that can use only the platform database. + {{% /alert %}} + +3. Store the role name as `database-username`. +4. Assign the **Storage Blob Data Contributor** role on the file container. +5. If Private Mendix Platform must store MDA files in Azure Blob Storage, assign the **Storage Blob Data Contributor** role on the MDA container, and the **Storage Blob Delegator** role on the storage account. +6. Set **Mda Location** as described in [Configuring MDA Storage Setting](/private-mendix-platform/configure-k8s/#mda-storage). +7. Write the secrets listed in [Installation Reference](/private-mendix-platform/installation-reference/#secret-provider-key). + + Do not create `database-password` when `secretProviderclass.database.passwordless` is `true`. Key Vault rejects an empty value, and any value you store is used as the password instead of an Entra token. + +8. To store a database password instead of using an Entra token, leave `secretProviderclass.database.passwordless` at `false` and create `database-password`. +9. To use a storage account key instead of the workload identity, set `useManagedIdentityForBlob` to `false` and also create `storage-azure-account-name` and `storage-azure-account-key`. + +#### Overriding App Constants {#override-constants} + +A mounted object named `mx-const-` sets that constant. The secret store value overrides the same constant on the MendixApp. A mounted object named `mx-runtime-` overrides that [runtime custom setting](/refguide/custom-settings/). + +When the chart renders the SecretProviderClass, it maps the vault keys `pclm-admin-username` and `pclm-admin-password` to `mx-const-Common.PCLM_USERNAME` and `mx-const-Common.PCLM_PASSWORD`. You do not add those two constant names yourself. That class lists a fixed set of keys: the MxAdmin password, the two license-manager keys, and the database and storage keys the secret store supplies. It has no entry for any other constant, such as `Encryption.EncryptionKey`. + +Starting from Private Mendix Platform 2.8.2, set `secretProviderclass.create` to `false` and write the SecretProviderClass yourself. `secretProviderclass.enable` stays `true`, so the chart still sets `allowOverrideSecretsWithSecretStoreCSIDriver` to `true`. It does not render a SecretProviderClass, and it ignores the `secretProviderclass` provider parameters. On 2.8.0 and 2.8.1 this value does not exist. Helm ignores it, and the chart still renders its own SecretProviderClass. + +```text +mxplatform: + secretProviderclass: + enable: true + # The chart still sets allowOverrideSecretsWithSecretStoreCSIDriver. + # It does not render a SecretProviderClass. + create: false +``` + +##### Requirements for SecretProviderClass + +Your SecretProviderClass must meet all of the following requirements: + +* Its name is the MendixApp name (`mxplatform` by default, or `-test` when `testApp` is `true`). The name is the app name, not the name of a separate Helm release. +* It is in the same namespace as the MendixApp. +* It has the annotation `privatecloud.mendix.com/environment-class: "true"`. +* It mounts the same object aliases the chart would have mounted (see the key table in [Installation Reference](/private-mendix-platform/installation-reference/#secret-provider-key)), plus the extra constants. When you write the class, include `mx-const-Common.PCLM_USERNAME` and `mx-const-Common.PCLM_PASSWORD` yourself. +* For a passwordless database, leave `database-password` out of this list. `secretProviderclass.database.passwordless` has no effect when `create` is `false`, so the chart does not remove that key for you. +* Keep `azureWorkloadIdentity.clientID` and `azureWorkloadIdentity.tenantID` in the values, so the chart can annotate the ServiceAccount. Repeat that client id and tenant id in the SecretProviderClass. The chart does not copy them when `create` is `false`. + +Azure Key Vault secret names cannot contain periods or underscores. Store the secret under a name that uses hyphens, and set `objectAlias` to the name the runtime reads. The alias keeps the periods and underscores. The chart does not rewrite those names. + +The following SecretProviderClass is a passwordless Azure setup. Blob access uses the workload identity, so the storage account name and key are absent. The license-manager keys are aliased to constants, and the remaining objects are further constants the chart cannot add. Keep the constants your app reads. + +{{% alert color="warning" %}} +The code samples are intended to show the range of available options. No rights can be derived from them, as they are presented as examples only, and may require significant adaptation to work in your own environment. It is your responsibility to interpret and adjust them to fit real-world scenarios. +{{% /alert %}} + +```text ++apiVersion: secrets-store.csi.x-k8s.io/v1 ++kind: SecretProviderClass ++metadata: + name: mxplatform + namespace: + annotations: + privatecloud.mendix.com/environment-class: "true" ++spec: + provider: azure + parameters: + clientID: "" + keyvaultName: "" + tenantID: "" + objects: | + array: + - | + objectName: database-type + objectType: secret + objectAlias: database-type + - | + objectName: database-jdbc-url + objectType: secret + objectAlias: database-jdbc-url + - | + objectName: database-host + objectType: secret + objectAlias: database-host + - | + objectName: database-name + objectType: secret + objectAlias: database-name + - | + objectName: database-username + objectType: secret + objectAlias: database-username + - | + objectName: storage-service-name + objectType: secret + objectAlias: storage-service-name + - | + objectName: storage-azure-container + objectType: secret + objectAlias: storage-azure-container + - | + objectName: storage-azure-blob-endpoint + objectType: secret + objectAlias: storage-azure-blob-endpoint + - | + objectName: storage-azure-use-default-azure-credential + objectType: secret + objectAlias: storage-azure-use-default-azure-credential + - | + objectName: storage-perform-delete + objectType: secret + objectAlias: storage-perform-delete + - | + objectName: storage-use-ca-certificates + objectType: secret + objectAlias: storage-use-ca-certificates + - | + objectName: storage-azure-use-https + objectType: secret + objectAlias: storage-azure-use-https + - | + objectName: mx-admin-password + objectType: secret + objectAlias: mx-admin-password + - | + objectName: pclm-admin-username + objectType: secret + objectAlias: mx-const-Common.PCLM_USERNAME + - | + objectName: pclm-admin-password + objectType: secret + objectAlias: mx-const-Common.PCLM_PASSWORD + - | + objectName: encryption-key + objectType: secret + objectAlias: mx-const-Encryption.EncryptionKey + - | + objectName: portunus-authenticator-username + objectType: secret + objectAlias: mx-const-PortunusAdaptor.MXPC_AUTHENTICATOR_USERNAME + - | + objectName: portunus-authenticator-password + objectType: secret + objectAlias: mx-const-PortunusAdaptor.MXPC_AUTHENTICATOR_PASSWORD + - | + objectName: portunus-collector-username + objectType: secret + objectAlias: mx-const-PortunusAdaptor.MXPC_COLLECTOR_USERNAME + - | + objectName: portunus-collector-password + objectType: secret + objectAlias: mx-const-PortunusAdaptor.MXPC_COLLECTOR_PASSWORD + - | + objectName: portunus-interactor-username + objectType: secret + objectAlias: mx-const-PortunusAdaptor.MXPC_INTERACTOR_USERNAME + - | + objectName: portunus-interactor-password + objectType: secret + objectAlias: mx-const-PortunusAdaptor.MXPC_INTERACTOR_PASSWORD + - | + objectName: jenkins-build-agent-user + objectType: secret + objectAlias: mx-const-Jenkins.BuildAgentUser + - | + objectName: jenkins-build-agent-password + objectType: secret + objectAlias: mx-const-Jenkins.BuildAgentPassword +``` + +Apply this object in the app namespace before the platform pod starts. The full key list, including runtime settings, is in [SecretProviderClass Keys](/developerportal/deploy/secret-store-credentials/#keys). + +Changing a constant or a runtime setting in the vault is picked up by the CSI driver after a short delay. The running runtime does not apply that change until the app is restarted. File storage credentials and the MxAdmin password are applied without that limitation. For the operator behavior, see [Additional Considerations](/developerportal/deploy/secret-store-credentials/#additional-considerations). + #### Auto-Generated Credentials Auto-generated credentials are used for internal component communication. @@ -707,7 +978,7 @@ This method is upgrade-safe. Existing credentials are preserved through lookup. Workload Identity enables components to connect to cloud resources without passwords. Instead of storing passwords and access keys in configuration files, components use cloud-native identity (AWS IAM or Azure Managed Identity) to authenticate. {{% alert color="info" %}} -You cannot combine Workload Identity with SecretProviderClass secret management. The two solutions are mutually exclusive. +On `mxplatform`, do not combine `useStoragePlanwithIRSA: true` with `secretProviderclass.enable: true`. You can use a workload identity with the secret store when the chart creates the ServiceAccount. See [Using a Secret Store for the Platform App](#disable-provisioners). {{% /alert %}} ### Supported Components @@ -897,23 +1168,17 @@ mx-privatecloud: password: "" # Empty - Managed Identity authentication ``` -#### Workload Identity vs Secret Provider Class +#### Workload Identity vs Secret Provider Class for PCLM and Mx-PrivateCloud -Workload Identity and Secret Provider Class are different approaches for database credentials management. +For `mx-privatecloud-license-manager` and `mx-privatecloud`, workload identity and the SecretProviderClass are two ways to supply database credentials. Use one of them for a component's database. For the Private Mendix Platform app, the secret store can be used with a plan and can still use a workload identity. A plan still provisions that resource. See [Storage Plans and the Secret Store for Mxplatform](#storage-plan-or-secret-store). | Feature | Workload Identity (IAM Authentication) | Secret Provider Class | | --- | --- | --- | -| Purpose | Passwordless database connection at runtime | Inject all secrets from vault during installation | -| What it secures | Database passwords only | Database credentials and all other secrets | -| Configuration | `awsIRSA.enable: true` or azureWorkloadIdentity.enable: true` and empty passwords | `secretProviderclass.enable: true` | +| Purpose | Passwordless database connection at runtime | Inject credentials from a vault | +| What it secures | Database passwords for PCLM, Authenticator, and Collector | Database credentials and the other secrets those components read from the vault | +| Configuration | `awsIRSA.enable: true` or `azureWorkloadIdentity.enable: true`, and an empty password | `secretProviderclass.enable: true` | | Works with | AWS RDS IAM authentication or Azure Database Managed Identity authentication | AWS Secrets Manager, Azure Key Vault, HashiCorp Vault | -| Credential type | Temporary cloud tokens (auto-rotated) | Static secrets from vault | -| Can it be combined? | No - mutually exclusive with Secret Provider Class | No - mutually exclusive with Workload Identity | - -##### Key Differences - -* Workload Identity - Components use cloud identity to connect to databases (no passwords stored anywhere). -* Secret Provider Class - Helm retrieves database passwords from a vault and injects them during installation. Passwords exist in vault as static secrets. +| Credential type | Temporary cloud tokens, rotated by the cloud provider | The values stored in the vault | ### Use Case 2: Mxplatform Database and Storage Authentication @@ -922,7 +1187,7 @@ For `mxplatform`, Workload Identity provides passwordless authentication for bot For complete scenarios and Storage Plan configuration examples, see [Storage Plans](/developerportal/deploy/private-cloud-storage-plans/). {{% alert color="info" %}} -This type of authentication applies to runtime data access. It does not apply to installation secrets (that is, admin passwords and PCLM credentials). For those secrets, use the Secret Provider Class. +On this path the operator creates the database, the file storage, and the identity. The MxAdmin password and the PCLM credentials stay in the values file. To read those settings from a vault, and to leave provisioning to yourself where you do not set a plan, use [Enabling the Secret Store](#enable-secret-store). {{% /alert %}} #### Configuring Workload Identity Authentication @@ -934,7 +1199,7 @@ To configure Workload Identity authentication, perform the following steps: * For AWS, specify the IAM role ARN that has permissions to access RDS/S3. * For Azure, specify the Managed Identity client ID that has permissions to access the Azure Database and Blob Storage. -2. Set `UseStoragePlanwithIRSA` to `true` in the Helmfile configuration for `mxplatform`. +2. Set `useStoragePlanwithIRSA` to `true` in the Helmfile configuration for `mxplatform`. 3. Reference these plans in `spec.database.servicePlan` and `spec.storage.servicePlan`. #### How It Works @@ -953,7 +1218,7 @@ Mendix Operator automatically performs the following tasks: * Configures mxplatform pods to use this ServiceAccount. {{% alert color="info" %}} -When `UseStoragePlanwithIRSA` is set to `true`, the Mendix Operator creates the ServiceAccount, not the Helm chart. This causes the following limitations: +When `useStoragePlanwithIRSA` is set to `true`, the Mendix Operator creates the ServiceAccount, not the Helm chart. This causes the following limitations: * Chart-level `azureWorkloadIdentity` configuration is not supported for mxplatform. * The chart cannot add `azure.workload.identity/client-id` annotation. The Service account will be created by the Operator. @@ -1005,7 +1270,7 @@ To configure an Azure Storage Plan with Managed Identity, perform the following mxplatform: enable: true # REQUIRED: Let Operator create ServiceAccount - UseStoragePlanwithIRSA: true + useStoragePlanwithIRSA: true pclm: serviceUrl: "http://mx-privatecloud-license-manager" username: "administrator" @@ -1023,133 +1288,57 @@ To configure an Azure Storage Plan with Managed Identity, perform the following mxAdminPassword: "admin-password" ``` -Mendix Operator creates the ServiceAccount with `azure.workload.identity/client-id annotation`, enabling passwordless Azure Database and Blob Storage access. +The Mendix Operator creates the ServiceAccount with the `azure.workload.identity/client-id` annotation. The app then connects to Azure Database for PostgreSQL and Blob Storage with that identity. -#### Workload Identity vs Secret Provider Class for Mxplatform +#### Storage Plans and the Secret Store for Mxplatform {#storage-plan-or-secret-store} -Workload Identity and Secret Provider Class are different approaches for database credentials management. +A storage plan with workload identity and the secret store can be used for the same platform app, with one limit. Do not set `useStoragePlanwithIRSA` to `true` together with the secret store. Both need to own the ServiceAccount. A database plan or a storage plan can still be set while the secret store is enabled. The operator provisions that resource, and the chart creates the ServiceAccount. -| Feature | Workload Identity (StoragePlan) | Secret Provider Class (CSI) | +| | Storage plan with workload identity | Secret store | | --- | --- | --- | -| Purpose | Runtime connection to cloud database and storage | Inject all secrets from vault | -| What it authenticates | mxplatform app connecting to database and storage | Database, Storage, Admin password, and PCLM credentials | -| Credentials | Temporary cloud tokens (auto-rotated by AWS or Azure) | Static secrets from vault | -| Configuration | In StoragePlan CRDs and `UseStoragePlanwithIRSA: true` | `secretProviderclass.enable: true` | -| ServiceAccount | Created by Mendix Operator (based on StoragePlan) | Created by Helm chart | -| Can it be combined? | No - mutually exclusive with Secret Provider Class | No - mutually exclusive with Workload Identity | - -##### Key Differences - -* Workload Identity - Your running Mendix application uses cloud identity to connect to its database and file storage (no database passwords in configuration). -* Secret Provider Class - Helm chart retrieves secrets from vault to configure or install the components (admin passwords, PCLM credentials, database connection strings). - -##### Decision Matrix - -Use Workload Identity (StoragePlan) when: - -* You want passwordless database and storage access for your running Mendix application. -* You are on AWS EKS or Azure AKS with native cloud database or storage services. -* You want automatic credential rotation (with the cloud provider handling the token refresh). -* You only need to secure runtime database or storage connections; admin password and PCLM can be set in a values file or traditional secrets. -* Example scenario: *My Mendix app should connect to Azure Database for PostgreSQL and Azure Blob Storage using Managed Identity, without storing any database passwords*. - -Use Secret Provider Class when: - -* You want all installation secrets (admin password, PCLM credentials, database connection strings, storage credentials) from a centralized vault. -* You need multi-cloud secret management (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault). -* You want centralized secret management across all Private Mendix Platform components (mx-privatecloud, svix-server, mxplatform). -* You are using HashiCorp Vault or managing secrets across multiple cloud providers. -* Example scenario: *I want to store all Private Mendix Platform installation secrets (PCLM password, admin password, database credentials) in Azure Key Vault and inject them during Helm installation.* - -The two solutions cannot be used together. They are mutually exclusive for `mxplatform`. +| Who creates the database, file container, and app identity | Mendix Operator, during deployment | You, when the plan is unset. The operator, when the plan is set | +| Database and file settings | Taken from the plan | Taken from the vault | +| ServiceAccount | Created by the operator. Set `useStoragePlanwithIRSA` to `true` | Created by the chart. Set `useStoragePlanwithIRSA` to `false` | +| Passwordless database and blob access | Yes, through the plan | Yes, when `secretProviderclass.database.passwordless` and `useManagedIdentityForBlob` are `true` | +| MxAdmin password and PCLM credentials | In the values file, unless you add them some other way | In the vault (`mx-admin-password`, `pclm-admin-username`, `pclm-admin-password`) | +| Extra roles, such as Storage Blob Delegator for MDA files | Assigned after the operator has created the identity | Assigned before installation, on the identity you created | +| App constants | On the MendixApp | Any `mx-const-` object in the secret store. See [Overriding App Constants](#override-constants) | -If `UseStoragePlanwithIRSA` is set to `true`, the Operator creates the ServiceAccount with database and storage identity. The chart then cannot use Secret Provider Class for that ServiceAccount. +Use a storage plan when you want the operator to create the database, the file container, and the identity while the app is deployed, and you can assign any further roles after that identity exists. -If `secretProviderclass.enable` is set to `true`, the chart creates the ServiceAccount with vault access. The chart cannot then use StoragePlan with Workload Identity for database or storage. +Use the secret store when the MxAdmin password, the license-manager credentials, and any extra app constants should come from the vault. Leave a plan unset when you want to create that resource yourself, before installation, including roles the plan does not grant, such as **Storage Blob Delegator**. Passwordless access still uses a workload identity. The chart attaches that identity to the ServiceAccount. The steps are in [Using a Secret Store for the Platform App](#disable-provisioners) and [Enabling the Secret Store](#enable-secret-store). -Both approaches must control the ServiceAccount annotations, but in different ways (through the Operator or Helm for Private Mendix Platform). - -##### Approach 1: Workload Identity (StoragePlan) +##### Approach 1: Storage Plan with Workload Identity {{% alert color="warning" %}} The code samples are intended to show the range of available options. No rights can be derived from them, as they are presented as examples only, and may require significant adaptation to work in your own environment. It is your responsibility to interpret and adjust them to fit real-world scenarios. {{% /alert %}} -This approach secures how your Mendix application connects to its database and storage at runtime with passwordless runtime database and storage access. +The Operator provisions the database and file storage and creates the ServiceAccount. Leave the secret store disabled. ```text mxplatform: - # Enable StoragePlan with Workload Identity - UseStoragePlanwithIRSA: true - # Installation secrets still in values file + useStoragePlanwithIRSA: true pclm: serviceUrl: "http://mx-privatecloud-license-manager" username: "administrator" password: "pclm-password" spec: - # Reference StoragePlans that have Managed Identity configuration - database: - servicePlan: "azure-postgres-plan" # StoragePlan with Managed Identity client ID - storage: - servicePlan: "azure-blob-plan" # StoragePlan with Managed Identity client ID - runtime: - mxAdminPassword: "admin-password" # Still in values file - secretProviderclass: - enable: false # Cannot be used - ServiceAccount managed by Operator -``` - -This secures the following: - -* Runtime database connection - The app uses Managed Identity to connect to PostgreSQL (no database password in configuration). -* Runtime storage connection - The app uses Managed Identity to access Blob Storage (no storage access key in configuration). - -Installation secrets (PCLM password, admin password) are still in the values file. - -##### Approach 2: Secret Provider Class - -{{% alert color="warning" %}} -The code samples are intended to show the range of available options. No rights can be derived from them, as they are presented as examples only, and may require significant adaptation to work in your own environment. It is your responsibility to interpret and adjust them to fit real-world scenarios. -{{% /alert %}} - -This approach secures centralized installation and configuration secrets by retrieving them from Azure Key Vault during Helm installation. - -```text -mxplatform: - # No StoragePlan workload identity - UseStoragePlanwithIRSA: false - # All credentials from Key Vault (empty values = injected from vault) - pclm: - serviceUrl: "http://mx-privatecloud-license-manager" - username: "" # Injected from Key Vault secret "pclm-admin-username" - password: "" # Injected from Key Vault secret "pclm-admin-password" - spec: - # Database and storage credentials from Key Vault database: - servicePlan: "" # Credentials injected from Key Vault + servicePlan: "azure-postgres-plan" storage: - servicePlan: "" # Credentials injected from Key Vault + servicePlan: "azure-blob-plan" runtime: - mxAdminPassword: "" # Injected from Key Vault secret "mx-admin-password" - # Managed Identity to ACCESS Key Vault (not for database/storage) - azureWorkloadIdentity: - enable: true - clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Identity with Key Vault Secrets User role - tenantID: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" + mxAdminPassword: "admin-password" secretProviderclass: - enable: true - provider: "azure" - azureparameters: - keyvaultName: "my-keyvault" # Vault containing all installation secrets + enable: false ``` -This secures the following: +The app connects to PostgreSQL and Blob Storage with the managed identity from the plan. The PCLM password and the MxAdmin password are still in the values file. -* PCLM credentials - Retrieved from Key Vault during installation. -* Admin password - Retrieved from Key Vault during installation. -* Database credentials - Retrieved from Key Vault (but stored as static passwords in Vault). -* Storage credentials - Retrieved from Key Vault (but stored as static access keys in vault). +##### Approach 2: Secret Store -Runtime connections still use static passwords and keys, not cloud-native passwordless authentication. +Enable the secret store and set `useStoragePlanwithIRSA` to `false`. Leave the database plan and the storage plan unset. Create the database, file storage, identity, and role assignments yourself. The values are in [Enabling the Secret Store](#enable-secret-store). To override a constant, see [Overriding App Constants](#override-constants). A plan can be set as well. The operator then provisions that resource. ## Troubleshooting Critical Issues diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index c21ed573bc5..5c82f1b5667 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -117,9 +117,11 @@ Configure the namespace by doing the following steps: {{< figure src="/attachments/private-platform/pmp-install5.png" class="no-border" >}} -## Optional: Configuring the AWS Secret Manager +## Optional: Configuring the AWS Secret Manager {#aws-secret-manager} -To use the secret provider option for your database plan or storage plan, configure the following keys in your AWS Secret Manager: +**USE-Secret-Provider** leaves that plan unset, so the Operator does not create the resource. Create it yourself, then store its settings in AWS Secrets Manager under the following keys. + +You can instead enter a plan. The Operator then creates that resource, and the secret store supplies the settings that do not come from a plan. For more information, see [What the Secret Store Does Not Provision](#secret-store-no-provisioner). ### Database Plan Keys @@ -130,7 +132,9 @@ To use the secret provider option for your database plan or storage plan, config | Database host | **database-host** | `pg.example.com:5432` | | Database name | **database-name** | `my-app-1` | | Database user name | **database-username** | `my-app-user-1` | -| Database password | **database-password** | | +| Database password | **database-password** | | + +Leave `database-password` out when the database authenticates the app by its identity. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). ### Storage Plan Keys @@ -154,9 +158,11 @@ Currently, only AWS S3 or S3-compatible providers are supported. | Private Mendix Platform admin password | **mx-admin-password** | | PCLM admin username | **pclm-admin-username** | -## Optional: Configuring Azure Key Vault +## Optional: Configuring Azure Key Vault {#azure-key-vault} -To use the secret provider option for your database plan or storage plan, configure the following keys in your Azure Key Vault. All keys are required unless noted otherwise. +**USE-Secret-Provider** leaves that plan unset, so the operator does not create the resource. Create it yourself, then store its settings in Azure Key Vault under the following keys. All keys are required unless noted otherwise. + +You can instead enter a plan. The operator then creates that resource, and the secret store supplies the settings that do not come from a plan. For more information, see [What the Secret Store Does Not Provision](#secret-store-no-provisioner). ### Database Plan Keys @@ -169,6 +175,8 @@ To use the secret provider option for your database plan or storage plan, config | Database user name | **database-username** | `pxx` | | Database password | **database-password** | `passxx` | +Leave `database-password` out when the database authenticates the app by its identity. Key Vault rejects an empty value, and a stored value is used instead of an Entra token. For more information, see [What the Secret Store Does Not Provision](#secret-store-no-provisioner). + ### Storage Plan Keys | Data Type | Key | Example Value | Notes | @@ -191,6 +199,28 @@ To use the secret provider option for your database plan or storage plan, config | Private Mendix Platform admin password | **mx-admin-password** | | PCLM admin username | **pclm-admin-username** | +The chart mounts `pclm-admin-username` and `pclm-admin-password` as the constants `Common.PCLM_USERNAME` and `Common.PCLM_PASSWORD`. + +## What the Secret Store Does Not Provision {#secret-store-no-provisioner} + +Enabling **Use Secret Provider** turns on the secret store described in [Retrieve Environment-Sensitive Data from a Secret Store](/developerportal/deploy/secret-store-credentials/). For **DatabasePlan** and **Storageplan**, **USE-Secret-Provider** leaves the plan unset and the operator does not create that resource. You create it and store its settings in the vault. A plan name still makes the operator create that resource. The secret store supplies the settings that do not come from a plan, including the MxAdmin password and the license-manager credentials. + +You must create the following before you install the app: + +* The identity the pod will use, and a federated credential for the ServiceAccount. The ServiceAccount name is the **AppName** (the default is `mxplatform`). With **StoragePlanwithIRSA** left disabled, the installer creates that ServiceAccount. +* The database, and a database user that can use that database only. Do not make the app identity a Microsoft Entra administrator of the whole PostgreSQL server. That role can read every database on the server, including the license manager database when they share a server. +* The file container for the app's own files, and permission for the identity to use that container. +* When the platform stores MDA files in Azure Blob Storage, the MDA container, **Storage Blob Data Contributor** on that container, and **Storage Blob Delegator** on the storage account. Set **Mda Location** as described in [Configuring MDA Storage Setting](/private-mendix-platform/configure-k8s/#mda-storage). +* The secrets listed in [Configuring the AWS Secret Manager](#aws-secret-manager) or [Configuring Azure Key Vault](#azure-key-vault). + ++In the installer, leave **StoragePlanwithIRSA** disabled. Enabling it turns **Use Secret Provider** off, because the operator would create the ServiceAccount from the storage plan. + +For a passwordless database, do not create `database-password`. Key Vault rejects an empty value, and any value you store is used as the password instead of a token. Starting from Private Mendix Platform 2.8.2, the Helmfile value `secretProviderclass.database.passwordless` keeps that key out of the SecretProviderClass. The charts shipped with Private Mendix Platform 2.8.0 and 2.8.1, and the interactive installer, always request the key. On those versions, remove the `database-password` object from the SecretProviderClass after install and after every upgrade that puts it back. See [Enabling the Secret Store](/private-mendix-platform/helmfile-installation/#enable-secret-store). + +**Use identity auth for Blob** corresponds to `useManagedIdentityForBlob`. Set it to **True** to omit `storage-azure-account-name` and `storage-azure-account-key`, and set `storage-azure-use-default-azure-credential` to `true`. + +To override any other app constant, such as `Encryption.EncryptionKey`, mount an object named `mx-const-`. The SecretProviderClass created by the installer lists only the fixed keys above. Starting from Private Mendix Platform 2.8.2, add further constants with Helmfile by setting `secretProviderclass.create` to `false` and writing the SecretProviderClass yourself. See [Overriding App Constants](/private-mendix-platform/helmfile-installation/#override-constants). + ## Installing Private Cloud License Manager {#install-pclm} Private Cloud License Manager is a required component of Private Mendix Platform. Before you install the Platform, install PCLM by doing the following steps: @@ -484,11 +514,11 @@ Install the Private Mendix Platform by doing the following steps: 3. Click **Configure**, and then specify the following parameters: * **AppName** - The default app name is `mxplatform`. You can change it as required. - * **DatabasePlan** - If you want to use AWS Secret Manager, select **USE-Secret-Provider**; the installer then uses the database configuration set in AWS Secret Manager. Otherwise, enter the name of the database plan that you created in [Installing and Configuring the Mendix Operator](#install-operator). - * **Storageplan** - If you want to use AWS Secret Manager, select **USE-Secret-Provider**; the installer then uses the storage configuration set in AWS Secret Manager. Otherwise, enter the name of the storage plan that you created in [Installing and Configuring the Mendix Operator](#install-operator). + * **DatabasePlan** - Enter the database plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the database. **USE-Secret-Provider** leaves the plan unset. You create the database and store its settings in the secret store. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). + * **Storageplan** - Enter the storage plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the file storage. **USE-Secret-Provider** leaves the plan unset. You create the container and its permissions. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). * **StoragePlanwithIRSA** - If your storage plan uses AWS IRSA or Azure Workload Identity, set this to **enabled**. - Enabling this option disables the **secretprovider** option. This is because for IRSA and Azure Workload Identity storage plans, the Service account is created by the Operator instead of Helm. + Enabling this option disables **Use Secret Provider**. The operator creates the ServiceAccount from the storage plan, and the secret store needs the installer to create that account. Leave this disabled when **Use Secret Provider** is enabled. You can still use a workload identity. The identity is the one you created, and the installer uses it to annotate the ServiceAccount. * **AppUrl** - The endpoint where you can connect to your running app. It must be a URL which is supported by your platform. If you leave it blank, Mendix Operator will create it. * **EnableTLS** - Allows you to enable or disable TLS for the Mendix app's Ingress or OpenShift Router. The default value is use the default settings. @@ -502,7 +532,7 @@ Install the Private Mendix Platform by doing the following steps: 4. Click **Runtime**, and then specify the following parameters: - * **MxAdminPassword** - Optional. The password for the admin user, required if you are not planning to use the AWS Secret Manager. It must have at least one number, one upper case letter, one lower case letter and one symbol, with a minimum length of 12 characters. + * **MxAdminPassword** - The password for the admin user. Leave it empty when **Use Secret Provider** is enabled. The app then reads `mx-admin-password` from the secret store. Otherwise this password is required. It must have at least one number, one upper case letter, one lower case letter and one symbol, with a minimum length of 12 characters. * **dtapmode** - For production deployments, leave this value set to **P**. For the development of the app, for example acceptance testing, set the value to **D**. * **ApplicationRootUrl** - Optional. Manually specify the URL of your Private Mendix Platform, for example, for use with SSO or when sending emails. For more information about this functionality, see [ApplicationRootUrl Needs to be Set Manually](/developerportal/deploy/private-cloud-operator/#applicationrooturl-needs-to-be-set-manually). * **Use Secret Provider** - Optional. Select this option to use the AWS Secret Manager or the Azure Key Vault. Selecting this option enables the following additional fields: diff --git a/content/en/docs/private-platform/secret-management/_index.md b/content/en/docs/private-platform/secret-management/_index.md index 82a0a8a7b72..d9b54123eaf 100644 --- a/content/en/docs/private-platform/secret-management/_index.md +++ b/content/en/docs/private-platform/secret-management/_index.md @@ -11,4 +11,6 @@ description_list: true Documents in this section provide more information about configuring secret management for Private Mendix Platform. Some of the settings that you configure here are initially set by the [Private Platform Configuration Wizard](/private-mendix-platform/configuration-wizard/). Administrators can also update them at any time after the initial configuration. +The documents cover credentials that Private Mendix Platform stores for its own administration, such as version control tokens. To run the platform app from the secret store described in [Retrieve Environment-Sensitive Data from a Secret Store](/developerportal/deploy/secret-store-credentials/), and to override app constants from that store, see [Using a Secret Store for the Platform App](/private-mendix-platform/helmfile-installation/#disable-provisioners). + For more information about all configuration options available to Private Mendix Platform administrators, refer to [Private Mendix Platform Functionalities - Administrators](/private-mendix-platform/reference-guide/admin/). From f96398ae8f32127995f6f348c7c5347a207e2c10 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:24:13 +0100 Subject: [PATCH 02/18] Update pmp-quickstart.md --- content/en/docs/private-platform/quickstart/pmp-quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index 5c82f1b5667..2db2e0efb55 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -518,7 +518,7 @@ Install the Private Mendix Platform by doing the following steps: * **Storageplan** - Enter the storage plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the file storage. **USE-Secret-Provider** leaves the plan unset. You create the container and its permissions. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). * **StoragePlanwithIRSA** - If your storage plan uses AWS IRSA or Azure Workload Identity, set this to **enabled**. - Enabling this option disables **Use Secret Provider**. The operator creates the ServiceAccount from the storage plan, and the secret store needs the installer to create that account. Leave this disabled when **Use Secret Provider** is enabled. You can still use a workload identity. The identity is the one you created, and the installer uses it to annotate the ServiceAccount. + Enabling this option disables **Use Secret Provider**. The operator creates the ServiceAccount from the storage plan, and the secret store needs the installer to create that account. Leave this disabled when **Use Secret Provider** is enabled. You can still use a Workload identity. The identity is the one you created, and the installer uses it to annotate the ServiceAccount. * **AppUrl** - The endpoint where you can connect to your running app. It must be a URL which is supported by your platform. If you leave it blank, Mendix Operator will create it. * **EnableTLS** - Allows you to enable or disable TLS for the Mendix app's Ingress or OpenShift Router. The default value is use the default settings. From 0c49a3c50015bbd1b256537fe19b2fe6ffb0a003 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 19 Nov 2026 20:26:35 +0100 Subject: [PATCH 03/18] vale --- .../quickstart/pmp-quickstart.md | 214 +++++++++--------- 1 file changed, 107 insertions(+), 107 deletions(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index 5c82f1b5667..81eb32c1b79 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -20,12 +20,12 @@ Before you start the installation, download the required files by performing the 2. Unzip the release binary to a local folder on your Windows or Linux server. The release binary contains the following files: - * **Tools** - *mx-pclm-cli*, which can be used to manage PCLM + * **Tools** – *mx-pclm-cli*, which can be used to manage PCLM * **helm**, and **helmfile** tools, which are used to deploy and manage Private Mendix Platform charts and Svix charts - * **images** - Private Mendix Platform image, PCLM image, Svix image, test application image - * **Installer** - installer tools - * **mxpc-cli** - installation tools which can be used to manage or configure the Mendix Operator - * **charts** - charts, including Private Mendix Platform charts and Svix charts + * **images** – Private Mendix Platform image, PCLM image, Svix image, test application image + * **Installer** – installer tools + * **mxpc-cli** – installation tools which can be used to manage or configure the Mendix Operator + * **charts** – charts, including Private Mendix Platform charts and Svix charts {{< figure src="/attachments/private-platform/pmp-binary.png" class="no-border" >}} @@ -78,8 +78,8 @@ Install the Mendix Operator by doing the following steps: 1. Run one of the following commands, where `-n` indicates the namespace: - * `./mxpc-cli installer -n=` - To install the Operator in [Standard](/developerportal/deploy/standard-operator/) mode - * `./mxpc-cli installer --global -n=` - To install the Operator in [Global](/developerportal/deploy/global-operator/) mode; you must use a Global namespace for this installation type. + * `./mxpc-cli installer -n=` – To install the Operator in [Standard](/developerportal/deploy/standard-operator/) mode + * `./mxpc-cli installer --global -n=` – To install the Operator in [Global](/developerportal/deploy/global-operator/) mode; you must use a Global namespace for this installation type. In order to install and configure a cluster with a Global installation of the Operator and the Agent, you must use Operator version 2.21.2 or above. @@ -230,7 +230,7 @@ Private Cloud License Manager is a required component of Private Mendix Platform 3. Specify the following parameters: * **Databasetype** – The database type, either **postgres** (default) or **sqlserver**. - * **DB Authentication mode** - The authentication mode for the database: + * **DB Authentication mode** – The authentication mode for the database: * **static** (default) * **aws-irsa** * **azure-wi** @@ -247,8 +247,8 @@ Private Cloud License Manager is a required component of Private Mendix Platform * **Admin Password** – A new PCLM admin password. When the PCLM server is set up, it contains an *administrator* user with a default password. This password should be modified immediately. * **PCLM Operator User** – A new PCLM operator user. * **PCLM Operator Password** – A new PCLM operator password. - * **Global Operator Namespace** - If you are using Mendix Operator in Global mode, enter the Global namespace information. If not, leave this field blank. - * **Customized cluster domain** - The default is `cluster.local`. Change the value if you are using a different internal cluster domain. + * **Global Operator Namespace** – If you are using Mendix Operator in Global mode, enter the Global namespace information. If not, leave this field blank. + * **Customized cluster domain** – The default is `cluster.local`. Change the value if you are using a different internal cluster domain. 4. Click **Install PCLM**. @@ -269,8 +269,8 @@ Svix is required if you want to use webhooks. Install the Svix component by doin 1. Configure the secret in AWS Secret Manager by providing the following information: - * **POSTGRES DSN** - The key is `svix-db-dsn`; an example value may be similar to `postgresql://postgres:postgres@pgbouncer/postgres`. - * **Redis DSN** - This value is only required if you also use Redis for Svix. The key is `svix-redis-dsn`; an example value may be similar to `redis://redis:6379`. + * **POSTGRES DSN** – The key is `svix-db-dsn`; an example value may be similar to `postgresql://postgres:postgres@pgbouncer/postgres`. + * **Redis DSN** – This value is only required if you also use Redis for Svix. The key is `svix-redis-dsn`; an example value may be similar to `redis://redis:6379`. 2. Configure an IAM role with the **secretsmanager:GetSecretValue** and **secretsmanager:DescribeSecret** permissions and allow it to assume the Service Account which the Svix pod will use to retrieve the secret info. @@ -310,28 +310,28 @@ Svix is required if you want to use webhooks. Install the Svix component by doin 3. Run the command `./installer component -n=`, where `-n` indicates a namespace. The namespace must be the same as the namespace that you plan to use for Private Mendix Platform. 4. Select **Svix**, and then specify the following parameters: - * **Image Prefix** - The registry and namespace (if it exists) where the *svix-server* image is located - * **Image Name** - The image name, for example, *svix-server* - * **Image Tag** - The image tag of the Svix-server image - * **Use Secret Provider** - Optional. Select this option to use the AWS Secret Manager or the Azure Key Vault. Selecting this option enables the following additional fields: + * **Image Prefix** – The registry and namespace (if it exists) where the *svix-server* image is located + * **Image Name** – The image name, for example, *svix-server* + * **Image Tag** – The image tag of the Svix-server image + * **Use Secret Provider** – Optional. Select this option to use the AWS Secret Manager or the Azure Key Vault. Selecting this option enables the following additional fields: * For AWS Secret Manager: - * **Secret Provider** - Set to **AWS**. - * **AWS-Role-ARN** - An AWS role ARN which can access the specified Secret Manager. - * **AWS SecretManager Name** - The AWS Secret Manager name where the sensitive data is stored. + * **Secret Provider** – Set to **AWS**. + * **AWS-Role-ARN** – An AWS role ARN which can access the specified Secret Manager. + * **AWS SecretManager Name** – The AWS Secret Manager name where the sensitive data is stored. * For Azure Key Vault: - * **Secret Provider** - Set to **Azure**. - * **Client ID** - Enter a Client ID assigned to the Azure Managed Identity which enables Private Mendix Platform to access Azure resources. - * **Tenant ID** - Enter the Directory ID of the key vault. - * **Key Vault Name** - Enter the key vault name. - * **Use identity auth for Blob** - Set to **True** if you use the Azure Blob Storage with managed identity auth; the default value is **false**. + * **Secret Provider** – Set to **Azure**. + * **Client ID** – Enter a Client ID assigned to the Azure Managed Identity which enables Private Mendix Platform to access Azure resources. + * **Tenant ID** – Enter the Directory ID of the key vault. + * **Key Vault Name** – Enter the key vault name. + * **Use identity auth for Blob** – Set to **True** if you use the Azure Blob Storage with managed identity auth; the default value is **false**. - * **POSTGRES_DSN** - Available only if you do not use the AWS Secret Manager. A Postgres DSN, for example, `postgresql://postgres:postgres@pgbouncer/postgres`. - * **Use Redis** - Optional. Select this check box if you want to use Redis for message cache and queues. - * **REDIS_DSN** - Available only if you do not use the AWS Secret Manager. The Redis DSN, for example, `redis://redis:6379`. This field is only available if you select the **Use Redis** check box. + * **POSTGRES_DSN** – Available only if you do not use the AWS Secret Manager. A Postgres DSN, for example, `postgresql://postgres:postgres@pgbouncer/postgres`. + * **Use Redis** – Optional. Select this check box if you want to use Redis for message cache and queues. + * **REDIS_DSN** – Available only if you do not use the AWS Secret Manager. The Redis DSN, for example, `redis://redis:6379`. This field is only available if you select the **Use Redis** check box. 5. Click **Install Svix** or **Upgrade Svix**. @@ -407,62 +407,62 @@ To install the Private Cloud components, perform the following steps: 6. Click **Install Private Cloud**. 7. Configure the **General Options**: - * **Image Prefix** - The registry and namespace (if it exists) where the *mx-private-cloud* images are located - * **Nats Address** - The address of your NATS server + * **Image Prefix** – The registry and namespace (if it exists) where the *mx-private-cloud* images are located + * **Nats Address** – The address of your NATS server 8. Configure the **Authenticator** and **Collector** options: - * **Host** - Database Host - * **Port** - Database port - * **DB Name** - Database name - * **DB User** - Database user - * **DB Password** - Database password - * **DB CA File Path** - If your database connection should [use SSL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html), specify the CA file path, otherwise leave blank + * **Host** – Database Host + * **Port** – Database port + * **DB Name** – Database name + * **DB User** – Database user + * **DB Password** – Database password + * **DB CA File Path** – If your database connection should [use SSL](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/UsingWithRDS.SSL.html), specify the CA file path, otherwise leave blank 9. Configure the **Interactor** options. - * **Enable Ingress** - Enable this setting to expose the Interactor Bridge with a generic Ingress template - * **Ingress Class Name** - The Ingress class name - * **Class as Annotation** - This option adds the legacy `kubernetes.io/ingress.class` annotation to set the Ingress class, instead of using the Ingress class name; enable it to add the legacy annotation - * **Enable TLS** - Enable this option if your TLS Certifcate is bound to Ingress - * **TLS secret** - The TLS secret name + * **Enable Ingress** – Enable this setting to expose the Interactor Bridge with a generic Ingress template + * **Ingress Class Name** – The Ingress class name + * **Class as Annotation** – This option adds the legacy `kubernetes.io/ingress.class` annotation to set the Ingress class, instead of using the Ingress class name; enable it to add the legacy annotation + * **Enable TLS** – Enable this option if your TLS Certifcate is bound to Ingress + * **TLS secret** – The TLS secret name {{% alert color="info" %}} To allow other clusters to connect to Private Mendix Platform, you must expose the Interactor Bridge Service. Currently, the installer only supports using the generic Ingress template to expose the service. If you want to expose the Interactor Bridge with other method (for example, Openshift Route), contact the Private Mendix Platform team.{{% /alert %}} 10. Optional: To support AWS IRSA and Azure workload identity for database connection, configure the following options: - * **Use AMI only** - Set to **enabled**. - * **Provider** - Enter **AWS** or **Azure**. - * **Client ID** - When using Azure, enter the Azure Managed Identity Client ID. - * **AWS-Role-ARN** - When using AWS, enter an AWS role ARN which can access the specified Secret Manager. + * **Use AMI only** – Set to **enabled**. + * **Provider** – Enter **AWS** or **Azure**. + * **Client ID** – When using Azure, enter the Azure Managed Identity Client ID. + * **AWS-Role-ARN** – When using AWS, enter an AWS role ARN which can access the specified Secret Manager. 11. Optional: To use the AWS Secret Manager or the Azure Key Vault as secret provider, configure the following options: - * **Use Secret Provider** - Set to **enabled**. - * **Secret Provider** - Enter **AWS** or **Azure**. + * **Use Secret Provider** – Set to **enabled**. + * **Secret Provider** – Enter **AWS** or **Azure**. * For Azure, configure the following settings: - * **Client ID** - Enter a Client ID assigned to the Azure Managed Identity which enables Private Mendix Platform to access Azure resources. - * **Tenant ID** - Enter the Directory ID of the key vault. - * **Key Vault Name** - Enter the key vault name. + * **Client ID** – Enter a Client ID assigned to the Azure Managed Identity which enables Private Mendix Platform to access Azure resources. + * **Tenant ID** – Enter the Directory ID of the key vault. + * **Key Vault Name** – Enter the key vault name. * For AWS, configure the following settings: - * **AWS-Role-ARN** - When using AWS, enter an AWS role ARN which can access the specified Secret Manager. - * **AWS SecretManager Name** - When using AWS, enter the AWS Secret Manager name where the sensitive data is stored. + * **AWS-Role-ARN** – When using AWS, enter an AWS role ARN which can access the specified Secret Manager. + * **AWS SecretManager Name** – When using AWS, enter the AWS Secret Manager name where the sensitive data is stored. 12. If you enabled the **Use Secret Provider** option, create the following secrets in your key vault or secret manager: - * `authenticator-db-name` - The Authenticator database name, for example, `authenticator` - * `authenticator-db-host` - The Authenticator database host, for example, `postgres.example.com` - * `authenticator-db-port` - The Authenticator database port, for example, `5432` - * `authenticator-db-user` - The Authenticator database username, for example, `auth_user` - * `authenticator-db-pass` - The Authenticator database password, for example, `StrongPassword123` - * `collector-db-name` - The Collector database name, for example, `collector` - * `collector-db-host` - The Collector database host, for example, `postgres.example.com - * `collector-db-port` - The Collector database port, for example, `5432` - * `collector-db-user` - The Collector database username, for example, `collector_user` - * `collector-db-pass` - The Collector database password, for example, `StrongPassword456` + * `authenticator-db-name` – The Authenticator database name, for example, `authenticator` + * `authenticator-db-host` – The Authenticator database host, for example, `postgres.example.com` + * `authenticator-db-port` – The Authenticator database port, for example, `5432` + * `authenticator-db-user` – The Authenticator database username, for example, `auth_user` + * `authenticator-db-pass` – The Authenticator database password, for example, `StrongPassword123` + * `collector-db-name` – The Collector database name, for example, `collector` + * `collector-db-host` – The Collector database host, for example, `postgres.example.com + * `collector-db-port` – The Collector database port, for example, `5432` + * `collector-db-user` – The Collector database username, for example, `collector_user` + * `collector-db-pass` – The Collector database password, for example, `StrongPassword456` 13. Click **Review and Apply > Apply Configuration**. @@ -487,10 +487,10 @@ The Build agent is required if you want to be able to build packages without hav 6. In the **Components at any ns** section, select **Build Agent**. 7. Configure the following settings: - * **Namespace** - The namespace where the Build agent will be installed - * **Image Prefix** - The registry and namespace (if it exists) where the *kube-agent* image is located - * **Image Name** - The image name, for example, *mxplatform-kube-agent* - * **Image Tag** - The image tag of the *mxplatform-kube-agent* + * **Namespace** – The namespace where the Build agent will be installed + * **Image Prefix** – The registry and namespace (if it exists) where the *kube-agent* image is located + * **Image Name** – The image name, for example, *mxplatform-kube-agent* + * **Image Tag** – The image tag of the *mxplatform-kube-agent* 8. Click **Install Build Agent**. @@ -513,53 +513,53 @@ Install the Private Mendix Platform by doing the following steps: 3. Click **Configure**, and then specify the following parameters: - * **AppName** - The default app name is `mxplatform`. You can change it as required. - * **DatabasePlan** - Enter the database plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the database. **USE-Secret-Provider** leaves the plan unset. You create the database and store its settings in the secret store. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). - * **Storageplan** - Enter the storage plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the file storage. **USE-Secret-Provider** leaves the plan unset. You create the container and its permissions. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). - * **StoragePlanwithIRSA** - If your storage plan uses AWS IRSA or Azure Workload Identity, set this to **enabled**. + * **AppName** – The default app name is `mxplatform`. You can change it as required. + * **DatabasePlan** – Enter the database plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the database. **USE-Secret-Provider** leaves the plan unset. You create the database and store its settings in the secret store. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). + * **Storageplan** – Enter the storage plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the file storage. **USE-Secret-Provider** leaves the plan unset. You create the container and its permissions. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). + * **StoragePlanwithIRSA** – If your storage plan uses AWS IRSA or Azure Workload Identity, set this to **enabled**. Enabling this option disables **Use Secret Provider**. The operator creates the ServiceAccount from the storage plan, and the secret store needs the installer to create that account. Leave this disabled when **Use Secret Provider** is enabled. You can still use a workload identity. The identity is the one you created, and the installer uses it to annotate the ServiceAccount. - * **AppUrl** - The endpoint where you can connect to your running app. It must be a URL which is supported by your platform. If you leave it blank, Mendix Operator will create it. - * **EnableTLS** - Allows you to enable or disable TLS for the Mendix app's Ingress or OpenShift Router. The default value is use the default settings. - * **TLS option** - Allows you to use an existing `kubernetes.io/tls` secret containing the TLS certificate, or to provide the `tls.crt` and `tls.key` values directly. - * **TLS Secret** - An existing `kubernetes.io/tls` secret containing the TLS certificate. Cannot be used together with certificate and key. If you leave it blank, the default TLS certificate from the Ingress Controller or OpenShift Router will be used. + * **AppUrl** – The endpoint where you can connect to your running app. It must be a URL which is supported by your platform. If you leave it blank, Mendix Operator will create it. + * **EnableTLS** – Allows you to enable or disable TLS for the Mendix app's Ingress or OpenShift Router. The default value is use the default settings. + * **TLS option** – Allows you to use an existing `kubernetes.io/tls` secret containing the TLS certificate, or to provide the `tls.crt` and `tls.key` values directly. + * **TLS Secret** – An existing `kubernetes.io/tls` secret containing the TLS certificate. Cannot be used together with certificate and key. If you leave it blank, the default TLS certificate from the Ingress Controller or OpenShift Router will be used. * **TLS certificate** and **TLS key** – Allows you to provide the `tls.crt` and `tls.key` values directly (not recommended for production environments). Cannot be used together with secretName. - * **SourceUrl** - The location of the deployment package, in the format `oci-image://`. This location must be accessible from your cluster. + * **SourceUrl** – The location of the deployment package, in the format `oci-image://`. This location must be accessible from your cluster. * **Replicas** – When you deploy your app, one replica is deployed automatically. Do not increase the number of replicas yourself, as this may cause data to be duplicated. {{< figure src="/attachments/private-platform/pmp-install7.png" class="no-border" >}} 4. Click **Runtime**, and then specify the following parameters: - * **MxAdminPassword** - The password for the admin user. Leave it empty when **Use Secret Provider** is enabled. The app then reads `mx-admin-password` from the secret store. Otherwise this password is required. It must have at least one number, one upper case letter, one lower case letter and one symbol, with a minimum length of 12 characters. - * **dtapmode** - For production deployments, leave this value set to **P**. For the development of the app, for example acceptance testing, set the value to **D**. - * **ApplicationRootUrl** - Optional. Manually specify the URL of your Private Mendix Platform, for example, for use with SSO or when sending emails. For more information about this functionality, see [ApplicationRootUrl Needs to be Set Manually](/developerportal/deploy/private-cloud-operator/#applicationrooturl-needs-to-be-set-manually). - * **Use Secret Provider** - Optional. Select this option to use the AWS Secret Manager or the Azure Key Vault. Selecting this option enables the following additional fields: + * **MxAdminPassword** – The password for the admin user. Leave it empty when **Use Secret Provider** is enabled. The app then reads `mx-admin-password` from the secret store. Otherwise this password is required. It must have at least one number, one upper case letter, one lower case letter and one symbol, with a minimum length of 12 characters. + * **dtapmode** – For production deployments, leave this value set to **P**. For the development of the app, for example acceptance testing, set the value to **D**. + * **ApplicationRootUrl** – Optional. Manually specify the URL of your Private Mendix Platform, for example, for use with SSO or when sending emails. For more information about this functionality, see [ApplicationRootUrl Needs to be Set Manually](/developerportal/deploy/private-cloud-operator/#applicationrooturl-needs-to-be-set-manually). + * **Use Secret Provider** – Optional. Select this option to use the AWS Secret Manager or the Azure Key Vault. Selecting this option enables the following additional fields: * For AWS Secret Manager: - * **Secret Provider** - Set to **AWS**. - * **AWS-Role-ARN** - An [AWS role ARN](/developerportal/deploy/secret-store-credentials/#aws-secrets-manager) which can access the specified Secret Manager. - * **AWS SecretManager Name** - The AWS Secret Manager name where the sensitive data is stored. + * **Secret Provider** – Set to **AWS**. + * **AWS-Role-ARN** – An [AWS role ARN](/developerportal/deploy/secret-store-credentials/#aws-secrets-manager) which can access the specified Secret Manager. + * **AWS SecretManager Name** – The AWS Secret Manager name where the sensitive data is stored. * For Azure Key Vault: - * **Secret Provider** - Set to **Azure**. - * **Client ID** - Enter a Client ID assigned to the Azure Managed Identity which enables Private Mendix Platform to access Azure resources. - * **Tenant ID** - Enter the Directory ID of the key vault. - * **Key Vault Name** - Enter the key vault name. - * **Use identity auth for Blob** - Set to **True** if you use the Azure Blob Storage with managed identity auth; the default value is **false**. + * **Secret Provider** – Set to **Azure**. + * **Client ID** – Enter a Client ID assigned to the Azure Managed Identity which enables Private Mendix Platform to access Azure resources. + * **Tenant ID** – Enter the Directory ID of the key vault. + * **Key Vault Name** – Enter the key vault name. + * **Use identity auth for Blob** – Set to **True** if you use the Azure Blob Storage with managed identity auth; the default value is **false**. 5. In the **Enabled Functions** section, select or clear the functions that you want to enable or disable: - * **Persist Config** - When enabled, this setting locks the Private Mendix Platform configuration, so that it can no longer be modified from the user interface. - * **Project Management** - Recommended. Enables you to create and manage your app projects. Enables app projects and related settings across the portal. Must be enabled for CI/CD capabilities. - * **Marketplace** - Recommended. Enables you to use the Private Platform's Marketplace capabilities to upload, import and manage Marketplace contents. The Marketplace enabled here is hosted entirely within your Private Mendix Platform. - * **Marketplace Approvals** - Optional. If enabled, contents that users publish to the private Marketplace require administrator approval before publishing. - * **Marketplace Import** - Optional. Enables content import with an external source. - * **IDP** - Optional. Enable users to login using SSO by configuring your IdP integration. - * **Webhook** - Optional. Webhooks allow to send information between platform and external systems, and can be triggered by events around Apps, Users, Groups, Marketplace and CI/CD. + * **Persist Config** – When enabled, this setting locks the Private Mendix Platform configuration, so that it can no longer be modified from the user interface. + * **Project Management** – Recommended. Enables you to create and manage your app projects. Enables app projects and related settings across the portal. Must be enabled for CI/CD capabilities. + * **Marketplace** – Recommended. Enables you to use the Private Platform's Marketplace capabilities to upload, import and manage Marketplace contents. The Marketplace enabled here is hosted entirely within your Private Mendix Platform. + * **Marketplace Approvals** – Optional. If enabled, contents that users publish to the private Marketplace require administrator approval before publishing. + * **Marketplace Import** – Optional. Enables content import with an external source. + * **IDP** – Optional. Enable users to login using SSO by configuring your IdP integration. + * **Webhook** – Optional. Webhooks allow to send information between platform and external systems, and can be triggered by events around Apps, Users, Groups, Marketplace and CI/CD. 6. Click **Review and Apply** > **Evaluate Configuration**. 7. Make any required changes or click **Run Test App**. @@ -587,11 +587,11 @@ To enable [Maia for Private Mendix Platform](/private-mendix-platform/maia/), pe 6. In the **Components at PMP ns** section, select **Maia**. 7. Configure the following settings: - * **Image Prefix** - The registry and namespace (if it exists) where the *maia-appgen-pmp* image is located - * **Image Name** - The image name, for example, *maia-appgen-pmp* - * **Image Tag** - The image tag of the AppGen image - * **Enable Ingress** - Enable or disable Nginx ingress - * **MXASSIST_COPILOT_MXID3_URL** - The OIDC URL of Private Mendix Platform, in the following format: `/oidc/` + * **Image Prefix** – The registry and namespace (if it exists) where the *maia-appgen-pmp* image is located + * **Image Name** – The image name, for example, *maia-appgen-pmp* + * **Image Tag** – The image tag of the AppGen image + * **Enable Ingress** – Enable or disable Nginx ingress + * **MXASSIST_COPILOT_MXID3_URL** – The OIDC URL of Private Mendix Platform, in the following format: `/oidc/` ### Installing the LLM Gateway @@ -605,11 +605,11 @@ Because Private Mendix Platform instances are hosted within the enterprise firew 6. In the **Components at PMP ns** section, select **Maia LLM Gateway**. 7. Configure the following settings: - * **Image Prefix** - The registry and namespace (if it exists) where the *maia-llm-gateway* image is located - * **Image Name** - The image name, for example, *maia-llm-gateway* - * **Image Tag** - The image tag of the LLM Gateway image - * **Enable Ingress** - Enable or disable Nginx ingress - * **MXASSIST_COPILOT_MXID3_URL** - The OIDC URL of Private Mendix Platform, in the following format: `/oidc/` + * **Image Prefix** – The registry and namespace (if it exists) where the *maia-llm-gateway* image is located + * **Image Name** – The image name, for example, *maia-llm-gateway* + * **Image Tag** – The image tag of the LLM Gateway image + * **Enable Ingress** – Enable or disable Nginx ingress + * **MXASSIST_COPILOT_MXID3_URL** – The OIDC URL of Private Mendix Platform, in the following format: `/oidc/` {{< figure src="/attachments/private-platform/pmp-install11.png" class="no-border" >}} @@ -631,10 +631,10 @@ To enable PDF Document Generation for Private Mendix Platform, perform the follo 6. In the **Components at PMP ns** section, select **PDF Gen**. 7. Configure the following settings: - * **Namespace** - The namespace where PDF Document Generation will be installed - * **Image Prefix** - The registry and namespace (if it exists) where the *document-generation-service* image is located - * **Image Name** - The image name, for example, *document-generation-service* - * **Image Tag** - The image tag of the AppGen image, for example, *1.0.2* + * **Namespace** – The namespace where PDF Document Generation will be installed + * **Image Prefix** – The registry and namespace (if it exists) where the *document-generation-service* image is located + * **Image Name** – The image name, for example, *document-generation-service* + * **Image Tag** – The image tag of the AppGen image, for example, *1.0.2* {{% alert color="info" %}} PDF Document Generation requires additional configuration for your Mendix apps to use the private service. For more information, see [Private PDF Document Generation Service: Configuring your Mendix Apps](/appstore/services/private-document-generation-service/#configuring-your-mendix-apps). From 2ea9dded66e7e5175b48c1f30e688dc59b801b08 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Thu, 19 Nov 2026 20:30:07 +0100 Subject: [PATCH 04/18] vale --- content/en/docs/private-platform/quickstart/pmp-quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index 983c3e60089..22c858ba632 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -330,8 +330,8 @@ Svix is required if you want to use webhooks. Install the Svix component by doin * **Use identity auth for Blob** – Set to **True** if you use the Azure Blob Storage with managed identity auth; the default value is **false**. * **POSTGRES_DSN** – Available only if you do not use the AWS Secret Manager. A Postgres DSN, for example, `postgresql://postgres:postgres@pgbouncer/postgres`. - * **Use Redis** – Optional. Select this check box if you want to use Redis for message cache and queues. - * **REDIS_DSN** – Available only if you do not use the AWS Secret Manager. The Redis DSN, for example, `redis://redis:6379`. This field is only available if you select the **Use Redis** check box. + * **Use Redis** – Optional. Select this checkbox if you want to use Redis for message cache and queues. + * **REDIS_DSN** – Available only if you do not use the AWS Secret Manager. The Redis DSN, for example, `redis://redis:6379`. This field is only available if you select the **Use Redis** checkbox. 5. Click **Install Svix** or **Upgrade Svix**. From 1be87d5f96897165b2bf21a7bf27f49e3b337700 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:06:49 +0100 Subject: [PATCH 05/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md Co-authored-by: Anton Popovichenko --- .../en/docs/private-platform/quickstart/pmp-quickstart-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index 9128e67fcbf..e21e8749b79 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -729,7 +729,7 @@ On AWS and with HashiCorp Vault the same rule applies. A plan still provisions t To enable the secret store for `mxplatform`, install the CSI driver and provider as in [Example - Install CSI Driver](#example), create the resources in [Using a Secret Store for the Platform App](#disable-provisioners), and use values like the following. {{% alert color="warning" %}} -+The code samples are intended to show the range of available options. No rights can be derived from them, as they are presented as examples only, and may require significant adaptation to work in your own environment. It is your responsibility to interpret and adjust them to fit real-world scenarios. +The code samples are intended to show the range of available options. No rights can be derived from them, as they are presented as examples only, and may require significant adaptation to work in your own environment. It is your responsibility to interpret and adjust them to fit real-world scenarios. {{% /alert %}} ```text From 0aab314ff32d9417cfbc5517b217bc5101d6ef3d Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:06:57 +0100 Subject: [PATCH 06/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md Co-authored-by: Anton Popovichenko --- .../en/docs/private-platform/quickstart/pmp-quickstart-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index e21e8749b79..b6250779c81 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -733,7 +733,7 @@ The code samples are intended to show the range of available options. No rights {{% /alert %}} ```text -+mxplatform: +mxplatform: enable: true name: mxplatform # The chart creates the ServiceAccount. The operator does not. From a9fd04cde9d11ab2274f39e0283b8314a3f6ea25 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:07:07 +0100 Subject: [PATCH 07/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md Co-authored-by: Anton Popovichenko --- .../docs/private-platform/quickstart/pmp-quickstart-helm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index b6250779c81..fa2fa7dc54e 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -844,9 +844,9 @@ The code samples are intended to show the range of available options. No rights {{% /alert %}} ```text -+apiVersion: secrets-store.csi.x-k8s.io/v1 -+kind: SecretProviderClass -+metadata: +apiVersion: secrets-store.csi.x-k8s.io/v1 +kind: SecretProviderClass +metadata: name: mxplatform namespace: annotations: From 80654695bf9c2b36016b21de80adffb965524355 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:14:29 +0100 Subject: [PATCH 08/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart.md Co-authored-by: Anton Popovichenko --- content/en/docs/private-platform/quickstart/pmp-quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index 22c858ba632..e6f8f58808b 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -213,7 +213,7 @@ You must create the following before you install the app: * When the platform stores MDA files in Azure Blob Storage, the MDA container, **Storage Blob Data Contributor** on that container, and **Storage Blob Delegator** on the storage account. Set **Mda Location** as described in [Configuring MDA Storage Setting](/private-mendix-platform/configure-k8s/#mda-storage). * The secrets listed in [Configuring the AWS Secret Manager](#aws-secret-manager) or [Configuring Azure Key Vault](#azure-key-vault). -+In the installer, leave **StoragePlanwithIRSA** disabled. Enabling it turns **Use Secret Provider** off, because the operator would create the ServiceAccount from the storage plan. +In the installer, leave **StoragePlanwithIRSA** disabled. Enabling it turns **Use Secret Provider** off, because the operator would create the ServiceAccount from the storage plan. For a passwordless database, do not create `database-password`. Key Vault rejects an empty value, and any value you store is used as the password instead of a token. Starting from Private Mendix Platform 2.8.2, the Helmfile value `secretProviderclass.database.passwordless` keeps that key out of the SecretProviderClass. The charts shipped with Private Mendix Platform 2.8.0 and 2.8.1, and the interactive installer, always request the key. On those versions, remove the `database-password` object from the SecretProviderClass after install and after every upgrade that puts it back. See [Enabling the Secret Store](/private-mendix-platform/helmfile-installation/#enable-secret-store). From f9e56dda95879c4d1aeafc2e4748b99c304dc393 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:20:02 +0100 Subject: [PATCH 09/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md Co-authored-by: Anton Popovichenko --- .../en/docs/private-platform/quickstart/pmp-quickstart-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index fa2fa7dc54e..e161a94c07b 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -720,7 +720,7 @@ Leave `pclm.username`, `pclm.password`, and `spec.runtime.mxAdminPassword` out o Keep `useStoragePlanwithIRSA` set to `false`. With `true`, the operator creates the ServiceAccount from the storage plan, and the chart cannot attach the secret store to it. -+The same identity can still open the database and the blob container without a stored password. That is workload identity on the ServiceAccount the chart creates. It is separate from the operator provisioner. See [Enabling the Secret Store](#enable-secret-store). +The same identity can still open the database and the blob container without a stored password. That is workload identity on the ServiceAccount the chart creates. It is separate from the operator provisioner. See [Enabling the Secret Store](#enable-secret-store). On AWS and with HashiCorp Vault the same rule applies. A plan still provisions that resource. When the plan is unset, you create the database, the file storage, and the identity, and the operator does not. The key names for S3 are listed in [SecretProviderClass Keys](/developerportal/deploy/secret-store-credentials/#keys). From c1e40c33be396c8c363e16c17607df9d6178a738 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:20:34 +0100 Subject: [PATCH 10/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md Co-authored-by: Anton Popovichenko --- .../en/docs/private-platform/quickstart/pmp-quickstart-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index e161a94c07b..c7afdd9323b 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -851,7 +851,7 @@ metadata: namespace: annotations: privatecloud.mendix.com/environment-class: "true" -+spec: +spec: provider: azure parameters: clientID: "" From 58b8471c2f9737c20423d6288a17b7f33e9ab63e Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 20 Nov 2026 10:29:05 +0100 Subject: [PATCH 11/18] sme review --- .../en/docs/private-platform/quickstart/pmp-quickstart-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index 9128e67fcbf..40d57244961 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -772,7 +772,7 @@ To enable the secret store for `mxplatform`, install the CSI driver and provider * `useStoragePlanwithIRSA: false` makes the chart create the ServiceAccount and annotate it with `privatecloud.mendix.com/environment-account: "true"`. With `azureWorkloadIdentity.enable` set to `true`, it also annotates the client id and tenant id. The operator requires that ServiceAccount when a SecretProviderClass is used. {{% alert color="info" %}} -`SecretProviderclass.database.passwordless` is available starting from Private Mendix Platform 2.8.2. With `passwordless` set to `true`, that chart leaves `database-password` out of the SecretProviderClass. +The `secretProviderclass.database.passwordless` property is available starting from Private Mendix Platform 2.8.2. With `passwordless` set to `true`, that chart leaves `database-password` out of the SecretProviderClass. The `mxplatform` charts shipped with Private Mendix Platform 2.8.0 and 2.8.1 do not include this value. Those charts always request `database-password`. Helm ignores `passwordless` on those versions, so the key stays in the object. Remove that object from the SecretProviderClass after installation and after every upgrade that rewrites the object, and do not create the secret. From c9f5c06458d65660c3a4ca9237886292f8f0a4d3 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 20 Nov 2026 10:30:03 +0100 Subject: [PATCH 12/18] sme review --- .../en/docs/private-platform/quickstart/pmp-quickstart-helm.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md index f48110004cc..6d54135cf7a 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -776,7 +776,7 @@ The `secretProviderclass.database.passwordless` property is available starting f The `mxplatform` charts shipped with Private Mendix Platform 2.8.0 and 2.8.1 do not include this value. Those charts always request `database-password`. Helm ignores `passwordless` on those versions, so the key stays in the object. Remove that object from the SecretProviderClass after installation and after every upgrade that rewrites the object, and do not create the secret. -`SecretProviderclass.create` is available in the same 2.8.2 release. See [Overriding App Constants](#override-constants). +The `secretProviderclass.create` option is available in the same 2.8.2 release. See [Overriding App Constants](#override-constants). {{% /alert %}} For AWS, set `awsIRSA.enable` and `awsIRSA.roleArn`, set `secretProviderclass.provider` to `aws`, and set `awsparameters.secretName`. For HashiCorp Vault, set `secretProviderclass.provider` to `vault` and fill in `vaultparameters`. From 28134d01c3dccc76ad2eaf6482e1cec04f513e3d Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 20 Nov 2026 10:46:43 +0100 Subject: [PATCH 13/18] sme review --- .../private-platform/quickstart/pmp-quickstart-artifacts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md index c58fba87cdd..63f0022dd06 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md @@ -880,7 +880,7 @@ The `mxplatform` component is used for Mendix application platform deployment. #### Secret Store -`SecretProviderclass.database.passwordless` and `secretProviderclass.create` are available starting from Private Mendix Platform 2.8.2. They are not included in the `mxplatform` charts shipped with 2.8.0 and 2.8.1. For more information, see [Enabling the Secret Store](/private-mendix-platform/helmfile-installation/#enable-secret-store). +The `secretProviderclass.database.passwordless` and `secretProviderclass.create` properties are available starting from Private Mendix Platform 2.8.2. They are not included in the `mxplatform` charts shipped with 2.8.0 and 2.8.1. For more information, see [Enabling the Secret Store](/private-mendix-platform/helmfile-installation/#enable-secret-store). | Field | Required | Description | | --- | --- | --- | From dbf4dfeaa84a373eb33fccf01d4b117e26c43973 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 20 Nov 2026 10:53:33 +0100 Subject: [PATCH 14/18] SME review --- content/en/docs/private-platform/quickstart/pmp-quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index e6f8f58808b..c9a576cbf83 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -518,7 +518,7 @@ Install the Private Mendix Platform by doing the following steps: * **Storageplan** – Enter the storage plan from [Installing and Configuring the Mendix Operator](#install-operator), or select **USE-Secret-Provider**. A plan name makes the operator create the file storage. **USE-Secret-Provider** leaves the plan unset. You create the container and its permissions. See [What the Secret Store Does Not Provision](#secret-store-no-provisioner). * **StoragePlanwithIRSA** – If your storage plan uses AWS IRSA or Azure Workload Identity, set this to **enabled**. - Enabling this option disables **Use Secret Provider**. The operator creates the ServiceAccount from the storage plan, and the secret store needs the installer to create that account. Leave this disabled when **Use Secret Provider** is enabled. You can still use a Workload identity. The identity is the one you created, and the installer uses it to annotate the ServiceAccount. + Enabling this option disables the **secretprovider** option. This is because for IRSA and Azure Workload Identity storage plans, the Service account is created by the Operator instead of Helm. When you use the secret store, leave this option disabled and enter the client ID or role in the secret store fields. The installer annotates the ServiceAccount with that identity. * **AppUrl** – The endpoint where you can connect to your running app. It must be a URL which is supported by your platform. If you leave it blank, Mendix Operator will create it. * **EnableTLS** – Allows you to enable or disable TLS for the Mendix app's Ingress or OpenShift Router. The default value is use the default settings. From 14da58cb79f0abc1b9e5767c2bbaea1705b85608 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 14:19:10 +0100 Subject: [PATCH 15/18] Update _index.md --- content/en/docs/private-platform/quickstart/_index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/content/en/docs/private-platform/quickstart/_index.md b/content/en/docs/private-platform/quickstart/_index.md index f8e4fbde448..da63ba50e7a 100644 --- a/content/en/docs/private-platform/quickstart/_index.md +++ b/content/en/docs/private-platform/quickstart/_index.md @@ -79,6 +79,9 @@ Before starting the installation process, make sure that you have all the necess * A command line terminal that supports the console API and mouse interactions. In Windows, this can be PowerShell or the Windows Command Prompt. * For OpenShift clusters, OpenShift CLI. For more information, see [Getting started with the CLI](https://docs.openshift.com/container-platform/4.1/cli_reference/getting-started-cli.html). * Kubectl installed if you are deploying to another Kubernetes platform. For more information, see [Install and Set Up kubectl](https://kubernetes.io/docs/tasks/tools/). + * On a Mac with Apple silicon, Rosetta must be installed before you run the Mac installer binary. The Mac installer is built for Intel processors. Rosetta may already be installed. If it is missing, open Terminal and run `softwareupdate --install-rosetta --agree-to-license`. If Rosetta is already installed, the command reports that. + + In case of an upgrade, macOS 27.0 and 27.1 do not restore an existing Rosetta installation. From macOS 27.2, the upgrade no longer removes Rosetta, but it does not put Rosetta back if an earlier upgrade already removed it. This applies only to the Mac installer binary, not to a Helmfile-only installation. * Optionally, if you plan to install the Svix component: From 2e21c22fa82c810dc61f0f9cc6f498891bb64db9 Mon Sep 17 00:00:00 2001 From: katarzyna_koltun Date: Fri, 20 Nov 2026 14:32:16 +0100 Subject: [PATCH 16/18] added note about Mac installs --- .../quickstart/pmp-download-portal.md | 2 ++ .../quickstart/pmp-quickstart-airgapped.md | 11 ++++++----- .../private-platform/quickstart/pmp-quickstart.md | 5 +++-- 3 files changed, 11 insertions(+), 7 deletions(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-download-portal.md b/content/en/docs/private-platform/quickstart/pmp-download-portal.md index 2e82fc9552d..7c846ad5936 100644 --- a/content/en/docs/private-platform/quickstart/pmp-download-portal.md +++ b/content/en/docs/private-platform/quickstart/pmp-download-portal.md @@ -110,6 +110,8 @@ To download a release from the table, perform the following steps: 3. Click **Download**. 4. Select your platform (Mac, Windows, or Linux). + On a Mac with Apple Silicon, make sure that Rosetta is installed before you run the installer binary. For more information, see [Quick Start Guide: Prerequisites](/private-mendix-platform/quickstart/). + The installer file downloads to your default download location. {{< figure src="/attachments/private-platform/pmp-downloadportal1.png" class="no-border" >}} diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md index 6ffe62f83e5..b400ac83152 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md @@ -36,7 +36,7 @@ For images downloaded from the Private Mendix Platform Download Portal or with t * For version 2.8.1 and newer, go to **Artifacts Management**, select the version from the **Private Mendix Platform Version** dropdown, and select **Chart** as the **Artifact Type**. Select the charts and click **Export Selection**. * For version 2.8.0 and older, go to **Releases**, click the three-dot menu (**•••**) for the desired release, and then click **View addons**. Find the *Addons/pmp-charts-x.x.x.zip* file, where `x.x.x` is the version number, and click **Download**. -3. Unzip the release binary to a local folder on your Windows or Linux server. The release binary contains the following files: +3. Unzip the release binary to a local folder on your server. The release binary contains the following files: * In the *Tools* folder: @@ -49,7 +49,8 @@ For images downloaded from the Private Mendix Platform Download Portal or with t * **mxpc-cli** - Installation tools which can be used to manage or configure the Mendix Operator * **charts** - Charts, including Private Mendix Platform charts and Svix charts -4. If your clusters can connect to a public registry with a passable network, skip to step 4 below, otherwise initialize the installation by performing the following steps: +4. On a Mac with Apple Silicon, make sure that Rosetta is installed before you run the installer binary. For more information, see [Quick Start Guide: Prerequisites](/private-mendix-platform/quickstart/). +5. If your clusters can connect to a public registry with a passable network, skip to step 6 below, otherwise initialize the installation by performing the following steps: 1. Upload the images to your private repository in an air-gapped environment: @@ -88,21 +89,21 @@ For images downloaded from the Private Mendix Platform Download Portal or with t privatecloud-license-manager_0.3.0 => [REDACTED] privatecloud-license-manager:0.3.0 - ok ``` -5. Migrate the files required to install the Private Cloud components by performing the following steps: +6. Migrate the files required to install the Private Cloud components by performing the following steps: 1. Download the *mx-private-cloud.zip* file from your Private Mendix Platform download portal. 2. Unzip the *mx-private-cloud.zip* file. 3. Copy the *images* from the *mx-private-cloud* directory to the *images* sub-directory of the installer by running the following command: `cp -r mx-private-cloud/images/* /pmp-binary-linux/images` 4. Upload the directory to your private registry by using the `installer init migrate` command. All the images must be in the same registry. -6. Migrate the files required to enable Maia for Private Mendix Platform by performing the following steps: +7. Migrate the files required to enable Maia for Private Mendix Platform by performing the following steps: 1. Download the *maia-appgen-pmp.zip* file from your Private Mendix Platform download portal. 2. Unzip the *maia-appgen-pmp.zip* file. 3. Copy the *maia-appgen-pmp* directory to the *images* sub-directory of the installer by running the following command: `cp -r maia-appgen-pmp/images/* /pmp-binary-linux/images` 4. Upload the Maia directory to your private registry by using the `installer init migrate` command. -7. After the migration is completed, [install Private Mendix Platform in interactive GUI mode](/private-mendix-platform/interactive-installation/). +8. After the migration is completed, [install Private Mendix Platform in interactive GUI mode](/private-mendix-platform/interactive-installation/). ### Images from the Public Mendix Registry diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index c9a576cbf83..5e9ea94d44f 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -17,8 +17,7 @@ In interactive mode, you manually install Private Mendix Platform components. Fo Before you start the installation, download the required files by performing the following steps: 1. Download the release binary from your [Private Mendix Platform download portal](https://privateplatform.mendix.com/). If you do not have access to the download portal, contact your Mendix partner for information. - -2. Unzip the release binary to a local folder on your Windows or Linux server. The release binary contains the following files: +2. Unzip the release binary to a local folder on your server. The release binary contains the following files: * **Tools** – *mx-pclm-cli*, which can be used to manage PCLM * **helm**, and **helmfile** tools, which are used to deploy and manage Private Mendix Platform charts and Svix charts @@ -29,6 +28,8 @@ Before you start the installation, download the required files by performing the {{< figure src="/attachments/private-platform/pmp-binary.png" class="no-border" >}} +3. On a Mac with Apple Silicon, make sure that Rosetta is installed before you run the installer binary. For more information, see [Quick Start Guide: Prerequisites](/private-mendix-platform/quickstart/). + ## Optional: Initializing the Installation for Air-Gapped Environments If your clusters can connect to a public registry with a passable network, skip to the next section, otherwise initialize the installation by performing the following steps: From f264c67bdaaa883a64d8e20d36bb1b3974bb46ef Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:57:48 +0100 Subject: [PATCH 17/18] Update pmp-quickstart.md --- content/en/docs/private-platform/quickstart/pmp-quickstart.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index 5e9ea94d44f..72970027042 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -161,9 +161,9 @@ Currently, only AWS S3 or S3-compatible providers are supported. ## Optional: Configuring Azure Key Vault {#azure-key-vault} -**USE-Secret-Provider** leaves that plan unset, so the operator does not create the resource. Create it yourself, then store its settings in Azure Key Vault under the following keys. All keys are required unless noted otherwise. +**USE-Secret-Provider** for **DatabasePlan** or **Storageplan** leaves that plan unset, so the Operator does not create the resource. Create it yourself, then store its settings in Azure Key Vault under the following keys. All keys are required unless noted otherwise. -You can instead enter a plan. The operator then creates that resource, and the secret store supplies the settings that do not come from a plan. For more information, see [What the Secret Store Does Not Provision](#secret-store-no-provisioner). +You can instead enter a plan name for **DatabasePlan** or **Storageplan**. The Operator then creates that resource, and you do not store that resource's keys in the vault. The secret store supplies the other settings, such as the MxAdmin password and the license-manager credentials. For more information, see [What the Secret Store Does Not Provision](#secret-store-no-provisioner). ### Database Plan Keys From b80c7a7530800b54524216b471b1285420b1b752 Mon Sep 17 00:00:00 2001 From: katarzyna-koltun-mx <108737161+katarzyna-koltun-mx@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:59:09 +0100 Subject: [PATCH 18/18] Update content/en/docs/private-platform/quickstart/pmp-quickstart.md Co-authored-by: Anton Popovichenko --- content/en/docs/private-platform/quickstart/pmp-quickstart.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index 72970027042..253e973b530 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -204,7 +204,7 @@ The chart mounts `pclm-admin-username` and `pclm-admin-password` as the constant ## What the Secret Store Does Not Provision {#secret-store-no-provisioner} -Enabling **Use Secret Provider** turns on the secret store described in [Retrieve Environment-Sensitive Data from a Secret Store](/developerportal/deploy/secret-store-credentials/). For **DatabasePlan** and **Storageplan**, **USE-Secret-Provider** leaves the plan unset and the operator does not create that resource. You create it and store its settings in the vault. A plan name still makes the operator create that resource. The secret store supplies the settings that do not come from a plan, including the MxAdmin password and the license-manager credentials. +Enabling **Use Secret Provider** turns on the secret store described in [Retrieve Environment-Sensitive Data from a Secret Store](/developerportal/deploy/secret-store-credentials/). For **DatabasePlan** and **Storageplan**, **USE-Secret-Provider** leaves the plan unset and the operator does not create that resource. You create it and store its settings in the vault. If you enter a plan name, the operator creates that resource. The secret store supplies the settings that do not come from a plan, including the MxAdmin password and the license-manager credentials. You must create the following before you install the app: