# Production-Ready Deployment Example with Detailed Comments
# This example shows a deployment that creates and manages multiple nginx pods
# 
# 🎯 What this does: Creates a deployment that:
# - Runs 3 copies of nginx web server (replicas)
# - Automatically restarts failed pods
# - Supports rolling updates (zero downtime)
# - Includes security, health checks, and resource management
# - Can be easily scaled up or down

# 📊 ASCII Diagram: How Deployments Work
# 
# ┌─────────────────────────────────────────────────────────────┐
# │                    DEPLOYMENT                               │
# │  ┌─────────────────────────────────────────────────────┐   │
# │  │  name: web-app                                      │   │
# │  │  replicas: 3                                        │   │
# │  └─────────────────────────────────────────────────────┘   │
# │                           │                                │
# │                           ▼                                │
# │  ┌─────────────────────────────────────────────────────┐   │
# │  │              POD TEMPLATE                            │   │
# │  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │   │
# │  │  │   POD 1     │  │   POD 2     │  │   POD 3     │  │   │
# │  │  │ nginx:latest│  │ nginx:latest│  │ nginx:latest│  │   │
# │  │  │ port: 80    │  │ port: 80    │  │ port: 80    │  │   │
# │  │  │ IP: 10.0.1.1│  │ IP: 10.0.1.2│  │ IP: 10.0.1.3│  │   │
# │  │  └─────────────┘  └─────────────┘  └─────────────┘  │   │
# │  └─────────────────────────────────────────────────────┘   │
# └─────────────────────────────────────────────────────────────┘
# 
# 🔄 Rolling Update Process:
# ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
# │   OLD POD   │  │   NEW POD   │  │   OLD POD   │
# │ nginx:v1.0  │  │ nginx:v1.1  │  │ nginx:v1.0  │
# └─────────────┘  └─────────────┘  └─────────────┘
#      │                 │                 │
#      ▼                 ▼                 ▼
# ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
# │   NEW POD   │  │   NEW POD   │  │   NEW POD   │
# │ nginx:v1.1  │  │ nginx:v1.1  │  │ nginx:v1.1  │
# └─────────────┘  └─────────────┘  └─────────────┘

apiVersion: apps/v1              # ← Kubernetes API version for Deployment resources
kind: Deployment                 # ← Resource type: Deployment (manages multiple pods)
metadata:                         # ← Metadata section: describes the deployment
  name: web-app                  # ← Unique name for this deployment
  namespace: my-app              # ← Namespace where deployment will be created
  labels:                        # ← Labels for organizing and selecting deployments
    app: web-app                 # ← Label: identifies this as a web application
    version: v1                  # ← Label: version of the application
    environment: production      # ← Label: environment this runs in
    team: backend               # ← Label: team responsible for this app
spec:                           # ← Specification: defines what the deployment should do
  replicas: 3                   # ← Number of pod copies to run (3 nginx instances)
  # Think of replicas like having 3 backup singers - if one gets sick, 
  # the show goes on with the other 2!
  
  selector:                     # ← How to find the pods this deployment manages
    matchLabels:                # ← Match pods with these labels
      app: web-app              # ← Only manage pods with label app=web-app
  
  template:                     # ← Template for creating new pods
    metadata:                   # ← Metadata for pods created from this template
      labels:                   # ← Labels applied to all pods created by this deployment
        app: web-app            # ← Must match selector above
        version: v1            # ← Version label for tracking
        environment: production # ← Environment label
        team: backend          # ← Team label
    
    spec:                      # ← Pod specification (same as basic-pod.yaml)
      # 🔒 Pod-Level Security Context
      # These settings apply to the entire pod
      securityContext:
        runAsNonRoot: true     # ← Don't run any container as root
        runAsUser: 1000        # ← Run as user ID 1000
        fsGroup: 2000          # ← Set group ID for mounted volumes
      
      containers:              # ← List of containers in each pod
      - name: web-app          # ← Container name
        image: nginx:latest    # ← Docker image to run
        ports:                 # ← Ports the container exposes
        - containerPort: 80    # ← Port 80 inside the container
          name: http           # ← Name for this port
        # 🔧 Resource Management
        # These limits prevent pods from consuming too many resources
        # Like setting a budget for each pod
        resources:
          requests:            # ← Minimum resources guaranteed to each pod
            memory: "64Mi"     # ← 64 megabytes of RAM (minimum guaranteed)
            cpu: "250m"        # ← 0.25 CPU cores (250 millicores = 25% of 1 CPU)
          limits:              # ← Maximum resources each pod can use
            memory: "128Mi"    # ← 128 megabytes of RAM (maximum allowed)
            cpu: "500m"        # ← 0.5 CPU cores (500 millicores = 50% of 1 CPU)
        
        # 🏥 Health Checks
        # These tell Kubernetes how to check if each pod is healthy
        # Like having a health monitor for each pod
        livenessProbe:         # ← Checks if the pod is alive (restarts if failed)
          httpGet:             # ← Use HTTP GET request to check health
            path: /            # ← Check the root path of nginx
            port: 80          # ← Check on port 80
          initialDelaySeconds: 30  # ← Wait 30 seconds before first check
          periodSeconds: 10   # ← Check every 10 seconds
          timeoutSeconds: 5   # ← Fail if response takes longer than 5 seconds
          failureThreshold: 3 # ← Restart pod after 3 consecutive failures
        
        readinessProbe:        # ← Checks if the pod is ready to receive traffic
          httpGet:             # ← Use HTTP GET request to check readiness
            path: /            # ← Check the root path
            port: 80          # ← Check on port 80
          initialDelaySeconds: 5   # ← Wait 5 seconds before first check
          periodSeconds: 5    # ← Check every 5 seconds
          timeoutSeconds: 3   # ← Fail if response takes longer than 3 seconds
          failureThreshold: 3 # ← Mark as not ready after 3 consecutive failures
        
        # 🔒 Container-Level Security Context
        # These settings make each container more secure
        securityContext:
          allowPrivilegeEscalation: false  # ← Prevent gaining root privileges
          readOnlyRootFilesystem: true     # ← Make root filesystem read-only
          capabilities:                    # ← Remove unnecessary Linux capabilities
            drop:                          # ← Drop these capabilities
            - ALL                          # ← Drop ALL capabilities (most restrictive)
        
        # 📁 Volume Mounts
        # These allow the container to access files from the pod
        volumeMounts:
        - name: tmp-volume      # ← Name of the volume to mount
          mountPath: /tmp      # ← Where to mount it inside the container
      
      # 💾 Volumes
      # These define storage that can be mounted into containers
      volumes:
      - name: tmp-volume        # ← Volume name (matches volumeMounts above)
        emptyDir: {}           # ← Empty directory volume (temporary)

# 🚀 How to use this:
# kubectl apply -f deployment-example.yaml
# kubectl get deployments                    # Check deployment status
# kubectl get pods -l app=web-app           # See all pods created by this deployment
# kubectl scale deployment web-app --replicas=5  # Scale up to 5 replicas
# kubectl set image deployment/web-app web-app=nginx:1.21  # Update to new version
# kubectl rollout status deployment/web-app  # Check rollout progress
# kubectl rollout undo deployment/web-app    # Rollback to previous version

# 📊 What happens when you apply this:
# 1. Kubernetes creates 3 nginx pods
# 2. Each pod runs nginx on port 80
# 3. Health checks ensure pods are working
# 4. If a pod fails, deployment automatically creates a new one
# 5. Load balancer can send traffic to any of the 3 pods

# 📚 Learn more:
# - Deployments: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
# - Rolling Updates: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-update-deployment
# - Scaling: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#scaling-a-deployment
# - Rollbacks: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#rolling-back-a-deployment