Como implantar o PostgreSQL no Kubernetes: guia passo a passo

O PostgreSQL é um sistema de gerenciamento de banco de dados relacional (RDBMS) amplamente utilizado que oferece recursos de alta disponibilidade, como replicação em streaming, replicação lógica e soluções de failover. Implantar o PostgreSQL no Kubernetes permite criar sistemas resilientes, garantindo mínimo tempo de inatividade e alta disponibilidade dos dados.

Com os StatefulSets do Kubernetes, é possível escalar o PostgreSQL de acordo com a demanda.

Preparando o ambiente Kubernetes

Copiar link

Certifique-se de ter os seguintes componentes:

• Cluster Kubernetes (na nuvem ou local): você pode configurar rapidamente um cluster no Hostman. Para ambiente local, use ferramentas como k3s, minikube, microk8s ou kind.

• kubectl: a ferramenta de linha de comando usada para interagir com o cluster. Ela requer um arquivo YAML de configuração com os detalhes do cluster (geralmente fornecido pelo provedor de nuvem). 

No painel do Hostman, é possível baixar esse arquivo com um clique e, em seguida, definir a variável de ambiente:

Para conectar, você precisa definir a variável de ambiente KUBECONFIG adequadamente.

export KUBECONFIG=/absolute/path/to/file/k8s-cluster-config.yaml

• Helm: é necessário o utilitário Helm CLI para instalar charts. Use a versão 3.

Implantar o PostgreSQL usando um chart Helm

Copiar link

O Helm é o gerenciador de pacotes do Kubernetes — semelhante ao apt no Ubuntu/Debian. Em vez de criar vários arquivos YAML manualmente (Pods, Services, Volumes, Secrets etc.), o Helm simplifica todo o processo em um único comando.

Passo 1: Adicionar o repositório Helm

Copiar link

helm repo add bitnami https://charts.bitnami.com/bitnami

Para sincronizar seu repositório Helm local com o remoto:

helm repo update

Passo 2: Gerenciar a persistência de dados

Copiar link

O PostgreSQL requer armazenamento persistente para garantir que os dados não sejam perdidos se um pod falhar ou for reimplantado.

Crie o arquivo postgres-local-pv.yaml:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: postgresql-local-pv
spec:
  capacity:
      storage: 5Gi
  accessModes:
      - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: manual
  hostPath:
      path: /mnt/data/postgresql

Atenção: o hostPath aponta para um diretório local em um nó específico — não recomendado para ambientes de produção. Para produção, utilize soluções de armazenamento nativas da nuvem (Ceph, Portworx, OpenEBS, GlusterFS) para obter confiabilidade e escalabilidade.

Crie a PersistentVolumeClaim (PVC) — arquivo postgres-local-pvc.yaml:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: postgresql-local-pvc
spec:
  accessModes:
      - ReadWriteOnce
  resources:
      requests:
          storage: 5Gi
  storageClassName: manual

O modo ReadWriteOnce permite acesso de leitura e gravação por apenas um nó por vez. Usar ReadWriteMany não aumenta a disponibilidade no PostgreSQL e pode causar corrupção de dados ou condições de corrida.

Aplique os manifests:

kubectl apply -f postgres-local-pv.yaml
kubectl apply -f postgres-local-pvc.yaml

Passo 3: Instalar o PostgreSQL com Helm

Copiar link

helm install tutorial-db bitnami/postgresql --set auth.username=bhuwan \
  --set auth.password=”AeSeigh2gieshe” \
  --set auth.database=k8s-tutorial \
  --set auth.postgresPassword=”Ze4hahshez6dop9vaing” \
  --set primary.persistence.existingClaim=postgresql-local-pvc \
  --set volumePermissions.enabled=true 

Verifique o status após alguns minutos:

kubectl get all

Passo 4: Testar a conexão

Copiar link

export POSTGRES_PASSWORD=$(kubectl get secret --namespace default tutorial-db-postgresql -o jsonpath="{.data.password}" | base64 -d)

kubectl run tutorial-db-postgresql-client --rm --tty -i --restart='Never' \
 --image docker.io/bitnami/postgresql:17.2.0-debian-12-r6 \
 --env="PGPASSWORD=$POSTGRES_PASSWORD" \
 --command -- psql --host tutorial-db-postgresql \
 -U bhuwan -d k8s-tutorial -p 5432

O pod será removido automaticamente após o encerramento da sessão devido à flag --rm. Se você alterou o nome do release, o usuário ou o banco de dados, atualize os comandos conforme necessário.

Implantar o PostgreSQL no Kubernetes do zero

Copiar link

Um StatefulSet é o tipo de recurso ideal para aplicativos com estado, como o PostgreSQL, pois fornece identidade de rede estável e volumes persistentes dedicados para cada pod.

Limpe e recrie os recursos:

helm delete tutorial-db
kubectl delete pvc postgresql-local-pvc
kubectl delete pv postgresql-local-pv

kubectl apply -f postgres-local-pv.yaml -f postgres-local-pvc.yaml

Crie o arquivo postgres-statefulset.yaml:

apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres-statefulset
  labels:
    app: postgres
spec:
  serviceName: "postgresql-headless-svc"
  replicas: 1
  selector:
    matchLabels:
      app: postgres
  template:
    metadata:
      labels:
        app: postgres
    spec:
      containers:
        - name: postgres
          image: postgres:17.2
          envFrom:
            - secretRef:
                name: postgresql-secret
          ports:
            - containerPort: 5432
              name: postgresdb
          volumeMounts:
            - name: pv-data
              mountPath: /var/lib/postgresql/db
      volumes:
        - name: pv-data
          persistentVolumeClaim:
            claimName: postgresql-local-pvc

Crie o Secret com as credenciais:

kubectl create secret generic postgresql-secret --from-literal=POSTGRES_PASSWORD=Ze4hahshez6dop9vaing

kubectl apply -f postgres-statefulset.yaml

Se o pod permanecer em Pending, crie uma StorageClass:

kind: StorageClass
apiVersion: storage.k8s.io/v1
metadata:
  name: manual
provisioner: kubernetes.io/no-provisioner
volumeBindingMode: WaitForFirstConsumer

Verifique detalhes e erros:

kubectl describe pod postgres-statefulset-0

Crie um Headless Service para acesso interno — arquivo postgres-service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: postgresql-headless-svc
spec:
  type: ClusterIP
  selector:
	app: postgres
  ports:
  	- port: 5432
    	targetPort: 5432
  clusterIP: None

Teste a conexão:

kubectl run tutorial-db-postgresql-client --rm --tty -i --restart='Never'  \
--image docker.io/bitnami/postgresql:17.2.0-debian-12-r6 \
--env="PGPASSWORD=Ze4hahshez6dop9vaing"  \
--command -- psql --host postgres-statefulset-0.postgresql-headless-svc  \
-U postgres  -p 5432

Escalabilidade, replicação e backup

Copiar link

Escalar o StatefulSet:

kubectl scale statefulset postgres-statefulset --replicas=3 

•  Cada pod pode ser acessado via o serviço headless, por exemplo:
  postgres-statefulset-1.postgresql-headless-svc.

• Backup: utilize um CronJob executando a ferramenta pg_dump. Também é possível usar VolumeSnapshots para maior segurança.

Boas práticas

Copiar link

• Requests e Limits: defina limites adequados de CPU e memória.

• Backups regulares: use CronJobs e snapshots.

• Monitoramento e logs: use Prometheus e Grafana para monitorar métricas como desempenho de consultas, uso de disco e status de replicação.

• Pod Disruption Budgets (PDBs): evite que muitos pods PostgreSQL sejam interrompidos simultaneamente durante atualizações.

Conclusão

Copiar link

O Helm Chart é a forma recomendada para implantações complexas e ambientes de produção. O Helm automatiza o controle de versões e simplifica a configuração dos componentes Kubernetes. Com o comando helm template, é possível gerar os manifests YAML localmente e ajustá-los conforme necessário.

O Kubernetes oferece escalabilidade, flexibilidade e automação para bancos de dados PostgreSQL. Usando StatefulSets, PVCs, PDBs e gestão de Secrets, você garante uma implantação de PostgreSQL pronta para produção — segura, confiável e altamente disponível.