Configuração do PostgreSQL

ChartVersion3.0.1TypeapplicationAppVersion17.5.0

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

O que é o PostgreSQL no TDP?

O PostgreSQL é o banco de dados relacional da infraestrutura TDP Kubernetes. Ele não é o motor analítico da plataforma; seu papel é oferecer armazenamento transacional para configurações, estado interno, catálogos, usuários, permissões ou histórico operacional dos componentes que o consomem.

Esta página concentra o próprio PostgreSQL: instalação, persistência, recursos, parâmetros de postgresql.conf, Service interno e credenciais administrativas. A configuração dos componentes que consomem esse banco deve ser feita na página de cada componente, porque cada integração define seus próprios parâmetros, Secrets e validações.

Para ambientes que exigirem alta disponibilidade, backup corporativo, replicação, políticas de manutenção próprias ou isolamento por componente, avalie usar uma instância PostgreSQL dedicada ou externa.

Estrutura de valores (Helm)

Todos os valores do PostgreSQL devem ficar sob a chave tdp-postgresql: (alias da dependência no Chart.yaml).

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

Visão geral

Propriedade	Valor
Chart	tdp-postgresql
Versão do PostgreSQL	17.5.0
Versão do Chart	3.0.1
Registry (OCI)	oci://registry.tecnisys.com.br/tdp/charts/tdp-postgresql

Páginas relacionadas

• Segurança - Padrões Gerais: credenciais, Secrets e boas práticas aplicáveis ao PostgreSQL.
• Integrações - Padrões Gerais: padrão de banco externo usado pelos componentes que consomem este PostgreSQL.

Pré-requisitos

Antes de instalar, confirme:

• Kubernetes 1.32+, Red Hat OpenShift 4.19+ ou Rancher Manager 2.10.x+;
• Helm 3.2.0+;
• StorageClass disponível para volumes persistentes;
• namespace definido para o release.

Em OpenShift, a compatibilidade de Security Context é habilitada por padrão com tdp-postgresql.global.compatibility.openshift.adaptSecurityContext: auto e tdp-postgresql.volumePermissions.enabled: false. Em Kubernetes vanilla, a escrita no volume ainda depende das permissões fornecidas pela StorageClass e pelo PersistentVolume do cluster.

Instalação

Instalação

O mesmo comando de instalação é usado em Kubernetes vanilla e OpenShift. Em OpenShift, a compatibilidade de Security Context já é tratada pelos valores padrão do chart.

Terminal input

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

Parâmetros principais

Parâmetros principais

Parâmetro	Descrição	Padrão
tdp-postgresql.postgresql.enabled	Habilita o subchart PostgreSQL	true
tdp-postgresql.primary.persistence.enabled	Habilita persistência	true
tdp-postgresql.primary.persistence.size	Tamanho do PVC	1Gi
tdp-postgresql.primary.resources.requests.cpu	CPU solicitada	500m
tdp-postgresql.primary.resources.requests.memory	Memória solicitada	1Gi
tdp-postgresql.primary.resources.limits.cpu	Limite de CPU	1000m
tdp-postgresql.primary.resources.limits.memory	Limite de memória	2Gi
tdp-postgresql.primary.configuration	Sobrescritas de postgresql.conf	""
tdp-postgresql.global.compatibility.openshift.adaptSecurityContext	Modo de compatibilidade com OpenShift SCC	auto
tdp-postgresql.volumePermissions.enabled	Init container de permissões de volume	false
tdp-postgresql.service.type	Tipo do Service	ClusterIP
tdp-postgresql.service.port	Porta do Service	5432
tdp-postgresql.startupProbe.enabled	Habilita a probe de inicialização do PostgreSQL	true
tdp-postgresql.metrics.enabled	Exporter de métricas	false

Para consultar a lista completa de parâmetros da versão instalada:

Terminal input

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

Detalhes de configuração

Persistência e recursos

O PostgreSQL armazena seus dados em PVC quando tdp-postgresql.primary.persistence.enabled: true. Ajuste tdp-postgresql.primary.persistence.size conforme o volume esperado de metadados, retenção operacional e política de backup do ambiente.

Os recursos de CPU e memória ficam em tdp-postgresql.primary.resources.*. Dimensione esses valores considerando número de conexões, carga dos componentes consumidores, frequência de jobs administrativos e janelas de manutenção.

Sobrescritas em postgresql.conf

O chart aceita configuração customizada via tdp-postgresql.primary.configuration. Use esse bloco quando precisar ajustar parâmetros do PostgreSQL, como conexões, WAL, logs ou comportamento de escrita.

Exemplo:

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'

Para usar o comportamento padrão do subchart, mantenha tdp-postgresql.primary.configuration: "" ou omita o bloco.

Acesso & Segurança

Acesso

Por padrão, o PostgreSQL é exposto por um Service ClusterIP na porta 5432. Esse acesso é destinado aos componentes e clientes que executam dentro do cluster:

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

Obter a senha do usuário postgres

Terminal input

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

Conectar a partir de um pod temporário

Para validar o acesso sem instalar cliente PostgreSQL na máquina local, crie um pod temporário com a imagem cliente e conecte-se com o psql. O pod se autoexclui ao encerrar a sessão (--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

Acesso pontual fora do cluster

Use port-forward apenas para administração ou diagnóstico pontual:

Terminal input

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

Em outro terminal, conecte com psql:

Terminal input

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

Segurança e credenciais

A senha do usuário postgres é armazenada em um Kubernetes Secret do release, na chave postgres-password. Trate esse Secret como credencial administrativa.

Não versione senhas em texto plano em arquivos de valores. Quando outro componente precisar criar ou acessar bancos neste PostgreSQL, configure a referência ao Secret conforme a documentação desse componente.

Para boas práticas gerais sobre Secrets, autenticação e TLS, consulte Segurança - Padrões Gerais.

Solução de problemas

Solução de problemas

Após instalar ou atualizar, valide os recursos principais:

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

Problemas comuns:

Sintoma	Possível causa	Verificação
Pod não inicia	PVC pendente ou StorageClass indisponível	kubectl -n <NAMESPACE> get pvc
Falha de escrita no volume	Permissões do PV/StorageClass incompatíveis	Eventos do pod e política do StorageClass
Componentes não conectam	Service, Secret ou senha incorretos	DNS do Service, Secret do release e logs do componente
Conexões saturadas	max_connections insuficiente para a carga	pg_stat_activity e parâmetros em postgresql.conf

Desinstalação

Desinstalação

Terminal input

helm uninstall <RELEASE_NAME> -n <NAMESPACE>