# Basic Pod Example with Detailed Comments
# This example shows a simple nginx pod with health checks and resource limits
#
# 🎯 What this does: Creates a single nginx web server pod that:
# - Runs nginx web server on port 80
# - Has health checks to ensure it's working
# - Has resource limits to prevent it from consuming too much CPU/memory
# - Includes security best practices
#
# 📚 EDUCATIONAL EXAMPLE (not from your codebase)
# This is a learning example. Your codebase uses Helm charts and Deployments instead of direct Pods.
#
# ⚠️  IMPORTANT: Direct Pod creation is NOT good practice for production!
# This example is for learning purposes only. In production, you should use:
# - Deployments (for applications)
# - StatefulSets (for databases)
# - Helm charts (for complex applications)
# - kubectl apply (for declarative deployments)

apiVersion: v1                    # ← Kubernetes API version for Pod resources
kind: Pod                        # ← Resource type: Pod (smallest deployable unit)
metadata:                         # ← Metadata section: describes the pod
  name: nginx-pod                # ← Unique name for this pod in the namespace
  namespace: default             # ← Namespace where pod will be created (default if not specified)
  labels:                        # ← Labels for organizing and selecting pods
    app: nginx                   # ← Label: identifies this as an nginx application
    version: v1                 # ← Label: version of the application
    environment: development    # ← Label: environment this pod runs in
spec:                           # ← Specification: defines what the pod should do
  containers:                   # ← List of containers in this pod
  - name: nginx                 # ← Container name (used for logs, exec, etc.)
    image: nginx:latest         # ← Docker image to run (nginx with latest tag)
    ports:                      # ← Ports the container exposes
    - containerPort: 80         # ← Port 80 inside the container (nginx default)
      name: http                # ← Name for this port (useful for service references)
      protocol: TCP             # ← Protocol (TCP is default)

    # 🔧 Resource Management
    # These limits prevent the pod from consuming too many resources
    # Think of it like setting a budget for CPU and memory usage
    resources:
      requests:                 # ← Minimum resources guaranteed to the pod
        memory: "64Mi"          # ← 64 megabytes of RAM (minimum guaranteed)
        cpu: "250m"             # ← 0.25 CPU cores (250 millicores = 25% of 1 CPU)
      limits:                   # ← Maximum resources the 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 the pod is healthy
    # Like a doctor checking your vital signs!
    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 (nginx startup time)
      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

    # 🔒 Security Context
    # These settings make the pod more secure
    # Like locking your doors and windows!
    securityContext:
      allowPrivilegeEscalation: false  # ← Prevent the container from gaining root privileges
      readOnlyRootFilesystem: true    # ← Make the root filesystem read-only (more secure)
      capabilities:                   # ← Remove unnecessary Linux capabilities
        drop:                         # ← Drop these capabilities
        - ALL                         # ← Drop ALL capabilities (most restrictive)
      runAsNonRoot: true              # ← Don't run as root user
      runAsUser: 101                 # ← Run as user ID 101 (nginx user)

    # 📁 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
      readOnly: false            # ← Allow read/write access

  # 💾 Volumes
  # These define storage that can be mounted into containers
  volumes:
  - name: tmp-volume             # ← Volume name (matches volumeMounts above)
    emptyDir: {}                # ← Empty directory volume (temporary, deleted when pod dies)
    # emptyDir creates a temporary directory that exists as long as the pod exists
    # Perfect for temporary files, caches, etc.

# 🚀 How to use this (FOR LEARNING ONLY):
# kubectl apply -f basic-pod.yaml
# kubectl get pods                    # Check if pod is running
# kubectl logs nginx-pod              # View nginx logs
# kubectl port-forward nginx-pod 8080:80  # Access nginx at http://localhost:8080
# kubectl exec -it nginx-pod -- /bin/bash  # Get a shell inside the pod

# 🏭 YOUR CODEBASE COMPARISON:
# 
# ❌ Your codebase does NOT create Pods directly like this
# ✅ Your codebase uses Helm charts and Deployments instead
# 
# Example from your codebase:
# - Helm charts in: freeleaps-ops/freeleaps/helm-pkg/
# - Deployments with replicas, rolling updates, etc.
# - Automatic pod creation via Deployment controllers
# 
# Commands your codebase actually uses:
# helm install/upgrade <release> <chart> --namespace <namespace> -f <values.yaml>
# kubectl get pods -n <namespace> -l app.kubernetes.io/name=<app-name>

# 🎯 PRODUCTION BEST PRACTICES:
#
# ❌ DON'T DO THIS (bad practices):
# kubectl run nginx --image=nginx:latest                    # Creates standalone Pod
# kubectl run my-app --image=my-app:latest --port=8080      # No self-healing
# kubectl run database --image=postgres:13 --port=5432      # No scaling
#
# ✅ DO THIS INSTEAD (good practices):
# kubectl create deployment nginx --image=nginx:latest       # Creates Deployment
# helm install my-app ./my-app-chart --namespace my-app     # Use Helm charts
# kubectl apply -f deployment.yaml                          # Declarative deployment
# kubectl apply -f statefulset.yaml                        # For databases
#
# 🔧 When kubectl run is OK (limited use cases):
# kubectl run debug-pod --image=busybox --rm -it --restart=Never -- nslookup my-service
# kubectl run test-pod --image=nginx --rm -it --restart=Never -- curl http://my-service:80

# 📚 Learn more:
# - Pods: https://kubernetes.io/docs/concepts/workloads/pods/
# - Deployments: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/
# - Helm: https://helm.sh/docs/
# - Health Checks: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/
# - Security Context: https://kubernetes.io/docs/tasks/configure-pod-container/security-context/
# - Resource Management: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/