diff --git a/content/en/docs/private-platform/quickstart/_index.md b/content/en/docs/private-platform/quickstart/_index.md index 8c37c6f6de9..b1c8ad27bb7 100644 --- a/content/en/docs/private-platform/quickstart/_index.md +++ b/content/en/docs/private-platform/quickstart/_index.md @@ -32,7 +32,9 @@ Private Mendix Platform can run with FIPS-compliant encryption across the entire You can perform the installation by using one of the following methods: * [With GUI](/private-mendix-platform/interactive-installation/), where you manually install Private Mendix Platform components -* [With Helmfile](/private-mendix-platform/helmfile-installation/), where you use Helmfile to automatically install Private Mendix Platform components. +* [With Helmfile](/private-mendix-platform/helmfile-installation/), where you use Helmfile to automatically install Private Mendix Platform components. Helm charts are available from Private Mendix Platform 2.8.0. Namespaces created with Private Mendix Platform 2.7.0 and older do not currently support Helm charts. + +Both types of installation can be performed in an [air-gapped environment](/private-mendix-platform/air-gapped-installation/). #### Installation Order diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md new file mode 100644 index 00000000000..55f5eb07d11 --- /dev/null +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-airgapped.md @@ -0,0 +1,186 @@ +--- +title: "Install Private Mendix Platform 2.8.0 for Air-Gapped Environments" +linktitle: "Air-Gapped Installation" +url: /private-mendix-platform/air-gapped-installation/ +description: "Documents the installation process for Private Mendix Platform for air-gapped environments." +weight: 32 +--- + +## Introduction + +This document describes how you can migrate artifacts (images and charts), in order to perform an air-gapped installation using one of the following methods: + +* [Install Private Mendix Platform in GUI Mode](/private-mendix-platform/interactive-installation/) +* [Install Private Mendix Platform with Helmfile](/private-mendix-platform/helmfile-installation/) + +## Image Migration for Private Mendix Platform + +The 2.8.0 release of Private Mendix Platform requires some manual steps to migrate images from various sources to the customer's air-gapped container registry: + +* Some platform component images are provided as tarballs in one of the following ways: + + * In zip files downloaded over HTTP from the [Private Mendix Platform Download Portal](/private-mendix-platform/download-portal/) + * Packaged inside the zip file of the Private Mendix Platform installer + +* Some Platform components and Mendix images are provided through the Mendix public image registry + +Either set uses a different tool to migrate. For more information, refer to the following sections. + +### Images in a Zip File + +For images downloaded from the Private Mendix Platform Download Portal or with the installer file, perform the following steps. + +1. Log in to your [Private Mendix Platform Download Portal](/private-mendix-platform/download-portal/). If you do not have access to the Download Portal, contact your Mendix partner for information. +2. Download the release binary from by performing the following steps, depending on your Private Mendix Platform version: + + * 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: + +* In the *Tools* folder: + + * **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 + +* In the *Installer* folder: + + * **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 + +3. 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: + + 1. Upload the images to your private repository in an air-gapped environment: + + ```text + ~/mpp-binary-linux$ ./installer init migrate --help + Migrate Mendix Private Platform related image to your own registry + + Usage: + installer init migrate [flags] + Flags: + -h, --help help for migrate + -r, --registryurl string registry url (required) + -e, --repo string Repository name + -u, --username string Username (required) for your private registry + ``` + + The destination image is named `${registryurl }/${repo}/mendix-private-platform: ${tag}`. The `registryurl` and `repo` are read from the input parameters. The `tag` is automatically read by the installer. + + 2. If the repository does not exist, you must create it before running the init migrate command: + + ```text + ~/mpp-binary-linux$ ./installer init migrate -r [registry] -u user -e [repositoryName] + Please enter user password: ****************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************** + + Confirm password: ****************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************************** + the config checksum is empty + The image destination[REDACTED] svix-server:v0.75.0 + The image destiation [REDACTED] mendix-private-platform:1.4.0.80d447b1 + the config checksum is empty + The image destiation [REDACTED] mxpc-test:1.0 + the config checksum is empty + The image destiation [REDACTED] privatecloud-license-manager:0.3.0 + svix-server_v0.75.0 => [REDACTED] svix-server:v0.75.0 - ok + mendix-private-platform_1.4.0.80d447b1 => [REDACTED] mendix-private-platform:1.4.0.80d447b1 - ok + mxpc-test_1.0 => [REDACTED] mxpc-test:1.0 - ok + privatecloud-license-manager_0.3.0 => [REDACTED] privatecloud-license-manager:0.3.0 - ok + ``` + +4. 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. + +5. 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. + +6. After the migration is completed, [install Private Mendix Platform in interactive GUI mode](/private-mendix-platform/interactive-installation/). + +### Images from the Public Mendix Registry + +For SVIX, the Mendix Operator and its subcomponents (for example, sidecars, storage provisioners, image builder), as well as Mendix runtime base images and app building blocks for supported Mendix versions, you have the option to use an AIP tool to download and migrate to a local registry. You can use the `oras cp` command instead, if your registry allows it. + +#### Accessing Mendix Container Images {#aip} + +To install Private Mendix Platform in an air-gapped environment, you must provision a list of images in your registry. + +1. Download an aip tool for your operating system. + + Mendix has created *aip* tools for different operating systems. Download them from the following links: + + * [Aip for Mac (amd64)](https://cdn.mendix.com/mendix-for-private-cloud/airgapped-image-package/airgapped-image-package-0.1.0-macos-amd64.tar.gz) + * [Aip for Mac (arm64)](https://cdn.mendix.com/mendix-for-private-cloud/airgapped-image-package/airgapped-image-package-0.1.0-macos-arm64.tar.gz) + * [Aip for Windows (amd64)](https://cdn.mendix.com/mendix-for-private-cloud/airgapped-image-package/airgapped-image-package-0.1.0-windows-amd64.zip) + * [Aip for Windows (arm64)](https://cdn.mendix.com/mendix-for-private-cloud/airgapped-image-package/airgapped-image-package-0.1.0-windows-arm64.zip) + * [Aip for Linux (amd64)](https://cdn.mendix.com/mendix-for-private-cloud/airgapped-image-package/airgapped-image-package-0.1.0-linux-amd64.tar.gz) + * [Aip for Linux (arm64)](https://cdn.mendix.com/mendix-for-private-cloud/airgapped-image-package/airgapped-image-package-0.1.0-linux-arm64.tar.gz) + +2. Export the image list. + + 1. In the [https://privateplatform.mendix.com/](https://privateplatform.mendix.com/), go to **Artifact Management** and select a Private Mendix Platform version. + 2. Filter by **Category** and **ArtifactType** to select the images, charts, and Helm file. + 3. Click **Export Selection** to export the list to a file named *export-images-vx.x.x.json*, where `x.x.x` corresponds to a Private Mendix Platform version. + +2. In the Mendix Portal, create a Personal Access Token (PAT) for private images that require a PAT for authentication. + + 1. Sign in to Mendix and go to **User Settings > Developer Settings > Personal Access Token** + 2. Click **New Token**. + 3. Under **OCI registry**, select the **mx:registry:access** as scope. + +3. Fetch the images by using the following aip commands: + + ```text + mkdir pmp-images + cd pmp-images + + # Initialize aip with the exported image list + aip init ~/Downloads/export-images-v2.7.0.json + + # Log in to the Mendix registry + aip login -u pat -p registry.mendix.com + + # Download all images from source registry to local folder. + aip pull + + # Configure the destination registry + aip set-base-destination + + # Log in to the new registry + aip login -u -p + + # Upload all the images to new registry. + aip push + ``` + +4. If your registry requires you to create a repository before pushing, use the following command: + + ```text + # get list of required repositories - these will need to be created before you can push to them + jq -r '.["images", "charts", "custom-artifacts"][] .destination' state.json + ``` + +5. After the migration is completed, [install Private Mendix Platform with Helmfile](/private-mendix-platform/helmfile-installation/). + +### Download Package API {#download-api} + +The following Download Portal APIs enable automating package downloads through manifest files. + +#### Get Private Mendix Platform Release Version List + +```text +GET https://privateplatform.mendix.com/rest/pmpreleaseservice/v1/versions +``` + +#### Get the Manifest of a Specific Private Mendix Platform Version + +```text +GET https://privateplatform.mendix.com/rest/pmpreleaseservice/v1/versions/{version}/manifest +``` \ No newline at end of file diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md b/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md new file mode 100644 index 00000000000..ba82594fe6c --- /dev/null +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-artifacts.md @@ -0,0 +1,1035 @@ +--- +title: "Installation Reference" +url: /private-mendix-platform/installation-reference/ +description: "Documents the required and optional components used in Private Mendix Platform installation." +weight: 18 +--- + +## Introduction + +The following reference document presents a list of required and optional components of Private Mendix Platform. + +## Images + +| Image | Description | Required | +| --- | --- | --- +| `privatecloud-license-manager` | Private Cloud License Manager (PCLM) | Required | +| `mendix-operator` | Mendix Operator | Required | +| `image-builder` | Builds app container images | Required | +| `mendix-private-platform` | Mendix Platform application runtime | Required | +| `mx-m2ee-sidecar` | M2EE sidecar for app pods | Required | +| `mxpc-test` | Private Cloud connectivity/validation tests | Required | +| `pmp-pipeline-tools` | PMP deployment pipeline tooling | Required | +| `app-building-blocks` | App runtime and JRE base layers - pull the versions matching your app deployment requirements | Per deployment | +| `storage-provisioner` | Provisions app databases and file storage - pull the variants matching your database and storage requirements | Per deployment | +| `kubernetes-agent` | Cluster agent - used in Interactor-Agent mode | Optional | +| `interactor` | Interactor service - used in Interactor-Agent mode | Optional | +| `interactor-bridge` | Interactor bridge - used in Interactor-Agent mode | Optional | +| `privatecloud-authenticator` | Authenticator service - used in Interactor-Agent mode | Optional | +| `privatecloud-collector` | Collector service - used in Interactor-Agent mode | Optional | +| `mxplatform-kube-agent` | Build agent for mxplatform | Optional | +| `maia-appgen` | Maia AI AppGen service - required only if Maia features are used | Optional | +| `maia-llm-gateway` | Maia LLM Gateway service - required only if Maia features are used | Optional | +| `document-generation-service` | PDF document generation service | Optional | +| `svix-server` | Webhook delivery service (upstream image `svix/svix-server`) | Optional | + +### Registry Paths + +* `registry.mendix.com/private-cloud/ (license-manager, operator, image-builder, m2ee-sidecar, storage-provisioner, app-building-blocks, kubernetes-agent, interactor, interactor-bridge, authenticator, collector)` +* `registry.mendix.com/private-platform/ (mxpc-test, pmp-pipeline-tools, mxplatform-kube-agent, mendix-private-platform)` +* `registry.mendix.com/maia/ (maia-appgen, maia-llm-gateway)` +* `registry.mendix.com/docgen/ (document-generation-service)`, Docker Hub +* `svix/ (svix-server)` + +## Charts + +| Component | Description | Namespace | Required | ServiceAccount | +| --- | --- | --- | --- | --- | +| `mx-privatecloud-operator-installer` | Mendix Operator installer | Independent | Required | created by chart | +| `mx-privatecloud-operator-crd` | Mendix Operator CRDs | Cluster-scoped | Required | N/A | +| `mx-privatecloud-license-manager` | Private Cloud License Manager (PCLM) | Shared | Required | `mendix-pclm` (created by chart) | +| `installer-config` | Shared installer configuration | Shared | Required | N/A | +| `mxplatform` | Mendix Platform application (MendixApp CR) | Shared | Required | `mxplatform` (created by chart or operator) | +| `mx-privatecloud` | Private Cloud services (authenticator, collector, interactor, bridge) - used in Interactor-Agent mode | Shared | Optional | `mx-privatecloud` (created by chart) | +| `mxplatform-kube-agent` | Build agent for mxplatform | Independent | Optional | `mxplatform-kube-agent` (created by chart) | +| `maia-appgen` | Maia AI AppGen service | Shared | Optional | `maia-appgen` (created by chart) | +| `maia-llm-gateway` | Maia LLM Gateway service for routing LLM requests | Shared | Optional | `maia-llm-gateway` (created by chart) | +| `mx-private-document-generation` | PDF document generation service | Independent | Optional | `mx-private-document-generation` (created by chart) | +| `svix-server` | Webhook delivery service | Shared | Optional | `svix` (created by chart) | + +### Pull Command + +```bash +helm pull oci://registry.mendix.com/private-cloud/charts/ --version +``` + +### Registry Paths + +* `private-cloud/charts/` (operator-installer, operator-crd, license-manager, mx-privatecloud) +* `private-platform/charts/` (mxplatform, mxplatform-kube-agent, installer-config, svix-server) +* `maia/charts/` (maia-appgen, maia-llm-gateway) +* `docgen/charts/` (mx-private-document-generation) + +## Custom Artifacts + +| Artifact | Description | Required | +| --- | --- | --- | +| `installer-helmfile` | Tarball containing the helmfile and `helmfile-config` sample values | Required | + +### Address + +* `registry.mendix.com/private-platform/installer-helmfile:` + +## Component Configurations + +The following configurations are component-specific. + +### Mx-privatecloud-license-manager + +This is the Private Cloud License Manager (PCLM) component. It is required for Private Mendix Platform deployment. It manages licenses for Mendix applications running in Private Cloud. + +#### Basic Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enable` | Boolean | Yes | Enable PCLM deployment | +| `image.registry` | string | No | Container registry URL (uses the global value if not specified) | +| `image.name` | string | Yes | The image name | +| `image.tag` | string | Yes | Image tag (version) | +| `jwt_secret` | string | No | The JWT secret for license token signing (auto-generated if empty) | + +#### Database Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `db.type` | string | Yes | Database type: `postgres` or `sqlserver` | +| `db.strict_tls` | Boolean | No (default: `false`) | Enable strict TLS for database connection | +| `db.ssl_root_cert` | string | Conditional | The SSL root certificate in PEM format; required when `strict_tls` is set to `true` | + +##### PostgreSQL Configuration + +The following settings are used when `db.type` is set to `postgres`. + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `db.postgres.host` | string | Yes | The PostgreSQL host | +| `db.postgres.port` | number | No (default: `5432`) | The PostgreSQL port | +| `db.postgres.name` | string | Yes | The PostgreSQL database name | +| `db.postgres.user` | string | Yes | The PostgreSQL username | +| `db.postgres.password` | string | Conditional | The PostgreSQL password; required only when not using Azure Workload Identity (when `azureWorkloadIdentity.enable` is set to `false`) or AWS IRSA (when `awsIRSA.enable` is set to `false`) for IAM-based database authentication | + +##### SQL Server Configuration + +The following settings are used when `db.type` is set to `sqlserver`. + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `db.sqlserver.host` | string | Yes | The SQL Server host | +| `db.sqlserver.port` | number | No (default: `1433`) | The SQL Server port | +| `db.sqlserver.name` | string | Yes | The SQL Server database name | +| `db.sqlserver.user` | string | Yes | The SQL Server username | +| `db.sqlserver.password` | string | Conditional | The SQL Server password; required only when not using Azure Workload Identity (when `azureWorkloadIdentity.enable` is set to `false`) or AWS IRSA (when `awsIRSA.enable` is set to `false`) for IAM-based database authentication | + +##### Bootstrap User Configuration + +{{% alert color="info" %}} +Bootstrap user credentials must match the configuration in both Mendix Operator and `mxplatform`. + +Operator user credentials (`operator_user` and `operator_password`) must exactly match the `licenseManager.username` and `licenseManager.password` in your Mendix Operator installation values. A mismatch will prevent the Operator from obtaining licenses. + +Admin user credentials (`admin_user` and `admin_password`) must exactly match the `pclm.username` and `pclm.password` in your `mxplatform` configuration. A mismatch will prevent `mxplatform` from obtaining licenses. +{{% /alert %}} + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `bootstrap_users.admin_user` | string | Yes | The Administrator user name | +| `bootstrap_users.admin_password` | string | Yes | The Administrator password | +| `bootstrap_users.create_operator_user` | Boolean | Yes | Set to true to create the Operator user | +| `bootstrap_users.operator_user` | string | Yes | The Operator username; must match the Mendix Operator configuration | +| `bootstrap_users.operator_password` | string | Yes | The Operator password; must match the Mendix Operator configuration | + +##### Ingress Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `ingress.enabled` | Boolean | No (default: `false`) | Enable ingress for external access | +| `ingress.host` | string | Conditional | The hostname for the PCLM web UI | +| `ingress.ingressClassName` | string | Conditional | The Ingress class name (for example, `nginx`) | +| `ingress.annotations` | object | No | Additional ingress annotations | +| `ingress.labels` | object | No | Additional ingress labels | + +##### TLS Configuration for Ingress + +| Field | Type | Required | Default | Description | +| --- | --- | --- | --- | --- | +| `ingress.enableTLS` | Boolean | No | `false` | Set to `true` to enable TLS termination at ingress. | +| `ingress.tlsSecretName` | string | Conditional | "" | Kubernetes Secret name containing TLS certificate. Required if `ingress.enableTLS: true`. | + +##### Workload Identity Configuration + +For passwordless database authentication using cloud-native identity, configure the following settings. + +###### Azure Workload Identity + +| Field | Type | Description | +| --- | --- | --- | +| `azureWorkloadIdentity.enable` | Boolean | Enable Azure Workload Identity | +| `azureWorkloadIdentity.clientID` | string | Azure Managed Identity Client ID | + +###### AWS IRSA (IAM Roles for Service Accounts) + +| Field | Type | Description | +| --- | --- | --- | +| `awsIRSA.enable` | Boolean | Enable AWS IRSA | +| `awsIRSA.roleArn` | string | AWS IAM Role ARN | + +{{% alert color="info" %}} +Component-level workload identity configuration overrides global settings. +{{% /alert %}} + +##### Example Configurations + +{{% 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 %}} + +The following is an example of basic setup with static credentials: + +```text +mx-privatecloud-license-manager: + enable: true + image: + name: "privatecloud-license-manager" + tag: "0.11.0" + # JWT secret (leave empty to auto-generate) + jwt_secret: "" + # Database configuration + db: + type: "postgres" + postgres: + host: "postgres.example.com" + port: 5432 + name: "pclm" + user: "pclm_user" + password: "StrongPassword123" + strict_tls: false + # Bootstrap users - MUST match operator installation + bootstrap_users: + admin_user: "administrator" + admin_password: "AdminPassword123" + create_operator_user: true + operator_user: "operatoruser" # Must match operator licenseManager.username + operator_password: "operatorpass" # Must match operator licenseManager.password + ingress: + enabled: false +``` + +The following is an example of an SSL/TLS database connection: + +```text +mx-privatecloud-license-manager: + enable: true + image: + name: "privatecloud-license-manager" + tag: "0.11.0" + jwt_secret: "" + db: + type: "postgres" + postgres: + host: "auto-infra-azure-postgre-db.postgres.database.azure.com" + port: 5432 + name: "pclm" + user: "postgres" + password: "StrongPassword123" + strict_tls: true # Enable strict TLS validation + ssl_root_cert: | + -----BEGIN CERTIFICATE----- + MIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG9w0BAQsFADBh + ... (Azure PostgreSQL DigiCert Global Root G2 certificate) + -----END CERTIFICATE----- + bootstrap_users: + admin_user: "administrator" + admin_password: "AdminPassword123" + create_operator_user: true + operator_user: "operatoruser" + operator_password: "operatorpass" + ingress: + enabled: false +``` + +The following example uses Azure Workload Identity with passwordless database authentication: + +```text +mx-privatecloud-license-manager: + enable: true + image: + name: "privatecloud-license-manager" + tag: "0.11.0" + # Enable Azure Workload Identity for passwordless database access + azureWorkloadIdentity: + enable: true + clientID: "cf85d643-0de1-477a-9d1b-647882fd44e0" # Managed Identity Client ID + jwt_secret: "" + db: + type: "postgres" + postgres: + host: "auto-infra-azure-postgre-db.postgres.database.azure.com" + port: 5432 + name: "pclm" + user: "pclm-database-identity" # Azure AD database user + password: "" # Empty - authentication via Managed Identity + strict_tls: true + ssl_root_cert: | + -----BEGIN CERTIFICATE----- + ... (Azure PostgreSQL certificate) + -----END CERTIFICATE----- + bootstrap_users: + admin_user: "administrator" + admin_password: "AdminPassword123" + create_operator_user: true + operator_user: "operatoruser" + operator_password: "operatorpass" + ingress: + enabled: false +``` + +#### Service URL + +The PCLM service is accessible within the cluster at the following: + +* Service name - `mx-privatecloud-license-manager` +* Port - 80 (HTTP) +* Full URL - `http://mx-privatecloud-license-manager` (when in same namespace) + +This URL is used by the following: + +* Mendix Operator (for obtaining licenses) +* `mxplatform` (configured through the `pclm.serviceUrl` field) + +### Mx-privatecloud + +The following configurations apply to Mendix Private Cloud core services (Authenticator, Collector, Interactor, Interactor-bridge). + +#### Quick Deployment Scenarios + +Refer to the following list for a quick summary of the supported deployment scenarios and the required configuration. + +* Basic setup + + Set the database credentials for authenticator and collector, and then configure NATS. + +* Database with SSL/TLS + + Set `dbssl` to `true` and provide a `dbca` certificate. + +* External agents + + Enable `interactor_bridge.ingress` with a host name. + +* AWS RDS IAM Authentication (Passwordless) + + Enable `awsIRSA` with `roleArn` and leave the database passwords empty. + +* Azure Managed Identity Database Auth (Passwordless) + + Enable `azureWorkloadIdentity` and leave the database passwords empty. + +* Azure Key Vault + + Enable `azureWorkloadIdentity + secretProviderclass` with `provider` set to `azure`. + +* AWS Secrets Manager + + Enable `awsIRSA + secretProviderclass` with `provider` set to `aws`. + +* HashiCorp Vault + + Enable `secretProviderclass` with `provider` set to `vault`. + +#### Basic Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enable` | Boolean | Yes | Enable `mx-privatecloud` deployment | +| `nats.server_addr` | string | Yes | The NATS server address, for example, `nats://nats.nats.svc:4222` | + +This chart deploys 4 components (Authenticator, Collector, Interactor, and Interactor-Bridge). + +#### NATS Setup + +This chart does not install NATS. You must deploy it separately by running the following commands: + +```text +helm repo add nats https://nats-io.github.io/k8s/helm/charts/ +helm install nats nats/nats --namespace nats --create-namespace +``` + +### Database Configuration + +The following configurations apply to databases. + +#### Authenticator Database and Collector Database + +The Authenticator and Collector database have the same structure. + +| Field | Required | Description | +| --- | --- | --- | +| `authenticator.database.host` | Conditional | Database host name; not required when `secretProviderclass.enable` is set to `true` | +| `authenticator.database.port` | No (default: `5432`) | Database port | +| `authenticator.database.name` | Conditional | Database name; not required when `secretProviderclass.enable` is set to `true` | +| `authenticator.database.user` | Conditional | Database user name; not required when `secretProviderclass.enable` is set to `true` | +| `authenticator.database.password` | Conditional | Database password; not required when using AWS IRSA (`awsIRSA.enable: true`) or Azure Workload Identity (`azureWorkloadIdentity.enable: true`) for IAM-based database authentication | +| `authenticator.database.dbssl` | No | Enables SSL/TLS | +| `authenticator.database.dbca` | Conditional | CA certificate; required if `dbssl` is set to `true` | + +#### RSA Keys and Internal Credentials + +| Field | Default | Recommendation | +| --- | --- | --- | +| `rsa.privateKey` | Has a default value | It is recommended to override this value in production | +| `rsa.publicKey` | Has a default value | It is recommended to override this value in production | +| `credentials.authenticator_admin_pass` | Auto-generated | It is recommended to set this value explicitly | +| `credentials.authenticator_standard_pass` | Auto-generated | It is recommended to set this value explicitly | +| `credentials.collector_api_pass` | Auto-generated | It is recommended to set this value explicitly | +| `credentials.interactor_api_pass` | Auto-generated | It is recommended to set this value explicitly | + +##### Generate RSA Keys + +```text +openssl genrsa -out private.pem 2048 +openssl rsa -in private.pem -pubout -out public.pem +``` + +#### Example Configurations + +{{% 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 %}} + +##### Minimal Setup + +```text +mx-privatecloud: + enable: true + nats: + server_addr: "nats://nats.nats.svc:4222" + authenticator: + database: + host: "postgres-auth.example.com" + name: "authenticator" + user: "auth_user" + password: "StrongPassword123" + collector: + database: + host: "postgres-collector.example.com" + name: "collector" + user: "collector_user" + password: "StrongPassword456" +``` + +##### With AWS IAM Database Authentication (Passwordless) + +```text +mx-privatecloud: + enable: true + nats: + server_addr: "nats://nats.nats.svc:4222" + # Enable AWS IRSA for IAM-based database authentication + awsIRSA: + enable: true + roleArn: "arn:aws:iam::123456789012:role/mx-privatecloud-rds-iam-role" + # Database passwords not required when using IAM authentication + authenticator: + database: + host: "postgres-auth.region.rds.amazonaws.com" + name: "authenticator" + user: "iam_auth_user" + password: "" # Empty - IAM authentication used + collector: + database: + host: "postgres-collector.region.rds.amazonaws.com" + name: "collector" + user: "iam_collector_user" + password: "" # Empty - IAM authe +``` + +##### With Azure Managed Identity Database Authentication (Passwordless) + +```text +mx-privatecloud: + enable: true + nats: + server_addr: "nats://nats.nats.svc:4222" + # Enable Azure Workload Identity for Managed Identity database authentication + azureWorkloadIdentity: + enable: true + clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + # Database passwords not required when using Managed Identity + authenticator: + database: + host: "postgres-auth.postgres.database.azure.com" + name: "authenticator" + user: "managed_identity_user" + password: "" # Empty - Managed Identity authentication used + collector: + database: + host: "postgres-collector.postgres.database.azure.com" + name: "collector" + user: "managed_identity_user" + password: "" # Empty - Managed Identity authentication used +``` + +##### With Database SSL + +```text +mx-privatecloud: + enable: true + nats: + server_addr: "nats://nats.nats.svc:4222" + authenticator: + database: + host: "postgres-auth.example.com" + name: "authenticator" + user: "auth_user" + password: "StrongPassword123" + dbssl: true + dbca: | + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- + collector: + database: + host: "postgres-collector.example.com" + name: "collector" + user: "collector_user" + password: "StrongPassword456" + dbssl: true + dbca: | + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- +``` + +##### With Azure Key Vault + +```text +mx-privatecloud: + enable: true + nats: + server_addr: "nats://nats.default:4222" + # Azure Workload Identity (REQUIRED for Azure Key Vault) + azureWorkloadIdentity: + enable: true + clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + tenantID: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" + secretProviderclass: + enable: true + provider: "azure" + azureparameters: + keyvaultName: "my-mx-keyvault" + # clientID and tenantID inherited from azureWorkloadIdentity + # Database fields ignored when using Secret Provider + authenticator: + database: {host: "", name: "", user: "", password: ""} + collector: + database: {host: "", name: "", user: "", password: ""} +``` + +##### Required Azure Key Vault Secrets + +When using Azure Key Vault (with `provider` set to `azure`), you must create the following secrets in your Key Vault: + +| Secret Name | Description | Example Value | +| --- | --- | --- | +| `authenticator-db-name` | Authenticator database name | `authenticator` | +| `authenticator-db-host` | Authenticator database host | `postgres.example.com` | +| `authenticator-db-port` | Authenticator database port | `5432` | +| `authenticator-db-user` | Authenticator database username | `auth_user` | +| `authenticator-db-pass` | Authenticator database password | `StrongPassword123` | +| `collector-db-name` | Collector database name | `collector` | +| `collector-db-host` | Collector database host | `postgres.example.com` | +| `collector-db-port` | Collector database port | `5432` | +| `collector-db-user` | Collector database username | `collector_user` | +| `collector-db-pass` | Collector database password | `StrongPassword456` | + +##### With Ingress for External Agents + +```text +mx-privatecloud: + enable: true + nats: + server_addr: "nats://nats.default:4222" + # ... database config ... + interactor_bridge: + ingress: + enable: true + className: "nginx" + hostName: "bridge.mendix.example.com" + certSecret: "bridge-tls-cert" +# Agent connection URL: wss://bridge.mendix.example.com/agent +``` + +### Maia-appgen + +This component provides the Maia AI AppGen service for AI-powered application generation. + +#### Basic Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enable` | Boolean | Yes | Enables Maia AppGen deployment | +| `env` | array | Yes | Must include the `MXASSIST_COPILOT_MXID3_URL` | + +#### Environment Variables + +##### Required + +```text +env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" # REQUIRED - OIDC endpoint +``` + +##### ServiceAccount + +| Field | Type | Must Stay | +| --- | --- | --- | +| `serviceAccount.create` | `true` | Yes - required for RBAC | +| `serviceAccount.name` | `maia-appgen` | Used for IRSA/Workload Identity | +| `serviceAccount.automount` | `true` | Yes - needs K8s API access | + +#### Example Configurations + +{{% 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 %}} + +##### Basic + +```text +maia-appgen: + enable: true + env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" +``` + +##### With Azure Workload Identity + +```text +maia-appgen: + enable: true + env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" + azureWorkloadIdentity: + enable: true + clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" +``` + +##### With Ingress + +```text +maia-appgen: + enable: true + env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" + ingress: + enable: true + className: "nginx" + hostName: "maia.example.com" + certSecret: "maia-tls-secret" +``` + +### Maia-llm-gateway + +The Maia LLM Gateway service is used for routing LLM requests to various AI model providers. + +#### Basic Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enable` | Boolean | Yes | Enables Maia LLM Gateway deployment | +| `env` | array | Yes | Must include `MXASSIST_COPILOT_MXID3_URL`; optional for `MXASSIST_COPILOT_MXID3_SSL_CA_CERT` | + +#### Environment Variables + +The chart uses a two-tier environment variable system: + +* `defaultEnv` - Chart-managed defaults set in `values.yaml`. Do not modify them. +* `env` - User-defined variables (your overrides and required settings). + +##### Required + +```text +env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" # REQUIRED - OIDC endpoint +``` + +##### Optional + +```text +env: + - name: MXASSIST_COPILOT_MXID3_SSL_CA_CERT + value: | + -----BEGIN CERTIFICATE----- + ... + -----END CERTIFICATE----- # Optional - Custom CA certificate for MxID3 +``` + +#### ServiceAccount + +| Field | Type | Must Stay | +| --- | --- | --- | +| `serviceAccount.create` | `true` | Yes - required for RBAC | +| `serviceAccount.name` | `maia-llm-gateway` | Used for IRSA/Workload Identity | +| `serviceAccount.automount` | `true` | Yes - needs K8s API access | + +#### Example Configurations + +{{% 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 %}} + +##### Basic + +```text +maia-llm-gateway: + enable: true + env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" +``` + +##### With Custom CA Certificate + +```text +maia-llm-gateway: + enable: true + env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" + - name: MXASSIST_COPILOT_MXID3_SSL_CA_CERT + value: | + -----BEGIN CERTIFICATE----- + MIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG... + -----END CERTIFICATE----- +``` + +##### With Ingress + +```text +maia-llm-gateway: + enable: true + env: + - name: MXASSIST_COPILOT_MXID3_URL + value: "https://pmp.example.com/oidc/" + ingress: + enable: true + className: "nginx" + hostName: "llm-gateway.example.com" + certSecret: "llm-gateway-tls-secret" +``` + +#### Integration with Mxplatform + +When `maia-llm-gateway` is enabled, `mxplatform` automatically configures the following microflow constants. You do not need to configure anything yourself - the integration happens automatically when you enable the component. + +| Constant | Value | Description | +| --- | --- | --- | +| `Maia.Enable` | `true | Set when `maia-llm-gateway` or `maia-appgen` is enabled | +| `Maia.Config_Secret_Name_LLM_GW` | Secret name | Auto-discovered through label lookup | +| `Maia.Config_Secret_Namespace_LLM_GW` | Namespace | Same as thw `mxplatform` namespace | +| `Maia.LLM_GW_URL` | `https://` | Set when Ingress is enabled with host name | + +### Svix-server + +The Svix webhooks server is used for event delivery and webhook management. + +#### Quick Deployment Scenarios + +Refer to the following list for a quick summary of the supported deployment scenarios and the required configuration. + +* Basic production + + Set `postgres`, and optionally also `redis` and `useRedis` to `true`. + +* Azure Key Vault + + Enable `azureWorkloadIdentity` and `secretProviderclass` with `provider` set to `azure`. + +* AWS Secrets Manager + + Enable `awsIRSA` and `secretProviderclass` with `provider` set to `aws`. + +* HashiCorp Vault + + Enable `secretProviderclass` with `provider` set to `vault`. + +#### Basic Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `enable` | Boolean | Yes | Enables svix-server deployment | +| `postgres` | string | Conditional | The PostgreSQL DSN. Required when `secretProviderclass.enable` is set to `false` | +| `secretKey` | string | Recommended | The JWT secret key; auto-generated if empty | + +#### Database and Cache + +```text +svix-server: + enable: true + postgres: "postgresql://user:pass@host:5432/svix" + redis: "redis://host:6379/0" # Optional + useRedis: false # Set true to enable Redis + secretKey: "" # Leave empty for auto-generation +``` + +#### Secret Key Management + +The JWT secret is managed through `svix-configmap` in the following way: + +* If the user provides a `secretKey`, the provided value is used. +* If the `secretKey` is empty and the ConfigMap exists, the existing key is preserved (`upgrade-safe`). +* If the `secretKey` is empty and the ConfigMap does not exist, a 64-character key is auto-generated. + +The JWT secret is automatically injected into the `SvixClient.JwtSecret` constant of the `mxplatform`. + +#### Example Configurations + +{{% 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 %}} + +##### Basic + +```text +svix-server: + enable: true + postgres: "postgresql://svix:pass@host:5432/svix" + secretKey: "" # Auto-generated +``` + +##### With Redis + +```text +svix-server: + enable: true + postgres: "postgresql://svix:pass@host:5432/svix" + redis: "redis://redis-master:6379/0" + useRedis: true +``` + +##### With Azure Key Vault + +```text +svix-server: + enable: true + # Azure Workload Identity (REQUIRED for Azure Key Vault) + azureWorkloadIdentity: + enable: true + clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" + tenantID: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" + secretProviderclass: + enable: true + provider: "azure" + azureparameters: + keyvaultName: "my-svix-keyvault" + # clientID and tenantID inherited from azureWorkloadIdentity + # postgres ignored when using Secret Provider +``` + +When using Azure Key Vault (with `provider` set to `azure`), you must create the following secrets in your Key Vault: + +| Secret Name | Description | Example Value | +| --- | --- | --- | +| `svix-db-dsn` | The PostgreSQL connection string | `postgresql://user:pass@host:5432/svix` | +| `svix-redis-dsn` | The Redis connection string (optional, used when `useRedis` is set to `true`) | `redis://host:6379/0` | + +### Mxplatform + +The `mxplatform` component is used for Mendix application platform deployment. + +#### Basic Configuration + +| Field | Type | Required | Description | +| --- | --- | --- | --- | +| `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 | + +#### PCLM Integration (Required) + +| Field | Required | Description | +| --- | --- | --- | +| `pclm.serviceUrl` | Yes | PCLM service endpoint | +| `pclm.username` | Conditional | The PCLM username; not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | +| `pclm.password` | Conditional | The PCLM password; not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | + +#### Spec Configuration + +| Field | Required | Description | +| --- | --- | --- | +| `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) | + +#### Automatic Integration Detection + +`Mxplatform` automatically integrates with enabled components. You only need to enable or disable components. Do not configure integration flags manually. + +| Auto-detected Flag | When Used | Purpose | +| --- | --- | --- | +| `privatecloudEnabled` | Set when `mx-privatecloud.enable` is set to `true` | Connects to Private Cloud services | +| `maiaEnabled` | Set when `maia-appgen.enable` is set to `true` | Enables the Maia AI assistant | +| `svixEnabled` | Set when `svix-server.enable` is set to `true` | Enables webhook delivery | +| `kubeAgentEnabled` | Set when `mxplatform-kube-agent.enable` is set to `true` | Enables build agent | + +#### Example Configurations + +{{% 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 %}} + +##### Basic + +```text +mxplatform: + enable: true + pclm: + serviceUrl: "http://mx-privatecloud-license-manager" + username: "administrator" + password: "PCLMPassword" + spec: + appURL: "app.example.com" + sourceURL: "oci-image://registry/app:1.0" + database: + servicePlan: "production-db" + storage: + servicePlan: "production-storage" + resources: + limits: + cpu: 2000m + memory: 4096Mi + requests: + cpu: 1000m + memory: 2048Mi + runtime: + applicationRootUrl: "https://app.example.com" + mxAdminPassword: "AdminPassword" + dtapMode: "P" +``` + +##### With Secret Provider + +```text +mxplatform: + enable: true + # PCLM credentials from Secret Provider + pclm: + serviceUrl: "http://mx-privatecloud-license-manager" + username: "" # Empty - injected from Secret Provider + password: "" # Empty - injected from Secret Provider + secretProviderclass: + enable: true + provider: "azure" + azureparameters: + clientID: "..." + tenantID: "..." + keyvaultName: "my-keyvault" + 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: + +| 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` | + +### Mxplatform-kube-agent + +Mxplatform-kube-agent is the Build agent for `mxplatform` app deployments. + +#### Basic Configuration + +| Field | Type | Required | +| --- | --- | --- | +| `enable` | Boolean | Yes | +| `namespace` | string | Yes | +| `config.buildUser` | string | No (default: `pmpbuilder`) | +| `config.buildPassword` | string | No (auto-generated) | + +##### Example + +{{% 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-kube-agent: + enable: true + namespace: "build-agents" +``` + +### Mx-private-document-generation + +Mx-private-document-generation is the PDF document generation service. + +The wervice URL for Mendix apps is `http://document-generation.:8085`. + +#### Basic Configuration + +| Field | Type | Required | +| --- | --- | --- | +| `enable` | Boolean | Yes | +| `namespace` | string | Yes | + +##### Example + +{{% 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 +mx-private-document-generation: + enable: true + namespace: "document-generation" + image: + registry: "registry.mendix.com" + name: "mendix/document-generation-service" + tag: "1.0.0" +``` 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 7b7137bd6c5..de024c18b88 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart-helm.md @@ -8,66 +8,11 @@ weight: 30 ## Introduction -To automate the declarative installation of Private Mendix Platform, you can now use Helm and Helmfile in order to automate the declarative installation of Private Mendix Platform. In this way, you can automatically install Private Mendix Platform components. If you would like to perform a manual installation instead, see [Install Private Mendix Platform in GUI Mode](/private-mendix-platform/interactive-installation/). +You can now use Helm and Helmfile in order to automate the declarative installation of Private Mendix Platform. In this way, you can automatically install Private Mendix Platform components. For other installation types, see the following topic: -### Supported Tasks +* [Install Private Mendix Platform in GUI Mode](/private-mendix-platform/interactive-installation/) -Helmfile installation supports the following tasks: - -* Installation and upgrade of components such as Svix, PCLM, and others -* Installation and upgrade of Private Mendix Platform - -### Out-of-Scope Tasks - -The following tasks are not performed by the Helmfile installation: - -* Mendix Operator installation -* Mendix Operator upgrade - -To install or upgrade the Operator, see [Installing Components through the Helm Chart UI](/developerportal/deploy/helm-charts/). - -## Components - -Helmfile manages multiple Helm releases with dependency ordering, ensuring components are installed in the correct sequence. - -The following components must be installed in a shared namespace (that is, the same namespace as Private Mendix Platform): - -* `mx-privatecloud` -* `maia-appgen` -* `svix-server` -* `mxplatform` - -The following components can use different (independent) namespaces: - -* `mxplatform-kube-agent` -* `mx-private-document-generation` - -| Component | Description | Namespace | Required | ServiceAccount | -| --- | --- | --- | --- | --- | -| `mx-privatecloud-license-manager` | Private Cloud License Manager (PCLM) | Shared | Required | `mendix-pclm` (created by chart) | -| `mx-privatecloud` | Private Cloud services (authenticator, collector, interactor, bridge) | Shared | Optional | `mx-privatecloud` (created by chart) | -| `maia-appgen` | Maia AI AppGen service | Shared | Optional | `maia-appgen` (created by chart) | -| `maia-llm-gateway` | Maia LLM Gateway service for routing LLM requests | Shared | Optional | `maia-llm-gateway` (created by chart) | -| `svix-server` | Webhook delivery service | Shared | Optional | `svix` (created by chart) | -| `mxplatform` | Mendix Platform application (MendixApp CR) | Shared | Optional | `mxplatform` (created by chart or operator) | -| `mxplatform-kube-agent` | Build agent for mxplatform | Independent | Optional | `mxplatform-kube-agent` (created by chart) | -| `mx-private-document-generation` | PDF document generation service | Independent | Optional | `mx-private-document-generation (created by chart)` | - -ServiceAccount creation depends on the value of the **UseStoragePlanwithIRSA** field. If set to **false**, Chart creates the ServiceAccount with workload identity annotations. If set to **true**, Mendix Operator creates ServiceAccount based on StoragePlan configuration. - -### Dependency and Install Order - -The following components are installed in parallel during the first phase of the installation: - -* `mx-privatecloud-license-manager` -* `mx-privatecloud` -* `maia-appgen` -* `svix-server` -* `maia-llm-gateway` -* `mxplatform-kube-agent` -* `mx-private-document-generation` - -The `mxplatform` component is installed during the second phase, with configurations depending on which components were enabled during the first phase. +Helm charts are available for Private Mendix Platform 2.8.0 and newer. Namespaces created with Private Mendix Platform 2.7.0 and older do not currently support Helm charts. ## Required Tools @@ -85,6 +30,16 @@ Before running Helmfile, ensure you have the following tools installed: `Helm-diff` is required for `helmfile apply` and `helmfile diff` commands. If you only use `helmfile sync` (which forces synchronization without using `diff`), it is optional. {{% /alert %}} +## Installation Overview + +The installation process consists of the following high-level steps. For more information, refer to the sections below. + +1. Retrieve the manifest of image and charts version through the Download Portal GUI or API. +2. Pull the images and charts marked **Required**, as well as any optional components your deployment needs. For a list of required and optional components, see [Installation Reference](/private-mendix-platform/installation-reference/). +3. Install the Operator charts. +4. Install Priave Mendix Platform charts using Helm. +5. Configure the PCLM host name, user name and password in the ` Developer Settings > Personal Access Token** + 2. Click **New Token**. + 3. Under **OCI registry**, select the **mx:registry:access** as scope. + +4. Pull the charts. -#### Example: Azure Database and Storage with Workload Identity + 1. Log in to the OCI registry for Helm by using the following command: `helm registry login -u pat -p ${YOUR_PAT} registry.mendix.com`. + 2. Use the `helm pull` command to download the Helmfile from the OCI registry, for example: -```yaml -# Credential Service Accounts (for Workload Identity) -credentialServiceAccounts: - enabled: true - serviceAccounts: - - authType: "azure-wi" - k8sServiceAccountName: "db-admin-sa" - azwiClientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - - authType: "azure-wi" - k8sServiceAccountName: "storage-admin-sa" - azwiClientID: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" - -# Database Storage Plans -database: - postgres: - enabled: true - plans: - - planName: "azure-db" - planType: "on-demand" - useAzureWIAuth: true - k8sServiceAccountName: "db-admin-sa" - host: "myserver.postgres.database.azure.com" - port: 5432 - database: "postgres" - user: "mendix-storage-admin" - password: "" # Empty when using Workload Identity - strictTLS: true - -# Object Store Storage Plans -storage: - azure_blob: - enabled: true - plans: - - planName: "azure-sp" - k8sServiceAccountName: "storage-admin-sa" - useAzureWIAuth: true - azureStorageAccount: "mystorageaccount" - azureResourceGroup: "my-resource-group" - azureAccountSubscriptionID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - azureContainerName: "" # Auto-created per environment - preventDataDeletion: false - -# Operator Configuration -operator_config: - runtimeAutomountServiceAccountToken: true # Required for Maia integration -``` + ```text + helm pull oci://registry.mendix.com/private-cloud/charts/mx-privatecloud-operator-installer --version 0.2.36 + helm install operator mx-privatecloud-operator-installer-0.2.36.tgz -f ./Downloads/20260916T113717Z-pmp-test-oci-generated-values.yaml --namespace pmp-oci-test + ``` + + where `/Downloads/20260916T113717Z-pmp-test-oci-generated-values.yaml` is the yaml file for Operator configuration. You can find this yaml file among the example files in the installer package. + +#### Download Package API {#download-api} -### Complete Operator Installation Example +The following Download Portal APIs enable automating package downloads. -For an example of the complete Operator installation values,see *samples/operator-sp.yaml*. +##### Get Private Mendix Platform Release Version List -To install the Operator, use the following commands: +```text +GET https://privateplatform.mendix.com/rest/pmpreleaseservice/v1/versions +``` + +##### Get the Manifest of a Specific Private Mendix Platform Version ```text -helm install --create-namespace \ - -n \ - -f samples/operator-sp.yaml \ - operator \ - mx-privatecloud-operator-installer +GET https://privateplatform.mendix.com/rest/pmpreleaseservice/v1/versions/{version}/manifest ``` -For detailed Operator installation instructions, see [Installing and Configuring Mendix on Kubernetes with Helm Charts](/developerportal/deploy/helm-charts/#installing-and-configuring-the-mendix-on-kubernetes-with-helm-charts). +## Helmfile Components + +Helmfile manages multiple Helm releases with dependency ordering, ensuring components are installed in the correct sequence. + +| Component | Description | Namespace | Required | ServiceAccount | +| --- | --- | --- | --- | --- | +| `mx-privatecloud-license-manager` | Private Cloud License Manager (PCLM) | Private Mendix Platform namespace | Required | `mendix-pclm` (created by Operator) | +| `mx-privatecloud` | Private Cloud services (authenticator, collector, interactor, bridge) | Private Mendix Platform namespace | Optional | `mx-privatecloud` (created by chart) | +| `maia-appgen` | Maia AI AppGen service | Private Mendix Platform namespace | Optional | `maia-appgen` (created by chart) | +| `maia-llm-gateway` | Maia LLM Gateway service for routing LLM requests | Private Mendix Platform namespace | Optional | `maia-llm-gateway` (created by chart) | +| `svix-server` | Webhook delivery service | Private Mendix Platform namespace | Optional | `svix` (created by chart) | +| `mxplatform` | Mendix Platform application (MendixApp CR) | Private Mendix Platform namespace | Optional | `mxplatform` (created by chart or Operator) | +| `mxplatform-kube-agent` | Build agent for mxplatform | Independent | Optional | `mxplatform-kube-agent` (created by chart) | +| `mx-private-document-generation` | PDF document generation service | Independent | Optional | `mx-private-document-generation` (created by chart) | + +ServiceAccount creation depends on the value of the **UseStoragePlanwithIRSA** field. If set to **false**, Chart creates the ServiceAccount with workload identity annotations. If set to **true**, Mendix Operator creates ServiceAccount based on StoragePlan configuration. + +### Dependency and Install Order + +The following components are installed in parallel during the first phase of the Helmfile installation: + +* `mx-privatecloud` +* `maia-appgen` +* `svix-server` +* `maia-llm-gateway` +* `mxplatform-kube-agent` +* `mx-private-document-generation` + +The `mxplatform` component is installed during the second phase, with configurations depending on which components were enabled during the first phase. ## Quick Start @@ -282,7 +216,6 @@ The code samples are intended to show the range of available options. No rights # 1. Create your values file cp examples/my-values.yaml my-values.yaml # Edit my-values.yaml with your configuration - # 2. Deploy all enabled components helmfile --file helmfile.d/helmfile.yaml \ --state-values-file my-values.yaml \ @@ -291,9 +224,11 @@ helmfile --file helmfile.d/helmfile.yaml \ ### Minimal Values File Template +Replace the component versions in the following template with the correct versions for your Private Mendix Platform release. For more information, refer to [Private Mendix Platform Release Notes](/releasenotes/private-platform/). + ```yaml # ───────────────────────────────────────────────────────────────────────────── -# REQUIRED: Shared namespace +# REQUIRED: Private Mendix Platform namespace namespace # ───────────────────────────────────────────────────────────────────────────── namespace: mendix-platform @@ -315,9 +250,9 @@ global: mx-privatecloud-license-manager: enable: true image: - registry: "private-cloud.registry.mendix.com" + registry: "registry.mendix.com" name: "privatecloud-license-manager" - tag: "0.11.0" + tag: "{insert component version as indicated in release notes}" # Database configuration db: @@ -454,13 +389,13 @@ helmfile --file helmfile.d/helmfile.yaml \ ### Disabling Mxplatform -Setting `mxplatform.enable: false` and running `helmfile sync` uninstalls the `mxplatform` release and deletes the MendixApp Custom Resource. - {{% alert color="warning" %}} -The Mendix Operator will react based on the reclaim policies in your StoragePlan and DBPlan. If configured with destructive policies, this will result in irreversible data loss. +This operation is dangerous and may cause serious issues if performed needlessly. The Mendix Operator will react based on the reclaim policies in your StoragePlan and DBPlan. If configured with destructive policies, this will result in irreversible data loss. {{% /alert %}} -Before disabling `mxplatform`, perform the following actions:: +Setting `mxplatform.enable: false` and running `helmfile sync` uninstalls the `mxplatform` release and deletes the MendixApp Custom Resource. + +Before disabling `mxplatform`, perform the following actions: 1. Review the reclaim policies of StoragePlan and DBPlan. 2. Ensure that you have backups. @@ -503,970 +438,42 @@ global: - name: acr-secret ``` -## Component Configurations - -The following configurations are component-specific. - -### Mx-privatecloud-license-manager - -This is the Private Cloud License Manager (PCLM) component. It is required for Private Mendix Platform deployment. It manages licenses for Mendix applications running in Private Cloud. - -#### Basic Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `enable` | boolean | Yes | Enable PCLM deployment | -| `image.registry` | string | No | Container registry URL (uses the global value if not specified) | -| `image.name` | string | Yes | The image name | -| `image.tag` | string | Yes | Image tag (version) | -| `jwt_secret` | string | No | The JWT secret for license token signing (auto-generated if empty) | - -#### Database Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `db.type` | string | Yes | Database type: `postgres` or `sqlserver` | -| `db.strict_tls` | Boolean | No (default: `false`) | Enable strict TLS for database connection | -| `db.ssl_root_cert` | string | Conditional | The SSL root certificate in PEM format; required when `strict_tls` is set to `true` | - -##### PostgreSQL Configuration - -The following settings are used when `db.type` is set to `postgres`. - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `db.postgres.host` | string | Yes | The PostgreSQL host | -| `db.postgres.port` | number | No (default: `5432`) | The PostgreSQL port | -| `db.postgres.name` | string | Yes | The PostgreSQL database name | -| `db.postgres.user` | string | Yes | The PostgreSQL username | -| `db.postgres.password` | string | Conditional | The PostgreSQL password; required only when not using Azure Workload Identity (when `azureWorkloadIdentity.enable` is set to `false`) or AWS IRSA (when `awsIRSA.enable` is set to `false`) for IAM-based database authentication | - -##### SQL Server Configuration - -The following settings are used when `db.type` is set to `sqlserver`. - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `db.sqlserver.host` | string | Yes | The SQL Server host | -| `db.sqlserver.port` | number | No (default: `1433`) | The SQL Server port | -| `db.sqlserver.name` | string | Yes | The SQL Server database name | -| `db.sqlserver.user` | string | Yes | The SQL Server username | -| `db.sqlserver.password` | string | Conditional | The SQL Server password; required only when not using Azure Workload Identity (when `azureWorkloadIdentity.enable` is set to `false`) or AWS IRSA (when `awsIRSA.enable` is set to `false`) for IAM-based database authentication | - -##### Bootstrap User Configuration - -{{% alert color="info" %}} -Bootstrap user credentials must match the configuration in both Mendix Operator and `mxplatform`. - -Operator user credentials (`operator_user` and `operator_password`) must exactly match the `licenseManager.username` and `licenseManager.password` in your Mendix Operator installation values. A mismatch will prevent the Operator from obtaining licenses. - -Admin user credentials (`admin_user` and `admin_password`) must exactly match the `pclm.username` and `pclm.password` in your `mxplatform` configuration. A mismatch will prevent `mxplatform` from obtaining licenses. -{{% /alert %}} - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `bootstrap_users.admin_user` | string | Yes | The Administrator user name | -| `bootstrap_users.admin_password` | string | Yes | The Administrator password | -| `bootstrap_users.create_operator_user` | Boolean | Yes | Set to true to create the Operator user | -| `bootstrap_users.operator_user` | string | Yes | The Operator username; must match the Mendix Operator configuration | -| `bootstrap_users.operator_password` | string | Yes | The Operator password; must match the Mendix Operator configuration | - -##### Ingress Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `ingress.enabled` | Boolean | No (default: `false`) | Enable ingress for external access | -| `ingress.host` | string | Conditional | The hostname for the PCLM web UI | -| `ingress.ingressClassName` | string | Conditional | The Ingress class name (for example, `nginx`) | -| `ingress.annotations` | object | No | Additional ingress annotations | -| `ingress.labels` | object | No | Additional ingress labels | - -##### Workload Identity Configuration - -For passwordless database authentication using cloud-native identity, configure the following settings. - -###### Azure Workload Identity - -| Field | Type | Description | -| --- | --- | --- | -| `azureWorkloadIdentity.enable` | Boolean | Enable Azure Workload Identity | -| `azureWorkloadIdentity.clientID` | string | Azure Managed Identity Client ID | - -###### AWS IRSA (IAM Roles for Service Accounts) - -| Field | Type | Description | -| --- | --- | --- | -| `awsIRSA.enable` | Boolean | Enable AWS IRSA | -| `awsIRSA.roleArn` | string | AWS IAM Role ARN | - -{{% alert color="info" %}} -Component-level workload identity configuration overrides global settings. -{{% /alert %}} - -##### Example Configurations - -{{% 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 %}} - -The following is an example of basic setup with static credentials: - -```text -mx-privatecloud-license-manager: - enable: true - image: - name: "privatecloud-license-manager" - tag: "0.11.0" - # JWT secret (leave empty to auto-generate) - jwt_secret: "" - # Database configuration - db: - type: "postgres" - postgres: - host: "postgres.example.com" - port: 5432 - name: "pclm" - user: "pclm_user" - password: "StrongPassword123" - strict_tls: false - # Bootstrap users - MUST match operator installation - bootstrap_users: - admin_user: "administrator" - admin_password: "AdminPassword123" - create_operator_user: true - operator_user: "operatoruser" # Must match operator licenseManager.username - operator_password: "operatorpass" # Must match operator licenseManager.password - ingress: - enabled: false -``` - -The following is an example of an SSL/TLS database connection: +### ChartRepo OCI Registry -```text -mx-privatecloud-license-manager: - enable: true - image: - name: "privatecloud-license-manager" - tag: "0.11.0" - jwt_secret: "" - db: - type: "postgres" - postgres: - host: "auto-infra-azure-postgre-db.postgres.database.azure.com" - port: 5432 - name: "pclm" - user: "postgres" - password: "StrongPassword123" - strict_tls: true # Enable strict TLS validation - ssl_root_cert: | - -----BEGIN CERTIFICATE----- - MIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG9w0BAQsFADBh - ... (Azure PostgreSQL DigiCert Global Root G2 certificate) - -----END CERTIFICATE----- - bootstrap_users: - admin_user: "administrator" - admin_password: "AdminPassword123" - create_operator_user: true - operator_user: "operatoruser" - operator_password: "operatorpass" - ingress: - enabled: false -``` +This is the custom Helm chart repository URL for all components. It allows you to host all charts in your own OCI registry instead of pulling from the default Mendix registry. -The following example uses Azure Workload Identity with passwordless database authentication: +* **Type** - `string` +* Default value - `""` (uses default Mendix registries) -```text -mx-privatecloud-license-manager: - enable: true - image: - name: "privatecloud-license-manager" - tag: "0.11.0" - # Enable Azure Workload Identity for passwordless database access - azureWorkloadIdentity: - enable: true - clientID: "cf85d643-0de1-477a-9d1b-647882fd44e0" # Managed Identity Client ID - jwt_secret: "" - db: - type: "postgres" - postgres: - host: "auto-infra-azure-postgre-db.postgres.database.azure.com" - port: 5432 - name: "pclm" - user: "pclm-database-identity" # Azure AD database user - password: "" # Empty - authentication via Managed Identity - strict_tls: true - ssl_root_cert: | - -----BEGIN CERTIFICATE----- - ... (Azure PostgreSQL certificate) - -----END CERTIFICATE----- - bootstrap_users: - admin_user: "administrator" - admin_password: "AdminPassword123" - create_operator_user: true - operator_user: "operatoruser" - operator_password: "operatorpass" - ingress: - enabled: false -``` +When `chartRepo` is not specified, each component pulls from its default Mendix registry location with the following full paths: -#### Integration with Mendix Operator +* `installer-config` - `oci://registry.mendix.com/private-platform/charts/installer-config` +* `mxplatform` - `oci://registry.mendix.com/private-platform/charts/mxplatform` +* `mxplatform-kube-agent` - `oci://registry.mendix.com/private-platform/charts/mxplatform-kube-agent` +* `svix-server` - `oci://registry.mendix.com/private-platform/charts/svix-server` +* `mx-privatecloud` - `oci://registry.mendix.com/private-cloud/charts/mx-privatecloud` +* `mx-privatecloud-license-manager` - `oci://registry.mendix.com/private-cloud/charts/mx-privatecloud-license-manager` +* `maia-appgen` - `oci://registry.mendix.com/maia/charts/maia-appgen` +* `maia-llm-gateway` - `oci://registry.mendix.com/maia/charts/maia-llm-gateway` +* `mx-private-document-generation` - `oci://registry.mendix.com/docgen/charts/mx-private-document-generation` -The Mendix Operator must be configured to use PCLM for license management. +#### Custom Repository Structure -{{% 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 %}} +When a custom Helm chart repository is configured using `chartRepo`, all charts are pulled using a flat structure. The chart name is appended to your repository URL, as in the following example: ```text -# In Mendix Operator installation values -licenseManager: - enable: true - credentialsSecretName: "mendix-pclm-credentials" - serverURL: "http://mx-privatecloud-license-manager" # Service name in same namespace - username: "operatoruser" # Must match bootstrap_users.operator_user - password: "operatorpass" # Must match bootstrap_users.operator_password +# Example: Use Azure Container Registry +chartRepo: "oci://crpmp001.azurecr.io/helm/pmp" +# Charts will be pulled from: +# - oci://crpmp001.azurecr.io/helm/pmp/mxplatform +# - oci://crpmp001.azurecr.io/helm/pmp/mx-privatecloud +# - oci://crpmp001.azurecr.io/helm/pmp/maia-appgen +# etc. ``` -#### Service URL - -The PCLM service is accessible within the cluster at the following: - -* Service name - `mx-privatecloud-license-manager` -* Port - 80 (HTTP) -* Full URL - `http://mx-privatecloud-license-manager` (when in same namespace) - -This URL is used by the following: - -* Mendix Operator (for obtaining licenses) -* `mxplatform` (configured through the `pclm.serviceUrl` field) - -### Mx-privatecloud - -The following configurations apply to Mendix Private Cloud core services (Authenticator, Collector, Interactor, Interactor-bridge). - -#### Quick Deployment Scenarios - -Refer to the following list for a quick summary of the supported deployment scenarios and the required configuration. - -* Basic setup - - Set the database credentials for authenticator and collector, and then configure NATS. - -* Database with SSL/TLS - - Set `dbssl` to `true` and provide a `dbca` certificate. - -* External agents - - Enable `interactor_bridge.ingress` with a host name. - -* AWS RDS IAM Authentication (Passwordless) - - Enable `awsIRSA` with `roleArn` and leave the database passwords empty. - -* Azure Managed Identity Database Auth (Passwordless) - - Enable `azureWorkloadIdentity` and leave the database passwords empty. - -* Azure Key Vault - - Enable `azureWorkloadIdentity + secretProviderclass` with `provider` set to `azure`. +## Component Configurations -* AWS Secrets Manager - - Enable `awsIRSA + secretProviderclass` with `provider` set to `aws`. - -* HashiCorp Vault - - Enable `secretProviderclass` with `provider` set to `vault`. - -#### Basic Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `enable` | Boolean | Yes | Enable `mx-privatecloud` deployment | -| `nats.server_addr` | string | Yes | The NATS server address, for example, `nats://nats.nats.svc:4222` | - -This chart deploys 4 components (Authenticator, Collector, Interactor, and Interactor-Bridge). - -#### NATS Setup - -This chart does not install NATS. You must deploy it separately by running the following commands: - -```text -helm repo add nats https://nats-io.github.io/k8s/helm/charts/ -helm install nats nats/nats --namespace nats --create-namespace -``` - -### Database Configuration - -The following configurations apply to databases. - -#### Authenticator Database and Collector Database - -The Authenticator and Collector database have the same structure. - -| Field | Required | Description | -| --- | --- | --- | -| `authenticator.database.host` | Conditional | Database host name; not required when `secretProviderclass.enable` is set to `true` | -| `authenticator.database.port` | No (default: `5432`) | Database port | -| `authenticator.database.name` | Conditional | Database name; not required when `secretProviderclass.enable` is set to `true` | -| `authenticator.database.user` | Conditional | Database user name; not required when `secretProviderclass.enable` is set to `true` | -| `authenticator.database.password` | Conditional | Database password; not required when using AWS IRSA (`awsIRSA.enable: true`) or Azure Workload Identity (`azureWorkloadIdentity.enable: true`) for IAM-based database authentication | -| `authenticator.database.dbssl` | No | Enables SSL/TLS | -| `authenticator.database.dbca` | Conditional | CA certificate; required if `dbssl` is set to `true` | - -#### RSA Keys and Internal Credentials - -| Field | Default | Recommendation | -| --- | --- | --- | -| `rsa.privateKey` | Has a default value | It is recommended to override this value in production | -| `rsa.publicKey` | Has a default value | It is recommended to override this value in production | -| `credentials.authenticator_admin_pass` | Auto-generated | It is recommended to set this value explicitly | -| `credentials.authenticator_standard_pass` | Auto-generated | It is recommended to set this value explicitly | -| `credentials.collector_api_pass` | Auto-generated | It is recommended to set this value explicitly | -| `credentials.interactor_api_pass` | Auto-generated | It is recommended to set this value explicitly | - -##### Generate RSA Keys - -```text -openssl genrsa -out private.pem 2048 -openssl rsa -in private.pem -pubout -out public.pem -``` - -#### Example Configurations - -{{% 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 %}} - -##### Minimal Setup - -```text -mx-privatecloud: - enable: true - nats: - server_addr: "nats://nats.nats.svc:4222" - authenticator: - database: - host: "postgres-auth.example.com" - name: "authenticator" - user: "auth_user" - password: "StrongPassword123" - collector: - database: - host: "postgres-collector.example.com" - name: "collector" - user: "collector_user" - password: "StrongPassword456" -``` - -##### With AWS IAM Database Authentication (Passwordless) - -```text -mx-privatecloud: - enable: true - nats: - server_addr: "nats://nats.nats.svc:4222" - # Enable AWS IRSA for IAM-based database authentication - awsIRSA: - enable: true - roleArn: "arn:aws:iam::123456789012:role/mx-privatecloud-rds-iam-role" - # Database passwords not required when using IAM authentication - authenticator: - database: - host: "postgres-auth.region.rds.amazonaws.com" - name: "authenticator" - user: "iam_auth_user" - password: "" # Empty - IAM authentication used - collector: - database: - host: "postgres-collector.region.rds.amazonaws.com" - name: "collector" - user: "iam_collector_user" - password: "" # Empty - IAM authe -``` - -##### With Azure Managed Identity Database Authentication (Passwordless) - -```text -mx-privatecloud: - enable: true - nats: - server_addr: "nats://nats.nats.svc:4222" - # Enable Azure Workload Identity for Managed Identity database authentication - azureWorkloadIdentity: - enable: true - clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - # Database passwords not required when using Managed Identity - authenticator: - database: - host: "postgres-auth.postgres.database.azure.com" - name: "authenticator" - user: "managed_identity_user" - password: "" # Empty - Managed Identity authentication used - collector: - database: - host: "postgres-collector.postgres.database.azure.com" - name: "collector" - user: "managed_identity_user" - password: "" # Empty - Managed Identity authentication used -``` - -##### With Database SSL - -```text -mx-privatecloud: - enable: true - nats: - server_addr: "nats://nats.nats.svc:4222" - authenticator: - database: - host: "postgres-auth.example.com" - name: "authenticator" - user: "auth_user" - password: "StrongPassword123" - dbssl: true - dbca: | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- - collector: - database: - host: "postgres-collector.example.com" - name: "collector" - user: "collector_user" - password: "StrongPassword456" - dbssl: true - dbca: | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- -``` - -##### With Azure Key Vault - -```text -mx-privatecloud: - enable: true - nats: - server_addr: "nats://nats.default:4222" - # Azure Workload Identity (REQUIRED for Azure Key Vault) - azureWorkloadIdentity: - enable: true - clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - tenantID: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" - secretProviderclass: - enable: true - provider: "azure" - azureparameters: - keyvaultName: "my-mx-keyvault" - # clientID and tenantID inherited from azureWorkloadIdentity - # Database fields ignored when using Secret Provider - authenticator: - database: {host: "", name: "", user: "", password: ""} - collector: - database: {host: "", name: "", user: "", password: ""} -``` - -##### Required Azure Key Vault Secrets - -When using Azure Key Vault (with `provider` set to `azure`), you must create the following secrets in your Key Vault: - -| Secret Name | Description | Example Value | -| --- | --- | --- | -| `authenticator-db-name` | Authenticator database name | `authenticator` | -| `authenticator-db-host` | Authenticator database host | `postgres.example.com` | -| `authenticator-db-port` | Authenticator database port | `5432` | -| `authenticator-db-user` | Authenticator database username | `auth_user` | -| `authenticator-db-pass` | Authenticator database password | `StrongPassword123` | -| `collector-db-name` | Collector database name | `collector` | -| `collector-db-host` | Collector database host | `postgres.example.com` | -| `collector-db-port` | Collector database port | `5432` | -| `collector-db-user` | Collector database username | `collector_user` | -| `collector-db-pass` | Collector database password | `StrongPassword456` | - -##### With Ingress for External Agents - -```text -mx-privatecloud: - enable: true - nats: - server_addr: "nats://nats.default:4222" - # ... database config ... - interactor_bridge: - ingress: - enable: true - className: "nginx" - hostName: "bridge.mendix.example.com" - certSecret: "bridge-tls-cert" -# Agent connection URL: wss://bridge.mendix.example.com/agent -``` - -### Maia-appgen - -This component provides the Maia AI AppGen service for AI-powered application generation. - -#### Basic Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `enable` | Boolean | Yes | Enables Maia AppGen deployment | -| `env` | array | Yes | Must include the `MXASSIST_COPILOT_MXID3_URL` | - -#### Environment Variables - -##### Required - -```text -env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" # REQUIRED - OIDC endpoint -``` - -##### ServiceAccount - -| Field | Type | Must Stay | -| --- | --- | --- | -| `serviceAccount.create` | `true` | Yes - required for RBAC | -| `serviceAccount.name` | `maia-appgen` | Used for IRSA/Workload Identity | -| `serviceAccount.automount` | `true` | Yes - needs K8s API access | - -#### Example Configurations - -{{% 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 %}} - -##### Basic - -```text -maia-appgen: - enable: true - env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" -``` - -##### With Azure Workload Identity - -```text -maia-appgen: - enable: true - env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" - azureWorkloadIdentity: - enable: true - clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" -``` - -##### With Ingress - -```text -maia-appgen: - enable: true - env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" - ingress: - enable: true - className: "nginx" - hostName: "maia.example.com" - certSecret: "maia-tls-secret" -``` - -### Maia-llm-gateway - -The Maia LLM Gateway service is used for routing LLM requests to various AI model providers. - -#### Basic Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `enable` | Boolean | Yes | Enables Maia LLM Gateway deployment | -| `env` | array | Yes | Must include `MXASSIST_COPILOT_MXID3_URL`; optional for `MXASSIST_COPILOT_MXID3_SSL_CA_CERT` | - -#### Environment Variables - -The chart uses a two-tier environment variable system: - -* `defaultEnv` - Chart-managed defaults set in `values.yaml`. Do not modify them. -* `env` - User-defined variables (your overrides and required settings). - -##### Required - -```text -env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" # REQUIRED - OIDC endpoint -``` - -##### Optional - -```text -env: - - name: MXASSIST_COPILOT_MXID3_SSL_CA_CERT - value: | - -----BEGIN CERTIFICATE----- - ... - -----END CERTIFICATE----- # Optional - Custom CA certificate for MxID3 -``` - -#### ServiceAccount - -| Field | Type | Must Stay | -| --- | --- | --- | -| `serviceAccount.create` | `true` | Yes - required for RBAC | -| `serviceAccount.name` | `maia-llm-gateway` | Used for IRSA/Workload Identity | -| `serviceAccount.automount` | `true` | Yes - needs K8s API access | - -#### Example Configurations - -{{% 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 %}} - -##### Basic - -```text -maia-llm-gateway: - enable: true - env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" -``` - -##### With Custom CA Certificate - -```text -maia-llm-gateway: - enable: true - env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" - - name: MXASSIST_COPILOT_MXID3_SSL_CA_CERT - value: | - -----BEGIN CERTIFICATE----- - MIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG... - -----END CERTIFICATE----- -``` - -##### With Ingress - -```text -maia-llm-gateway: - enable: true - env: - - name: MXASSIST_COPILOT_MXID3_URL - value: "https://pmp.example.com/oidc/" - ingress: - enable: true - className: "nginx" - hostName: "llm-gateway.example.com" - certSecret: "llm-gateway-tls-secret" -``` - -#### Integration with Mxplatform - -When `maia-llm-gateway` is enabled, `mxplatform` automatically configures the following microflow constants. You do not need to configure anything yourself - the integration happens automatically when you enable the component. - -| Constant | Value | Description | -| --- | --- | --- | -| `Maia.Enable` | `true | Set when `maia-llm-gateway` or `maia-appgen` is enabled | -| `Maia.Config_Secret_Name_LLM_GW` | Secret name | Auto-discovered through label lookup | -| `Maia.Config_Secret_Namespace_LLM_GW` | Namespace | Same as thw `mxplatform` namespace | -| `Maia.LLM_GW_URL` | `https://` | Set when Ingress is enabled with host name | - -### Svix-server - -The Svix webhooks server is used for event delivery and webhook management. - -#### Quick Deployment Scenarios - -Refer to the following list for a quick summary of the supported deployment scenarios and the required configuration. - -* Basic production - - Set `postgres`, and optionally also `redis` and `useRedis` to `true`. - -* Azure Key Vault - - Enable `azureWorkloadIdentity` and `secretProviderclass` with `provider` set to `azure`. - -* AWS Secrets Manager - - Enable `awsIRSA` and `secretProviderclass` with `provider` set to `aws`. - -* HashiCorp Vault - - Enable `secretProviderclass` with `provider` set to `vault`. - -#### Basic Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `enable` | Boolean | Yes | Enables svix-server deployment | -| `postgres` | string | Conditional | The PostgreSQL DSN. Required when `secretProviderclass.enable` is set to `false` | -| `secretKey` | string | Recommended | The JWT secret key; auto-generated if empty | - -#### Database and Cache - -```text -svix-server: - enable: true - postgres: "postgresql://user:pass@host:5432/svix" - redis: "redis://host:6379/0" # Optional - useRedis: false # Set true to enable Redis - secretKey: "" # Leave empty for auto-generation -``` - -#### Secret Key Management - -The JWT secret is managed through `svix-configmap` in the following way: - -* If the user provides a `secretKey`, the provided value is used. -* If the `secretKey` is empty and the ConfigMap exists, the existing key is preserved (`upgrade-safe`). -* If the `secretKey` is empty and the ConfigMap does not exist, a 64-character key is auto-generated. - -The JWT secret is automatically injected into the `SvixClient.JwtSecret` constant of the `mxplatform`. - -#### Example Configurations - -{{% 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 %}} - -##### Basic - -```text -svix-server: - enable: true - postgres: "postgresql://svix:pass@host:5432/svix" - secretKey: "" # Auto-generated -``` - -##### With Redis - -```text -svix-server: - enable: true - postgres: "postgresql://svix:pass@host:5432/svix" - redis: "redis://redis-master:6379/0" - useRedis: true -``` - -##### With Azure Key Vault - -```text -svix-server: - enable: true - # Azure Workload Identity (REQUIRED for Azure Key Vault) - azureWorkloadIdentity: - enable: true - clientID: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" - tenantID: "yyyyyyyy-yyyy-yyyy-yyyy-yyyyyyyyyyyy" - secretProviderclass: - enable: true - provider: "azure" - azureparameters: - keyvaultName: "my-svix-keyvault" - # clientID and tenantID inherited from azureWorkloadIdentity - # postgres ignored when using Secret Provider -``` - -When using Azure Key Vault (with `provider` set to `azure`), you must create the following secrets in your Key Vault: - -| Secret Name | Description | Example Value | -| --- | --- | --- | -| `svix-db-dsn` | The PostgreSQL connection string | `postgresql://user:pass@host:5432/svix` | -| `svix-redis-dsn` | The Redis connection string (optional, used when `useRedis` is set to `true`) | `redis://host:6379/0` | - -### Mxplatform - -The `mxplatform` component is used for Mendix application platform deployment. - -#### Basic Configuration - -| Field | Type | Required | Description | -| --- | --- | --- | --- | -| `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 | - -#### PCLM Integration (Required) - -| Field | Required | Description | -| --- | --- | --- | -| `pclm.serviceUrl` | Yes | PCLM service endpoint | -| `pclm.username` | Conditional | The PCLM username; not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | -| `pclm.password` | Conditional | The PCLM password; not required when `secretProviderclass.enable` is set to `true` (for credentials injected from a secret manager) | - -#### Spec Configuration - -| Field | Required | Description | -| --- | --- | --- | -| `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) | - -#### Automatic Integration Detection - -`Mxplatform` automatically integrates with enabled components. You only need to enable or disable components. Do not configure integration flags manually. - -| Auto-detected Flag | When Used | Purpose | -| --- | --- | --- | -| `privatecloudEnabled` | Set when `mx-privatecloud.enable` is set to `true` | Connects to Private Cloud services | -| `maiaEnabled` | Set when `maia-appgen.enable` is set to `true` | Enables the Maia AI assistant | -| `svixEnabled` | Set when `svix-server.enable` is set to `true` | Enables webhook delivery | -| `kubeAgentEnabled` | Set when `mxplatform-kube-agent.enable` is set to `true` | Enables build agent | - -#### Example Configurations - -{{% 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 %}} - -##### Basic - -```text -mxplatform: - enable: true - pclm: - serviceUrl: "http://mx-privatecloud-license-manager" - username: "administrator" - password: "PCLMPassword" - spec: - appURL: "app.example.com" - sourceURL: "oci-image://registry/app:1.0" - database: - servicePlan: "production-db" - storage: - servicePlan: "production-storage" - resources: - limits: - cpu: 2000m - memory: 4096Mi - requests: - cpu: 1000m - memory: 2048Mi - runtime: - applicationRootUrl: "https://app.example.com" - mxAdminPassword: "AdminPassword" - dtapMode: "P" -``` - -##### With Secret Provider - -```text -mxplatform: - enable: true - # PCLM credentials from Secret Provider - pclm: - serviceUrl: "http://mx-privatecloud-license-manager" - username: "" # Empty - injected from Secret Provider - password: "" # Empty - injected from Secret Provider - secretProviderclass: - enable: true - provider: "azure" - azureparameters: - clientID: "..." - tenantID: "..." - keyvaultName: "my-keyvault" - 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: - -| 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` | - -### Mxplatform-kube-agent - -Mxplatform-kube-agent is the Build agent for `mxplatform` app deployments. - -#### Basic Configuration - -| Field | Type | Required | -| --- | --- | --- | -| `enable` | Boolean | Yes | -| `namespace` | string | Yes | -| `config.buildUser` | string | No (default: `pmpbuilder`) | -| `config.buildPassword` | string | No (auto-generated) | - -##### Example - -{{% 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-kube-agent: - enable: true - namespace: "build-agents" -``` - -### Mx-private-document-generation - -Mx-private-document-generation is the PDF document generation service. - -The wervice URL for Mendix apps is `http://document-generation.:8085`. - -#### Basic Configuration - -| Field | Type | Required | -| --- | --- | --- | -| `enable` | Boolean | Yes | -| `namespace` | string | Yes | - -##### Example - -{{% 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 -mx-private-document-generation: - enable: true - namespace: "document-generation" - image: - registry: "private-cloud.registry.mendix.com" - name: "mendix/document-generation-service" - tag: "1.0.0" -``` +For a list of component-specific configurations, see [Installation Reference](/private-mendix-platform/installation-reference/). ## Container Registry Configuration diff --git a/content/en/docs/private-platform/quickstart/pmp-quickstart.md b/content/en/docs/private-platform/quickstart/pmp-quickstart.md index d929efb56e8..4c2e4e54058 100644 --- a/content/en/docs/private-platform/quickstart/pmp-quickstart.md +++ b/content/en/docs/private-platform/quickstart/pmp-quickstart.md @@ -8,7 +8,9 @@ weight: 20 ## Introduction -In interactive mode, you manually install Private Mendix Platform components. If you would like to perform an automatic installation instead, see [Install Private Mendix Platform with Helmfile](/private-mendix-platform/helmfile-installation/). +In interactive mode, you manually install Private Mendix Platform components. For other installation types, see the following topic: + +* [Install Private Mendix Platform with Helmfile](/private-mendix-platform/helmfile-installation/) ## Preparing the Installation Files