Copy page

User Guides

Installation With Helm

Overview

This guide documents the process for installing Monad into a Kubernetes cluster using Helm. The primary installation method uses the Kubernetes Gateway API for ingress. If your cluster uses a traditional ingress controller instead, see Alternative: Ingress Controller at the end of this document.

---

Phase 1: Prerequisites

These must be installed before the Monad Helm chart can be deployed.

Authentication Provider

Monad supports local authentication, Auth0, and AWS Cognito, with Auth0 being the default.

Required Operators/Controllers

1. Victoria Metrics Operator

   • Required for internal metrics and dashboards, deployed by Custom Resources from within the chart. This does not replace an observability stack like Prometheus, and all components expose endpoints for scraping by an observability platform.
   • Installation: https://docs.victoriametrics.com/operator/

2. CloudNativePG (CNPG) - PostgreSQL operator

   • Required unless you're using an external PostgreSQL instance
   • Installation: https://cloudnative-pg.io/documentation/current/installation_upgrade/

Gateway or Ingress Controller

• Monad recommends using the Kubernetes Gateway API for ingress and will create HTTPRoute and TCPRoute resources automatically. You need a Gateway API implementation installed in your cluster (e.g., Traefik, Istio, Envoy Gateway, kgateway, or any other conformant implementation).
• Your implementation must support the experimental Gateway API channel, which includes TCPRoute.
• Installation varies by implementation. Refer to your implementation's documentation.
• This guide assumes the use of Gateway API, though alternatives for using an ingress controller are provided at the end of the document.

Create Namespace

Code
kubectl create namespace monad

---

Phase 2: Create Required Secrets

These secrets must exist before installing the Helm chart. All secrets are created in the monad namespace.

1. License Secret

The Monad license is a TLS certificate. You should have received a license.crt file from Monad.

Code
kubectl create secret generic monad-license \
  --from-file=license.crt=/path/to/license.crt \
  -n monad

2. Encryption Key Secret

Used for encrypting sensitive data within Monad. This is a base64-encoded random 32-byte key.

Code
# Generate the encryption key
ENCRYPTION_KEY=$(dd if=/dev/urandom bs=1 count=32 2>/dev/null | base64)

# Create the secret
kubectl create secret generic secret \
  --from-literal=MONAD_ENCRYPTION_KEY="${ENCRYPTION_KEY}" \
  -n monad

3. Key Encryption Key (KEK)

Each Monad organization is issued its own DEK, which is wrapped by the active KEK before being stored. Decryption requires the same KEK version that performed the wrap, so the Secret holds every version that has ever been used. The KEK never leaves the cluster.

The Helm chart consumes the KEK from a Kubernetes Secret named monad-master-encryption-key in the monad namespace. Each data field is a numeric version label (1, 2, 3, …) holding a base64-encoded 32-byte random key. The highest numeric field is the active version; new versions are appended on rotation, and old versions are never deleted or overwritten. When a new version appears, Monad automatically re-wraps every organization's DEK to the new active KEK — no manual re-encryption step is required.

Recommended: sync from your secrets manager

In production, the KEK should originate in the secrets manager you already operate — HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, 1Password, etc. — and be reconciled into the cluster via External Secrets Operator (ESO), so that backups, audit, and rotation flow through the same controls as the rest of your secrets.

Store an item in your secrets manager (e.g. named monad-key-encryption-key) with one numeric field per version, each value a base64-encoded 32-byte random key (openssl rand 32 | base64 or any equivalent CSPRNG). Then enable the chart's ExternalSecret in your values-override.yaml:

Code
api:
  externalsecrets:
    monad-master-encryption-key:
      enabled: true
      # Optional: point at a specific ClusterSecretStore. Falls back to the
      # global externalsecret.secretStoreRef if omitted.
      # secretStoreRef:
      #   name: my-secret-store
      #   kind: ClusterSecretStore
      dataFrom:
        - extract:
            key: monad-key-encryption-key

The extract directive syncs every field of the upstream item into the K8s Secret, so adding a new numeric version upstream needs no chart or values change.

Without an external secret store

For air-gapped clusters or environments without ESO (or an equivalent bridge like SealedSecrets / SOPS), you can create the Secret directly with kubectl. Generate and back up the key material in something durable before applying it — once it lives only in the cluster, K8s becomes the source of truth, which is fragile.

Code
kubectl create secret generic monad-master-encryption-key \
  -n monad \
  --from-literal=1="$(openssl rand 32 | base64)"

Rotations are performed by kubectl patch-ing in a new numeric field, or by re-creating the Secret with all existing versions plus the new one.

Verify

After install, confirm the api and operator pods see the mount:

Code
kubectl exec -n monad deploy/monad-api -- ls /secrets/key-encryption-key

4. Image Pull Secret

You should have received credentials from Monad support for accessing the images in Docker Hub. Configure those here as default-pull-secret (required name).

Code
kubectl create secret docker-registry default-pull-secret \
  --docker-server=registry-1.docker.io \
  --docker-username=monadinc \
  --docker-password=<PERSONAL_ACCESS_TOKEN> \
  -n monad

5. Authentication Secrets

Using External Secrets Operator

If you're using an external secrets store, you'll need to either save your secrets with the property names found in values.yaml or update the values.yaml to match your secret property names.

Code
  externalsecret:
    enabled: true
    data:
      - secretKey: AUTH0_DOMAIN
        remoteRef:
          key: env-secrets
          property: MONAD_AUTH_AUTH0_API_AUDIENCE # <-- update these to match your secret property names
      - secretKey: AUTH0_API_AUDIENCE
        remoteRef:
          key: env-secrets
          property: MONAD_AUTH_AUTH0_API_AUDIENCE
...

Not Using External Secrets Operator

If you're not using an External Secrets operator, you need to create secrets for authentication backend credentials. Below is an example file of key/value environment variable pairs that you can create a secret from.

Note: Some of these variables exist in two forms. Monad is migrating from variable names like AUTH0_CLIENT_ID to MONAD_AUTH_AUTH0_CLIENT_ID. The MONAD_-prefixed variables are the new names, and the old names will be deprecated in a future release. For current and future compatibility, use both until informed that the old names can be removed.

api.env

Code
# Required
AUTH_SECRET=<AUTH_SECRET>
MONAD_AUTH_SECRET=<AUTH_SECRET>

# Required for AUTH0
MONAD_AUTH_TYPE=auth0
MONAD_AUTH_AUTH0_CLIENT_ID=<AUTH0_CLIENT_ID>
MONAD_AUTH_AUTH0_API_AUDIENCE=<AUTH0_API_AUDIENCE>
MONAD_AUTH_AUTH0_API_CLIENT_ID=<AUTH0_API_CLIENT_ID>
MONAD_AUTH_AUTH0_CLIENT_SECRET=<AUTH0_API_CLIENT_SECRET>
MONAD_AUTH_AUTH0_DOMAIN=<AUTH0_DOMAIN>
MONAD_AUTH_AUTH0_ISSUER=<AUTH0_ISSUER>
MONAD_AUTH_AUTH0_MACHINE_CLIENT_SECRET=<AUTH0_MACHINE_CLIENT_SECRET>
MONAD_AUTH_AUTH0_MACHINE_CLIENT_ID=<AUTH0_MACHINE_CLIENT_ID>
MONAD_AUTH_AUTH0_MACHINE_AUDIENCE=<AUTH0_MACHINE_AUDIENCE>

# Required for Cognito
MONAD_AUTH_TYPE=cognito
MONAD_AUTH_COGNITO_AWS_REGION=<COGNITO_AWS_REGION>
MONAD_AUTH_COGNITO_USER_POOL_ID=<COGNITO_USER_POOL_ID>
MONAD_AUTH_COGNITO_CLIENT_ID=<COGNITO_CLIENT_ID>
MONAD_AUTH_COGNITO_DOMAIN=<COGNITO_DOMAIN>
MONAD_AUTH_COGNITO_SECRET=<COGNITO_SECRET>
MONAD_AUTH_COGNITO_ISSUER_URL=<COGNITO_ISSUER_URL>

# Optional
GOOGLE_OAUTH_CLIENT_ID=<GOOGLE_OAUTH_CLIENT_ID>
GOOGLE_OAUTH_CLIENT_SECRET=<GOOGLE_OAUTH_CLIENT_SECRET>
ZOOM_OAUTH_CLIENT_ID=<ZOOM_OAUTH_CLIENT_ID>
ZOOM_OAUTH_CLIENT_SECRET=<ZOOM_OAUTH_CLIENT_SECRET>

Create the Secret api from the file:

Code
kubectl create secret generic api \
  --from-env-file=api.env \
  -n monad

ui.env

Code
# Required
AUTH_SECRET=<AUTH_SECRET>

# Required for Auth0
MONAD_AUTH_TYPE=auth0
AUTH_AUTH0_DOMAIN=<AUTH0_DOMAIN>
AUTH_AUTH0_CLIENT_ID=<AUTH0_CLIENT_ID>
AUTH_AUTH0_API_AUDIENCE=<AUTH0_API_AUDIENCE>
AUTH_AUTH0_CLIENT_SECRET=<AUTH0_CLIENT_SECRET>
AUTH_SECRET=<AUTH_SECRET>

# Required for Cognito
MONAD_AUTH_TYPE=cognito
AUTH_COGNITO_AWS_REGION=<COGNITO_AWS_REGION>
AUTH_COGNITO_USER_POOL_ID=<COGNITO_USER_POOL_ID>
AUTH_COGNITO_CLIENT_ID=<COGNITO_CLIENT_ID>
AUTH_COGNITO_DOMAIN=<COGNITO_DOMAIN>
AUTH_COGNITO_SECRET=<COGNITO_SECRET>
AUTH_COGNITO_ISSUER_URL=<COGNITO_ISSUER_URL>

Create the secret ui from the file:

Code
kubectl create secret generic ui \
  --from-env-file=ui.env \
  -n monad

---

Phase 3: Configure TLS

For the remainder of this guide we will be using monad.example.com as our example domain.

Monad requires two TLS certificates:

1. Gateway Certificate

Used by the Gateway to terminate HTTPS for all web traffic. This is a standard certificate for your Monad hostname (e.g., monad.example.com).

The Secret must be created in the same namespace as your Gateway resource (not the monad namespace). This is a Gateway API requirement: certificate secrets must be co-located with the Gateway that references them.

See TLS with cert-manager for instructions on creating this certificate automatically.

2. HTTP Input TLS Certificate

Monad's HTTP Input workload handles inputs such as Syslog that require direct TLS termination at the Pod level. This certificate is separate from the Gateway certificate and must be named http-input-tls in the monad namespace.

Syslog and other TCP-terminated inputs use the hostname with SNI for routing, with names like cef85707-4b6e-405a-aea9-3237d520e805.l4.monad.example.com. It should answer to both l4.monad.example.com and the wildcard domain *.l4.monad.example.com. You will also need a DNS record pointing *.l4.monad.example.com to the load balancer address that handles TCP traffic into your cluster.

See TLS with cert-manager for instructions on creating this certificate automatically.

Configure Your Gateway

Your Gateway resource needs an HTTPS listener that references the Gateway certificate Secret. The exact configuration depends on your implementation, but the Gateway API spec looks like:

Code
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: <your-gateway>
  namespace: <gateway-namespace>
spec:
  gatewayClassName: <your-gateway-class>
  listeners:
    - name: web
      port: 80
      protocol: HTTP
      allowedRoutes:
        namespaces:
          from: All
    - name: websecure
      port: 443
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - name: monad-example-com-crt
            namespace: <gateway-namespace>
    - name: otel-grpc
      port: 4317
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - name: monad-example-com-crt
            namespace: <gateway-namespace>
    - name: otel-https
      port: 4318
      protocol: HTTPS
      allowedRoutes:
        namespaces:
          from: All
      tls:
        mode: Terminate
        certificateRefs:
          - name: monad-example-com-crt
            namespace: <gateway-namespace>
    - name: tcp
      port: 6514
      protocol: TCP
      allowedRoutes:
        namespaces:
          from: All

Refer to your Gateway implementation's documentation for how to configure listeners.

---

Phase 4: Configure values.yaml Overrides

Create a values-override.yaml file with the following configurations.

With Gateway API enabled, Monad's chart generates HTTPRoute resources automatically for all components. You do not need to configure ingress per-component — setting hostnames and routing at the top level is sufficient for all components to be reachable.

Code
# The hostname(s) at which Monad will be accessible.
# All HTTPRoutes, backend URLs, and the UI origin are derived from this.
hostnames:
  - monad.example.com

# Pull images from Docker Hub instead of GHCR
image:
  repository: registry-1.docker.io/monadinc/

imagePullSecrets:
  - name: default-pull-secret

# Enable Gateway API routing
routing:
  enabled: true

# Point all routes at your Gateway
routes:
  default:
    parentRefs:
      - namespace: <gateway-namespace>
        name: <your-gateway-name>
        sectionName: websecure
  otel:
    parentRefs:
      - namespace: <gateway-namespace>
        name: <your-gateway-name>
        sectionName: otel-grpc
      - namespace: <gateway-namespace>
        name: <your-gateway-name>
        sectionName: otel-https
  tcp:
    parentRefs:
      - namespace: <gateway-namespace>
        name: <your-gateway-name>
        sectionName: tcp

# Set this to your cluster's storageClassName (even if you have a default storage class, you have to override the setting in values.yaml)
nats:
  config:
    jetstream:
      fileStore:
        pvc:
          storageClassName: <your-storage-class>

operator:
  env:
    MONAD_PIPELINE_IMAGE_REGISTRY:
      value: registry-1.docker.io/monadinc/

---

Phase 5: Install Monad

Log in to OCI Registry

Before you can pull the Helm chart, authenticate to the Docker registry:

Code
helm registry login registry-1.docker.io --username monadinc
Password:
Login Succeeded

Note: Credentials are provided by Monad support. The login persists in ~/.docker/config.json.

Install with Custom Values

Code
helm upgrade monad oci://registry-1.docker.io/monadinc/monad \
  --install \
  --namespace monad \
  --values values-override.yaml \
  --timeout 10m

Verify Installation

Some pods will initially come up in an Error state as they wait for the database to be ready. They should all be Running (or Completed) within a few minutes.

Code
# Check all pods are running
kubectl get pods -n monad

# Check services
kubectl get svc -n monad

# Check Gateway API routes (replaces kubectl get ingress)
kubectl get httproute -n monad
kubectl get certificate -n monad

---

Phase 6: Post-Installation

At this point, Monad should be up and running. Access it at your designated hostname.

---

Alternative Installation Options

TLS with cert-manager

If you're using cert-manager for certificate management, create a ClusterIssuer and two Certificate resources as described below.

ClusterIssuer

Code
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: your-email@example.com
    privateKeySecretRef:
      name: letsencrypt-prod
    solvers:
      - http01:
          ingress:
            class: traefik

Gateway Certificate

Create this in your Gateway's namespace (e.g., kube-system for Traefik on k3s):

Code
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: monad-example-com-crt
  namespace: <gateway-namespace>
spec:
  secretName: monad-example-com-crt
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - monad.example.com

HTTP Input TLS Certificate

Create this in the monad namespace:

Code
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: http-input-tls
  namespace: monad
spec:
  secretName: http-input-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - l4.monad.example.com
    - "*.l4.monad.example.com"

---

External Postgres

If you want to use an external Postgres instance, you can disable the CloudNativePG operator and provide the connection details in the monad-db-app Secret.

Below is an example file you can create a Secret from. It uses the following values:

• dbname: monad
• user: monad
• password: somereallylongandcomplexpassword
• host: monad-db-rw.postgres / monad-db-rw.postgres.svc.cluster.local (default CNPG service structure for a database in the postgres namespace)
• port: 5432

Code
# db.env
dbname=monad
fqdn-jdbc-uri=jdbc:postgresql://monad-db-rw.postgres.svc.cluster.local:5432/monad?password=somereallylongandcomplexpassword&user=monad
fqdn-url=postgresql://monad:somereallylongandcomplexpassword@monad-db-rw.postgres.svc.cluster.local:5432/monad
host=monad-db-rw.postgres
jdbc-uri=jdbc:postgresql://monad-db-rw.postgres:5432/monad?password=somereallylongandcomplexpassword&user=monad
password=somereallylongandcomplexpassword
pgpass=monad-db-rw.postgres:5432:monad:monad:somereallylongandcomplexpassword
port=5432
uri=postgresql://monad:somereallylongandcomplexpassword@monad-db-rw.postgres:5432/monad
user=monad
username=monad

Create the Secret monad-db-app from the file:

Code
kubectl create secret generic monad-db-app \
  --from-env-file=db.env \
  -n monad

Disable the CloudNativePG operator in your values-override.yaml:

Code
postgresql:
  cnpg:
    enabled: false

Local Authentication

Local authentication creates an admin user of admin@monad.local and a random password. To activate this, remove the Auth0 and Cognito configuration from the api and ui secrets, and set MONAD_AUTH_TYPE to local for both components in your values-override.yaml:

Code
ui:
  env:
    MONAD_AUTH_TYPE:
      value: local
api:
  env:
    MONAD_AUTH_TYPE:
      value: local
http-input:
  env:
    MONAD_AUTH_TYPE:
      value: local

After completing the installation, retrieve the Secret with the username and password:

Code
kubectl get secret app-bootstrap-admin -n monad \
  -o go-template='{{range $k,$v := .data}}{{printf "%s: %s\n" $k ($v | base64decode)}}{{end}}'

This secret is only used to deliver credentials after installation and can be deleted after retrieval.

Local authentication does not allow the creation of more users than the local admin. If you wish to have multiple users, log in as the admin user and set up SSO from the Settings menu.

---

Ingress Controller

If your cluster uses a traditional Kubernetes Ingress resource rather than Gateway API, use the following values-override.yaml instead of the one in Phase 4. All other phases remain the same, except:

• The TLS certificate Secret should be created in the monad namespace instead of the Gateway namespace
• Use kubectl get ingress -n monad instead of kubectl get httproute -n monad to verify routing

Remove the routing and routes keys from the earlier example of values-override.yaml and add the following:

Code
ingress:
  className: "<your-ingress-class>"   # e.g., traefik, nginx
  annotations:
    cert-manager.io/cluster-issuer: "letsencrypt-prod"
  tls:
    - secretName: monad-example-com-crt
      hosts:
        - monad.example.com

api:
  ingress:
    enabled: true

docs:
  ingress:
    enabled: true

http-input:
  ingress:
    enabled: true

ui:
  ingress:
    enabled: true