Deploy the control plane

Goal

For platform teams. In this task you start the control plane as a container, with a database and an identity provider, and you check that it runs. You also learn what to do for a second instance and for an upgrade.

Before you start

This is not available yet. Joomiz has no public download for the image of the control plane. Ask the team that gives you the Joomiz platform for the image, and use its name where this page says <control plane image>.

You have a PostgreSQL database and a user for it. The user must be able to create tables in the schema public. This page was checked with PostgreSQL 18.
You have an identity provider that signs people in with OAuth 2.0. Connect an identity provider lists what it must offer. You need two values from it: its issuer address, and the audience that your tokens carry.
The container runtime of your platform can set environment variables from your secret store. Do not write the password of the database in a file of a project.
If you run the control plane as a Java program and not as a container, you need Java 25.

Steps

Know the settings that you must give

The control plane does not start without these settings. Settings reference describes each one:

Setting	Environment variable	What it is
`spring.datasource.url`	`SPRING_DATASOURCE_URL`	The JDBC address of the database.
`spring.datasource.username`	`SPRING_DATASOURCE_USERNAME`	The user of the database.
`spring.datasource.password`	`SPRING_DATASOURCE_PASSWORD`	The password of that user.
`joomiz.auth.issuer-uri`	`JOOMIZ_AUTH_ISSUERURI`	The issuer of your identity provider. Use its `https` address.
`joomiz.auth.audience`	`JOOMIZ_AUTH_AUDIENCE`	The audience that a token must carry.
`joomiz.auth.provider`	`JOOMIZ_AUTH_PROVIDER`	`azure_ad` (the default) or `generic_oidc`. It says which claim of the token holds the roles.

The control plane reads the discovery document of the issuer when it starts. So the issuer must answer from the place where the control plane runs.

Set the variables in your deployment tool, with the values from your secret store. This command takes each value from the environment of the shell, so no value is on the command line:

docker run --detach --name joomiz-control-plane --publish 8080:8080 --publish 8081:8081 \
  --env SPRING_DATASOURCE_URL --env SPRING_DATASOURCE_USERNAME --env SPRING_DATASOURCE_PASSWORD \
  --env JOOMIZ_AUTH_PROVIDER --env JOOMIZ_AUTH_ISSUERURI --env JOOMIZ_AUTH_AUDIENCE \
  <control plane image>

Port 8080 is the API. Port 8081 answers the health paths.

People, the CLI and the dashboard use the API at an https address. Put a reverse proxy or an ingress with TLS in front of port 8080.

Know what a start without a required setting looks like

The control plane checks its settings at the start. If one is missing, it stops and names it. With no database address, the container ends with exit code 1 and this report:

Description:
Failed to configure a DataSource: 'url' attribute is not specified and no embedded datasource could be configured.
Reason: Failed to determine a suitable driver class

With the database but without the issuer and the audience, the report names both. The text goes on after the first sentence of each reason. This output is cut:

Property: joomiz.auth.issuerUri
Reason: joomiz.auth.issuer-uri is required

Property: joomiz.auth.audience
Reason: joomiz.auth.audience is required

Fix the setting, and start again. Settings reference lists the other values that the control plane refuses.

Let the control plane create the tables

The first start fills an empty database. The control plane creates its tables and its catalog of types, one migration after the other. It does this every time it starts, and it does nothing when the database is up to date:

INFO Creating Schema History table "public"."flyway_schema_history" ...
INFO Migrating schema "public" to version "1 - create owners table"
INFO Migrating schema "public" to version "2 - create applications table"
INFO Migrating schema "public" to version "3 - create targets table"
...
INFO Started PlatformApplicationKt in 2.841 seconds (process running for 3.025)

You write no SQL. Do not change the tables by hand.

Run more than one instance

You can run more than one instance of the control plane against one database. Each instance needs the same settings. The instances share the database, and the database holds the apply lock, so two instances never apply to one environment at the same time.

Start the instances together, or one after the other. A second instance waits for the first one to finish the migrations. This is the log of a second instance that started at the same time as the first one:

INFO Schema "public" is up to date. No migration necessary.
INFO Started PlatformApplicationKt in 3.633 seconds (process running for 3.814)

Each instance runs the background work: the questions to provisioners about slow operations, the check for stuck runs, and the deletion of old audit events. You do not need to choose a leader. The setting joomiz.jobs.enabled turns this work off for one instance.

Check the health with probes

Use /health/liveness and /health/readiness on port 8081 as the probes of your platform. Check health and follow a run shows the paths, the answers and a probe for Kubernetes.

Allow the networks of your provisioners

By default, the control plane calls no provisioner in a private network. Set joomiz.provisioners.allowed-networks to the range of your provisioners. Allow the address of your provisioner explains it.

Upgrade

Make a backup of the database.
Start the instances with the new image, one after the other. The first one that starts applies the new migrations.
Check the health paths and the list of runs.

The new migrations run when the first instance starts. You write no SQL for an upgrade.

Check

Set JOOMIZ_SERVER_URL to the address of port 8080, and JOOMIZ_MANAGEMENT_URL to the address of port 8081.

The health path answers UP:

curl -s -w '\nHTTP %{http_code}\n' "$JOOMIZ_MANAGEMENT_URL/health/readiness"

{"status":"UP"}
HTTP 200

The schema answers. It needs no token:

curl -s -o /dev/null -w 'HTTP %{http_code}\n' "$JOOMIZ_SERVER_URL/schema"

HTTP 200

A token of an operator gets an answer from the API. Connect an identity provider shows how people get a token. This is a new control plane, so the list of runs is empty:

joomiz runs

no runs found

Troubleshooting

Symptom	Cause	Fix
The container ends and the report names `joomiz.auth.issuer-uri` or `joomiz.auth.audience`	A required setting is missing.	Set it.
The container ends and the report says `Failed to configure a DataSource`	The database address is missing.	Set `SPRING_DATASOURCE_URL`.
The container ends and the log says that the password of the user failed	The user or the password of the database is wrong.	Check `SPRING_DATASOURCE_USERNAME` and `SPRING_DATASOURCE_PASSWORD`.
The container ends and the log names the database host	The control plane cannot reach the database.	Check the address, the network and the database.
The container ends and the log says `Unable to resolve the Configuration with the provided Issuer`	The issuer does not answer at the address, or it has no discovery document.	Check `JOOMIZ_AUTH_ISSUERURI` and the network of the container.
`/health/readiness` answers `503`	The database or the issuer does not answer.	Check health and follow a run explains the check.
A call with a token gets `403` and `No Joomiz role`	The token has no `operator` role and no `owner:<team>` role.	Give the user a role at the identity provider. The check of the roles is on Connect an identity provider.
A call with a token gets `401`	The token is not for this audience or this issuer, or it has expired, or it has no claim with the user ID.	Compare the audience and the issuer of the token with the two settings. Connect an identity provider names the claim.
A registration of a provisioner gets `400` and `address that is not allowed`	The network of the provisioner is not allowed.	Set `joomiz.provisioners.allowed-networks`.

Deploy the web site of the platform in Deploy the dashboard.