# Install Install Monad on your own Kubernetes cluster with Helm, Argo CD or Flux. Before you start, work through [Before You Install](/docs/guides/self-managed/before-you-install): the operators, the namespace and the required Secrets must exist first. The same command also upgrades an existing install; see [Upgrade](#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: ```bash helm registry login registry-1.docker.io --username monadinc ``` 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](/docs/release-notes). These pages describe chart 2.101.0 and later. Pull that version: ```bash helm pull oci://registry-1.docker.io/monadinc/monad --version --untar ``` 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](/docs/guides/self-managed/networking). ## Build your values file Copy the example to `values.yaml` and replace every `example.com` name and `` 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`. :::warning[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](https://yamllint.readthedocs.io/) reports a repeated key: ```bash yamllint -d '{rules: {key-duplicates: enable}}' values.yaml ``` 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`: ```bash helm template monad oci://registry-1.docker.io/monadinc/monad --version \ --namespace monad --values values.yaml > /dev/null ``` ## Choose a release name Any release name works. The chart's NATS, Dragonfly and Kratos are named after the release, such as `-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](/docs/guides/self-managed/before-you-install#namespace). ## Install with Helm ```bash helm upgrade --install monad oci://registry-1.docker.io/monadinc/monad \ --version \ --namespace monad \ --values values.yaml ``` 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](#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](/docs/guides/self-managed/authentication#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](/docs/guides/self-managed/networking#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 1. Create the namespace and the [required Secrets](/docs/guides/self-managed/before-you-install#required-secrets). With local authentication, also create the Kratos Secret and set `kratos.secret.generate: false`, as `local-auth-external-postgres.yaml` does. 2. Give Argo CD the registry credentials, as a repository Secret in Argo CD's namespace: ```yaml apiVersion: v1 kind: Secret metadata: name: monad-chart-registry namespace: argocd labels: argocd.argoproj.io/secret-type: repository stringData: name: monad url: registry-1.docker.io/monadinc type: helm enableOCI: "true" username: monadinc password: ``` 3. Create an Application that takes the chart from the registry and your values file from Git. Here the values file is `monad/values.yaml` in your configuration repository: ```yaml apiVersion: argoproj.io/v1alpha1 kind: Application metadata: name: monad namespace: argocd spec: project: default destination: server: https://kubernetes.default.svc namespace: monad sources: - repoURL: registry-1.docker.io/monadinc chart: monad targetRevision: "" helm: valueFiles: - $values/monad/values.yaml - repoURL: https://git.example.com/platform/monad-config.git targetRevision: main ref: values ``` 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](/docs/guides/self-managed/before-you-install#cluster-permissions). Argo CD does not show the chart's post-install notes; see [First sign-in](#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`: ```yaml apiVersion: source.toolkit.fluxcd.io/v1 kind: OCIRepository metadata: name: monad namespace: monad spec: interval: 10m url: oci://registry-1.docker.io/monadinc/monad ref: tag: "" secretRef: name: default-pull-secret layerSelector: mediaType: application/vnd.cncf.helm.chart.content.v1.tar+gzip operation: copy --- apiVersion: helm.toolkit.fluxcd.io/v2 kind: HelmRelease metadata: name: monad namespace: monad spec: interval: 10m chartRef: kind: OCIRepository name: monad valuesFrom: - kind: ConfigMap name: monad-values ``` `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: ```yaml apiVersion: kustomize.config.k8s.io/v1beta1 kind: Kustomization namespace: monad resources: - monad.yaml configMapGenerator: - name: monad-values files: - values.yaml generatorOptions: disableNameSuffixHash: true ``` Here `monad.yaml` holds the `OCIRepository` and `HelmRelease` above, next to `values.yaml`. ## Verify the installation 1. Watch the pods come up. Some restart while Postgres starts; within a few minutes every pod should be `Running` or `Completed`. ```bash kubectl get pods -n monad --watch ``` A pod waiting in `ContainerCreating` or `CreateContainerConfigError` is missing a Secret, and so is an `l4-input` pod that restarts after logging `TLS certs not found or invalid`; see [Required Secrets](/docs/guides/self-managed/before-you-install#required-secrets). 2. Check the routes. With Gateway API you should see the HTTPRoutes `api-default`, `docs-default`, `http-input-default`, `http-input-otel`, `mcp-default` and `ui-default`, and the TCPRoute `l4-input-tcp`. Each should list your Gateway as a parent with the condition `Accepted` set to `True`: ```bash kubectl get httproute,tcproute -n monad kubectl describe httproute ui-default -n monad ``` With an ingress controller, run `kubectl get ingress -n monad` instead. 3. Check the metrics store. `STATUS` should read `operational`: ```bash kubectl get vmcluster billing-metrics -n monad ``` 4. With the chart's own Postgres, check the database. `STATUS` should read `Cluster in healthy state`: ```bash kubectl get clusters.postgresql.cnpg.io monad-db -n monad ``` For a map of what is now running and how data flows through it, see [Platform Architecture](/docs/guides/architecture). When something does not come up, see [Troubleshooting](/docs/guides/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](/docs/guides/self-managed/authentication) covers both in detail. ## Upgrade 1. Read the [release notes](/docs/release-notes) for every version between yours and the target. 2. Run the same `helm upgrade --install` command with the new `--version` and the same values files. With Argo CD, change `targetRevision`; with Flux, change `ref.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.size` as installed. [Grow the JetStream volume](/docs/guides/self-managed/nats#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](/docs/guides/self-managed/networking#upgrading-gateway-api-crds) has the procedure. ## Uninstall :::danger[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](/docs/guides/self-managed/backup-and-restore#take-the-first-backup) first if you may want the configuration back. ::: ```bash helm uninstall monad -n monad ``` 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: ```bash kubectl delete crd organizations.pipeline.monad.com pipelines.pipeline.monad.com pipelinenodes.pipeline.monad.com ``` 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: ```bash for r in $(kubectl get organizations.pipeline.monad.com,pipelines.pipeline.monad.com -n monad -o name); do kubectl patch "$r" -n monad --type=merge -p '{"metadata":{"finalizers":null}}' done ``` Then delete this release's objects. Kubernetes deletes the pods the operator created for them: ```bash kubectl delete organizations.pipeline.monad.com,pipelines.pipeline.monad.com,pipelinenodes.pipeline.monad.com -n monad --all ``` If no other release in the cluster uses the CRDs, delete them too: ```bash kubectl delete crd organizations.pipeline.monad.com pipelines.pipeline.monad.com pipelinenodes.pipeline.monad.com ``` To remove the data as well, delete the leftover PersistentVolumeClaims, and the namespace once nothing else in it is needed.