# Kubernetes: Distribuire la prima applicazione > Guida pratica per distribuire un'applicazione su Kubernetes. Dall'installazione di minikube a Deployment, Service e ConfigMap con esempi concreti. - Published: 2026-02-12 - Updated: 2026-04-28 - Author: SharpSkill - Tags: kubernetes, k8s, container orchestration, devops, deployment - Reading time: 16 min --- Kubernetes (K8s) è diventato lo standard di fatto per l'orchestrazione dei container. Progettato da Google e attualmente mantenuto dalla CNCF, Kubernetes automatizza il deployment, la scalabilità e la gestione delle applicazioni containerizzate. Questa guida illustra la configurazione di un cluster locale e il deployment di una prima applicazione. > **Prerequisiti** > > Si consiglia di avere conoscenze di base di Docker prima di approfondire Kubernetes. I container sono i blocchi fondamentali che Kubernetes orchestra. Leggere prima la guida Docker semplifica notevolmente la comprensione dei concetti presentati qui. ## Comprendere l'architettura di Kubernetes Kubernetes si basa su un'architettura master-worker. Il Control Plane prende le decisioni globali sul cluster, mentre i Node eseguono i carichi di lavoro. ``` # Simplified Kubernetes Architecture ┌─────────────────────────────────────────────────────────────┐ │ CONTROL PLANE │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │ │ API Server │ │ Scheduler │ │ Controller Manager │ │ │ └─────────────┘ └─────────────┘ └─────────────────────┘ │ │ ┌─────────────────────────────────────────────────────────┐│ │ │ etcd ││ │ └─────────────────────────────────────────────────────────┘│ └─────────────────────────────────────────────────────────────┘ │ ┌────────────────────┼────────────────────┐ ▼ ▼ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ NODE 1 │ │ NODE 2 │ │ NODE 3 │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │ │ │ kubelet │ │ │ │ kubelet │ │ │ │ kubelet │ │ │ ├───────────┤ │ │ ├───────────┤ │ │ ├───────────┤ │ │ │ kube-proxy│ │ │ │ kube-proxy│ │ │ │ kube-proxy│ │ │ ├───────────┤ │ │ ├───────────┤ │ │ ├───────────┤ │ │ │ Pods │ │ │ │ Pods │ │ │ │ Pods │ │ │ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` L'API Server è il punto d'ingresso per tutti i comandi. etcd memorizza lo stato del cluster. Lo Scheduler assegna i Pod ai Node. I Controller mantengono lo stato desiderato del sistema. ## Configurare l'ambiente locale Esistono diverse opzioni per sperimentare Kubernetes localmente: minikube, kind, k3d o Docker Desktop. Minikube rimane la soluzione più popolare per imparare. ```bash # terminal # Install kubectl (Kubernetes client) curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" chmod +x kubectl sudo mv kubectl /usr/local/bin/ # Verify installation kubectl version --client # Client Version: v1.31.0 # Install minikube curl -LO https://storage.googleapis.com/minikube/releases/latest/minikube-linux-amd64 sudo install minikube-linux-amd64 /usr/local/bin/minikube # Start the local cluster minikube start --driver=docker --cpus=2 --memory=4096 # Check status minikube status # minikube: Running # cluster: Running # kubectl: Configured ``` Minikube crea un cluster Kubernetes a singolo nodo all'interno di una macchina virtuale o di un container Docker. Le risorse allocate (CPU, memoria) si possono adeguare alle esigenze. ```bash # terminal # Access the Kubernetes dashboard (web interface) minikube dashboard # Check cluster nodes kubectl get nodes # NAME STATUS ROLES AGE VERSION # minikube Ready control-plane 5m v1.31.0 # Detailed cluster information kubectl cluster-info ``` > **Alternative a Minikube** > > Kind (Kubernetes in Docker) si avvia più rapidamente e si adatta meglio ai test in CI/CD. K3d utilizza k3s, una distribuzione leggera di Kubernetes. Docker Desktop integra Kubernetes direttamente, ma consuma più risorse. ## Pod: l'unità di base Un Pod è la più piccola unità distribuibile in Kubernetes. Un Pod racchiude uno o più container che condividono la stessa rete e lo stesso storage. ```yaml # pod-simple.yaml apiVersion: v1 kind: Pod metadata: # Unique Pod name within the namespace name: nginx-pod # Labels for organization and selection labels: app: nginx environment: development spec: containers: # Main container definition - name: nginx # Docker image to use image: nginx:1.25-alpine # Ports exposed by the container ports: - containerPort: 80 # Container resource allocation resources: requests: memory: "64Mi" cpu: "100m" limits: memory: "128Mi" cpu: "200m" ``` Questo manifest YAML dichiara un Pod che contiene un singolo container nginx. Le label permettono di identificare e selezionare i Pod. Le risorse definiscono le garanzie minime (requests) e i limiti massimi (limits). ```bash # terminal # Create the Pod kubectl apply -f pod-simple.yaml # pod/nginx-pod created # List Pods kubectl get pods # NAME READY STATUS RESTARTS AGE # nginx-pod 1/1 Running 0 30s # Full Pod details kubectl describe pod nginx-pod # Container logs kubectl logs nginx-pod # Execute a command inside the Pod kubectl exec -it nginx-pod -- /bin/sh # Delete the Pod kubectl delete pod nginx-pod ``` I Pod sono effimeri per natura. In caso di crash o eliminazione, Kubernetes non li ricrea automaticamente. I Deployment risolvono questo limite. ## Deployment: gestione dichiarativa Un Deployment definisce lo stato desiderato per un insieme di Pod identici. Kubernetes mantiene automaticamente questo stato creando, aggiornando o eliminando i Pod quando necessario. ```yaml # deployment.yaml apiVersion: apps/v1 kind: Deployment metadata: # Deployment name name: webapp-deployment labels: app: webapp spec: # Desired number of replicas replicas: 3 # Selector to identify managed Pods selector: matchLabels: app: webapp # Template for Pod creation template: metadata: labels: app: webapp spec: containers: - name: webapp image: nginx:1.25-alpine ports: - containerPort: 80 resources: requests: memory: "64Mi" cpu: "100m" limits: memory: "128Mi" cpu: "200m" # Liveness probe: restarts container on failure livenessProbe: httpGet: path: / port: 80 initialDelaySeconds: 10 periodSeconds: 10 # Readiness probe: removes Pod from Service on failure readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 5 periodSeconds: 5 ``` Il Deployment crea un ReplicaSet che mantiene 3 Pod identici. Le probe verificano lo stato dei container e permettono a Kubernetes di reagire automaticamente ai problemi. ```bash # terminal # Create the Deployment kubectl apply -f deployment.yaml # deployment.apps/webapp-deployment created # Verify the Deployment kubectl get deployments # NAME READY UP-TO-DATE AVAILABLE AGE # webapp-deployment 3/3 3 3 1m # List Pods created by the Deployment kubectl get pods -l app=webapp # NAME READY STATUS RESTARTS AGE # webapp-deployment-7d9f8b6c4-abc12 1/1 Running 0 1m # webapp-deployment-7d9f8b6c4-def34 1/1 Running 0 1m # webapp-deployment-7d9f8b6c4-ghi56 1/1 Running 0 1m # Manual scaling kubectl scale deployment webapp-deployment --replicas=5 # Deployment history kubectl rollout history deployment webapp-deployment ``` Eliminare un Pod attiva automaticamente la creazione di un nuovo Pod per mantenere il numero desiderato di repliche. ## Service: esposizione di rete I Pod hanno indirizzi IP effimeri. I Service forniscono un indirizzo stabile per accedere a un insieme di Pod, con bilanciamento del carico integrato. ```yaml # service.yaml apiVersion: v1 kind: Service metadata: name: webapp-service spec: # Service type: ClusterIP (internal), NodePort, LoadBalancer type: ClusterIP # Selector to identify target Pods selector: app: webapp ports: # Port exposed by the Service - port: 80 # Target container port targetPort: 80 # Protocol (TCP by default) protocol: TCP ``` Questo Service ClusterIP è accessibile solo dall'interno del cluster. Le richieste verso `webapp-service:80` vengono distribuite tra i Pod che hanno la label `app: webapp`. ```bash # terminal # Create the Service kubectl apply -f service.yaml # service/webapp-service created # List Services kubectl get services # NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE # webapp-service ClusterIP 10.96.123.456 80/TCP 30s # Test from a temporary Pod kubectl run curl-test --rm -it --image=curlimages/curl -- curl webapp-service # Detailed Service description kubectl describe service webapp-service ``` Per esporre l'applicazione fuori dal cluster, è necessario un tipo NodePort o LoadBalancer. ```yaml # service-nodeport.yaml apiVersion: v1 kind: Service metadata: name: webapp-nodeport spec: type: NodePort selector: app: webapp ports: - port: 80 targetPort: 80 # Port on each Node (30000-32767) nodePort: 30080 ``` Con minikube, il comando `minikube service webapp-nodeport` apre automaticamente il browser sull'URL corretto. ## ConfigMap: configurazione esternalizzata Le ConfigMap separano la configurazione dal codice. I valori vengono iniettati come variabili d'ambiente o montati come file. ```yaml # configmap.yaml apiVersion: v1 kind: ConfigMap metadata: name: webapp-config data: # Simple key-value pairs APP_ENV: "production" LOG_LEVEL: "info" MAX_CONNECTIONS: "100" # Multiline configuration (complete file) nginx.conf: | server { listen 80; server_name localhost; location / { root /usr/share/nginx/html; index index.html; } location /health { return 200 'OK'; add_header Content-Type text/plain; } } ``` Le ConfigMap memorizzano dati non sensibili. Per i segreti (password, token), i Secret di Kubernetes sono più appropriati. ```yaml # deployment-with-config.yaml apiVersion: apps/v1 kind: Deployment metadata: name: webapp-configured spec: replicas: 2 selector: matchLabels: app: webapp-configured template: metadata: labels: app: webapp-configured spec: containers: - name: webapp image: nginx:1.25-alpine ports: - containerPort: 80 # Inject environment variables envFrom: - configMapRef: name: webapp-config # Or individual variables env: - name: SPECIFIC_VAR valueFrom: configMapKeyRef: name: webapp-config key: LOG_LEVEL # Mount configuration file volumeMounts: - name: nginx-config mountPath: /etc/nginx/conf.d/default.conf subPath: nginx.conf volumes: - name: nginx-config configMap: name: webapp-config ``` Questa configurazione inietta variabili d'ambiente e monta il file nginx.conf all'interno del container. ```bash # terminal # Apply resources kubectl apply -f configmap.yaml kubectl apply -f deployment-with-config.yaml # Verify environment variables kubectl exec deployment/webapp-configured -- printenv | grep APP_ENV # APP_ENV=production # Verify mounted file kubectl exec deployment/webapp-configured -- cat /etc/nginx/conf.d/default.conf ``` > **Aggiornamento delle ConfigMap** > > Modificare una ConfigMap non riavvia automaticamente i Pod. Per applicare le modifiche serve un riavvio manuale: `kubectl rollout restart deployment webapp-configured`. Strumenti come Reloader automatizzano questo processo. ## Secret: dati sensibili I Secret memorizzano informazioni sensibili come password, token o chiavi SSH. Sebbene siano codificati in base64, non sono cifrati per impostazione predefinita a riposo. ```yaml # secret.yaml apiVersion: v1 kind: Secret metadata: name: webapp-secrets type: Opaque # Values must be base64-encoded data: # echo -n 'admin' | base64 username: YWRtaW4= # echo -n 'supersecretpassword' | base64 password: c3VwZXJzZWNyZXRwYXNzd29yZA== --- # Alternative: stringData accepts plain text values apiVersion: v1 kind: Secret metadata: name: webapp-secrets-plain type: Opaque stringData: username: admin password: supersecretpassword ``` I Secret vengono iniettati allo stesso modo delle ConfigMap. ```yaml # deployment-with-secrets.yaml apiVersion: apps/v1 kind: Deployment metadata: name: webapp-secure spec: replicas: 1 selector: matchLabels: app: webapp-secure template: metadata: labels: app: webapp-secure spec: containers: - name: webapp image: nginx:1.25-alpine env: - name: DB_USERNAME valueFrom: secretKeyRef: name: webapp-secrets key: username - name: DB_PASSWORD valueFrom: secretKeyRef: name: webapp-secrets key: password ``` ```bash # terminal # Create the Secret kubectl apply -f secret.yaml # List Secrets (values are not displayed) kubectl get secrets # NAME TYPE DATA AGE # webapp-secrets Opaque 2 10s # Decode a value kubectl get secret webapp-secrets -o jsonpath='{.data.password}' | base64 -d # supersecretpassword ``` ## Namespace: isolamento logico I Namespace partizionano un cluster in ambienti virtuali isolati. Questa separazione consente di gestire più team o ambienti sullo stesso cluster. ```yaml # namespace.yaml apiVersion: v1 kind: Namespace metadata: name: development labels: environment: development --- apiVersion: v1 kind: Namespace metadata: name: staging labels: environment: staging ``` Ogni risorsa può essere creata in un namespace specifico. ```bash # terminal # Create namespaces kubectl apply -f namespace.yaml # List namespaces kubectl get namespaces # NAME STATUS AGE # default Active 1d # development Active 10s # staging Active 10s # Create a resource in a specific namespace kubectl apply -f deployment.yaml -n development # List Pods in a namespace kubectl get pods -n development # Change default namespace kubectl config set-context --current --namespace=development ``` Le risorse di namespace diversi sono isolate per impostazione predefinita. La comunicazione cross-namespace avviene tramite il DNS interno: `service-name.namespace.svc.cluster.local`. ## Applicazione completa: assemblare le risorse Di seguito un'applicazione completa che combina tutti i concetti presentati. ```yaml # complete-app.yaml --- # Dedicated Namespace apiVersion: v1 kind: Namespace metadata: name: myapp --- # ConfigMap for configuration apiVersion: v1 kind: ConfigMap metadata: name: myapp-config namespace: myapp data: APP_NAME: "MyApp" LOG_LEVEL: "info" --- # Secret for sensitive data apiVersion: v1 kind: Secret metadata: name: myapp-secrets namespace: myapp type: Opaque stringData: api-key: "sk-1234567890abcdef" --- # Deployment with 3 replicas apiVersion: apps/v1 kind: Deployment metadata: name: myapp namespace: myapp spec: replicas: 3 selector: matchLabels: app: myapp template: metadata: labels: app: myapp spec: containers: - name: myapp image: nginx:1.25-alpine ports: - containerPort: 80 envFrom: - configMapRef: name: myapp-config env: - name: API_KEY valueFrom: secretKeyRef: name: myapp-secrets key: api-key resources: requests: memory: "64Mi" cpu: "100m" limits: memory: "128Mi" cpu: "200m" livenessProbe: httpGet: path: / port: 80 initialDelaySeconds: 10 periodSeconds: 10 readinessProbe: httpGet: path: / port: 80 initialDelaySeconds: 5 periodSeconds: 5 --- # Service for internal exposure apiVersion: v1 kind: Service metadata: name: myapp-service namespace: myapp spec: type: ClusterIP selector: app: myapp ports: - port: 80 targetPort: 80 --- # NodePort Service for external access (development) apiVersion: v1 kind: Service metadata: name: myapp-nodeport namespace: myapp spec: type: NodePort selector: app: myapp ports: - port: 80 targetPort: 80 nodePort: 30100 ``` Questo unico file distribuisce un'applicazione completa con configurazione esternalizzata, segreti, alta disponibilità ed esposizione di rete. ```bash # terminal # Deploy the complete application kubectl apply -f complete-app.yaml # Verify all resources kubectl get all -n myapp # NAME READY STATUS RESTARTS AGE # pod/myapp-7d9f8b6c4-abc12 1/1 Running 0 30s # pod/myapp-7d9f8b6c4-def34 1/1 Running 0 30s # pod/myapp-7d9f8b6c4-ghi56 1/1 Running 0 30s # # NAME TYPE CLUSTER-IP PORT(S) AGE # service/myapp-service ClusterIP 10.96.123.456 80/TCP 30s # service/myapp-nodeport NodePort 10.96.123.789 80:30100/TCP 30s # # NAME READY UP-TO-DATE AVAILABLE AGE # deployment.apps/myapp 3/3 3 3 30s # Access the application with minikube minikube service myapp-nodeport -n myapp ``` ## Aggiornamenti e rollback Kubernetes facilita gli aggiornamenti progressivi e i rollback. ```bash # terminal # Update the Deployment image kubectl set image deployment/myapp myapp=nginx:1.26-alpine -n myapp # Track deployment in real-time kubectl rollout status deployment/myapp -n myapp # Waiting for deployment "myapp" rollout to finish: 1 out of 3 new replicas updated # Waiting for deployment "myapp" rollout to finish: 2 out of 3 new replicas updated # deployment "myapp" successfully rolled out # Revision history kubectl rollout history deployment/myapp -n myapp # REVISION CHANGE-CAUSE # 1 # 2 # Rollback to previous revision kubectl rollout undo deployment/myapp -n myapp # Rollback to a specific revision kubectl rollout undo deployment/myapp --to-revision=1 -n myapp ``` La strategia di aggiornamento predefinita (RollingUpdate) sostituisce progressivamente i Pod vecchi con quelli nuovi, garantendo la disponibilità continua. ## Comandi kubectl essenziali ```bash # terminal # ======================================== # General Information # ======================================== kubectl cluster-info # Cluster info kubectl get nodes -o wide # Nodes with details kubectl api-resources # List resource types # ======================================== # Resource Management # ======================================== kubectl get all # All namespace resources kubectl get pods -A # Pods from all namespaces kubectl get pods -o wide # Pods with IP and Node kubectl get pods -w # Watch mode (real-time) # ======================================== # Inspection and Debugging # ======================================== kubectl describe pod # Full details kubectl logs -f # Streaming logs kubectl logs -c # Specific container logs kubectl exec -it -- /bin/sh # Interactive shell kubectl port-forward 8080:80 # Local tunnel to Pod # ======================================== # Editing and Deletion # ======================================== kubectl edit deployment # Live editing (vi) kubectl delete -f manifest.yaml # Delete via file kubectl delete pod --force # Force deletion ``` ## Conclusione Kubernetes trasforma la gestione delle applicazioni containerizzate fornendo un framework dichiarativo, resiliente ed estensibile. I concetti fondamentali presentati qui costituiscono la base per i deployment pronti per la produzione. ### Checklist per un primo deployment Kubernetes - ✅ Cluster locale funzionante (minikube, kind o k3d) - ✅ kubectl installato e configurato - ✅ Deployment con repliche e health probe - ✅ Service per l'esposizione di rete - ✅ ConfigMap per la configurazione esternalizzata - ✅ Secret per i dati sensibili - ✅ Namespace per l'isolamento - ✅ Limiti di risorse definiti (requests/limits) - ✅ Strategia di aggiornamento e rollback padroneggiate Padroneggiare Kubernetes apre la strada ad architetture cloud-native scalabili. I prossimi passi includono l'esplorazione degli Ingress Controller per il routing HTTP, dei PersistentVolume per lo storage e di Helm per la gestione dei pacchetti. Kubernetes diventa una risorsa importante durante i colloqui DevOps e SRE. --- Source: SharpSkill (https://sharpskill.dev), tech interview preparation for your real stack. HTML version of this page: https://sharpskill.dev/it/blog/devops/kubernetes-deploying-first-application