Skip to content

SECRET-MANAGEMENT.md

Latest commit

 

History

History
123 lines (101 loc) · 3.95 KB

SECRET-MANAGEMENT.md

File metadata and controls

123 lines (101 loc) · 3.95 KB

Secret Management

Secret Modes

Set secrets.mode in your countly.yaml:

Mode: values (default)

Provide secrets directly in your values files:

secrets:
  mode: values
  common:
    encryptionReportsKey: "my-key"
    webSessionSecret: "my-session"
    passwordSecret: "my-password"
    mailConfigAuthUser: "smtp-user"
    mailConfigAuthPass: "smtp-pass"
  clickhouse:
    password: "ch-password"
  mongodb:
    password: "mongo-password"

For production, encrypt these files with SOPS and use the helm-secrets plugin.

Mode: existingSecret

Reference pre-created Kubernetes secrets:

secrets:
  mode: existingSecret
  common:
    existingSecret: my-countly-common
  clickhouse:
    existingSecret: my-countly-clickhouse
  kafka:
    existingSecret: my-countly-kafka
  mongodb:
    existingSecret: my-countly-mongodb

Mode: externalSecret

Use External Secrets Operator to sync from external secret stores:

secrets:
  mode: externalSecret
  externalSecret:
    refreshInterval: "1h"
    secretStoreRef:
      name: my-secret-store
      kind: ClusterSecretStore
    remoteRefs:
      common:
        encryptionReportsKey: "acme-countly-encryption-reports-key"
        webSessionSecret: "acme-countly-web-session-secret"
        passwordSecret: "acme-countly-password-secret"
        # Optional SMTP auth refs:
        # mailConfigAuthUser: "my-smtp-auth-user-secret"
        # mailConfigAuthPass: "my-smtp-auth-pass-secret"
      clickhouse:
        password: "acme-countly-clickhouse-password"
      mongodb:
        password: "acme-mongodb-app-password"

Recommended naming convention:

  • <customer>-gar-dockerconfig
  • <customer>-countly-encryption-reports-key
  • <customer>-countly-web-session-secret
  • <customer>-countly-password-secret
  • <customer>-countly-clickhouse-password
  • <customer>-kafka-connect-clickhouse-password
  • <customer>-clickhouse-default-user-password
  • <customer>-mongodb-admin-password
  • <customer>-mongodb-app-password
  • <customer>-mongodb-metrics-password

Required Secrets

All secrets are required on first install. On upgrades, existing values are preserved automatically.

Chart Secret Key Purpose
countly common encryptionReportsKey Report encryption (min 8 chars)
countly common webSessionSecret Session cookie signing (min 8 chars)
countly common passwordSecret Password hashing (min 8 chars)
countly common mailConfigAuthUser Optional SMTP auth username
countly common mailConfigAuthPass Optional SMTP auth password
countly clickhouse password ClickHouse default user auth
countly mongodb password MongoDB app user auth, reuse the same GSM key as countly-mongodb.users.app.password
countly-mongodb users.app password Must match countly secrets.mongodb.password
countly-mongodb users.metrics password Prometheus exporter auth
countly-clickhouse auth.defaultUserPassword password Must match countly secrets.clickhouse.password
countly-kafka kafkaConnect.clickhouse password Must match ClickHouse password

Secret Rotation

  1. Update the password in your values files
  2. Change secrets.rotationId to trigger pod rollouts: 
    secrets:
  rotationId: "2026-03-08"
  3. Apply charts in order: ClickHouse -> Kafka -> Countly

Cross-Chart Password Consistency

The ClickHouse password must be identical across three charts:

  • countly.yaml -> secrets.clickhouse.password
  • clickhouse.yaml -> auth.defaultUserPassword.password
  • kafka.yaml -> kafkaConnect.clickhouse.password

For External Secrets / Secret Manager, use one shared secret name for all three references by default, for example acme-clickhouse-password.

The MongoDB password must match across two charts:

  • countly.yaml -> secrets.mongodb.password
  • mongodb.yaml -> users.app.password