Skip to content

cluster-connection.md

Latest commit

 

History

History
183 lines (146 loc) · 5.96 KB

cluster-connection.md

File metadata and controls

183 lines (146 loc) · 5.96 KB
Raw

ClusterConnection

The ClusterConnection Custom Resource Definition (CRD) defines the connection details for a PostgreSQL cluster.
It specifies the host, port, database, and the credentials to use for administrative operations.

Other Custom Resources (like Database, Role, Schema, Grant, DefaultPrivilege) reference a specific target PostgreSQL cluster using clusterRef on which to execute the operations.

Spec

Field Type Description Required Mutable
host string The hostname of the PostgreSQL instance. Yes Yes
port integer The port of the PostgreSQL instance (1-65535). Yes Yes
database string The database to connect to (usually postgres for admin operations). Yes Yes
adminSecretRef ResourceRef Reference to the Kubernetes Secret containing the admin credentials. No Yes
adminSecretFileRef FileRef Reference to a file containing the admin credentials. No Yes
parameters map[string]string Additional connection parameters. No Yes

Note: Exactly one of adminSecretRef or adminSecretFileRef must be provided.

ResourceRef (adminSecretRef)

Field Type Description Required
namespace string Namespace of the referenced Kubernetes Secret. If not specified, uses the owning CR's namespace. No
name string Name of the referenced Kubernetes Secret. Yes

The referenced secret must be of type kubernetes.io/basic-auth and contain the keys username and password.

FileRef (adminSecretFileRef)

Field Type Description Required
path string The path to the file containing the admin credentials. Yes

Use this option when the credentials are mounted as a file instead of a Kubernetes Secret.

File format

The file must contain JSON with the following fields:

{
  "username": "root",
  "password": "password"
}
  • password required
  • username required

Mount the credentials file

The file must be accessible inside the operator pod at the path specified in adminSecretFileRef.path. Mount it using a Volume and VolumeMount on the operator Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: postgresql-operator
spec:
  template:
    spec:
      containers:
        - name: postgresql-operator
          volumeMounts:
            - name: db-credentials
              mountPath: /mnt/secrets
              readOnly: true
      volumes:
        - name: db-credentials
          secret:
            secretName: db-credentials-secret

Note: The volume source can be any type that provides a file.

With the Helm chart

The chart exposes the app.volumes and app.volumeMounts values. Both take the raw Kubernetes syntax, so any volume source works. Pass them in your own values file:

app:
  volumes:
    - name: db-credentials
      secret:
        secretName: db-credentials-secret
  volumeMounts:
    - name: db-credentials
      mountPath: /mnt/secrets
      readOnly: true
helm install postgresql-operator <chart-url> --values values.yaml

See the installation section of the README for the chart URL.

With the Secrets Store CSI driver

Use this option to read the credentials from an external secret store, for example AWS Secrets Manager. The chart does not create the SecretProviderClass, so you have to apply it yourself:

apiVersion: secrets-store.csi.x-k8s.io/v1
kind: SecretProviderClass
metadata:
  name: db-credentials
spec:
  provider: aws
  parameters:
    objects: |
      - objectName: "my/db/credentials"
        objectAlias: "db-credentials.json"

Then reference it from the chart values:

app:
  volumes:
    - name: db-credentials
      csi:
        driver: secrets-store.csi.k8s.io
        readOnly: true
        volumeAttributes:
          secretProviderClass: db-credentials
  volumeMounts:
    - name: db-credentials
      mountPath: /mnt/secrets
      readOnly: true

Note: The SecretProviderClass must live in the namespace of the operator.

Examples

Using a Kubernetes Secret (adminSecretRef)

apiVersion: v1
kind: Secret
metadata:
  name: my-db-secret
type: kubernetes.io/basic-auth
stringData:
  username: postgres
  password: password
apiVersion: postgresql.aboutbits.it/v1
kind: ClusterConnection
metadata:
  name: my-postgres-connection
spec:
  adminSecretRef:
    name: my-db-secret
  host: localhost
  port: 5432
  database: postgres
  # Example parameters
  parameters:
    ApplicationName: "k8s-operator" # Helps identify this connection in Postgres logs
    #sslmode: "require" # Enforce SSL encryption
    #connectTimeout: "10" # Timeout in seconds for connection attempts

Using a file reference (adminSecretFileRef)

apiVersion: postgresql.aboutbits.it/v1
kind: ClusterConnection
metadata:
  name: quarkus-postgres-connection
spec:
  adminSecretFileRef:
    path: "/mnt/secrets/db-credentials.json"
  host: localhost
  port: 5432
  database: postgres