Vai al contenuto principale

Distribuire un'applicazione web con PostgreSQL su Kubernetes

Questo tutorial le fa costruire un'applicazione web completa su Hikube: un cluster Kubernetes che esegue l'applicazione, un database PostgreSQL gestito che ne conserva i dati, una pubblicazione in HTTPS con certificato automatico e infine il monitoraggio dell'insieme.

L'applicazione di esempio è Miniflux, un lettore di feed RSS open source: una sola immagine di container, un database PostgreSQL, un'interfaccia web.

DifficoltàIntermedio
DurataCirca 45 minuti
Imparerà aCollegare un cluster Kubernetes a un database gestito dello stesso progetto, passare le credenziali tramite un Secret, pubblicare un servizio in HTTPS

Cosa costruirà​

  • Il database non è esposto su Internet: l'applicazione lo raggiunge tramite il suo host interno, riservato alle risorse del progetto.
  • La password del database non compare in alcun file: si trova in un Secret Kubernetes.
  • Solo l'Ingress è pubblico, in HTTPS, con un certificato Let's Encrypt rinnovato automaticamente.

Prerequisiti​

  • Un account Hikube e un progetto con quote sufficienti per un control plane, un nodo s1.large (4 vCPU, 8 GB) e un database s1.small
  • Il ruolo di amministratore del progetto, per scaricare il kubeconfig del cluster
  • kubectl e openssl installati sulla sua postazione
  • Un nome di dominio di cui gestisce la zona DNS, per la pubblicazione in HTTPS (passo 6). Questo tutorial usa miniflux.example.com: lo sostituisca ovunque con il suo.
  • Nozioni di base di Kubernetes: pod, Deployment, Service

Passo 1: Creare il cluster Kubernetes​

Il cluster è la risorsa più lunga da creare: inizi da questo, creerà il database mentre si avvia.

  1. Nella console Hikube, selezioni il suo progetto, quindi apra Infrastructure > Kubernetes.
  2. Faccia clic su Create cluster e compili la procedura guidata:
Passaggio della procedura guidataCampoValore
GeneralCluster nametuto-web
Kubernetes Versionla versione preselezionata
Control Plane Instance Sizes1.small — 1 CPU / 2Gi
Control Plane High Availability3 (HA)
NodesGruppo worker-pool-1Instance type s1.large, Minimum nodes 1, Maximum nodes 3, Exposed on the internet (Public IP) attivato
AddonsMantenga Cert-Manager, Ingress NGINX e Monitoring Agents, selezionati per impostazione predefinita
  1. Al passaggio Summary, faccia clic su Create cluster.

Ogni campo è descritto in dettaglio nell'avvio rapido Kubernetes.

Risultato atteso: tuto-web compare nell'elenco Kubernetes Clusters con lo stato Creating. Passi al passo successivo senza attendere.


Passo 2: Creare il database PostgreSQL​

  1. Apra DB & Messaging → PostgreSQL, quindi faccia clic su Create a cluster.
  2. Compili la procedura guidata:
Passaggio della procedura guidataCampoValore
GeneralCluster Nametuto-db
ConfigurationPostgreSQL Version18
Instance presets1.small — 1 CPU / 2Gi
Disk size (GB)10
Number of replicas1 (Standalone)
External accessDisattivato: l'applicazione raggiungerà il database dall'interno del progetto
DatabasesDatabase nameminiflux, quindi Add
UsersUsernameminiflux, Database name miniflux, Rights Administrator (Admin), quindi Add
  1. Al passaggio Summary, faccia clic su Create cluster.

Il passaggio Finish mostra la Password dell'utente miniflux, nella sezione User Credentials.

Copi subito la password

Viene mostrata una sola volta. La copi in un gestore di password prima di fare clic su Finish. In caso di smarrimento, ne generi una nuova dalla scheda Users del cluster (Actions → Change Password).

  1. Faccia clic su Finish. Nella pagina del cluster, nel riquadro Connection and Databases, copi l'host della zona Internal (From the project's resources only) con il pulsante di copia: è l'indirizzo che l'applicazione utilizzerà, sulla porta 5432.

Risultato atteso: dopo alcuni minuti, tuto-db passa allo stato Ready e la zona External mostra Disabled.


Passo 3: Connettersi al cluster​

Attenda che il cluster sia Ready e che il suo primo nodo si sia avviato, qualche minuto dopo la creazione.

  1. Apra Infrastructure > Kubernetes, quindi la pagina del cluster tuto-web.
  2. Nella sezione Actions, faccia clic su Kubeconfig. Il browser scarica kubeconfig-tuto-web.yaml.
export KUBECONFIG=~/Downloads/kubeconfig-tuto-web.yaml
kubectl get nodes

Risultato atteso: un nodo con stato Ready.

NAME STATUS ROLES AGE VERSION
kubernetes-tuto-web-worker-pool-1-xxxxx-xxxxx Ready <none> 3m v1.xx.x
Il cluster è Ready, ma non compare alcun nodo

Lo stato Ready riguarda il control plane. Il primo nodo e gli addon si avviano subito dopo: se kubectl get nodes risponde No resources found, attenda e rilanci il comando.

Verifichi anche che gli addon siano in esecuzione:

kubectl get pods -A | grep -E "cert-manager|ingress-nginx"

Risultato atteso: tutti i pod in Running.


Passo 4: Verificare l'accesso del cluster al database​

Prima di distribuire l'applicazione, verifichi che il cluster raggiunga il database. Inserisca la password di miniflux senza che compaia a schermo né nella cronologia della shell, quindi la riponga in un Secret:

read -rs PGPASSWORD # incolli la password, poi Invio
export PGHOST=<host-interno> # l'host copiato al passo 2

kubectl create secret generic pg-test --from-literal=PGPASSWORD="$PGPASSWORD"

Avvii un client psql effimero nel cluster:

kubectl run pg-test --rm -i --restart=Never --image=postgres:18-alpine \
--overrides='{"spec":{"containers":[{"name":"pg-test","image":"postgres:18-alpine",
"envFrom":[{"secretRef":{"name":"pg-test"}}],
"command":["psql","host='"$PGHOST"' port=5432 dbname=miniflux user=miniflux sslmode=require",
"-c","SELECT current_user, version();"]}]}}'

Risultato atteso:

current_user | version
--------------+-----------------------------------------------------
miniflux | PostgreSQL 18.x ...
(1 row)

Elimini il secret di test:

kubectl delete secret pg-test

Se il comando non riesce, vedere Un pod non raggiunge un database gestito del progetto.


Passo 5: Distribuire l'applicazione​

Riporre le credenziali nei secret​

Miniflux legge l'indirizzo del suo database dalla variabile DATABASE_URL. La crei in un Secret, con la password inserita al passo 4:

kubectl create secret generic miniflux-db \
--from-literal=DATABASE_URL="host=$PGHOST port=5432 dbname=miniflux user=miniflux password='$PGPASSWORD' sslmode=require"

Crei poi l'account amministratore di Miniflux, con una password casuale:

kubectl create secret generic miniflux-admin \
--from-literal=username=admin \
--from-literal=password="$(openssl rand -base64 18)"

Distribuire Miniflux​

miniflux.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: miniflux
labels:
app: miniflux
spec:
replicas: 1
selector:
matchLabels:
app: miniflux
template:
metadata:
labels:
app: miniflux
spec:
containers:
- name: miniflux
image: miniflux/miniflux:2.3.5
ports:
- containerPort: 8080
env:
- name: LISTEN_ADDR
value: "0.0.0.0:8080"
- name: RUN_MIGRATIONS # crea le tabelle al primo avvio
value: "1"
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: miniflux-db
key: DATABASE_URL
- name: CREATE_ADMIN # crea l'account admin se non esiste
value: "1"
- name: ADMIN_USERNAME
valueFrom:
secretKeyRef:
name: miniflux-admin
key: username
- name: ADMIN_PASSWORD
valueFrom:
secretKeyRef:
name: miniflux-admin
key: password
readinessProbe:
httpGet:
path: /healthcheck
port: 8080
livenessProbe:
httpGet:
path: /healthcheck
port: 8080
initialDelaySeconds: 10
resources:
requests:
cpu: 50m
memory: 64Mi
limits:
cpu: 500m
memory: 256Mi
---
apiVersion: v1
kind: Service
metadata:
name: miniflux
spec:
selector:
app: miniflux
ports:
- port: 80
targetPort: 8080
kubectl apply -f miniflux.yaml
kubectl rollout status deployment/miniflux
kubectl logs deployment/miniflux

Risultato atteso: la distribuzione va a buon fine e i log mostrano la creazione dello schema, dell'account admin, poi l'avvio del server.

level=INFO msg="Running database migrations" current_version=0 latest_version=...
level=INFO msg="Created new admin user" username=admin user_id=1
level=INFO msg="Starting HTTP server" listen_address=0.0.0.0:8080

Passare a due repliche​

La distribuzione ha avviato un solo pod, il tempo che Miniflux creasse le proprie tabelle. Ora che lo schema esiste, aggiunga un secondo pod: l'applicazione resta disponibile se uno dei due si riavvia.

kubectl scale deployment/miniflux --replicas=2
kubectl get pods -l app=miniflux

Risultato atteso: due pod miniflux-… in Running, 1/1.


Passo 6: Pubblicare l'applicazione in HTTPS​

Puntare il dominio al cluster​

Recuperi l'indirizzo IP pubblico del controller Ingress NGINX (colonna EXTERNAL-IP):

kubectl get svc -n cozy-ingress-nginx ingress-nginx-controller

Presso il suo provider DNS, crei un record A da miniflux.example.com verso questo indirizzo. Verifichi la propagazione:

dig +short miniflux.example.com

Creare l'emittente di certificati​

cluster-issuer.yaml
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
name: letsencrypt-prod
spec:
acme:
server: https://acme-v02.api.letsencrypt.org/directory
email: admin@example.com # il suo indirizzo, per gli avvisi di scadenza
privateKeySecretRef:
name: letsencrypt-prod-account-key
solvers:
- http01:
ingress:
ingressClassName: nginx
kubectl apply -f cluster-issuer.yaml

Creare l'Ingress​

miniflux-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: miniflux
annotations:
cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
ingressClassName: nginx
tls:
- hosts:
- miniflux.example.com
secretName: miniflux-tls
rules:
- host: miniflux.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: miniflux
port:
number: 80
kubectl apply -f miniflux-ingress.yaml
kubectl get certificate miniflux-tls --watch

Risultato atteso: dopo uno o due minuti, il certificato passa a READY True. Interrompa il comando con Ctrl+C.

NAME READY SECRET AGE
miniflux-tls True miniflux-tls 90s

Aprire l'applicazione​

curl -I http://miniflux.example.com # 308: reindirizzamento a HTTPS
curl https://miniflux.example.com/healthcheck # OK

Apra https://miniflux.example.com nel browser. Viene visualizzata la pagina Sign In di Miniflux. La password dell'account admin si legge nel suo secret:

kubectl get secret miniflux-admin -o jsonpath='{.data.password}' | base64 -d; echo

Si connetta, quindi aggiunga un primo feed (Feeds → Add feed). Ogni feed e ogni articolo vengono salvati nel database tuto-db.

Se il certificato resta a False, vedere la verifica del certificato nella guida Ingress con TLS.


Passo 7: Monitorare l'applicazione​

L'addon Monitoring Agents, attivato al passo 1, raccoglie già le metriche e i log del cluster. Guardi prima cosa consumano i suoi due pod:

kubectl top pods -l app=miniflux

Risultato atteso: una riga per replica, con un consumo basso finché l'applicazione riceve poco traffico.

NAME CPU(cores) MEMORY(bytes)
miniflux-xxxxxxxxxx-xxxxx 1m 12Mi
miniflux-xxxxxxxxxx-yyyyy 1m 12Mi

Legga poi i log delle due repliche:

kubectl logs -l app=miniflux --prefix --tail=5

Risultato atteso: le ultime righe di ogni pod, precedute dal suo nome, tra cui Starting HTTP server.

Sul lato database, la pagina del cluster tuto-db mostra il suo stato e la scheda Users gestisce le password.

Vedere Come configurare il monitoraggio per i dettagli sugli agenti installati.


Passo 8: Pulizia​

Se non conserva l'applicazione, elimini le risorse per liberare le quote del progetto:

  1. Infrastructure > Kubernetes: apra il menu Actions di tuto-web, scelga Delete, inserisca il nome del cluster, quindi faccia clic su Permanently delete. L'applicazione, i suoi secret e il suo certificato scompaiono con il cluster.
  2. DB & Messaging → PostgreSQL: apra tuto-db, faccia clic su Delete cluster, inserisca il suo nome, quindi faccia clic su Permanently delete.
  3. Elimini il record DNS miniflux.example.com presso il suo provider.
avviso

Queste eliminazioni sono irreversibili: i dati del database vanno persi definitivamente.


Ha:

  • creato un cluster Kubernetes con Ingress NGINX, Cert-Manager e la supervisione;
  • creato un database PostgreSQL gestito senza esposizione su Internet;
  • collegato l'applicazione al database tramite l'host interno, con credenziali riposte in Secret;
  • distribuito l'applicazione su due repliche, dopo una prima migrazione dello schema;
  • pubblicato l'applicazione in HTTPS con un certificato Let's Encrypt automatico.

Per approfondire​

  • Alta disponibilità del database: ricrei il database con 2 (High Availability) repliche; il numero di repliche non può più essere modificato dopo la creazione. Vedere i concetti PostgreSQL.
  • Backup: programmi i backup del database, vedere Come configurare i backup.
  • Scalabilità: il gruppo di nodi sale da solo fino a 3 nodi; per adattare il numero di pod al carico, vedere Come configurare l'autoscaling.
  • Distribuzione continua: descriva l'applicazione in un repository Git e lasci che Flux la applichi, vedere Come distribuire con FluxCD.
  • Automazione: il cluster e il database si creano anche tramite l'API pubblica; le schede API degli avvii rapidi Kubernetes e PostgreSQL forniscono le richieste equivalenti.