pos-system/.agent/rules/deployment-kubernetes.md

trigger

trigger
always_on

Kubernetes Deployment Patterns

When to Use This Skill

Use this skill when:

• Deploying services to staging/production environments
• Creating or updating Kubernetes manifests
• Configuring autoscaling (HPA/VPA)
• Setting up ingress and load balancing
• Managing secrets and configmaps
• Troubleshooting deployment issues
• Implementing health checks and probes
• Setting up monitoring and logging

Core Concepts

Deployment Strategy

• Rolling updates for zero-downtime deployments
• Resource limits and requests for stability
• Health checks (liveness/readiness probes)
• Horizontal Pod Autoscaler (HPA) for auto-scaling
• ConfigMaps for configuration, Secrets for sensitive data

Key Patterns

Deployment Manifest

apiVersion: apps/v1
kind: Deployment
metadata:
  name: auth-service
  namespace: goodgo
spec:
  replicas: 3
  selector:
    matchLabels:
      app: auth-service
  template:
    spec:
      containers:
      - name: auth-service
        image: goodgo/auth-service:v1.0.0
        resources:
          requests: { memory: "256Mi", cpu: "250m" }
          limits: { memory: "512Mi", cpu: "500m" }
        livenessProbe:
          httpGet: { path: /health, port: 3000 }
          initialDelaySeconds: 30
        readinessProbe:
          httpGet: { path: /ready, port: 3000 }
          initialDelaySeconds: 5
        env:
        - name: DATABASE_URL
          valueFrom:
            secretKeyRef: { name: db-secrets, key: url }

HPA Configuration

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: auth-service
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target: { type: Utilization, averageUtilization: 70 }

Ingress

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls:
  - hosts: [api.goodgo.com]
    secretName: api-tls-secret
  rules:
  - host: api.goodgo.com
    http:
      paths:
      - path: /auth
        pathType: Prefix
        backend:
          service: { name: auth-service, port: { number: 80 } }

Best Practices

• Resource Management: Always set resource requests and limits, use HPA for scaling
• Configuration: Use ConfigMaps for config, Secrets for sensitive data
• Health Checks: Implement both liveness and readiness probes
• Deployment: Use rolling updates, set maxSurge/maxUnavailable appropriately
• Security: Run as non-root, use network policies, update base images regularly
• Monitoring: Expose metrics endpoint, set up alerts

Common Mistakes

1. No Resource Limits: Pods consuming all node resources

   # GOOD: Set limits
   resources:
     requests: { memory: "256Mi", cpu: "250m" }
     limits: { memory: "512Mi", cpu: "500m" }
   

2. Missing Health Checks: K8s can't detect unhealthy pods

   # GOOD: Add probes
   livenessProbe:
     httpGet: { path: /health, port: 3000 }
   readinessProbe:
     httpGet: { path: /ready, port: 3000 }
   

3. Hardcoded Secrets: Exposing sensitive data

   # BAD: value: "secret123"
   # GOOD: valueFrom: secretKeyRef: { name: secrets, key: password }
   

4. Using latest Tag: Unpredictable deployments

   # BAD: image: app:latest
   # GOOD: image: app:v1.2.3
   

Quick Reference

Resource	Command
Apply manifests	kubectl apply -f kubernetes/
Get pods	kubectl get pods -n goodgo
Get logs	kubectl logs -f deployment/app -n goodgo
Scale	kubectl scale deployment/app --replicas=5
Rollback	kubectl rollout undo deployment/app
Port forward	kubectl port-forward svc/app 3000:80
Exec into pod	kubectl exec -it pod-name -- /bin/sh

Resource Sizing Guidelines:

Service Type	Memory Request	Memory Limit	CPU Request	CPU Limit
Microservice	256Mi	512Mi	250m	500m
API Gateway	512Mi	1Gi	500m	1000m
Database	1Gi	2Gi	500m	1000m

Health Check Defaults:

livenessProbe:
  initialDelaySeconds: 30  # Wait for app startup
  periodSeconds: 10        # Check every 10s
  failureThreshold: 3      # Restart after 3 failures

readinessProbe:
  initialDelaySeconds: 5   # Start checking early
  periodSeconds: 5         # Check frequently
  failureThreshold: 3      # Remove from LB after 3 failures

Resources

• Kubernetes Documentation - Official K8s docs
• Helm - K8s package manager
• Detailed Manifests
• Infrastructure as Code - Terraform patterns
• Observability & Monitoring - Health checks
• Service Discovery - K8s DNS patterns