Deploy Production PostgreSQL

Hydrolix provisions a single internal PostgreSQL pod to store the catalog. This default configuration has no high availability or automated backups and isn't suitable for production.

For production deployments, choose an option:

• CloudNativePG: Manages a high-availability PostgreSQL cluster inside the EKS cluster. Best for deployments that keep all components in Kubernetes and back up to object storage.
• Amazon RDS: A fully managed PostgreSQL service in AWS. Best for deployments that prefer an externally managed database with AWS-native backups and maintenance.

New deployments don't require migration

For new Hydrolix installations, complete all steps on this page after deploying the Operator and HydrolixCluster resource, but before ingesting any data. The Operator creates the required databases, users, and permissions on the external or CNPG instance. No migration is needed.

Existing deployments require migration

Switching an existing deployment from the internal PostgreSQL pod to an external database requires a catalog migration. Catalog loss can lead to data becoming unrecoverable. Contact Hydrolix support and review Migrate to External PostgreSQL before proceeding.

Prerequisites

• A Hydrolix deployment on EKS. See Deploy Hydrolix on EKS.
• kubectl configured to access the EKS cluster.

For Amazon RDS, also:

• AWS CLI installed and authenticated with permission to create RDS instances in the EKS account and region.

Deploy high-availability PostgreSQL in Kubernetes

Use CloudNativePG (CNPG) to manage a high-availability PostgreSQL cluster in Kubernetes. CNPG is external to Hydrolix. Alternatively, set up an RDS instance in the same account as the EKS cluster.

1. Install the CNPG operator. See Installation and upgrades - CloudNativePG for instructions.

2. Create a catalog.yaml file with this minimal configuration:

   apiVersion: postgresql.cnpg.io/v1
   kind: Cluster
   metadata:
     name: catalog
     namespace: {namespace}
   spec:
     backup: {backup}      # -- Specify the object storage path here
     bootstrap:
       initdb:
         database: catalog
         owner: query_api
     enableSuperuserAccess: true
     imageName: ghcr.io/cloudnative-pg/postgresql:15.12
     instances: 3
     primaryUpdateMethod: switchover
     storage:
       size: 100Gi
   

   • backup: Specify an object storage path for archiving Write-Ahead Logging (WAL) files and backups. See Appendix C - Common object stores for backups - CloudNativePG for supported options.
   • owner: query_api: The PostgreSQL role that owns the catalog database. Hydrolix uses this role internally - don't change this value.
   • enableSuperuserAccess: Must be true so Hydrolix can log in with the root user to create the Keycloak and Config API databases and users.

3. Apply the Cluster object and wait for the status to show as healthy.

   kubectl apply -f catalog.yaml
   kubectl -n "${namespace}" get cluster catalog
   

   A healthy cluster shows Cluster in healthy state in the STATUS column with all instances ready:

   NAME      AGE   INSTANCES   READY   STATUS                     PRIMARY
   catalog   5m    3           3       Cluster in healthy state   catalog-1
   

Configure RDS PostgreSQL

The RDS PostgreSQL instance must be in the same account, VPC, and AWS region as the EKS cluster.

Find the cluster VPC ID

aws eks describe-cluster --name ${HDX_KUBERNETES_NAMESPACE} --query 'cluster.resourcesVpcConfig.vpcId'

1. Navigate to the AWS console.
2. Search for and select Aurora and RDS.
3. Click Create a database, then select Full configuration.
4. Select PostgreSQL as the engine type and choose a version from the menu. Amazon defaults to the latest stable version.
5. Select the Production template.
6. Select Multi-AZ DB instance for availability and durability.
7. Configure these sections:
   • Settings: Enter a name in the DB instance identifier field.
   • Credentials Settings: Enter a master username and password. Hydrolix uses these to access the database.
   • Storage: Select General Purpose SSD (gp3) with 100 GiB of allocated storage.
   • Connectivity: Select the VPC associated with the EKS cluster and the default DB Subnet group.
   • VPC security group: Select Choose existing and add both the EKS cluster and node security groups.
8. Disable:
   • Monitoring > Enable Performance Insights
   • Additional configuration > Enable auto minor version upgrade
9. Review any remaining sections and adjust settings for your environment as needed, such as credential management or log exports.
10. Click Create database.

It takes about 10 minutes to create the database. When ready, AWS provides an endpoint to connect to the database. Find this endpoint in the Connectivity & security tab of the database details page. Use this endpoint as the catalog_db_host value when editing the HydrolixCluster resource.

Define the external PostgreSQL connection

Disable the internal PostgreSQL instance and configure Hydrolix to connect to the external PostgreSQL endpoint.

1. Edit the HydrolixCluster resource.

   kubectl edit hydrolixcluster hdx -n {namespace}
   

2. Fill in the values for catalog_db_admin_user, catalog_db_admin_db, and catalog_db_host. Set scale.postgres.replicas to 0.

   • For CloudNativePG, use catalog-rw as the catalog_db_host value. This is the CNPG read-write service endpoint that routes to the primary instance.
   • For an external managed PostgreSQL service, use the endpoint the cloud provider supplies.

   spec:
     catalog_db_admin_user: postgres      #<--- Admin user
     catalog_db_admin_db: postgres        #<--- Database for initial admin connection
     catalog_db_host: <postgresql-host>   #<--- catalog-rw for CNPG, or the external endpoint
   
     scale:
       postgres:
         replicas: 0                      #<---- Disable the internal PostgreSQL pod
     scale_profile: prod
   

Create the secret

Store the PostgreSQL credentials in a curated Kubernetes secret.

If using CloudNativePG, retrieve the auto-generated passwords first.

ROOT_PWD=$(kubectl -n {namespace} get secret catalog-superuser -o jsonpath='{.data.password}' | base64 -d)
CATALOG_PWD=$(kubectl -n {namespace} get secret catalog-app -o jsonpath='{.data.password}' | base64 -d)

1. Edit the curated secret.

   kubectl edit secret curated -n {namespace}
   

2. Add the stringData property with the required credentials. Kubernetes encodes values from stringData and stores them in data. When reading the curated secret, only the data key is present.

   For CloudNativePG, include both passwords:

   stringData:
     ROOT_DB_PASSWORD: ${ROOT_PWD}
     CATALOG_DB_PASSWORD: ${CATALOG_PWD}
   

   For an externally managed PostgreSQL service, include only the admin password set when creating the instance:

   stringData:
     ROOT_DB_PASSWORD: <postgresql-admin-password>
   

New and existing deployments

The Operator picks up the secret on first deploy for new deployments.

If the Hydrolix cluster is already running, restart all deployments to apply the new credentials. Secret changes don't trigger automatic restarts.

kubectl rollout restart deployment