Helm and Kubernetes

Deploy Marmot to a Kubernetes cluster with the official Helm chart.

Install

1. 1

   Add the Helm repository

   helm repo add marmotdata https://marmotdata.github.io/charts
   helm repo update

2. 2

   Install Marmot

   helm install marmot marmotdata/marmot

3. 3

   Sign in

   Forward the port to your machine:

   kubectl port-forward svc/marmot 8080:8080

   Open http://localhost:8080 and sign in as admin with the password admin. Marmot asks you to choose a new password straight away.

Database

Marmot needs PostgreSQL. Use one of these:

Connect Marmot to your existing PostgreSQL database:

config:
  database:
    host: postgres.example.com
    port: 5432
    user: marmot
    passwordSecretRef:
      name: marmot-db-secret
      key: password
    name: marmot
    sslmode: require

For development and testing, turn on the embedded PostgreSQL:

helm install marmot marmotdata/marmot \
  --set postgresql.enabled=true

The chart generates a PostgreSQL password Secret named <release>-postgresql with a password key and reuses it on upgrades. To use an existing Secret:

postgresql:
  auth:
    existingSecret: marmot-postgres-credentials
    passwordKey: password

For production, CloudNativePG runs PostgreSQL with automatic failover, read replicas and connection pooling.

1. 1

   Install the CloudNativePG operator

   Install the operator with the CloudNativePG installation guide, or apply its release manifest:

   kubectl apply --server-side -f \
     https://raw.githubusercontent.com/cloudnative-pg/cloudnative-pg/main/releases/cnpg-1.25.1.yaml

2. 2

   Configure and install Marmot with CNPG

   # values.yaml
   cnpg:
     enabled: true
     instances: 3  # 1 primary + 2 read replicas
     password: "<database-password>"
   
     parameters:
       shared_buffers: "256MB"
       work_mem: "64MB"
       effective_cache_size: "1GB"
   
     persistence:
       size: "10Gi"
   
     pooler:
       enabled: true
       instances: 2
       poolMode: "transaction"

   helm install marmot marmotdata/marmot -f values.yaml

3. 3

   Verify the cluster is ready

   kubectl get clusters
   kubectl get pods -l cnpg.io/cluster=marmot-cnpg

   Every pod shows Running, and the primary's name ends in -1.

Encryption key

Marmot encrypts the credentials it stores with this key, so every install needs one.

By default the chart generates a key and stores it in a Secret:

config:
  server:
    autoGenerateEncryptionKey: true

Back up the generated key

If the Secret is deleted, Marmot can't read the credentials it stored. Back the key up as soon as you install.

For a release named marmot, the Secret is marmot-encryption-key:

kubectl get secret marmot-encryption-key \
  -o jsonpath='{.data.encryption-key}' | base64 -d

1. 1

   Generate an encryption key

   marmot generate-encryption-key
   # or
   openssl rand -base64 32

2. 2

   Create a Kubernetes secret

   kubectl create secret generic marmot-encryption \
     --from-literal=encryption-key="<encryption-key>"

3. 3

   Configure the Helm chart

   config:
     server:
       autoGenerateEncryptionKey: false
       encryptionKeySecretRef:
         name: marmot-encryption
         key: encryption-key

For local development only, Marmot can run without a key and store credentials unencrypted:

config:
  server:
    autoGenerateEncryptionKey: false
    allow_unencrypted: true

Development only

Every stored credential would be readable by anyone with access to the database. Never use this in production.

Serving plugins

To let plugins that run in your own networks answer data queries, turn on the serve listener. It needs an encryption key.

config:
  query:
    serve:
      enabled: true
serveService:
  type: LoadBalancer

The chart opens port 8443, creates a separate <release>-serve Service for it and tells each replica the address its peers forward queries to. Expose the Service with a TCP load balancer or TLS passthrough, never one that terminates TLS. See serve queries from your network.

Chart values

Every value the chart takes, with its default:

helm show values marmotdata/marmot

Or read values.yaml on GitHub.

Next steps

• Configuration reference: every setting, set under config in the chart's values.
• Monitoring and metrics: scrape Marmot with the Prometheus Operator.
• Single sign-on: let your team sign in with your identity provider.