Modelix Kubernetes

Helm chart and supporting OCI images to run Modelix Workspaces in Kubernetes.

Deploying Modelix Workspaces

You can deploy the published Helm chart like this:

helm install --repo https://artifacts.itemis.cloud/repository/helm-modelix/ dev modelix

Caution

If you already have the chart installed and want to upgrade its version use helm helm upgrade and not helm uninstall. In the default setup helm uninstall would remove the database and uploaded files.

Tip

Locally you can run a Kubernetes Cluster (among other options) with Docker Desktop.

When doing so, you change the memory limit to 8 GB or more Resources.

Also, if you use Docker Desktop >= 4.2.0 you have to add the option "deprecatedCgroupv1": true to the file ~/Library/Group Containers/group.com.docker/settings.json. Otherwise, MPS (the JBR) will not use the correct memory limit.

Tip

Helm allows you to deploy multiple instances of modelix to the same cluster. You could have one instance for testing and one production instance. Just specify a different instance name and hostname when running helm:

• helm install --repo https://artifacts.itemis.cloud/repository/helm-modelix/ xyz modelix --set ingress.hostname=xyz.127.0.0.1.nip.io
  • "xyz" is the name of your modelix instance.
  • "xyz.127.0.0.1.nip.io" is the hostname used to access the modelix instance. In a development environment you can use nip.io to get different hostnames that resolve to 127.0.0.1.

Building workspaces in your own CI pipeline

Instead of letting Modelix build an MPS project inside the cluster, the build pipeline you already have can upload its result using the Gradle plugin org.modelix.workspaces. Set the build mode of the workspace to EXTERNAL and instances of it will run the uploaded artifact. See docs/external-ci-builds.md for a guide and workspace-gradle-plugin/README.md for the reference of the plugin.

Developing Modelix Workspaces

This Helm chart is tightly coupled and has to be developed in together with Modelix Workspace components.

REST APIs and the dashboard

• openapi/specifications contains the OpenAPI specifications of the REST APIs. The Ktor server stubs (openapi/api-server-stubs-ktor) used by the workspace-manager, the Ktor client (openapi/api-client-ktor) used by the integration tests and the API clients of the dashboard are generated from them during the build.
• dashboard contains the web UI that the proxy serves under /modelix/dashboard/. To run it with hot reloading, generate the API clients with ./gradlew :dashboard:generateApis and then run pnpm dev in the dashboard directory.

Making changes to the Helm chart and OCI images in this repository

1. Set up the project by running:

   ./gradlew

2. Build your changes by running:

   ./gradlew build

3. Build OCI images with Docker by running:

   ./docker-build-local-and-publish-on-ci-all.sh

4. Update the versions in the local helm chart with:

   ./helm/update-versions.sh

5. Install the Helm chart with the changed images:

   ./helm/install.sh

   [!NOTE]
   If you already have the chart installed, you can run:

   ./helm/upgrade.sh

   This will only update all images while keeping all data.

Making changes to Modelix Workspace components

1. Follow the instructions in Modelix Workspace components to build OCI images with local changes.

2. Update the modelixWorkspacesVersion in versions.properties to the version of the locally built images.
   You can find out the version in the labels of the newly built images or in the workspaces-version.txt in your locally checked out Modelix Workspace components where you build the images in. The versions.properties would the look like:

    # Modelix core version.
    modelixCoreVersion=2.10.5
    # Modelix Workspaces versions
    # 0.0.2-9-gb8651c9 is an example for the versions of Workspace components you want to run the Helm chart with.
    modelixWorkspacesVersion=0.0.2-9-gb8651c9

3. Update the versions in the local helm chart with:

   ./helm/update-versions.sh

4. Install the Helm chart with the changed images:

   ./helm/install.sh

   [!NOTE]
   If you already have the chart installed, you can run:

   ./helm/upgrade.sh

   This will only update all images while keeping all data.

Additional Configuration

Admin password

After Modelix is deployed, make sure to change the password of the admin account.

• Open http://localhost/admin/master/console/#/realms/master/users
• The default password for the user admin is modelix.
• Navigate to Edit > Credentials > Reset Password
• Enter a new password and disable Temporary
• Set keycloak.adminPassword to the new password in your Helm values. The Job that applies the realm configuration after each helm upgrade logs in with it.

Keycloak realm

Keycloak imports keycloak-realm.json only when the realm doesn't exist yet. After each helm install and helm upgrade, a Job runs keycloak-config-cli to apply the Modelix roles and clients of that file to an existing realm, so that changes of newer chart versions reach existing installations. Nothing is deleted. It can be disabled with keycloak.realmSync.enabled: false.

Login with an external identity provider

Users can log in with an external OpenID Connect or SAML identity provider (e.g. ADFS or Entra ID) that is configured in keycloak.identityProviders. See values.yaml for an example. The client secret is read from a Kubernetes Secret.

Database size

The PersistentVolumeClaim of the database is 20Gi for new installations. Existing installations keep their size, unless db.storage is set. Increasing it requires a StorageClass that allows volume expansion.

Node Pools

If you are using a cloud provider that supports auto-scaling create a separate node pool for the MPS instances. Add a taint "workspace-client" with the value "true" and the type "NoExecute". This taint ensures that the pool can be scaled down after Modelix stopped the MPS instances and the nodes don't keep running because some other small pod was scheduled to them.

An MPS instances with a lot of languages and plugins can require ~8 GB of memory. 16 GB of memory for a node is a reasonable size.

Publishing

Releases are managed by release-please. For each commit on main, it updates a release PR that bumps the version in Chart.yaml and adds the changes to the CHANGELOG.md. The version and the changelog are derived from the Conventional Commits messages. Merging the release PR creates the tag and the GitHub release. The same workflow run then publishes the OCI images, the Gradle plugin and the Helm chart.

Because the chart version in git is always the version of the latest release, a checkout of a release tag can also be installed directly (helm install modelix ./helm/modelix), and it uses the images of that release.

Update the versions.properties to update the versions of:

• Modelix Model Server
• Modelix Workspace components