Install
Install Monad on your own Kubernetes cluster with Helm, Argo CD or Flux. Before you start, work through Before You Install: the operators, the namespace and the required Secrets must exist first. The same command also upgrades an existing install; see Upgrade.
You need kubectl, Helm 3.10 or later, and the Docker Hub token Monad support gives you. Earlier Helm versions fail to render the chart.
Log in to the registry
The chart is published to Docker Hub with Monad's images. Log in with the token from Monad support:
Code
Helm keeps the login in its own registry config file, not in Docker's. helm env HELM_REGISTRY_CONFIG prints where.
Get the chart and its examples
Pick a chart version from the release notes. These pages describe chart 2.101.0 and later. Pull that version:
Code
This writes the chart to ./monad. Example values files are in ./monad/examples/, and ./monad/values.yaml describes every setting, as does the chart's README.md.
Choose an example
Start from the example closest to your setup. Each file says which Secrets and pages it needs before you install.
| File | Starts you with |
|---|---|
minimal.yaml | Gateway API routing, the chart's own Postgres and Auth0. For Amazon Cognito, start here too: the provider is chosen in the api and ui Secrets. |
local-auth-external-postgres.yaml | Local authentication and your own Postgres. Every render of it is the same, so it suits Argo CD. |
private-cluster.yaml | Images from your own registry, dedicated nodes, your own PriorityClasses, an authenticated message bus and sized resources, with the chart's Postgres and Auth0. |
Every example sets hostnames, attaches routes to a Gateway and sizes the NATS volume. minimal.yaml and local-auth-external-postgres.yaml pull Monad's images from Docker Hub with default-pull-secret. To use an ingress controller instead of Gateway API, see Networking and TLS.
Build your values file
Copy the example to values.yaml and replace every example.com name and <your-...> placeholder. hostnames is the name users reach Monad at: the routes, the backend URLs and the console's origin all derive from it.
The other pages in this guide give each setting as a snippet with its full path from the top-level key. Add a snippet's settings under the top-level key your file already has, such as global or nats.
Keep each top-level key once
YAML lets a file repeat a key, and Helm keeps only the last copy without a warning. A second nats: block pasted below the example's replaces the whole first one, including the NATS volume size, which cannot change after the first install.
yamllint reports a repeated key:
Code
You can also split your settings across several files and pass each with its own --values. Helm merges them in order: maps merge key by key, a later file wins for the same key, and a list in a later file replaces the earlier list whole.
Before installing, render the chart once. It fails with a message on settings that cannot work, such as postgresql.cnpg.backup.enabled without postgresql.cnpg.backup.objectStore.destinationPath:
Code
Choose a release name
Any release name works. The chart's NATS, Dragonfly and Kratos are named after the release, such as <release>-nats, and Monad's components find them by that name. This guide uses monad. Install one release per namespace, and set crds.create: false on every release after the first in the cluster; see Namespace.
Install with Helm
Code
Pin --version: without it, Helm takes the newest chart. Add a --values for each extra file, in order.
Helm then prints the console address and how to sign in. helm get notes monad -n monad shows them again. Continue with Verify the installation.
Install with Argo CD or Flux
What changes when the chart is rendered with helm template
Argo CD renders the chart with helm template and applies the result itself, so Helm never reads the cluster. By default Argo CD passes the cluster's Kubernetes version and API versions to the render. Other tools that render with helm template, such as a CI job that commits manifests, need the matching --api-versions flags.
| What the chart does | With helm template | What to set |
|---|---|---|
With local authentication, generates the Kratos Secret, monad-kratos-secrets, with random values once, and reads it back with lookup on later upgrades | lookup returns nothing, so every render generates new values. Applying them rotates the Kratos database password and its cookie and cipher secrets. | kratos.secret.generate: false, and provide the Kratos Secret yourself |
Renders ExternalSecrets at external-secrets.io/v1, or at v1beta1 when the cluster serves only that | Without the cluster's API versions, renders v1, which older External Secrets Operator releases do not serve | On such a cluster, --api-versions external-secrets.io/v1beta1/ExternalSecret |
Renders TCPRoute and TLSRoute at gateway.networking.k8s.io/v1, or at v1alpha2 and v1alpha3 when the cluster's Gateway API CRDs serve only those | Without the cluster's API versions, renders v1, which older Gateway API CRDs do not serve; TCPRoute is served at v1 from Gateway API v1.6 | On such a cluster, --api-versions gateway.networking.k8s.io/v1alpha2/TCPRoute, plus gateway.networking.k8s.io/v1alpha3/TLSRoute if you add a tls route. See Gateway API route versions. |
Fails the render when postgresql.cnpg.monitoring.enabled or victoriametrics.monitoring.enabled is on and the cluster has no PodMonitor or ServiceMonitor CRD | Fails unless the API version is passed | --api-versions monitoring.coreos.com/v1/PodMonitor or monitoring.coreos.com/v1/ServiceMonitor |
With the Kratos Secret provided, the same values render the same manifests every time.
Argo CD
-
Create the namespace and the required Secrets. With local authentication, also create the Kratos Secret and set
kratos.secret.generate: false, aslocal-auth-external-postgres.yamldoes. -
Give Argo CD the registry credentials, as a repository Secret in Argo CD's namespace:
Code -
Create an Application that takes the chart from the registry and your values file from Git. Here the values file is
monad/values.yamlin your configuration repository:Code
The Helm release is named after the Application. Leave helm.releaseName unset: with Argo CD's label-based tracking, Argo CD sets the app.kubernetes.io/instance label to the Application's name, and the chart's selectors use that label with the release name.
The chart creates CustomResourceDefinitions and PriorityClasses, which are cluster-scoped. If your AppProject restricts cluster-scoped resources, allow both kinds, or turn them off as in Cluster permissions.
Argo CD does not show the chart's post-install notes; see First sign-in.
Flux
Flux's helm-controller installs and upgrades the release with Helm against the cluster, so lookup and the API version checks work as with helm upgrade, and the chart can generate the Kratos Secret itself.
Point an OCIRepository at the chart, using default-pull-secret for the registry credentials, and a HelmRelease at the OCIRepository:
Code
monad-values is a ConfigMap holding your values file under the key values.yaml. The release is named monad, after the HelmRelease.
To build the ConfigMap from the values file in Git with a Kustomize configMapGenerator, turn off the hash Kustomize appends to the name. Kustomize does not update a HelmRelease's valuesFrom to the hashed name, so with the hash the HelmRelease cannot find its values:
Code
Here monad.yaml holds the OCIRepository and HelmRelease above, next to values.yaml.
Verify the installation
-
Watch the pods come up. Some restart while Postgres starts; within a few minutes every pod should be
RunningorCompleted.CodeA pod waiting in
ContainerCreatingorCreateContainerConfigErroris missing a Secret, and so is anl4-inputpod that restarts after loggingTLS certs not found or invalid; see Required Secrets. -
Check the routes. With Gateway API you should see the HTTPRoutes
api-default,docs-default,http-input-default,http-input-otel,mcp-defaultandui-default, and the TCPRoutel4-input-tcp. Each should list your Gateway as a parent with the conditionAcceptedset toTrue:CodeWith an ingress controller, run
kubectl get ingress -n monadinstead. -
Check the metrics store.
STATUSshould readoperational:Code -
With the chart's own Postgres, check the database.
STATUSshould readCluster in healthy state:Code
For a map of what is now running and how data flows through it, see Platform Architecture. When something does not come up, see Troubleshooting.
First sign-in
Open https:// followed by the first entry in hostnames.
- Local authentication: on a new install, the login page sends you to Create the admin account. Choose the admin's email and password, then sign in with them.
- Auth0 or Amazon Cognito: the login page redirects to your identity provider. Sign in with an account from it.
Authentication covers both in detail.
Upgrade
- Read the release notes for every version between yours and the target.
- Run the same
helm upgrade --installcommand with the new--versionand the same values files. With Argo CD, changetargetRevision; with Flux, changeref.tag.
Two settings need care across upgrades:
- NATS volume size: Kubernetes does not let the NATS volume template change after the first install, so leave
nats.config.jetstream.fileStore.pvc.sizeas installed. Grow the JetStream volume covers growing the volume by hand. - Gateway API CRDs: before you install Gateway API CRDs that stop serving the alpha route versions, upgrade Monad once while the cluster still serves both. Upgrading Gateway API CRDs has the procedure.
Uninstall
Uninstalling deletes the chart's Postgres
With the chart's Postgres, CloudNativePG deletes the database and its volumes with the Cluster. Take a Postgres backup first if you may want the configuration back.
Code
Deleting the Flux HelmRelease uninstalls the release the same way, and so does deleting the Argo CD Application with cascading deletion.
The CRDs stay, so other releases that use them keep working: deleting a CRD deletes every Organization, Pipeline and PipelineNode in the cluster. Helm keeps them because the chart marks them to keep. Argo CD keeps them because it never deletes a CustomResourceDefinition when it deletes an Application's resources, whatever the CRD's annotations.
For an install you want gone entirely, such as a test cluster, upgrade with crds.keep: false before uninstalling. Helm reads the setting from the deployed release, so it takes effect only after that upgrade. The uninstall then deletes the CRDs, and Kubernetes deletes every Organization, Pipeline and PipelineNode in the cluster with them, other releases' included. Argo CD keeps the CRDs whatever the setting, so with Argo CD delete them by hand once the Application is gone, with the same effect:
Code
What the uninstall removes and what stays:
| Removed | Stays |
|---|---|
Everything else the chart rendered: Monad's components, the PriorityClasses, the NATS servers, Dragonfly, Kratos, the VictoriaMetrics resources and the CloudNativePG Cluster | The three CRDs, this release's Organizations, Pipelines and PipelineNodes, and the pods the operator created for them |
The chart's Postgres volumes and its monad-db-app Secret, which CloudNativePG deletes with the Cluster | The monad-kratos-secrets Secret: the chart marks the one it generates to keep, and one you provide is yours |
| Secrets that the chart's ExternalSecrets created. Your secrets manager keeps the values. | The NATS JetStream and vmstorage volumes (PersistentVolumeClaims), which Kubernetes keeps when their StatefulSets go |
| Postgres backups in your object store | |
The Secrets you created: api, ui, the license, the key encryption key, the pull secret, http-input-tls, and your database and NATS credentials | |
| The namespace |
To install again later, reuse the release name and namespace, so Helm takes the kept CRDs back. A release with another name sets crds.create: false.
Remove the pipelines
The pipeline pods keep running without the operator, NATS or the database until you remove their objects. The operator puts finalizers on Organizations and Pipelines, and only the operator removes them, so clear them first:
Code
Then delete this release's objects. Kubernetes deletes the pods the operator created for them:
Code
If no other release in the cluster uses the CRDs, delete them too:
Code
To remove the data as well, delete the leftover PersistentVolumeClaims, and the namespace once nothing else in it is needed.