Skip to main content

Configure your database

This guide will help you configure your database. Parameters here should not be changed after installation unless you know what you are doing, as it may result in data losses.

PostgreSQL#

You can use the provided database, or bring your own. Both can be used with any installation method (embedded cluster or existing cluster).

Embedded versus external#

The embedded PostgreSQL requires no additional configuration. It is great for testing and small-size instances. It does not provide high availability. For backups, refer to the backup page.

The external PostgreSQL requires having an external database set up (e.g. with RDS on AWS). This is the recommended setup for large-scale deployments. Scaling, high availability, and backups should be managed with the provider's tools.

Embedded configuration#

The embedded PostgreSQL is a PostgreSQL 13 running on a single pod.
The only configurable option is the size of the disk. The default value should be enough for most cases.

You may increase it after installation, but not decrease it.
See here for detailed procedure and prerequisites.

External configuration#

For an external PostgreSQL, you have the following configuration options:

  • Host: the IP or hostname for your PostgreSQL. Defaults to "postgres".
  • Port: the port on which PostgreSQL listens. Defaults to "5432".
  • Username: the user used to connect to the database. Required.
  • Password: the password used to connect to the database. Required.
  • Database: the name of the database to connect to. Defaults to "prm". The database must exist.

For scaling recommendations, refer to the hardware requirements for embedded clusters or existing clusters.

Helm-based installation#

Helm installation currently supports only external databases.
When installing via Helm, parameters will be passed via a YAML file. The following parameters must be set inline :

  • host
  • username if relevant
  • database
  • port (5432 will be used as default)

As for the password, it can either be set inside a Kubernetes secret, fetched from an external secret, or set inline like the other parameters. Using secrets should be preferred over setting sensitive parameters inline in values.

If you choose the first method, add a secret to your namespace, if it doesn't exist yet:

kubectl create secret generic postgresql-config-secret-name \    --from-literal=POSTGRES_PASSWORD=my_pg_password

If you intend to enable TLS for your PostgreSQL database, the secret containing the password should also contain the TLS information. Refer to the secret as the postgresql.existingSecret parameter. the key to the password in this secret should be set as postgresql.existingSecretKeys.password:

postgresql:  host: null  # PostgreSQL Database host name  username: null  # PostgreSQL Database username  database: null  # PostgreSQL database name  port: 5432  existingSecret: ""  existingSecretKeys:    password: "POSTGRES_PASSWORD"

If you choose the second method, your YAML file should contain this extract:

postgresql:  host: null  # PostgreSQL Database host name  username: null  # PostgreSQL Database username  database: null  # PostgreSQL database name  port: 5432  password: "my_pg_password"

Redis#

You can use the provided cache, or bring your own. Both can be used with any installation method (embedded cluster or existing cluster).

Type: embedded/external#

The embedded Redis requires no additional configuration. It is great for testing and small-size instances.
It does not provide high availability.
For backups, refer to the backup page.

The external Redis requires having an external cache set up (e.g. with Elasticache on AWS). This is the recommended setup for large-scale deployments.
Scaling, high availability, and backups should be managed with the provider's tools.

External configuration#

For an external Redis, you have the following configuration options:

  • Host: the IP or hostname for your Redis. Defaults to "redis".
  • Port: the port on which Redis listens. Defaults to "6379".
  • Username: the user used to connect to the cache. Can be left empty.
  • Password: the password used to connect to the cache. Required.
  • Use TLS: checkbox to specify how to communicate with Redis.

Helm-based installation#

Helm installation currently supports only external databases.
When installing via Helm, parameters will be passed via a YAML file.

You can pass the whole URL directly, or provide host, username, password and port individually. The URL will be composed in the following way:

redis(s)://$user:$password@$host:$port

Additionally, the password and url should be passed via a Kubernetes secret, though it is possible to pass them inline, or via an external secret. Using secrets should be preferred over setting sensitive parameters inline in values.

If you choose the first option, create a Kubernetes secret in your cluster containing either the URL or the password to your Redis, and refer to it as the existingSecret in your values file.

kubectl create secret generic redis-config-secret-name \    --from-literal=REDIS_PASSWORD=my_redis_password

If you intend to enable TLS for your Redis, the secret containing the password should also contain the TLS information.

Depending on your choices, your YAML file should contain one of:

Sensitive parameter in secret (preferred)Sensitive parameter inline
Url passed directly
redis:  main:    existingSecret: "custom-redis-secret"    existingSecretKeys:      url: "REDIS_URL"
redis:  main:    url: "url"
Url recomposed from elements
redis:  main:    user: "redis_user"    host: "123.456.789.123"    port: 6379    existingSecret: "custom-redis-secret"    existingSecretKeys:      password: "REDIS_PASSWORD"
redis:  main:    user: "redis_user"    host: "123.456.789.123"    port: 6379    password: "redis_password"

Second Redis instance for commit cache#

You can configure a second Redis instance that will be dedicated to the commit cache feature.

Commit cache allows better performances for both real-time and historical scans by keeping the results of commits already scanned in a cache.

You can configure a second Redis instance that will be dedicated to the commit cache feature. We only recommend this option for big instances (more than 100GB of code for the entire perimeter) where the commit cache should be configured with a minimum of 16GB.

This second Redis instance has the same configuration options as the main one.

On KOTS-based installations, you can access configuration options by checking the Commit cache Redis checkbox in the Redis section in the KOTS Admin Portal.

On Helm-based installations, you can configure this option under the redis.commitCache keys in your values file.