proc-configuring-postgresql-instance-using-the-operator.adoc

Configuring an external PostgreSQL instance using the Operator

You can configure an external PostgreSQL instance using the {product} Operator. By default, the Operator creates and manages a local instance of PostgreSQL in the same namespace where you have deployed the {product-very-short} instance. However, you can change this default setting to configure an external PostgreSQL database server, for example, Amazon Web Services (AWS) Relational Database Service (RDS) or Azure database.

Prerequisites

• You meet the {about-book-link}#rhdh-sizing_about-rhdh[Sizing requirements for external PostgreSQL deployments].

• You are using a supported version of PostgreSQL. For more information, see the Product life cycle page.

• You have the following details:

  • db-host: Denotes your PostgreSQL instance Domain Name System (DNS) or IP address

  • db-port: Denotes your PostgreSQL instance port number, such as 5432

  • username: Denotes the user name to connect to your PostgreSQL instance

  • password: Denotes the password to connect to your PostgreSQL instance

• You have installed the {product} Operator.

• Optional: You have a CA certificate, Transport Layer Security (TLS) private key, and TLS certificate so that you can secure your database connection by using the TLS protocol. For more information, refer to your PostgreSQL vendor documentation.

Note	By default, {product-short} uses a database for each plugin and automatically creates it if none is found. You might need the Create Database privilege in addition to PSQL Database privileges for configuring an external PostgreSQL instance.

Procedure

1. Optional: Create a certificate secret to configure your PostgreSQL instance with a TLS connection:

   $ cat <<EOF | oc -n {my-product-namespace} create -f -
   apiVersion: v1
   kind: Secret
   metadata:
    name: {my-product-database-certificates-secrets} (1)
   type: Opaque
   stringData:
    postgres-ca.pem: |-
     -----BEGIN CERTIFICATE-----
     <ca-certificate-key> (2)
    postgres-key.key: |-
     -----BEGIN CERTIFICATE-----
     <tls-private-key> (3)
    postgres-crt.pem: |-
     -----BEGIN CERTIFICATE-----
     <tls-certificate-key> (4)
     # ...
   EOF

   1. Provide the name of the certificate secret.

   2. Provide the CA certificate key.

   3. Optional: Provide the TLS private key.

   4. Optional: Provide the TLS certificate key.

2. Create a credential secret to connect with the PostgreSQL instance:

   $ cat <<EOF | oc -n {my-product-namespace} create -f -
   apiVersion: v1
   kind: Secret
   metadata:
    name: {my-product-database-secrets} (1)
   type: Opaque
   stringData: (2)
    POSTGRES_PASSWORD: <password>
    POSTGRES_PORT: "<db-port>"
    POSTGRES_USER: <username>
    POSTGRES_HOST: <db-host>
    PGSSLMODE: <ssl-mode> # for TLS connection (3)
    NODE_EXTRA_CA_CERTS: <abs-path-to-pem-file> # for TLS connection, e.g. /opt/app-root/src/postgres-crt.pem (4)
   EOF

   1. Provide the name of the credential secret.

   2. Provide credential data to connect with your PostgreSQL instance.

   3. Optional: Provide the value based on the required Secure Sockets Layer (SSL) mode.

   4. Optional: Provide the value only if you need a TLS connection for your PostgreSQL instance.

      ../shared/snip-create-kubernetes-service-for-external-postgresql.adoc

3. Optional: Ensure your external PostgreSQL instance is configured with recommended performance tuning parameters.

   Set shared_buffers to approximately 1/4 and effective_cache_size to approximately 1/2 of the allocated database memory.

4. Create your {product-custom-resource-type} custom resource (CR):

   cat <<EOF | oc -n {my-product-namespace} create -f -
   apiVersion: rhdh.redhat.com/v1alpha3
   kind: Backstage
   metadata:
     name: <backstage-instance-name>
   spec:
     database:
       enableLocalDb: false (1)
     application:
       extraFiles:
         mountPath: <path> # e g /opt/app-root/src
         secrets:
           - name: {my-product-database-certificates-secrets} (2)
             key: postgres-crt.pem, postgres-ca.pem, postgres-key.key # key name as in {my-product-database-certificates-secrets} Secret
       extraEnvs:
         secrets:
           - name: {my-product-database-secrets} (3)
           # ...

   1. Set the value of the enableLocalDb parameter to false to disable creating local PostgreSQL instances.

   2. Provide the name of the certificate secret if you have configured a TLS connection.

   3. Provide the name of the credential secret that you created.

      Note	The environment variables listed in the Backstage CR work with the Operator default configuration. If you have changed the Operator default configuration, you must reconfigure the Backstage CR accordingly.

5. Apply the {product-custom-resource-type} CR to the namespace where you have deployed the {product-short} instance.