The module lifecycle stage: Generally available version

The module has requirements for installation

This page describes the minimum configuration that starts Deckhouse Development Portal (DDP) and the ways to connect PostgreSQL, Redis and ClickHouse. Before you start, check that the cluster meets the system requirements of the module.

Managed instances are recommended for demo installations; external instances are recommended for production. Internal instances are available as a separate installation option.

The postgres.mode, redis.mode and clickhouse.mode parameters are required and have no default value. Without them, installation and upgrade fail settings validation.

Installation with managed instances

In the managed mode, the module creates PostgreSQL, Valkey (Redis-compatible) and ClickHouse instances. Before installing DDP, the corresponding Deckhouse modules must be enabled in the cluster for each service with mode: managed:

DDP setting Module that must be enabled
postgres.mode: managed managed-postgres
redis.mode: managed managed-valkey
clickhouse.mode: managed managed-clickhouse

For the demo configuration below, enable all three modules using ModuleConfig:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: managed-postgres
spec:
  enabled: true
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: managed-valkey
spec:
  enabled: true
---
apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: managed-clickhouse
spec:
  enabled: true

If a required module is not enabled, DDP installation fails with an error naming the module to enable.

Enabling the module

To install DDP, enable the development-platform module with ModuleConfig. The minimum configuration sets the super administrator, the encryption key and the deployment mode of PostgreSQL, Redis and ClickHouse:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io # Email of the user with full access to the platform configuration. Can be changed at any time.
    security:
      secretKey: "16charssecretkey" # Key that encrypts stored credentials: 16, 24 or 32 printable ASCII characters. Replace the example value with your own key.
    postgres:
      mode: managed # Deployment mode: managed, external or internal. Required for postgres, redis and clickhouse.
    redis:
      mode: managed
    clickhouse:
      mode: managed

The web interface address is built from the publicDomainTemplate cluster parameter and the domain.prefix module parameter, ddp by default. For example, with publicDomainTemplate: "%s.example.com" the web interface opens at https://ddp.example.com. To use another domain, set the domain.useCustomDomain and domain.customDomain parameters. All parameters are listed in the module settings.

Configuring instance resources

With mode: managed, the connection host and port are resolved automatically. The host, port and image parameters are not used in this mode.

Set instance resources in instance.cpu, instance.memory and instance.persistentVolumeClaim. Select the class with instance.className, default by default; it defines allowed sizes and placement of the instance. Specify memory and disk sizes as Kubernetes quantities, such as 512Mi or 20Gi.

Example of PostgreSQL resource settings:

    postgres:
      mode: managed
      instance:
        className: default
        cpu:
          cores: 2
          coreFraction: 50          # For redis and clickhouse, a string, for example "50%"
        memory:
          size: 2Gi
        persistentVolumeClaim:
          size: 20Gi
          storageClassName: replicated  # Optional, the cluster default StorageClass is used by default

The disk size can only be increased, and only if the StorageClass supports volume expansion.

Installation with external instances

The postgres, redis and clickhouse sections switch each component to an external instance with mode: external. The sections are independent: you can connect only some of the components and set mode: internal or mode: managed for the rest.

Connecting external PostgreSQL

To use an external PostgreSQL instance, specify the connection parameters in the postgres section:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io
    security:
      secretKey: "16charssecretkey"
    postgres:
      mode: external
      host: postgres.example.com  # Hostname or IP address of the PostgreSQL server.
      port: 5432                  # PostgreSQL port.
      database: ddp               # Database name.
      username: ddp_user          # Username for the connection.
      password: secure_password   # Password for the connection.
    redis:
      mode: internal
    clickhouse:
      mode: internal

pg_trgm extension

DDP requires the PostgreSQL pg_trgm extension. For PostgreSQL deployed in the cluster, the module creates the extension automatically. For external PostgreSQL, create it before starting DDP: connect to the database as a user with the privilege to create extensions and run the command:

CREATE EXTENSION IF NOT EXISTS pg_trgm;

Connecting external Redis

To use an external Redis instance, specify the connection parameters in the redis section:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io
    security:
      secretKey: "16charssecretkey"
    postgres:
      mode: internal
    redis:
      mode: external
      host: redis.example.com       # Hostname or IP address of the Redis server.
      port: 6379                    # Redis port.
      database: "0"                 # Redis database index.
      password: redis_password      # Password for the connection. Leave empty if Redis has no password.
    clickhouse:
      mode: internal

Connecting external ClickHouse

ClickHouse stores the historical data of the platform, such as the history of entity property changes. To run without the features that require ClickHouse, set mode: external and leave host empty. The rest of the platform works without changes.

To use an external ClickHouse instance, specify the connection parameters in the clickhouse section:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io
    security:
      secretKey: "16charssecretkey"
    postgres:
      mode: internal
    redis:
      mode: internal
    clickhouse:
      mode: external
      host: clickhouse.example.com  # Hostname or IP address of the ClickHouse server.
      port: 9000                    # ClickHouse native protocol port.
      database: ddp                 # Database name.
      username: ddp_user            # Username for the connection.
      password: secure_password     # Password for the connection.

Creating the ClickHouse database

DDP applies schema migrations to the database from the database parameter but does not create the database itself.

With mode: managed, the module creates the database automatically.

With mode: external, create the database before starting DDP:

CREATE DATABASE IF NOT EXISTS ddp;

With mode: internal, the module creates the database on the first start with an empty ClickHouse volume. If the volume already contains data, for example after a restore from a backup, or if you change the database parameter, create the database manually. Replace ddp with the value of the database parameter:

d8 k -n d8-development-platform exec clickhouse-0 -c clickhouse -- \
  sh -c 'clickhouse-client --user "$CLICKHOUSE_USER" --password "$CLICKHOUSE_PASSWORD" --query "CREATE DATABASE IF NOT EXISTS ddp"'

Complete example with external instances

Example configuration with connections to external PostgreSQL, Redis and ClickHouse instances:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io
    security:
      secretKey: "16charssecretkey"
    postgres:
      mode: external
      host: postgres.production.example.com
      port: 5432
      database: ddp
      username: ddp_user
      password: secure_postgres_password
    redis:
      mode: external
      host: redis.production.example.com
      port: 6379
      database: "0"
      password: secure_redis_password
    clickhouse:
      mode: external
      host: clickhouse.production.example.com
      port: 9000
      database: ddp
      username: ddp_user
      password: secure_clickhouse_password

Installation with internal instances

With mode: internal, the module deploys PostgreSQL, Redis and ClickHouse in the cluster. Explicitly select this mode for each service:

apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io # Email of the user with full access to the platform configuration. Can be changed at any time.
    security:
      secretKey: "16charssecretkey" # Key that encrypts stored credentials: 16, 24 or 32 printable ASCII characters. Replace the example value with your own key.
    postgres:
      mode: internal # Deployment mode: internal, external or managed. Required for postgres, redis and clickhouse.
    redis:
      mode: internal
    clickhouse:
      mode: internal

Installing PostgreSQL, Redis and ClickHouse from a private registry

With mode: internal, the module deploys PostgreSQL, Redis and ClickHouse in the cluster from public images. To pull the images from a private container registry:

  1. Create a Secret of the kubernetes.io/dockerconfigjson type with the registry credentials in the d8-development-platform namespace.

  2. Set the images in the image parameters and the Secret name in the additionalImagePullSecrets parameter:

    apiVersion: deckhouse.io/v1alpha1
kind: ModuleConfig
metadata:
  name: development-platform
spec:
  enabled: true
  version: 2
  settings:
    rbac:
      superAdminEmail: admin@deckhouse.io
    security:
      secretKey: "16charssecretkey"
    postgres:
      mode: internal
      image: registry.example.com/postgres:16.3
    redis:
      mode: internal
      image: registry.example.com/redis:7.4.0
    clickhouse:
      mode: internal
      image: registry.example.com/clickhouse/clickhouse-server:24.3
    additionalImagePullSecrets:
      - custom-registry-secret

Changing the encryption key

DDP encrypts stored credentials with the key from the security.secretKey parameter. If you replace the key in ModuleConfig without re-encryption, DDP cannot decrypt the saved credentials.

To change the key:

  1. In the DDP web interface, open “Administration” → “Credentials” and click “Rotate encryption key”. The button is available to users with the permission to rotate the encryption key.
  2. Enter the current key in “Old encryption key” and the new key in “New encryption key”, then click “Re-encrypt”.
  3. Check that the result table has no records in the “Failed” column.
  4. Set the new key in the security.secretKey parameter of ModuleConfig development-platform. The DDP pods restart automatically.

Stored credentials are unavailable between re-encryption and the pod restart with the new key. Changing the key invalidates current user sessions.