YAML per Kubernetes: Pattern Essenziali per i Manifest
Kubernetes viene configurato interamente tramite manifest YAML. Ogni pod, deployment, service e ingress è definito in YAML. Padroneggiare questi pattern è essenziale per chiunque lavori con l'orchestrazione dei container. Questa guida copre i tipi di risorse più importanti con esempi pronti per la produzione.
I Quattro Campi Obbligatori
Ogni manifest Kubernetes necessita di:
apiVersion: apps/v1 # Versione API per questo tipo di risorsa
kind: Deployment # Tipo di risorsa
metadata: # Identificazione della risorsa
name: my-app
namespace: production
labels:
app: my-app
spec: # Specifica dello stato desiderato
# ... configurazione specifica della risorsa
Deployment
La risorsa più comune — gestisce un insieme di pod identici:
apiVersion: apps/v1
kind: Deployment
metadata:
name: api-server
labels:
app: api-server
environment: production
spec:
replicas: 3
selector:
matchLabels:
app: api-server
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
template:
metadata:
labels:
app: api-server
spec:
containers:
- name: api
image: myapp/api:v1.2.3
ports:
- containerPort: 8080
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: db-credentials
key: url
resources:
requests:
cpu: 100m
memory: 128Mi
limits:
cpu: 500m
memory: 512Mi
livenessProbe:
httpGet:
path: /healthz
port: 8080
initialDelaySeconds: 15
periodSeconds: 10
readinessProbe:
httpGet:
path: /ready
port: 8080
initialDelaySeconds: 5
periodSeconds: 5
Pattern Chiave
Imposta sempre richieste e limiti delle risorse: Senza di essi, un singolo pod può consumare tutte le risorse del nodo.
Configura sempre le sonde di salute:
livenessProbe: Riavvia il pod se diventa non responsivoreadinessProbe: Smetti di inviare traffico finché il pod non è pronto
Usa tag immagine specifici: Non usare mai latest in produzione — rende impossibili i rollback.
Service
Espone i pod al traffico di rete:
apiVersion: v1
kind: Service
metadata:
name: api-server
spec:
type: ClusterIP
selector:
app: api-server
ports:
- port: 80
targetPort: 8080
protocol: TCP
Tipi di Service:
- ClusterIP (predefinito): Solo accesso interno al cluster
- NodePort: Espone su ogni IP del nodo a una porta statica
- LoadBalancer: Provisiona un load balancer cloud
- ExternalName: Mappa a un nome DNS
ConfigMap e Secret
ConfigMap (dati non sensibili)
apiVersion: v1
kind: ConfigMap
metadata:
name: app-config
data:
LOG_LEVEL: "info"
MAX_CONNECTIONS: "100"
config.yaml: |
server:
port: 8080
timeout: 30s
Secret (dati sensibili)
apiVersion: v1
kind: Secret
metadata:
name: db-credentials
type: Opaque
stringData:
url: "postgres://user:password@db:5432/myapp"
api-key: "sk-1234567890"
Utilizzo nei Pod
# Come variabili d'ambiente
env:
- name: LOG_LEVEL
valueFrom:
configMapKeyRef:
name: app-config
key: LOG_LEVEL
# Come file montato
volumes:
- name: config
configMap:
name: app-config
Ingress
Instrada il traffico HTTP esterno ai service:
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: api-ingress
annotations:
nginx.ingress.kubernetes.io/ssl-redirect: "true"
spec:
ingressClassName: nginx
tls:
- hosts:
- api.example.com
secretName: tls-secret
rules:
- host: api.example.com
http:
paths:
- path: /
pathType: Prefix
backend:
service:
name: api-server
port:
number: 80
Horizontal Pod Autoscaler
Scala i pod in base a CPU o metriche personalizzate:
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
name: api-server-hpa
spec:
scaleTargetRef:
apiVersion: apps/v1
kind: Deployment
name: api-server
minReplicas: 2
maxReplicas: 10
metrics:
- type: Resource
resource:
name: cpu
target:
type: Utilization
averageUtilization: 70
Errori Comuni
1. Errori di Indentazione
L'indentazione YAML è critica in Kubernetes. Uno spazio fuori posto cambia completamente la struttura. Valida i tuoi manifest con il nostro Validatore YAML.
2. Mismatch delle Label
Il selettore del Service deve corrispondere esattamente alle label del Pod. Un mismatch significa che il Service non può trovare pod a cui instradare il traffico.
3. Limiti delle Risorse Mancanti
I pod senza limiti di risorse possono affamare altri workload. Includi sempre sia le richieste (minimo garantito) che i limiti (massimo consentito).
4. Tag Immagine Mutabili
Usare latest o altri tag mutabili rende impossibili i rollback e i deploy imprevedibili. Fissa a versioni specifiche o usa digest immutabili.
Manifest Multi-Documento
Combina risorse correlate in un unico file usando --- come separatore di documento:
apiVersion: apps/v1
kind: Deployment
metadata:
name: api-server
spec:
# ... spec del deployment
---
apiVersion: v1
kind: Service
metadata:
name: api-server
spec:
# ... spec del service
Per approfondimenti sui pattern di sintassi YAML, vedi il nostro tutorial sulla sintassi YAML.
FAQ
Devo scrivere YAML Kubernetes a mano o usare generatori?
Inizia scrivendo YAML a mano per capire la struttura. Per la produzione, usa strumenti come Helm (manifest templated), Kustomize (personalizzazione basata su overlay) o CDK8s (generazione basata su codice). Questi strumenti riducono la ripetizione e abilitano la configurazione specifica per ambiente senza duplicare i manifest.
Come faccio a debuggare errori YAML Kubernetes?
Usa kubectl apply --dry-run=client -f manifest.yaml per validare senza applicare. Per errori di sintassi, kubectl explain deployment.spec.template.spec.containers mostra la struttura attesa. Gli strumenti kubeval e kubeconform validano contro gli schema API di Kubernetes prima del deploy.
Risorse Correlate
- Validatore YAML — Valida i manifest Kubernetes
- YAML per Docker Compose — Pattern YAML per Docker
- Best Practice per il Linting YAML — Cattura errori prima del deploy