@rubix0270/arboris 1.0.1 → 1.0.3

package/prisma/skills/kubernetes-patterns/SKILL.md

@@ -1,756 +0,0 @@
----
-name: kubernetes-patterns
-description: Kubernetes workload patterns, resource management, RBAC, probes, autoscaling, ConfigMap/Secret handling, and kubectl debugging for production-grade deployments.
-metadata:
-  origin: ECC
----
-
-# Kubernetes Patterns
-
-Production-grade Kubernetes patterns for deploying, managing, and debugging workloads reliably.
-
-## When to Activate
-
-- Writing Kubernetes manifests (Deployments, Services, Ingress, Jobs)
-- Configuring resource requests/limits, liveness/readiness probes
-- Setting up RBAC, namespaces, or ServiceAccounts
-- Managing configuration and secrets in K8s
-- Debugging CrashLoopBackOff, OOMKilled, pending pods, or image pull errors
-- Configuring HPA (Horizontal Pod Autoscaler) or PodDisruptionBudgets
-- Reviewing K8s YAML for security or correctness
-
-## When to Use
-
-> Same as **When to Activate** above. This alias satisfies repo skill-format conventions. Use this skill any time you are writing, reviewing, or debugging Kubernetes YAML and workloads.
-
-## How It Works
-
-This skill provides **copy-pasteable, production-grade YAML patterns** and **kubectl debugging commands** organized by task:
-
-1. **Deployment template** — A fully configured production `Deployment` with security context, rolling update strategy, all three probe types, resource limits, and environment injection from ConfigMap/Secret.
-2. **Probes** — Decision table for startup vs liveness vs readiness, with correct `failureThreshold × periodSeconds` math.
-3. **Services & Ingress** — ClusterIP, LoadBalancer, and TLS Ingress patterns with cert-manager annotations.
-4. **ConfigMaps & Secrets** — `envFrom`, file-mount, and external secrets guidance.
-5. **Resource management** — Requests vs limits rules of thumb by workload type (web API, JVM, worker, sidecar).
-6. **RBAC** — Least-privilege ServiceAccount → Role → RoleBinding chain.
-7. **HPA & PDB** — Autoscaling and node-drain safety configurations.
-8. **Jobs & CronJobs** — One-off and scheduled workload patterns with correct `restartPolicy`.
-9. **kubectl cheatsheet** — Logs, exec, rollback, port-forward, dry-run, and common error diagnosis commands.
-10. **Anti-patterns & checklist** — What NOT to do, and a security/reliability/observability checklist.
-
-## Examples
-
-See the sections below for complete, runnable examples. Quick references:
-
-| Task | Jump to |
-|------|---------|
-| Full production Deployment YAML | [Core Workload Patterns](#core-workload-patterns) |
-| Probe configuration | [Probes](#probes--liveness-readiness-startup) |
-| RBAC least-privilege setup | [RBAC](#rbac--roles-and-serviceaccounts) |
-| Debug a CrashLoopBackOff | [kubectl Debugging Cheatsheet](#kubectl-debugging-cheatsheet) |
-| Autoscaling | [HPA](#horizontal-pod-autoscaler-hpa) |
-
----
-
-## Core Workload Patterns
-
-### Deployment — Production Template
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: my-app
-  namespace: my-namespace
-  labels:
-    app: my-app
-    version: "1.0.0"
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: my-app
-  strategy:
-    type: RollingUpdate
-    rollingUpdate:
-      maxSurge: 1          # Allow 1 extra pod during update
-      maxUnavailable: 0    # Never reduce below desired count
-  template:
-    metadata:
-      labels:
-        app: my-app
-        version: "1.0.0"
-    spec:
-      # Security context at pod level
-      securityContext:
-        runAsNonRoot: true
-        runAsUser: 1001
-        fsGroup: 1001
-
-      # Graceful shutdown
-      terminationGracePeriodSeconds: 30
-
-      containers:
-        - name: my-app
-          image: ghcr.io/org/my-app:1.0.0   # Never use :latest
-          imagePullPolicy: IfNotPresent
-
-          ports:
-            - containerPort: 8080
-              protocol: TCP
-
-          # Resource requests AND limits are both required
-          resources:
-            requests:
-              cpu: "100m"
-              memory: "128Mi"
-            limits:
-              cpu: "500m"
-              memory: "256Mi"
-
-          # Container security context
-          securityContext:
-            allowPrivilegeEscalation: false
-            readOnlyRootFilesystem: true
-            capabilities:
-              drop:
-                - ALL
-
-          # Probes (see Probes section below)
-          startupProbe:
-            httpGet:
-              path: /health
-              port: 8080
-            failureThreshold: 30
-            periodSeconds: 5
-          livenessProbe:
-            httpGet:
-              path: /health
-              port: 8080
-            initialDelaySeconds: 0
-            periodSeconds: 30
-            failureThreshold: 3
-          readinessProbe:
-            httpGet:
-              path: /ready
-              port: 8080
-            initialDelaySeconds: 5
-            periodSeconds: 10
-            failureThreshold: 2
-
-          # Environment from ConfigMap and Secret
-          envFrom:
-            - configMapRef:
-                name: my-app-config
-          env:
-            - name: DB_PASSWORD
-              valueFrom:
-                secretKeyRef:
-                  name: my-app-secrets
-                  key: db-password
-
-          # Writable tmp directory when readOnlyRootFilesystem: true
-          volumeMounts:
-            - name: tmp
-              mountPath: /tmp
-
-      volumes:
-        - name: tmp
-          emptyDir: {}
-```
-
----
-
-## Probes — Liveness, Readiness, Startup
-
-Understanding when to use each probe is critical:
-
-| Probe | Failure Action | Use For |
-|-------|---------------|---------|
-| `startupProbe` | Kills container if slow to start | Slow-starting apps (JVM, Python) |
-| `livenessProbe` | Restarts container | Deadlock / hung process detection |
-| `readinessProbe` | Removes from Service endpoints | Temporary unavailability (DB reconnect) |
-
-```yaml
-# Correct pattern: startupProbe covers slow startup,
-# then liveness/readiness take over
-startupProbe:
-  httpGet:
-    path: /health
-    port: 8080
-  failureThreshold: 30  # 30 * 5s = 150s max startup time
-  periodSeconds: 5
-
-livenessProbe:
-  httpGet:
-    path: /health
-    port: 8080
-  periodSeconds: 30
-  failureThreshold: 3   # 3 * 30s = 90s before restart
-
-readinessProbe:
-  httpGet:
-    path: /ready         # Separate endpoint: checks DB, cache, etc.
-    port: 8080
-  periodSeconds: 10
-  failureThreshold: 2
-```
-
-```yaml
-# WRONG: initialDelaySeconds without startupProbe
-# If the app takes 60s to start, set a startupProbe instead
-livenessProbe:
-  httpGet:
-    path: /health
-    port: 8080
-  initialDelaySeconds: 60   # BAD: Arbitrary wait, race condition
-```
-
----
-
-## Services and Ingress
-
-### Service Types
-
-```yaml
-# ClusterIP (default) — internal-only
-apiVersion: v1
-kind: Service
-metadata:
-  name: my-app
-  namespace: my-namespace
-spec:
-  selector:
-    app: my-app
-  ports:
-    - port: 80
-      targetPort: 8080
-      protocol: TCP
-  type: ClusterIP
-```
-
-```yaml
-# LoadBalancer — external traffic (cloud providers)
-spec:
-  type: LoadBalancer
-  ports:
-    - port: 443
-      targetPort: 8080
-```
-
-### Ingress with TLS
-
-```yaml
-apiVersion: networking.k8s.io/v1
-kind: Ingress
-metadata:
-  name: my-app
-  namespace: my-namespace
-  annotations:
-    nginx.ingress.kubernetes.io/ssl-redirect: "true"
-    cert-manager.io/cluster-issuer: "letsencrypt-prod"
-spec:
-  ingressClassName: nginx
-  tls:
-    - hosts:
-        - myapp.example.com
-      secretName: my-app-tls
-  rules:
-    - host: myapp.example.com
-      http:
-        paths:
-          - path: /
-            pathType: Prefix
-            backend:
-              service:
-                name: my-app
-                port:
-                  number: 80
-```
-
----
-
-## ConfigMaps and Secrets
-
-### ConfigMap — Non-sensitive configuration
-
-```yaml
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: my-app-config
-  namespace: my-namespace
-data:
-  LOG_LEVEL: "info"
-  APP_ENV: "production"
-  MAX_CONNECTIONS: "100"
-  # Mount as a file for complex config
-  app.yaml: |
-    server:
-      port: 8080
-      timeout: 30s
-```
-
-```yaml
-# Mount ConfigMap as a file
-volumes:
-  - name: config
-    configMap:
-      name: my-app-config
-      items:
-        - key: app.yaml
-          path: app.yaml
-volumeMounts:
-  - name: config
-    mountPath: /etc/app
-    readOnly: true
-```
-
-### Secrets — Sensitive data
-
-```bash
-# Create secret from literal (CLI, then store in Vault/SOPS)
-kubectl create secret generic my-app-secrets \
-  --from-literal=db-password='s3cr3t' \
-  --namespace=my-namespace \
-  --dry-run=client -o yaml | kubectl apply -f -
-```
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
-  name: my-app-secrets
-  namespace: my-namespace
-type: Opaque
-# Values are base64-encoded (NOT encrypted — use Sealed Secrets or ESO for real encryption)
-data:
-  db-password: czNjcjN0  # base64 of 's3cr3t'
-```
-
-> **Important:** Raw Kubernetes Secrets are only base64-encoded, not encrypted at rest unless your cluster has encryption configured. Use [Sealed Secrets](https://github.com/bitnami-labs/sealed-secrets) or [External Secrets Operator](https://external-secrets.io) for production.
-
----
-
-## Resource Requests and Limits
-
-```yaml
-resources:
-  requests:       # Scheduler uses this to place the pod
-    cpu: "100m"   # 100 millicores = 0.1 CPU
-    memory: "128Mi"
-  limits:         # Container is killed/throttled above this
-    cpu: "500m"
-    memory: "256Mi"
-```
-
-**Rules of thumb:**
-
-| Workload Type | CPU Request | Memory Request | Notes |
-|---------------|-------------|----------------|-------|
-| Web API | 100–250m | 128–256Mi | Set limits 2-4x requests |
-| Worker/consumer | 250–500m | 256–512Mi | Memory limit = request for predictability |
-| JVM app | 500m–1 | 512Mi–2Gi | Allow headroom above `-Xmx` for JVM overhead |
-| Sidecar | 10–50m | 32–64Mi | Keep minimal |
-
-```yaml
-# WRONG: No requests or limits — unpredictable scheduling, OOM evictions
-containers:
-  - name: app
-    image: myapp:latest
-    # Missing resources: {} — this is dangerous in production
-
-# WRONG: Limits without requests — requests default to limits, over-reserves capacity
-resources:
-  limits:
-    cpu: "2"
-    memory: "1Gi"
-  # requests missing — will default to limits values
-```
-
----
-
-## RBAC — Roles and ServiceAccounts
-
-### Principle of Least Privilege
-
-**Two patterns depending on whether the app calls the Kubernetes API:**
-
-#### Pattern A — App does NOT need the Kubernetes API (most apps)
-
-Disable token automounting on the ServiceAccount. The Role/RoleBinding are not needed.
-
-```yaml
-# ServiceAccount with token disabled — safest default
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: my-app-sa
-  namespace: my-namespace
-automountServiceAccountToken: false   # No K8s API token injected into pods
-```
-
-```yaml
-# Reference in Deployment — no token, no API access
-spec:
-  template:
-    spec:
-      serviceAccountName: my-app-sa
-      automountServiceAccountToken: false   # Belt-and-suspenders: also set at pod level
-```
-
-#### Pattern B — App DOES need the Kubernetes API (operators, controllers, config watchers)
-
-Enable the token and grant only the permissions actually required.
-
-```yaml
-# 1. ServiceAccount — enable token for this SA
-apiVersion: v1
-kind: ServiceAccount
-metadata:
-  name: my-app-sa
-  namespace: my-namespace
-automountServiceAccountToken: true    # Token required: app calls K8s API
-```
-
-```yaml
-# 2. Role — grant only what the app needs (namespace-scoped)
-apiVersion: rbac.authorization.k8s.io/v1
-kind: Role
-metadata:
-  name: my-app-role
-  namespace: my-namespace
-rules:
-  - apiGroups: [""]
-    resources: ["configmaps"]
-    verbs: ["get", "list", "watch"]    # Read-only, specific resource
-  - apiGroups: [""]
-    resources: ["secrets"]
-    resourceNames: ["my-app-secrets"]  # Restrict to specific secret by name
-    verbs: ["get"]
-```
-
-```yaml
-# 3. Bind Role to ServiceAccount
-apiVersion: rbac.authorization.k8s.io/v1
-kind: RoleBinding
-metadata:
-  name: my-app-rolebinding
-  namespace: my-namespace
-subjects:
-  - kind: ServiceAccount
-    name: my-app-sa
-    namespace: my-namespace
-roleRef:
-  kind: Role
-  apiGroup: rbac.authorization.k8s.io
-  name: my-app-role
-```
-
-```yaml
-# 4. Reference SA in Deployment
-spec:
-  template:
-    spec:
-      serviceAccountName: my-app-sa
-      # automountServiceAccountToken defaults to true from SA — token is injected
-```
-
----
-
-## Horizontal Pod Autoscaler (HPA)
-
-```yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: my-app-hpa
-  namespace: my-namespace
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: my-app
-  minReplicas: 2      # Always at least 2 for HA
-  maxReplicas: 10
-  metrics:
-    - type: Resource
-      resource:
-        name: cpu
-        target:
-          type: Utilization
-          averageUtilization: 70    # Scale up when avg CPU > 70%
-    - type: Resource
-      resource:
-        name: memory
-        target:
-          type: Utilization
-          averageUtilization: 80
-```
-
-> HPA requires `resources.requests` to be set on all containers — it calculates utilization as `current / request`.
-
----
-
-## PodDisruptionBudget (PDB)
-
-Prevent too many pods going down during node drains or rolling updates:
-
-```yaml
-apiVersion: policy/v1
-kind: PodDisruptionBudget
-metadata:
-  name: my-app-pdb
-  namespace: my-namespace
-spec:
-  minAvailable: 2           # OR use maxUnavailable: 1
-  selector:
-    matchLabels:
-      app: my-app
-```
-
----
-
-## Namespaces and Multi-Tenancy
-
-```bash
-# Create namespace with resource quotas
-kubectl create namespace my-namespace
-
-# Apply ResourceQuota to limit namespace consumption
-kubectl apply -f - <<EOF
-apiVersion: v1
-kind: ResourceQuota
-metadata:
-  name: my-namespace-quota
-  namespace: my-namespace
-spec:
-  hard:
-    requests.cpu: "4"
-    requests.memory: 4Gi
-    limits.cpu: "8"
-    limits.memory: 8Gi
-    pods: "20"
-EOF
-```
-
----
-
-## Jobs and CronJobs
-
-```yaml
-# One-off Job (DB migration, data processing)
-apiVersion: batch/v1
-kind: Job
-metadata:
-  name: db-migrate
-  namespace: my-namespace
-spec:
-  backoffLimit: 3          # Retry up to 3 times on failure
-  ttlSecondsAfterFinished: 3600   # Auto-delete after 1h
-  template:
-    spec:
-      restartPolicy: OnFailure    # Never for Jobs (not Always)
-      containers:
-        - name: migrate
-          image: ghcr.io/org/my-app:1.0.0
-          command: ["python", "manage.py", "migrate"]
-          resources:
-            requests:
-              cpu: "100m"
-              memory: "256Mi"
-```
-
-```yaml
-# CronJob
-apiVersion: batch/v1
-kind: CronJob
-metadata:
-  name: cleanup-job
-  namespace: my-namespace
-spec:
-  schedule: "0 2 * * *"         # 2am daily
-  concurrencyPolicy: Forbid      # Don't run if previous still running
-  successfulJobsHistoryLimit: 3
-  failedJobsHistoryLimit: 1
-  jobTemplate:
-    spec:
-      template:
-        spec:
-          restartPolicy: OnFailure
-          containers:
-            - name: cleanup
-              image: ghcr.io/org/cleanup:1.0.0
-              resources:
-                requests:
-                  cpu: "50m"
-                  memory: "64Mi"
-```
-
----
-
-## kubectl Debugging Cheatsheet
-
-```bash
-# --- Pod status and logs ---
-kubectl get pods -n my-namespace
-kubectl get pods -n my-namespace -o wide          # Show node assignment
-kubectl describe pod <pod-name> -n my-namespace   # Events and state details
-kubectl logs <pod-name> -n my-namespace           # Current logs
-kubectl logs <pod-name> -n my-namespace --previous  # Logs from crashed container
-kubectl logs <pod-name> -n my-namespace -c <container>  # Multi-container pod
-
-# --- Execute into a running container ---
-kubectl exec -it <pod-name> -n my-namespace -- sh
-kubectl exec -it <pod-name> -n my-namespace -- bash
-
-# --- Check resource usage ---
-kubectl top pods -n my-namespace
-kubectl top nodes
-
-# --- Deployment operations ---
-kubectl rollout status deployment/my-app -n my-namespace
-kubectl rollout history deployment/my-app -n my-namespace
-kubectl rollout undo deployment/my-app -n my-namespace      # Rollback
-kubectl rollout undo deployment/my-app --to-revision=2 -n my-namespace
-
-# --- Scale manually ---
-kubectl scale deployment my-app --replicas=5 -n my-namespace
-
-# --- Inspect events (cluster-wide issues) ---
-kubectl get events -n my-namespace --sort-by='.lastTimestamp'
-
-# --- Port-forward for local debugging ---
-kubectl port-forward pod/<pod-name> 8080:8080 -n my-namespace
-kubectl port-forward svc/my-app 8080:80 -n my-namespace
-
-# --- Dry-run to validate YAML ---
-kubectl apply -f deployment.yaml --dry-run=client
-kubectl apply -f deployment.yaml --dry-run=server   # Validates against live cluster
-```
-
-### Diagnosing Common Errors
-
-```bash
-# CrashLoopBackOff: container keeps crashing
-kubectl logs <pod-name> --previous -n my-namespace  # Check crash logs
-kubectl describe pod <pod-name> -n my-namespace     # Check exit code & OOMKilled
-
-# ImagePullBackOff: can't pull image
-kubectl describe pod <pod-name> -n my-namespace     # Check Events section
-# Causes: wrong image tag, missing imagePullSecret, private registry
-
-# Pending pod: not scheduled
-kubectl describe pod <pod-name> -n my-namespace
-# Causes: insufficient resources, no matching node selector, taint/toleration mismatch
-
-# OOMKilled: out of memory
-# Increase memory limits, check for memory leaks
-kubectl describe pod <pod-name> -n my-namespace | grep -A5 "Last State"
-```
-
----
-
-## Anti-Patterns
-
-```yaml
-# BAD: Using :latest tag — non-deterministic deployments
-image: myapp:latest
-
-# GOOD: Pin to a specific immutable tag (SHA or semver)
-image: ghcr.io/org/myapp:1.4.2
-# or
-image: ghcr.io/org/myapp@sha256:abc123...
-
-# ---
-
-# BAD: Running as root
-securityContext: {}    # Defaults to root
-
-# GOOD: Non-root with explicit UID
-securityContext:
-  runAsNonRoot: true
-  runAsUser: 1001
-
-# ---
-
-# BAD: No resource limits — one pod can starve the entire node
-containers:
-  - name: app
-    image: myapp:1.0.0
-    # No resources defined
-
-# GOOD: Always set requests and limits
-resources:
-  requests:
-    cpu: "100m"
-    memory: "128Mi"
-  limits:
-    cpu: "500m"
-    memory: "256Mi"
-
-# ---
-
-# BAD: Storing plaintext secrets in ConfigMaps
-apiVersion: v1
-kind: ConfigMap
-data:
-  DB_PASSWORD: "mysecretpassword"   # NEVER — use Secret or external secrets manager
-
-# ---
-
-# BAD: ClusterAdmin for application service accounts
-apiVersion: rbac.authorization.k8s.io/v1
-kind: ClusterRoleBinding
-roleRef:
-  kind: ClusterRole
-  name: cluster-admin    # Grants god-mode to your app
-
-# ---
-
-# BAD: minAvailable: 0 in PDB — defeats the purpose
-spec:
-  minAvailable: 0
-
-# ---
-
-# BAD: restartPolicy: Always in a Job (causes infinite restart loop)
-spec:
-  restartPolicy: Always   # Use OnFailure or Never for Jobs
-```
-
----
-
-## Best Practices Checklist
-
-### Security
-- [ ] Container runs as non-root (`runAsNonRoot: true`, `runAsUser` set)
-- [ ] `readOnlyRootFilesystem: true` with `emptyDir` for writable paths
-- [ ] `allowPrivilegeEscalation: false`
-- [ ] All capabilities dropped (`capabilities.drop: [ALL]`)
-- [ ] Dedicated ServiceAccount per app, not `default`
-- [ ] `automountServiceAccountToken: false` unless needed
-- [ ] RBAC follows least privilege (use `Role`, not `ClusterRole` unless needed)
-- [ ] Secrets managed via Sealed Secrets or External Secrets Operator
-
-### Reliability
-- [ ] All 3 probe types configured (startup + liveness + readiness)
-- [ ] Resource requests AND limits set on every container
-- [ ] `minReplicas: 2+` for any production workload
-- [ ] PodDisruptionBudget defined for stateful or critical services
-- [ ] `RollingUpdate` strategy with `maxUnavailable: 0`
-- [ ] HPA configured for variable-load services
-
-### Observability
-- [ ] App exposes `/health` (liveness) and `/ready` (readiness) endpoints
-- [ ] Structured JSON logging (no PII in logs)
-- [ ] Resource labels: `app`, `version`, `environment`
-
----
-
-## Related Skills
-
-- `docker-patterns` — Multi-stage Dockerfiles and image security
-- `deployment-patterns` — CI/CD pipelines, rollback strategy, health check endpoints
-- `security-review` — Broader security hardening context
-- `git-workflow` — GitOps integration with K8s (ArgoCD / Flux patterns)