Guide: running instant3Dhub with external PostgreSQL

Read First

instant3Dhub comes packaged with PostgreSQL. This guide explains how to provision a separate PostgreSQL instance. It is advised to remove the PostgreSQL services from your deploy configuration if you choose to host your own PostgreSQL instance.

Prerequisites

It is necessary to have a running PostgreSQL instance that is accessible from the Kubernetes cluster where instant3Dhub is deployed. The PostgreSQL instance must be configured to allow connections from the cluster, and the necessary ports must be open.

To run instant3Dhub, it is necessary to create at least one database with UTF-8 encoding and a user that has the ability to create tables and functions, as well as read and write permissions on the database. However, it is recommended to create separate databases according to their content and desired operation management:

  • A database that contains the license usage data for the license server (backups are recommended)

  • A database that stores the spaces (backups are recommended)

  • A database that contains the resource management and cache information

Furthermore, it is possible to use two types of users:

  • An admin user that is capable of creating tables and functions

  • A runtime user that only has read and write permissions

To create a new database with a new user, please refer to the official PostgreSQL documentation.

Configure instant3Dhub

To use the created database(s) and user(s) with instant3Dhub, it is necessary to create Kubernetes secrets that contain the database credentials as a connection string according to the pattern described here.

postgresql://{USER}:{PASSWORD}@{HOSTNAME}:{PORT}/{DATABASE}?sslmode=disable

Note

Replace {USER}, {PASSWORD}, {HOSTNAME}, {PORT}, and {DATABASE} with your actual values. The ?sslmode=disable query parameter is optional and can be omitted to use the default SSL mode prefer, or set require to enforce SSL. If you want to enforce SSL verification and use custom CA signed certificates, make sure to register them in values.yaml as described in the section security.customCAs.

To correctly encode such a connection string, use the following command:

echo -n "postgresql://myuser:mypassword@dbhost:5432/mydb?sslmode=disable" | base64 -w 0

Then, create a secret with the encoded connection string(s) as follows:

apiVersion: v1
kind: Secret
metadata:
  name: my-postgres-secrets
data:
  licenseAdminConnStr: <base64_encoded_connection_string>
  licenseRuntimeConnStr: <base64_encoded_connection_string>
  spacesAdminConnStr: <base64_encoded_connection_string>
  spacesRuntimeConnStr: <base64_encoded_connection_string>
  resourceAdminConnStr: <base64_encoded_connection_string>
  resourceRuntimeConnStr: <base64_encoded_connection_string>

The data block must contain entries for all database and user combinations that you want to use with instant3Dhub. If you use the same database and user for all three components, you can reuse a single connection string secret. You can freely choose the key names, but it is helpful to use a consistent naming scheme to avoid confusion.

Finally, it is necessary to update the instant3Dhub configuration to use the created secret. To do so, modify the values.yaml file as follows:

credentials:
  postgres:
    system:
      # This disables the internal postgres deployment.
      external: true
      admin:
        secretKeyRef:
          name: my-postgres-secrets
          key: resourceAdminConnStr
      runtime:
        secretKeyRef:
          name: my-postgres-secrets
          key: resourceRuntimeConnStr
      exporter:
        secretKeyRef:
          name: my-postgres-secrets
          key: resourceRuntimeConnStr
    spaces:
      admin:
        secretKeyRef:
          name: my-postgres-secrets
          key: spacesAdminConnStr
      runtime:
        secretKeyRef:
          name: my-postgres-secrets
          key: spacesRuntimeConnStr
    license:
      admin:
        secretKeyRef:
          name: my-postgres-secrets
          key: licenseAdminConnStr
      runtime:
        secretKeyRef:
          name: my-postgres-secrets
          key: licenseRuntimeConnStr