---
metadata:
  - name: generator
    content: Diplodoc Platform v5.63.0
alternate:
  - en/concepts/secrets-instance
  - href: en/concepts/secrets-instance.md
    type: text/markdown
    title: Markdown version
csp:
  - script-src:
      - https://mc.yandex.ru
    img-src:
      - https://mc.yandex.ru
    connect-src:
      - https://mc.yandex.ru
      - wss://mc.yandex.ru
    child-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-src:
      - 'blob:'
      - https://mc.yandex.ru
    frame-ancestors:
      - 'blob:'
      - https://mc.yandex.ru
canonical: en/concepts/secrets-instance.html
title: Secrets DataLens On-premises
description: >-
  This section describes all the secrets used during DataLens On-premises
  deployment.
vcsPath: en/concepts/secrets-instance.md
---

# Secrets DataLens On-premises

This document describes all the secrets used during DataLens On-premises deployment.

You can set secrets in two ways:

1. Via properties in the `values.yaml` [file](./create-instance.md#values-parameters) (recommended for first deployment).
1. Via an external [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/), with a link in `secrets.ref`.

When using the `./init.sh` script, secrets are generated automatically on first [deployment](./create-instance.md#enterprise-deployment) and stored in the Kubernetes cluster secrets.

## Classification of secrets based on requirement {#classification-by-required}

### 🔴 Required secrets (RSA authentication keys) {#required}

These secrets are required when authentication is enabled (`features.auth.enabled: true`, enabled by default).

| Secret | Autogeneration | Format | Description |
|--------|---------------|--------|----------|
| `AUTH_TOKEN_PRIVATE_KEY` | ✅ On first deployment | RSA 4096-bit PEM | Private key for signing JWT authentication tokens |
| `AUTH_TOKEN_PUBLIC_KEY` | ✅ On first deployment | RSA 4096-bit PEM | Public key for verifying JWT tokens |

{% note info %}

When using `./init.sh`, these keys are generated automatically. To regenerate, use the `--auth-rsa-gen` flag.

{% endnote %}

### 🟡 Conditionally required secrets {#cond-required}

#### Secrets for Temporal (workbook import or export) {#secret-temporal}

These secrets are required when you enable one of the following features:

* `features.meta_manager.enabled: true`
* `features.export.enabled: true`
* `features.usage_tracking.enabled: true`

| Secret | Autogeneration | Format | Description |
|--------|---------------|--------|----------|
| `TEMPORAL_AUTH_PRIVATE_KEY` | ✅ On first deployment | RSA 4096-bit PEM | Private key for authentication in Temporal |
| `TEMPORAL_AUTH_PUBLIC_KEY` | ✅ On first deployment | RSA 4096-bit PEM | Public key for authentication in Temporal |

{% note info %}

To regenerate, use the `--temporal-rsa-gen` flag.

{% endnote %}

#### Secret for a private Docker image registry {#secret-docker}

| Secret | Autogeneration | Format | When it is required |
|--------|---------------|--------|------------------|
| `DOCKER_CONFIG_JSON` | ❌ | JSON (docker config) | If `registry.private: true` and `registry.docker_config.secret.ref` is not specified |

### 🟢 Autogenerated secrets {#secret-auto-generated}

These secrets are autogenerated on first deployment unless explicitly specified. The values ​​are stored in Kubernetes secrets and reused in subsequent deployments.

#### Authentication and security secrets {#secret-auth-security}

| Secret | Length | Format | Description |
|--------|-------|--------|----------|
| `AUTH_ADMIN_PASSWORD` | 32 characters | alphanumeric | System administrator password (`admin`) |
| `AUTH_CALLBACK_COOKIE_SECRET` | 32 characters | alphanumeric | Cookie encryption key for authentication callbacks |
| `CSRF_SECRET` | 16 characters | alphanumeric | CSRF token generation key for protection against CSRF attacks |

#### Cross-service communication master tokens {#secret-token}

| Secret | Length | Format | Description |
|--------|-------|--------|----------|
| `AUTH_MASTER_TOKEN` | 32 characters | alphanumeric | Authorization token for requests to authentication service |
| `US_MASTER_TOKEN` | 32 characters | alphanumeric | Authorization token for requests to United Storage |
| `FILE_UPLOADER_MASTER_TOKEN` | 32 characters | alphanumeric | Authorization token for requests to file upload service |

#### Encryption keys {#encryption-keys}

| Secret | Length | Format | Description |
|--------|-------|--------|----------|
| `CONTROL_API_CRYPTO_KEY` | 32 characters | base64(alphanumeric) | Encryption key for confidential connection data (passwords, tokens) |
| `EXPORT_DATA_VERIFICATION_KEY` | 32 characters | alphanumeric | Data integrity verification key for workbook import and export |

#### PostgreSQL passwords {#postgres-passwords}

| Secret | Length | Description |
|--------|-------|----------|
| `POSTGRES_PASSWORD_ROOT` | 32 characters | PostgreSQL superuser password |
| `POSTGRES_PASSWORD_US` | 32 characters | United Storage DB password (metadata) |
| `POSTGRES_PASSWORD_COMPENG` | 32 characters | Computation engine DB password |
| `POSTGRES_PASSWORD_AUTH` | 32 characters | Authentication service DB password |
| `POSTGRES_PASSWORD_TEMPORAL` | 32 characters | Temporal DB password |
| `POSTGRES_PASSWORD_META_MANAGER` | 32 characters | Meta Manager DB password |
| `POSTGRES_PASSWORD_DEMO` | 32 characters | Demo database password |

#### Infrastructure component passwords {#mdb-passwords}

| Secret | Length | When is it used | Description |
|--------|-------|-------------------|----------|
| `CLICKHOUSE_PASSWORD` | 32 characters by default | If `features.files.enabled` or `features.usage_tracking.enabled` | ClickHouse® user password |
| `REDIS_PASSWORD` | 64 characters by default | If `features.files.enabled`, `features.cache.enabled`, or `features.background_exports.enabled` | Valkey™ password |
| `S3_ACCESS_KEY_ID` | strictly 32 characters | If `features.files.enabled` or `features.background_exports.enabled` | Access key ID for S3 (MinIO) |
| `S3_SECRET_ACCESS_KEY` | strictly 64 characters | If `features.files.enabled` or `features.background_exports.enabled` | Secret access key for S3 (MinIO) |

### ⚪ Optional secrets {#secret-optional}

| Secret | Format | Description |
|--------|--------|----------|
| `AUTH_PROVIDERS_CONFIG` | JSON array | Configuration of external authentication providers (LDAP, OIDC). The default value is an empty array (`[]`). |
| `secrets.ref` | string | Link to an existing Kubernetes secret to use instead of creating a new one |


## Example YAML configuration {#yaml-example}

```yaml
secrets:
  ref: null                              # Link to an external Kubernetes secret
  #
  # === RSA authentication keys (required) ===
  AUTH_TOKEN_PRIVATE_KEY: null           # Generated automatically on first deployment
  AUTH_TOKEN_PUBLIC_KEY: null            # Generated automatically on first deployment
  AUTH_PROVIDERS_CONFIG: null            # JSON array of providers (optional)
  AUTH_ADMIN_PASSWORD: null              # The admin password (generated automatically)
  AUTH_CALLBACK_COOKIE_SECRET: null      # Generated automatically
  #
  # === Security ===
  CSRF_SECRET: null                      # Generated automatically
  #
  # === Master tokens ===
  AUTH_MASTER_TOKEN: null                # Generated automatically
  US_MASTER_TOKEN: null                  # Generated automatically
  FILE_UPLOADER_MASTER_TOKEN: null       # Generated automatically
  EXPORT_DATA_VERIFICATION_KEY: null     # Generated automatically
  #
  # === Encryption keys ===
  CONTROL_API_CRYPTO_KEY: null           # Generated automatically
  #
  # === Docker Registry ===
  DOCKER_CONFIG_JSON: null               # Required if registry.private: true
  #
  # === PostgreSQL ===
  POSTGRES_PASSWORD_ROOT: null           # Generated automatically
  POSTGRES_PASSWORD_US: null             # Generated automatically
  POSTGRES_PASSWORD_COMPENG: null        # Generated automatically
  POSTGRES_PASSWORD_AUTH: null           # Generated automatically
  POSTGRES_PASSWORD_TEMPORAL: null       # Generated automatically
  POSTGRES_PASSWORD_META_MANAGER: null   # Generated automatically
  POSTGRES_PASSWORD_DEMO: null           # Generated automatically
  #
  # === Temporal RSA keys (for import/export) ===
  TEMPORAL_AUTH_PRIVATE_KEY: null        # Generated if features.export is enabled
  TEMPORAL_AUTH_PUBLIC_KEY: null         # Generated if features.export is enabled
  #
  # === Infrastructure components ===
  CLICKHOUSE_PASSWORD: null              # Generated automatically
  REDIS_PASSWORD: null                   # Generated automatically
  S3_ACCESS_KEY_ID: null                 # Generated automatically
  S3_SECRET_ACCESS_KEY: null             # Generated automatically
```

## Detailed description of secrets {#secret-detailed}

| Parameter | Type | Default value | Requirement | Description |
|----------|-----|----------------------|----------------|----------|
| `secrets.ref` | string | `null` | ❌ Optional (required if using ArgoCD). | Link to an external Kubernetes secret. When specified, other secrets are ignored. |
| `secrets.AUTH_TOKEN_PRIVATE_KEY` | string | `null` | 🔴 Required | RSA private key (4096-bit, PEM) for signing JWT authentication tokens |
| `secrets.AUTH_TOKEN_PUBLIC_KEY` | string | `null` | 🔴 Required | RSA public key (4096-bit, PEM) for verifying JWT tokens |
| `secrets.AUTH_PROVIDERS_CONFIG` | string | `[]` | ❌ Optional | Configuration of authentication providers in JSON format. Read more in `./help/auth-provider-config.example.json`. |
| `secrets.AUTH_ADMIN_PASSWORD` | string | autogeneration | ✅ Autogeneration | Admin password. Get: `./init.sh --get-admin-password` |
| `secrets.AUTH_CALLBACK_COOKIE_SECRET` | string | autogeneration | ✅ Autogeneration | Cookie encryption key for OAuth/OIDC callbacks |
| `secrets.CSRF_SECRET` | string | autogeneration | ✅ Autogeneration | CSRF token encryption key for form protection |
| `secrets.AUTH_MASTER_TOKEN` | string | autogeneration | ✅ Autogeneration | Master token for cross-service requests to auth service |
| `secrets.US_MASTER_TOKEN` | string | autogeneration | ✅ Autogeneration | Master token for cross-service requests to United Storage |
| `secrets.FILE_UPLOADER_MASTER_TOKEN` | string | autogeneration | ✅ Autogeneration | Master token for cross-service requests to file-uploader |
| `secrets.EXPORT_DATA_VERIFICATION_KEY` | string | autogeneration | ✅ Autogeneration | Data integrity check key for import and export |
| `secrets.CONTROL_API_CRYPTO_KEY` | string | autogeneration | ✅ Autogeneration | Encryption key for confidential connection data (base64) |
| `secrets.DOCKER_CONFIG_JSON` | string | `{}` | 🟡 Conditionally | Configuration of access to a private Docker image registry. Format: Docker config JSON |
| `secrets.POSTGRES_PASSWORD_ROOT` | string | autogeneration | ✅ Autogeneration | PostgreSQL root user password |
| `secrets.POSTGRES_PASSWORD_US` | string | autogeneration | ✅ Autogeneration | United Storage DB password |
| `secrets.POSTGRES_PASSWORD_COMPENG` | string | autogeneration | ✅ Autogeneration | Computation engine DB password |
| `secrets.POSTGRES_PASSWORD_AUTH` | string | autogeneration | ✅ Autogeneration | Authentication service DB password |
| `secrets.POSTGRES_PASSWORD_TEMPORAL` | string | autogeneration | ✅ Autogeneration | Temporal DB password |
| `secrets.POSTGRES_PASSWORD_META_MANAGER` | string | autogeneration | ✅ Autogeneration | Meta Manager DB password |
| `secrets.POSTGRES_PASSWORD_DEMO` | string | autogeneration | ✅ Autogeneration | Demo database password |
| `secrets.TEMPORAL_AUTH_PRIVATE_KEY` | string | `null` | 🟡 Conditionally | RSA private key for Temporal. Required if `features.export.enabled` |
| `secrets.TEMPORAL_AUTH_PUBLIC_KEY` | string | `null` | 🟡 Conditionally | RSA public key for Temporal. Required if `features.export.enabled` |
| `secrets.CLICKHOUSE_PASSWORD` | string | autogeneration | ✅ Autogeneration | ClickHouse® user password |
| `secrets.REDIS_PASSWORD` | string | autogeneration | ✅ Autogeneration | Valkey™ password |
| `secrets.S3_ACCESS_KEY_ID` | string | autogeneration | ✅ Autogeneration | Access key ID for S3-compatible storage |
| `secrets.S3_SECRET_ACCESS_KEY` | string | autogeneration | ✅ Autogeneration | Secret access key for S3-compatible storage |

## Manual generation of RSA keys {#rsa-key-generation}

If you need to generate RSA keys manually, use the following commands:

```bash
# Generating a private key (4096 bit)
openssl genpkey -algorithm RSA -pkeyopt "rsa_keygen_bits:4096" -out private.pem

# Extracting a public key
openssl rsa -in private.pem -pubout -out public.pem

# Viewing content to insert into values.yaml
cat private.pem
cat public.pem
```

When specifying in `values.yaml`, use the multi-line YAML format:

```yaml
secrets:
  AUTH_TOKEN_PRIVATE_KEY: |
    -----BEGIN PRIVATE KEY-----
    MIIJQgIBADANBgkqhkiG9w0BAQEFAASCCSwwggkoAgEAAoICAQC...
    ...
    -----END PRIVATE KEY-----
  AUTH_TOKEN_PUBLIC_KEY: |
    -----BEGIN PUBLIC KEY-----
    MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA...
    ...
    -----END PUBLIC KEY-----
```

## DOCKER_CONFIG_JSON format {#docker-config-json}

Example configuration for a private registry:

```json
{
  "auths": {
    "registry.example.com": {
      "username": "user",
      "password": "password",
      "auth": "base64(user:password)"
    }
  }
}
```

For details, see the example in the `./help/docker-config.example.json` file.

---

## Using an external Kubernetes secret {#external-secret}

If secrets already exist in the Kubernetes cluster, provide a link to the secret:

```yaml
secrets:
  ref: my-existing-secret
```

In which case all other values ​​in the `secrets` section will be ignored, and the system will use the values ​​from the specified Kubernetes secret.

The external secret must contain all the necessary keys with relevant names.

## Secret rotation {#secret-rotation}

There is no automatic rotation of secrets. Secrets are preserved between updates thanks to the `lookup` mechanism in the [Helm chart](https://helm.sh/docs/topics/charts/) that reuses existing values ​​from Kubernetes secrets.

Where necessary, rotation is performed manually with due regard to consequences for each secret type.

### Classification based on rotation capability {#classification-by-rotation}

| Category | Rotation capability | Consequences |
|-----------|---------------------|-------------|
| 👮 Safe rotation | Ready for rotation | Minimal impact on system operation |
| 🟡 Rotation with consequences | Ready for rotation | There are side effects to consider |
| 🔴 Rotation not possible | Not recommended | Causes data loss or malfunction |

### 🟢 Secrets with safe rotation {#safe-rotation}

You can rotate these secrets without significant consequences. Following rotation, pods must be restarted.

| Secret | Rotation procedure | Consequences |
|--------|-------------------|-------------|
| `AUTH_CALLBACK_COOKIE_SECRET` | Change in values.yaml and run `helm upgrade` | OAuth/OIDC callbacks will be invalidated during authentication |
| `DOCKER_CONFIG_JSON` | Change in values.yaml and run `helm upgrade` | No impact on running pods |
| `AUTH_PROVIDERS_CONFIG` | Change in values.yaml and run `helm upgrade` | No impact (provider configuration) |
| `EXPORT_DATA_VERIFICATION_KEY` | Change in values.yaml and run `helm upgrade` | Previously exported workbooks will be imported with a warning |

### 🟡 Secrets with rotation and consequences {#unsafe-rotation}

You can rotate these secrets; however, it will cause some side effects.

| Secret | Rotation procedure | Consequences |
|--------|-------------------|-------------|
| `AUTH_TOKEN_PRIVATE_KEY` / `AUTH_TOKEN_PUBLIC_KEY` | `./init.sh --auth-rsa-gen` | ⚠️ All active user sessions will be invalidated. Users will be required to re-login |
| `CSRF_SECRET` | Change in values.yaml and run `helm upgrade` | ⚠️ Data requests will return errors until the upgrade is complete |
| `TEMPORAL_AUTH_PRIVATE_KEY` / `TEMPORAL_AUTH_PUBLIC_KEY` | `./init.sh --temporal-rsa-gen` | ⚠️ Temporal tasks in progress may fail with an error. We recommend to wait until all tasks are completed before rotating |
| `AUTH_MASTER_TOKEN` | Change in values.yaml and run `helm upgrade` | ⚠️ Temporary unavailability of the authentication service until all dependent pods are restarted |
| `US_MASTER_TOKEN` | Change in values.yaml and run `helm upgrade` | ⚠️ Temporary unavailability of United Storage until all dependent pods are restarted |
| `FILE_UPLOADER_MASTER_TOKEN` | Change in values.yaml and run `helm upgrade` | ⚠️ Temporary unavailability of file uploads until all pods are restarted |

### 🔴 Secrets not recommended for rotation {#not-recommended-rotation}

Rotating these secrets without further action causes data loss or system malfunction.

| Secret | Why not to rotate | What to do if compromised |
|--------|--------------------------|------------------------------|
| `AUTH_ADMIN_PASSWORD` | 🚫 The administrator password can be changed only through the DataLens interface |  |
| `CONTROL_API_CRYPTO_KEY` | 🚫 Used to encrypt passwords and tokens in connections to data sources. If you change the key, all existing connections will become unreadable | Can be recreated by restoring from a backup |
| `POSTGRES_PASSWORD_*` | 🚫 Passwords are used both in the application and the database. Changing them only in the secrets will cause connection errors | You need to change the passwords in PostgreSQL and the secrets in a synchronized manner. When using the built-in PostgreSQL, it is a complex procedure with downtime |
| `CLICKHOUSE_PASSWORD` | 🚫 Similarly to PostgreSQL, the password must match in the database and the secrets. | Synchronized change in ClickHouse® and the secrets |
| `REDIS_PASSWORD` | 🚫 Similarly, the password must match in Valkey™ and the secrets. | Synchronized change in Valkey™ and the secrets |
| `S3_ACCESS_KEY_ID` / `S3_SECRET_ACCESS_KEY` | 🚫 Credentials must match the S3/MinIO settings | Synchronized change in S3 and the secrets |

In addition, when updating database passwords, you can create a new user and password with similar access permissions and migrate the workload to it without downtime.

### RSA authentication key rotation procedure {#rsa-auth-rotation}

```bash
# 1. (Optional) Warn users to re-login

# 2. Generate new keys and run an update
./init.sh --auth-rsa-gen

# 3. Make sure all pods have restarted
./init.sh --kubectl get pods

# 4. Check that authentication is working
```

### Master token rotation procedure {#token-rotation}

```bash
# 1. Prepare new token values ​​(32 characters, alphanumeric)
NEW_TOKEN=$(openssl rand -base64 32 | tr -dc 'a-zA-Z0-9' | head -c 32)

# 2. Create or update values.yaml with new values
# secrets:
#   US_MASTER_TOKEN: "<new token>"

# 3. Perform an update
./init.sh --values ./my-values.yaml

# 4. Make sure all pods have restarted
./init.sh --kubectl rollout status deployment --timeout=300s
```

### Database password rotation procedure (built-in PostgreSQL) {#password-rotation}

{% note warning %}

This procedure requires downtime. Perform it with extreme caution.

{% endnote %}

```bash
# 1. Create a backup
./init.sh --dump-postgres

# 2. Connect to PostgreSQL
./init.sh --pg-sql

# 3. Change user password in PostgreSQL
ALTER USER "pg-us-user" WITH PASSWORD 'new_password';

# 4. Update the secret in values.yaml
# secrets:
#   POSTGRES_PASSWORD_US: "new_password"

# 5. Perform an update
./init.sh --values ./my-values.yaml

# 6. Restart the pods using this password
./init.sh --kubectl rollout restart deployment
```

---

### Security recommendations {#recommendations}

* Keep your secrets secure: use external secret management systems (HashiCorp Vault, Yandex Lockbox) and refer to them via `secrets.ref`.
* Do not rotate `CONTROL_API_CRYPTO_KEY` unless you have to. Doing so will break existing connections. Seamless rotation is currently not supported.
* Schedule your rotation for low-load periods, because rotating some of the secrets involves restarting the services.
* Create backups prior to rotation, especially before you change your database passwords.


## Useful commands {#commands}

```bash
# To get the administrator password
./init.sh --get-admin-password

# To generate new RSA keys for authentication
./init.sh --auth-rsa-gen

# To generate new RSA keys for Temporal
./init.sh --temporal-rsa-gen

# To specify the authentication provider configuration file
./init.sh --auth-providers-config ./my-auth-config.json

# To create a PostgreSQL backup prior to rotation
./init.sh --dump-postgres

# To check pod statuses after rotation
./init.sh --kubectl get pods

# To view logs to diagnose issues
./init.sh --stern .
```

<!-- source: en/_includes/clickhouse-disclaimer.md -->
_ClickHouse® is a registered trademark of [ClickHouse, Inc](https://clickhouse.com)._
<!-- endsource: en/_includes/clickhouse-disclaimer.md -->