Database and Cache
Monad keeps its configuration in Postgres and caches in a Redis-compatible store. By default the chart runs both in your cluster: Postgres through the CloudNativePG operator, and Dragonfly as the cache. Read this page to size the chart's Postgres, or to use a Postgres or cache you already run. Decide before the first install: the chart's Postgres volumes keep the StorageClass they are created with, and moving Monad to another database later is a migration you do yourself.
Merge snippets into your values file
Each values snippet gives full paths from the top-level key. The chart's example files already have some of these keys, such as global in every example and postgresql in private-cluster.yaml and local-auth-external-postgres.yaml. Add a snippet's settings under the key you already have: a second copy of a top-level key silently replaces the first. See Install.
Chart-managed Postgres
With postgresql.cnpg.enabled: true, the default, the chart creates a CloudNativePG Cluster, which needs the CloudNativePG operator (Operators and controllers). Postgres runs the image your operator defaults to. CloudNativePG creates an app database owned by an app user, and writes their connection to the Secret monad-db-app, which Monad's components read through global.monad.dbSecret. With local authentication, the chart also creates a kratos database and role in it.
| Key | Default | What it sets |
|---|---|---|
postgresql.cnpg.instances | 3 | Postgres instances: one primary, the rest standbys |
postgresql.cnpg.minSyncReplicas | 1 | Fewest standbys that must confirm each commit |
postgresql.cnpg.maxSyncReplicas | 1 | Most standbys that confirm each commit synchronously. Must be lower than instances. |
postgresql.cnpg.storage.size | 5Gi | Each instance's data volume. It can grow later where the StorageClass allows expansion, and cannot shrink. |
postgresql.cnpg.storage.storageClass | Cluster default | StorageClass for the data volumes. Existing volumes keep the class they were created with. |
postgresql.cnpg.resources | Requests 10m CPU, 512Mi memory | Requests and limits for each instance |
postgresql.cnpg.name | monad-db | Name of the Cluster. CloudNativePG writes the connection to <name>-app, so set global.monad.dbSecret to match when you change it. |
postgresql.cnpg.monitoring.enabled | false | Renders a PodMonitor for the Postgres pods. The render fails unless the Prometheus Operator CRDs are installed. |
postgresql.cnpg.spec | {} | Any other CloudNativePG Cluster field, copied in as written, such as imageName or postgresql.parameters. A field the chart also sets, such as instances or storage, takes the value here instead. |
For example, to size the instances and put them on a particular StorageClass. In private-cluster.yaml, add these under its existing postgresql.cnpg key, which already sets the image and resources:
Code
For a single instance, such as on a development cluster, also set minSyncReplicas: 0 and maxSyncReplicas: 0 in the same block. CloudNativePG rejects a Cluster whose maxSyncReplicas is not lower than instances.
Every PVC the chart creates is listed in the storage table. Placement and priority for the Postgres pods are on Scheduling and Resources, and backups on Backup and Restore.
Your own Postgres
To use a Postgres you run yourself, turn off the chart's, give Monad a database and a user, and put their connection in a Secret. The chart's examples/local-auth-external-postgres.yaml is a complete values file for your own Postgres with local authentication; see Get the chart and its examples.
Requirements
-
Version. Use PostgreSQL 16 or later.
-
A database the Monad user owns. Monad's migrations, which run before each api pod starts, create the
uuid-osspextension, tables, indexes and functions, and a dailypartition-managerjob creates and drops monthly partitions of the audit log. If your provider restricts extensions, allowuuid-osspfirst. For example, as a user allowed to create roles and databases:CodeThe
GRANTlets an administrator that is not a superuser, as on most managed services, give the database tomonad. -
Network access from the pods in the release namespace.
-
TLS as described below.
How the components connect over TLS depends on the useInsecure key in the database Secret, or global.monad.dbUseInsecure when the Secret has none (default "false"):
| Setting | Connection |
|---|---|
"true" | Without TLS |
| Anything else | With TLS when the server offers it, without verifying the server's certificate; without TLS when it does not |
The migrations and partition-manager connect with the uri key as written instead, so set its sslmode to match, such as sslmode=require with TLS or sslmode=disable with useInsecure: "true".
Create the database Secret
Create a Secret named monad-db-app in the release namespace. The components read it through the Kubernetes API when they start, so it must be in the same namespace as Monad.
| Key | Read by | Value |
|---|---|---|
host | api, api-grpc, eventhandler, quota-service-cron | The server's host name. Monad does not read a port key, so for a port other than 5432 add it here, such as db.example.com:6432. |
user | The same | The Monad user |
password | The same | Its password |
dbname | The same | The Monad database |
uri | The api's migrations, partition-manager | The full connection URI, such as postgresql://monad:<password>@db.example.com:5432/monad?sslmode=require |
useInsecure | Optional | "true" to connect without TLS |
Passwords go into a URI
Use a password of letters and digits, such as one from openssl rand -hex 24. Monad puts the password into a connection URI, and in some versions a character such as @, / or % makes it fail to connect or reach the wrong host. Put the password in password as it is, and percent-encode any character other than a letter or digit in uri.
For example, from a file named db.env. Keep each line exactly key=value, with no comments or trailing spaces, because kubectl copies everything after the = into the value:
Code
Code
To use another name, set global.monad.dbSecret to it. Every component that connects to the database reads the Secret it names, including the migrations and partition-manager.
Point the chart at your database
Turn off the chart's Postgres in your values:
Code
The CloudNativePG operator is then not needed. With local authentication, Kratos also needs a database of its own; see the next section.
Kratos on your own Postgres
With local authentication, Kratos keeps its data in its own database. The chart creates it only in its own Postgres, so with yours:
-
Create a database for Kratos and a user that owns it. Kratos creates its tables when it starts, so the database can be empty:
Code -
Create the
monad-kratos-secretsSecret with adsnpointing at that database, such aspostgres://kratos:<password>@db.example.com:5432/kratos?sslmode=require, and setkratos.secret.generate: false. Both steps are in Provide the Kratos Secret yourself. The chart fails to render if Kratos is on with your own Postgres andgenerateis stilltrue.
Your own Redis-compatible cache
To use a Redis-compatible cache you already run instead of the chart's Dragonfly, turn Dragonfly off and set the cache's URL. If your values file already has a global block, as the chart's examples do, add monad.redisUrl under it rather than repeating global, because a repeated top-level key replaces the earlier one without an error:
Code
The chart fails to render with dragonfly.enabled: false and no redisUrl. The URL takes the form redis://[[user]:password@]host:port, or rediss:// for TLS; percent-encode reserved characters in the user and password. It reaches the api, api-grpc, http-input and the operator, and the operator passes it to the pipeline and alert pods it creates, as a plain environment variable that anyone who can read those pods can see.
The operator still starts a separate Dragonfly for each pipeline that needs its own store. Its image is set apart from the chart's; see Images and Registries.