External database setup

The PostgreSQL database is used by the Che server for persisting data about the state of Che. It contains information about user accounts, workspaces, preferences, and other details.

By default, the Che Operator creates and manages the database deployment.

However, the Che Operator does not support full life-cycle capabilities, such as backups and recovery.

For a business-critical setup, configure an external database with the following recommended disaster-recovery options:

  • High Availability (HA)

  • Point In Time Recovery (PITR)

Configure an external PostgreSQL instance on-premises or use a cloud service, such as Amazon Relational Database Service (Amazon RDS). With Amazon RDS, it is possible to deploy production databases in a Multi-Availability Zone configuration for a resilient disaster recovery strategy with daily and on-demand snapshots.

The recommended configuration of the example database is:

Parameter Value

Instance class

db.t2.small

vCPU

1

RAM

2 GB

Multi-az

true, 2 replicas

Engine version

9.6.11

TLS

enabled

Automated backups

enabled (30 days)

Configuring external PostgreSQL

By configuring the external PostgreSQL, you can make the workspace metadata and the user information persistent.

Procedure
  1. Define the values of the following placeholders:

    • <database-user> is the Che server database user name

    • <database-password> is the Che server database password

    • <database> is the Che server database name

  2. Use the following SQL script to create a user and a database for the Che server to make workspace metadata persistent:

    CREATE USER <database-user> WITH PASSWORD '<database-password>'
    CREATE DATABASE <database>
    GRANT ALL PRIVILEGES ON DATABASE <database> TO <database-user>
    ALTER USER <database-user> WITH SUPERUSER
  3. Define the value of the following placeholder:

    • <identity-database-password> is the Keycloak database password

  4. Use the following SQL script to create a database for the Keycloak back end to make the user information persistent:

    CREATE USER keycloak WITH PASSWORD '<identity-database-password>'
    CREATE DATABASE keycloak
    GRANT ALL PRIVILEGES ON DATABASE keycloak TO keycloak

Configuring Che to work with an external PostgreSQL

Prerequisites
  • The kubectl tool is available.

Procedure
  1. Pre-create a namespace for Che:

    $ kubectl create namespace eclipse-che
  2. Create a secret to store Che server database credentials:

    $ kubectl create secret generic <server-database-credentials> \ (1)
    --from-literal=user=<database-user> \ (2)
    --from-literal=password=<database-password> \ (3)
    -n eclipse-che
    1 Secret name to store Che server database credentials
    2 Che server database username
    3 Che server database password
  3. Add the required labels to the Che server database credentials secret:

    $ kubectl label secret <server-database-credentials> \ (1)
     app.kubernetes.io/part-of=che.eclipse.org -n eclipse-che
    1 Secret name to store Che server database credentials
  4. Create a secret to store Keycloak database credentials:

    $ kubectl create secret generic <identity-database-credentials> \ (1)
    --from-literal=password=<identity-database-password> \ (2)
    -n eclipse-che
    1 Secret name to store Keycloak database credentials
    2 Keycloak database password
  5. Add the required labels to the Keycloak database credentials secret:

    $ kubectl label secret <identity-database-credentials> \ (1)
    app.kubernetes.io/part-of=che.eclipse.org -n eclipse-che
    1 Secret name to store Keycloak database credentials
  6. Deploy Eclipse Che by executing the chectl command with applying a patch. For example:

    $ chectl server:deploy --che-operator-cr-patch-yaml=patch.yaml ...

patch.yaml should contain the following to make the Operator skip deploying a database and pass connection details of an existing database to a Che server:

spec:
  database:
    externalDb: true
    chePostgresHostName: <hostname>                     (1)
    chePostgresPort: <port>                             (2)
    chePostgresSecret: <server-database-credentials>    (3)
    chePostgresDb: <database>                           (4)
spec:
  auth:
    identityProviderPostgresSecret: <identity-database-credentials> (5)
1 External database host name
2 External database port
3 Secret name with Che server database credentials
4 Che server database name
5 Secret name with Keycloak database credentials
Additional resources