PostgreSQL Configuration

ChartVersion3.0.1TypeapplicationAppVersion17.5.0

CompatibilityKubernetes1.32+OpenShift4.19+Rancher2.10.x+

What is PostgreSQL in TDP?

PostgreSQL is the relational database of the TDP Kubernetes infrastructure. It is not the platform analytics engine; its role is to provide transactional storage for configuration, internal state, catalogs, users, permissions, or operational history for the components that consume it.

This page covers PostgreSQL itself: installation, persistence, resources, postgresql.conf parameters, internal Service access, and administrative credentials. The configuration of components that consume this database should be done in each component page, because each integration defines its own parameters, Secrets, and validation steps.

For environments that require high availability, corporate backup, replication, independent maintenance policies, or component isolation, consider using a dedicated or external PostgreSQL instance.

Helm value structure

All PostgreSQL values must be placed under the tdp-postgresql: key (the dependency alias in Chart.yaml).

tdp-postgresql:
  primary:
    persistence:
      size: 10Gi

Overview

Property	Value
Chart	tdp-postgresql
PostgreSQL version	17.5.0
Chart version	3.0.1
Registry (OCI)	oci://registry.tecnisys.com.br/tdp/charts/tdp-postgresql

Related pages

• Security - General Patterns: credentials, Secrets, and best practices applicable to PostgreSQL.
• Integrations - General Patterns: external database pattern used by components that consume this PostgreSQL.

Prerequisites

Before installing, confirm:

• Kubernetes 1.32+, Red Hat OpenShift 4.19+, or Rancher Manager 2.10.x+;
• Helm 3.2.0+;
• StorageClass available for persistent volumes;
• namespace defined for the release.

On OpenShift, Security Context compatibility is enabled by default with tdp-postgresql.global.compatibility.openshift.adaptSecurityContext: auto and tdp-postgresql.volumePermissions.enabled: false. On vanilla Kubernetes, write access to the volume still depends on the permissions provided by the cluster StorageClass and PersistentVolume.

Installation

Installation

The same installation command is used on vanilla Kubernetes and OpenShift. On OpenShift, Security Context compatibility is already handled by the chart defaults.

Terminal input

helm upgrade --install <RELEASE_NAME> oci://registry.tecnisys.com.br/tdp/charts/tdp-postgresql -n <NAMESPACE> --create-namespace

Main parameters

Main Parameters

Parameter	Description	Default
tdp-postgresql.postgresql.enabled	Enables the PostgreSQL subchart	true
tdp-postgresql.primary.persistence.enabled	Enables persistence	true
tdp-postgresql.primary.persistence.size	PVC size	1Gi
tdp-postgresql.primary.resources.requests.cpu	Requested CPU	500m
tdp-postgresql.primary.resources.requests.memory	Requested memory	1Gi
tdp-postgresql.primary.resources.limits.cpu	CPU limit	1000m
tdp-postgresql.primary.resources.limits.memory	Memory limit	2Gi
tdp-postgresql.primary.configuration	postgresql.conf overrides	""
tdp-postgresql.global.compatibility.openshift.adaptSecurityContext	OpenShift SCC compatibility mode	auto
tdp-postgresql.volumePermissions.enabled	Volume permissions init container	false
tdp-postgresql.service.type	Service type	ClusterIP
tdp-postgresql.service.port	Service port	5432
tdp-postgresql.startupProbe.enabled	Enables the PostgreSQL startup probe	true
tdp-postgresql.metrics.enabled	Metrics exporter	false

To inspect the full parameter list for the installed version:

Terminal input

helm show values oci://registry.tecnisys.com.br/tdp/charts/tdp-postgresql --version <CHART_VERSION>

Configuration details

Persistence and Resources

PostgreSQL stores its data in a PVC when tdp-postgresql.primary.persistence.enabled: true. Adjust tdp-postgresql.primary.persistence.size according to expected metadata volume, operational retention, and the environment backup policy.

CPU and memory resources are configured under tdp-postgresql.primary.resources.*. Size these values considering the number of connections, consumer component load, administrative job frequency, and maintenance windows.

postgresql.conf Overrides

The chart accepts custom configuration through tdp-postgresql.primary.configuration. Use this block when you need to adjust PostgreSQL parameters such as connections, WAL, logs, or write behavior.

Example:

tdp-postgresql:
  primary:
    configuration: |-
      listen_addresses = '*'
      max_connections = 400
      superuser_reserved_connections = 10
      wal_level = 'replica'
      fsync = 'on'
      max_wal_size = '400MB'
      max_wal_senders = '16'
      wal_keep_size = '128MB'
      hot_standby = 'on'
      log_connections = 'false'
      log_disconnections = 'false'
      log_hostname = 'false'
      client_min_messages = 'error'

To use the subchart default behavior, keep tdp-postgresql.primary.configuration: "" or omit the block.

Access & Security

Access

By default, PostgreSQL is exposed through a ClusterIP Service on port 5432. This access is intended for components and clients running inside the cluster:

<RELEASE_NAME>.<NAMESPACE>.svc.cluster.local:5432

Get the postgres User Password

Terminal input

export POSTGRES_PASSWORD=$(kubectl get secret --namespace <NAMESPACE> <RELEASE_NAME> -o jsonpath="{.data['postgres-password']}" | base64 -d)

Connect from a Temporary Pod

To validate access without installing a PostgreSQL client on the local machine, create a temporary pod with the client image and connect with psql. The pod self-deletes when the session ends (--rm):

Terminal input

kubectl run <RELEASE_NAME>-client --rm --tty -i --restart='Never' --namespace <NAMESPACE> \
  --image docker.io/bitnamilegacy/postgresql:17.5.0-debian-12-r20 --env="PGPASSWORD=$POSTGRES_PASSWORD" \
  --command -- psql -h <RELEASE_NAME> -p 5432 -U postgres -d postgres

Occasional Access from Outside the Cluster

Use port-forward only for occasional administration or diagnostics:

Terminal input

kubectl port-forward --namespace <NAMESPACE> svc/<RELEASE_NAME> 5432:5432

In another terminal, connect with psql:

Terminal input

psql -h 127.0.0.1 -p 5432 -U postgres -d postgres

Security and Credentials

The postgres user password is stored in a Kubernetes Secret for the release, in the postgres-password key. Treat this Secret as an administrative credential.

Do not version plain-text passwords in values files. When another component needs to create or access databases in this PostgreSQL instance, configure the Secret reference according to that component's documentation.

For general best practices about Secrets, authentication, and TLS, see Security - General Patterns.

Troubleshooting

Troubleshooting

After installing or upgrading, validate the main resources:

Terminal input

kubectl -n <NAMESPACE> get pods
kubectl -n <NAMESPACE> get svc
kubectl -n <NAMESPACE> get pvc
kubectl -n <NAMESPACE> get events --sort-by=.lastTimestamp

Common issues:

Symptom	Possible cause	Check
Pod does not start	Pending PVC or unavailable StorageClass	kubectl -n <NAMESPACE> get pvc
Volume write failure	Incompatible PV/StorageClass permissions	Pod events and StorageClass policy
Components cannot connect	Incorrect Service, Secret, or password	Service DNS, release Secret, and component logs
Connections are saturated	max_connections is insufficient for the load	pg_stat_activity and postgresql.conf parameters

Uninstallation

Uninstall

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>