Distribuire PostgreSQL su Kubernetes: guida passo per passo

PostgreSQL è un sistema di gestione di database relazionali (RDBMS) molto diffuso, che offre funzionalità di alta disponibilità come la replicazione in streaming, la replicazione logica e soluzioni di failover. Distribuire PostgreSQL su Kubernetes consente di creare sistemi resilienti, garantendo minimi tempi di inattività e disponibilità continua dei dati.

Con gli StatefulSet di Kubernetes, è possibile scalare il deployment di PostgreSQL in base alla domanda.

Choose hour server now!

Configurazione dell’ambiente Kubernetes

Assicurati di avere i seguenti componenti:

• Cluster Kubernetes (cloud o locale): puoi crearne uno su Hostman in pochi minuti. Se vuoi seguire la guida in locale, puoi utilizzare strumenti come k3s, minikube, microk8s o kind.

• kubectl: lo strumento da riga di comando per interagire con il cluster Kubernetes. Richiede un file YAML di configurazione che contiene i dettagli del cluster (solitamente fornito dal tuo provider).

Puoi scaricarlo dal pannello di controllo di Hostman e impostare la variabile d’ambiente:

Per connettersi, è necessario impostare di conseguenza la variabile di ambiente KUBECONFIG.

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

• Helm: è necessario lo strumento CLI di Helm per installare i chart. È richiesta la versione 3.

Distribuire PostgreSQL utilizzando un chart Helm

Helm è un gestore di pacchetti per Kubernetes, simile a apt su Ubuntu o Debian. Invece di creare manualmente più file YAML (Pods, Services, Volumi, Secrets, ecc.), Helm semplifica il tutto in un unico comando.

Passaggio 1: Aggiungere il repository Helm

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

Per sincronizzare il repository Helm locale con quello remoto:

helm repo update

Passaggio 2: Gestire la persistenza dei dati

PostgreSQL necessita di uno storage persistente per garantire che i dati rimangano disponibili anche se un pod si arresta o viene ripianificato.

Crea il file 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

⚠️ Nota: hostPath fa riferimento a una directory locale di un nodo specifico. Se il nodo diventa inattivo, i dati non saranno più accessibili. Per gli ambienti di produzione, è fortemente consigliato usare soluzioni di storage cloud-native (Ceph, Portworx, OpenEBS, GlusterFS) per una maggiore affidabilità e scalabilità.

Crea la PersistentVolumeClaim (PVC) — file postgres-local-pvc.yaml:

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

Il parametro ReadWriteOnce permette l’accesso in lettura/scrittura da un solo nodo alla volta. L’utilizzo di ReadWriteMany (RWX) potrebbe sembrare utile per aumentare la disponibilità, ma in PostgreSQL può causare corruzione dei dati o stati incoerenti.

Applica i manifest:

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

Passaggio 3: Installare PostgreSQL con Helm

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 

Verifica dopo alcuni minuti:

kubectl get all

Passaggio 4: Test e connessione

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

Il pod verrà eliminato automaticamente grazie al flag --rm.

👉 Se hai modificato il nome del rilascio, l’utente o il database, aggiorna i comandi di conseguenza.

Distribuire PostgreSQL su Kubernetes da zero

Uno StatefulSet è la risorsa più adatta per distribuire applicazioni con stato, come PostgreSQL. Ogni pod ottiene un’identità di rete stabile e un volume persistente dedicato.

Pulisci e ricrea le risorse:

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

Crea il file 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

Crea il Secret per le credenziali:

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

kubectl apply -f postgres-statefulset.yaml

Se il pod rimane in stato Pending, crea una StorageClass:

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

Controlla eventuali problemi:

kubectl describe pod postgres-statefulset-0

Crea un Headless Service per l’accesso interno — file 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

Test di connessione:

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

Scalabilità, replica e backup

Scalare lo StatefulSet:

kubectl scale statefulset postgres-statefulset --replicas=3 

•  Puoi accedere ai singoli pod tramite il servizio headless, ad esempio:
  postgres-statefulset-1.postgresql-headless-svc.

• Backup: utilizza un CronJob con l’utilità pg_dump. In alternativa, puoi abilitare VolumeSnapshots se il provider lo consente.

Buone pratiche

• Resource Requests e Limits: imposta limiti di CPU e memoria appropriati.

• Backup regolari: usa CronJobs e snapshot.

• Monitoraggio e log: utilizza Prometheus e Grafana per raccogliere metriche (prestazioni delle query, utilizzo disco, stato della replica).

• Pod Disruption Budget (PDB): evita che troppi pod PostgreSQL vengano interrotti contemporaneamente durante aggiornamenti.

Choose your server now!

Conclusione

Il chart Helm è il metodo consigliato per implementazioni complesse o in ambienti di produzione. Helm automatizza la gestione delle versioni e semplifica la configurazione delle risorse Kubernetes. Con il comando helm template, puoi generare localmente i manifest YAML e personalizzarli prima del deployment.

Kubernetes offre scalabilità, flessibilità e automazione per PostgreSQL. Utilizzando StatefulSet, PVC, PDB e la gestione dei Secret, puoi ottenere un database PostgreSQL pronto per la produzione, affidabile e sicuro.