@synapta/skills 0.1.0 → 0.1.2

package/skills/deploy-k8s/references/conditional/observability-stacks.md

@@ -0,0 +1,80 @@
+# Observability Stacks
+
+**Load this reference when detected:** Prometheus Operator, kube-prometheus-stack, ServiceMonitor, PodMonitor, PrometheusRule, AlertmanagerConfig, OpenTelemetry Collector, OpenTelemetry Operator, Loki, Grafana, Tempo, metrics, logs, traces, dashboards, or telemetry pipelines.
+
+## Why this matters
+
+Observability add-ons use CRDs, label selectors, generated scrape config, and deployment modes that differ by stack. LLMs frequently generate resources that apply successfully but are never selected, never scraped, or duplicate data. Do not load this file for basic application logging unless an observability stack is involved.
+
+## Prometheus Operator
+
+ServiceMonitor and PodMonitor behavior depends on selectors.
+
+- `ServiceMonitor` selects Services, not Deployments.
+- The Service must expose a named port, and the ServiceMonitor endpoint should reference that port name.
+- `PodMonitor` selects Pods directly and should be used only when a Service is unnecessary or unavailable.
+- Prometheus or PrometheusAgent selects monitors through label and namespace selectors; labels must match both sides.
+- `PrometheusRule` must be selected by the relevant Prometheus rule selectors.
+- Do not create ServiceMonitor/PodMonitor resources unless the CRDs are installed.
+
+## OpenTelemetry Collector
+
+Choose collector mode by signal source.
+
+- `DaemonSet`: node-local logs, host metrics, kubelet metrics, or per-node collection.
+- `Deployment`: centralized OTLP gateway, cluster events, or singleton receivers.
+- `StatefulSet`: stable identity or persistent queue/storage requirements.
+- Avoid duplicate cluster-wide receivers across multiple replicas unless the receiver supports it.
+- Set memory limits and memory limiter processor together.
+- Bind receivers as narrowly as practical and expose OTLP only inside the cluster unless explicitly required.
+
+## Loki and Logs
+
+- Choose Loki deployment mode by scale: monolithic for small stacks, scalable or microservices for production/high volume.
+- Configure durable object storage for production Loki; do not rely on ephemeral storage.
+- Keep log labels low-cardinality. Do not label on request IDs, user IDs, pod UIDs, or raw paths.
+- Prefer structured JSON logs to stdout/stderr from applications.
+- Separate log collection agents from application pods unless the sidecar is explicitly required.
+
+## Grafana and Dashboards
+
+- Treat dashboards and datasources as configuration owned by the observability platform.
+- Avoid embedding secrets in dashboard ConfigMaps or Helm values.
+- When using sidecar dashboard discovery, ensure labels match the sidecar selector.
+- Keep dashboard ConfigMaps namespace and RBAC aligned with the deployed Grafana chart.
+
+## Alerting
+
+- Alerts should be actionable, routed, and include runbook context.
+- Use `for:` durations to reduce flapping.
+- Avoid high-cardinality alert labels.
+- Separate symptom alerts from cause alerts; do not page on every transient pod restart.
+- Validate PromQL against the actual metric names emitted by the stack.
+
+## Validation
+
+- `kubectl get crd | grep -Ei "servicemonitors|podmonitors|prometheusrules"` (or `findstr /i` on Windows)
+- `kubectl get servicemonitor,podmonitor,prometheusrule -A`
+- Inspect Prometheus target discovery for selected monitors.
+- Check generated Prometheus config or operator logs when targets are missing.
+- `helm template` observability charts and validate rendered CRDs/resources before applying.
+- For OpenTelemetry, inspect Collector logs for invalid pipeline components and dropped data.
+
+## LLM Mistake Checklist
+
+- Creating ServiceMonitor selectors that match Deployment labels but not Service labels.
+- Referencing a numeric port when the ServiceMonitor expects a named Service port.
+- Forgetting that Prometheus selectors must select the monitor.
+- Creating monitoring CRDs when the Prometheus Operator is not installed.
+- Running cluster-wide OpenTelemetry receivers in multiple replicas and duplicating data.
+- Choosing Loki monolithic mode for high-volume production without durable storage.
+- Creating high-cardinality Loki labels or alert labels.
+- Shipping dashboards with plaintext datasource credentials.
+
+## Grounding Sources
+
+- Prometheus Operator design: https://prometheus-operator.dev/docs/getting-started/design/
+- Prometheus Operator ServiceMonitor and PodMonitor getting started: https://prometheus-operator.dev/docs/developer/getting-started/
+- Prometheus Operator troubleshooting: https://prometheus-operator.dev/docs/platform/troubleshooting/
+- OpenTelemetry Collector Helm chart: https://opentelemetry.io/docs/platforms/kubernetes/helm/collector/
+- Loki Helm installation: https://grafana.com/docs/loki/latest/setup/install/helm/

package/skills/deploy-k8s/references/conditional/openshift-patterns.md

@@ -0,0 +1,67 @@
+# OpenShift Patterns
+
+**Load this reference when detected:** OpenShift, OKD, ROSA, ARO, Route, SecurityContextConstraints, SCC, restricted-v2, OpenShift Pipelines, OpenShift GitOps, OperatorHub, OLM, ImageStream, or `oc`.
+
+## Why this matters
+
+OpenShift is Kubernetes with important platform APIs and security defaults. Generic upstream manifests often fail because of SecurityContextConstraints, arbitrary UID requirements, Routes, and operator-managed platform components. Do not load this file for vanilla clusters unless OpenShift APIs are present.
+
+## Security Context Constraints
+
+SCCs are admission controls for pod privileges.
+
+- Do not modify default SCCs.
+- Prefer workloads that run under `restricted-v2` or the platform default restricted SCC.
+- Do not hardcode `runAsUser: 1000` or another fixed UID unless the namespace/SCC permits it.
+- Build images to run with an arbitrary UID and writable group-owned paths.
+- If a workload needs `anyuid`, host networking, host mounts, or privileged mode, require a justification and bind the narrowest SCC only to the dedicated ServiceAccount.
+- Use RBAC to grant SCC use to ServiceAccounts, not broad users or groups.
+
+## Routes and Ingress
+
+OpenShift Routes are first-class edge routing resources.
+
+- Use `Route` when the user asks for OpenShift-native exposure.
+- Choose TLS termination deliberately: edge, passthrough, or re-encrypt.
+- Do not assume Ingress annotations from nginx, AWS, GCE, or AGIC apply to Routes.
+- For portable upstream manifests, use Ingress only when the target OpenShift cluster supports the intended IngressController behavior.
+
+## Images and Runtime Assumptions
+
+OpenShift security often exposes image problems.
+
+- Avoid images that require root by default.
+- Ensure writable directories can be written by an arbitrary UID, commonly through group permissions.
+- Do not rely on Docker socket mounts or hostPath except for platform-level agents with explicit SCC approval.
+- For internal registry or ImageStream workflows, keep image references and pull policies aligned with the platform's promotion model.
+
+## Operators and OLM
+
+When OperatorHub, OLM, or custom operators are in scope:
+
+- Prefer Subscription/OperatorGroup/InstallPlan patterns only when the user is actually managing operators.
+- Do not hand-roll CRDs owned by an installed operator unless the operator documentation requires it.
+- Validate custom resources against installed CRDs, not only generic Kubernetes schemas.
+
+## Validation
+
+- `oc apply --dry-run=server -f <manifest>`
+- `oc auth can-i use scc/restricted-v2 --as=system:serviceaccount:<namespace>:<serviceaccount>`
+- `oc describe pod <name>` for SCC admission failures
+- `oc get route -n <namespace>` for Route readiness
+- `oc get csv,subscription,operatorgroup -A` when OLM-managed resources are involved
+
+## LLM Mistake Checklist
+
+- Hardcoding a UID that violates OpenShift namespace UID ranges.
+- Asking users to edit default SCCs.
+- Granting `anyuid` or `privileged` SCC to broad groups.
+- Generating Ingress-controller annotations for OpenShift Routes.
+- Assuming root-capable images will run under restricted SCCs.
+- Forgetting `oc` validation and SCC checks.
+- Creating operator-owned resources without verifying the CRD exists.
+
+## Grounding Sources
+
+- OpenShift SecurityContextConstraints: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/authentication_and_authorization/managing-pod-security-policies
+- OpenShift Routes: https://docs.redhat.com/en/documentation/openshift_container_platform/latest/html/ingress_and_load_balancing/routes

package/skills/deploy-k8s/references/daemonset-operator-patterns.md

@@ -0,0 +1,155 @@
+# DaemonSet and Operator Patterns -- Node-Level and Custom Controllers
+
+**Load this reference when generating:** DaemonSet, PriorityClass, CRDs, or any workload that must run on every (or a targeted subset of) node(s).
+
+## When to Use a DaemonSet
+Exactly one pod per qualifying node: log collectors (Fluent Bit, Vector), monitoring agents (node-exporter, Datadog), network plugins (CNI, kube-proxy, Cilium), CSI node drivers, security agents (Falco). If you need multiple replicas per node or the workload is not node-scoped, use a Deployment.
+
+## Update Strategies
+| Strategy | Behavior | Use when |
+|---|---|---|
+| `RollingUpdate` | Replaces pods node-by-node; `maxUnavailable` controls pace | Normal updates |
+| `OnDelete` | Pods replaced only when manually deleted | Critical infra (CNI, kube-proxy) needing manual control |
+
+For large clusters, set `maxUnavailable` to a percentage (e.g., `"10%"`) to speed rollouts.
+
+## Node Selectors and Tolerations
+**Targeting**: use `nodeSelector` for simple matching, `nodeAffinity` for richer expressions:
+```yaml
+nodeSelector:
+  node.kubernetes.io/os: linux
+  kubernetes.io/arch: amd64
+```
+
+**Tolerations**: DaemonSets often must run on tainted nodes (control-plane, GPU pools). Add only the tolerations you need:
+```yaml
+tolerations:
+  - key: node-role.kubernetes.io/control-plane
+    operator: Exists
+    effect: NoSchedule
+  - key: node.kubernetes.io/not-ready
+    operator: Exists
+    effect: NoExecute
+```
+Never use `operator: Exists` without a `key` (tolerates everything) unless the DaemonSet truly belongs on every node.
+
+## Resource Management
+DaemonSet pods run on **every node**. 200m CPU x 100 nodes = 20 cores cluster-wide. Be conservative:
+- `requests` = steady-state consumption. `limits` = burst cap.
+- Monitor actual usage and right-size iteratively.
+
+## Priority Classes
+Prevent preemption of system DaemonSets with a custom PriorityClass:
+```yaml
+apiVersion: scheduling.k8s.io/v1
+kind: PriorityClass
+metadata:
+  name: system-node-agent
+value: 1000000
+globalDefault: false
+preemptionPolicy: PreemptLowerPriority
+description: "Node-level DaemonSet agents (logging, monitoring)."
+```
+Built-in `system-cluster-critical` and `system-node-critical` are reserved for core components. Use a custom class in the 100000-10000000 range.
+
+## Operator Pattern Overview
+An operator is a custom controller that watches CRs and reconciles cluster state. Use when:
+- Complex operational logic (failover, backup, scaling) exceeds built-in controllers.
+- Users need a simple declarative API for a complex system (database, queue).
+- Manual runbooks are error-prone and should be codified.
+
+Do NOT build an operator when Helm, Kustomize, or a Job suffices. Operators carry significant maintenance burden.
+
+## CRD Basics
+```yaml
+apiVersion: apiextensions.k8s.io/v1
+kind: CustomResourceDefinition
+metadata:
+  name: postgresclusters.db.example.com
+spec:
+  group: db.example.com
+  scope: Namespaced
+  names: { plural: postgresclusters, singular: postgrescluster, kind: PostgresCluster, shortNames: ["pgc"] }
+  versions:
+    - name: v1alpha1
+      served: true
+      storage: true
+      schema:
+        openAPIV3Schema:
+          type: object
+          properties:
+            spec:
+              type: object
+              required: ["replicas", "version"]
+              properties:
+                replicas: { type: integer, minimum: 1, maximum: 10 }
+                version:  { type: string, enum: ["15", "16"] }
+                storage:
+                  type: object
+                  properties:
+                    size: { type: string, pattern: "^[0-9]+Gi$" }
+```
+Always include `openAPIV3Schema` with validation. CRDs without it accept arbitrary YAML, causing runtime errors.
+
+## Operator Frameworks
+- **kubebuilder**: upstream Go framework. Generates scaffolding, RBAC, CRD manifests, webhooks. Preferred for Go teams.
+- **operator-sdk**: extends kubebuilder; adds Ansible and Helm operator support for non-Go teams.
+
+Both produce the same runtime pattern: a manager running reconciliation loops.
+
+## Example: Log Collector DaemonSet
+```yaml
+apiVersion: apps/v1
+kind: DaemonSet
+metadata:
+  name: fluent-bit
+  labels: { app.kubernetes.io/name: fluent-bit, app.kubernetes.io/component: log-collector }
+spec:
+  selector:
+    matchLabels: { app.kubernetes.io/name: fluent-bit, app.kubernetes.io/component: log-collector }
+  updateStrategy: { type: RollingUpdate, rollingUpdate: { maxUnavailable: "10%" } }
+  template:
+    metadata:
+      labels: { app.kubernetes.io/name: fluent-bit, app.kubernetes.io/component: log-collector }
+    spec:
+      priorityClassName: system-node-agent
+      serviceAccountName: fluent-bit
+      nodeSelector: { node.kubernetes.io/os: linux }
+      tolerations:
+        - { key: node-role.kubernetes.io/control-plane, operator: Exists, effect: NoSchedule }
+        - { key: node.kubernetes.io/not-ready, operator: Exists, effect: NoExecute, tolerationSeconds: 60 }
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10000
+        runAsGroup: 10000
+        seccompProfile: { type: RuntimeDefault }
+      containers:
+        - name: fluent-bit
+          image: fluent/fluent-bit:3.0.4
+          ports: [{ containerPort: 2020, name: metrics, protocol: TCP }]
+          resources:
+            requests: { cpu: 50m, memory: 64Mi }
+            limits:   { cpu: 200m, memory: 128Mi }
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities: { drop: ["ALL"] }
+          volumeMounts:
+            - { name: varlog, mountPath: /var/log, readOnly: true }
+            - { name: config, mountPath: /fluent-bit/etc, readOnly: true }
+            - { name: buffer, mountPath: /fluent-bit/buffer }
+      volumes:
+        - { name: varlog, hostPath: { path: /var/log, type: Directory } }
+        - { name: config, configMap: { name: fluent-bit-config } }
+        - { name: buffer, emptyDir: { sizeLimit: 256Mi } }
+```
+
+## LLM Mistake Checklist
+1. **DaemonSet with `replicas` field.** DaemonSets have no `replicas`. The scheduler places one pod per qualifying node. Including it is an API error.
+2. **Missing tolerations for tainted nodes.** Without explicit tolerations, pods stay Pending on control-plane or special-purpose nodes.
+3. **Overly generous resource requests.** Multiplied across every node, small over-requests waste enormous capacity. Keep requests minimal.
+4. **Using system-node-critical without justification.** Reserved for core components. Use a custom PriorityClass for application agents.
+5. **hostPath without `type`.** Always set `hostPath.type` (Directory, Socket, File) to catch mount errors at startup, not runtime.
+6. **CRD without openAPIV3Schema.** No validation = any YAML accepted = inscrutable controller errors. Always define a strict schema.
+7. **Blanket toleration (no key).** `operator: Exists` with no `key` tolerates every taint including NoExecute eviction taints. Only tolerate specific, known taints.
+8. **Forgetting serviceAccountName.** DaemonSets accessing host paths or the API need a dedicated ServiceAccount with minimal RBAC.

package/skills/deploy-k8s/references/deployment-patterns.md

@@ -0,0 +1,146 @@
+# Deployment Patterns -- Stateless Workloads
+
+**Load this reference when generating:** Deployment, Service, HPA, PDB, Ingress, or any stateless application manifest.
+
+## When to Use a Deployment
+Any workload that is stateless: web apps, REST/gRPC APIs, microservices, frontend proxies, queue-consuming workers. If pods are interchangeable and need no stable identity or persistent local storage, use a Deployment.
+
+## Minimum Production Checklist
+1. `replicas` >= 2 -- never ship a single replica to production.
+2. `resources.requests` AND `resources.limits` on every container (cpu + memory).
+3. Pod-level `securityContext` satisfying PSS **restricted** profile.
+4. `readinessProbe` (gates traffic) and `livenessProbe` (restarts stuck pods) on separate endpoints.
+5. `topologySpreadConstraints` or pod anti-affinity across failure domains.
+6. An accompanying `PodDisruptionBudget`.
+
+## Label Strategy
+```yaml
+labels:
+  app.kubernetes.io/name: order-service      # app identity -- use in selectors
+  app.kubernetes.io/version: "1.4.2"         # NEVER put in selector.matchLabels
+  app.kubernetes.io/component: api           # role: api | worker | cache
+  app.kubernetes.io/part-of: ecommerce       # higher-level system
+  app.kubernetes.io/managed-by: helm         # tooling
+```
+
+## Service Wiring
+Default: **ClusterIP + Ingress**. ClusterIP for in-cluster traffic; Ingress terminates TLS and routes externally. Avoid LoadBalancer Services unless no Ingress controller exists or the workload needs raw TCP/UDP.
+
+## Config Mounting
+- **Prefer volume mounts** for file-based config -- enables atomic updates on ConfigMap rotation.
+- Use `env`/`envFrom` only for simple key-value pairs.
+- Set `immutable: true` on Secrets that should never change in place.
+
+## Environment-Specific Configuration
+- **Kustomize overlays**: `base/` + `overlays/{dev,staging,prod}/` for per-env patching (replicas, resources, images).
+- **Helm values**: `values-prod.yaml` per environment when conditionals or loops are needed.
+
+## Example: Production Deployment + Service + HPA
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: order-service
+  labels: &labels
+    app.kubernetes.io/name: order-service
+    app.kubernetes.io/component: api
+    app.kubernetes.io/part-of: ecommerce
+spec:
+  replicas: 3
+  revisionHistoryLimit: 5
+  selector:
+    matchLabels: { app.kubernetes.io/name: order-service, app.kubernetes.io/component: api }
+  strategy: { type: RollingUpdate, rollingUpdate: { maxSurge: 1, maxUnavailable: 0 } }
+  template:
+    metadata:
+      labels: { <<: *labels, app.kubernetes.io/version: "1.4.2" }
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 10000
+        runAsGroup: 10000
+        fsGroup: 10000
+        seccompProfile: { type: RuntimeDefault }
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: topology.kubernetes.io/zone
+          whenUnsatisfiable: DoNotSchedule
+          labelSelector:
+            matchLabels: { app.kubernetes.io/name: order-service }
+      containers:
+        - name: order-service
+          image: registry.example.com/order-service:1.4.2
+          ports: [{ containerPort: 8080, protocol: TCP }]
+          resources:
+            requests: { cpu: 250m, memory: 256Mi }
+            limits:   { cpu: "1", memory: 512Mi }
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities: { drop: ["ALL"] }
+          readinessProbe:
+            httpGet: { path: /healthz/ready, port: 8080 }
+            initialDelaySeconds: 5
+            periodSeconds: 10
+          livenessProbe:
+            httpGet: { path: /healthz/live, port: 8080 }
+            initialDelaySeconds: 15
+            periodSeconds: 20
+          volumeMounts:
+            - { name: config, mountPath: /etc/order-service, readOnly: true }
+            - { name: tmp, mountPath: /tmp }
+      volumes:
+        - { name: config, configMap: { name: order-service-config } }
+        - { name: tmp, emptyDir: {} }
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: order-service
+spec:
+  type: ClusterIP
+  selector: { app.kubernetes.io/name: order-service, app.kubernetes.io/component: api }
+  ports: [{ port: 80, targetPort: 8080, protocol: TCP }]
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: order-service
+spec:
+  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: order-service }
+  minReplicas: 3
+  maxReplicas: 15
+  metrics:
+    - type: Resource
+      resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }
+    - type: Pods
+      pods:
+        metric: { name: http_requests_per_second }
+        target: { type: AverageValue, averageValue: "1000" }
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies: [{ type: Percent, value: 25, periodSeconds: 60 }]
+    scaleUp:
+      stabilizationWindowSeconds: 30
+      policies: [{ type: Percent, value: 50, periodSeconds: 60 }]
+---
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: order-service
+spec:
+  minAvailable: 2
+  selector:
+    matchLabels: { app.kubernetes.io/name: order-service, app.kubernetes.io/component: api }
+```
+
+## LLM Mistake Checklist
+1. **Version label in selector.** Never put `app.kubernetes.io/version` in `selector.matchLabels` -- selectors are immutable; this breaks upgrades.
+2. **Missing readOnlyRootFilesystem.** PSS restricted requires it. Mount an `emptyDir` at `/tmp` if the app writes temp files.
+3. **Omitting resource limits.** Both `requests` and `limits` are required. Without them the pod is BestEffort QoS and evicted first.
+4. **Single replica in production.** Always `replicas >= 2` with a PDB. One replica = zero availability during node drains.
+5. **HPA without scaleDown stabilization.** Default scale-down is aggressive. Set `stabilizationWindowSeconds: 300` to prevent thrashing.
+6. **Probes hitting the main API path.** Use dedicated `/healthz/*` endpoints to avoid cascading failures under load.
+7. **Forgetting /tmp emptyDir.** With `readOnlyRootFilesystem: true`, processes writing to `/tmp` crash without this volume.
+8. **LoadBalancer Service by default.** Each provisions a cloud LB -- use ClusterIP + Ingress instead.

package/skills/deploy-k8s/references/do-dont-patterns.md

@@ -0,0 +1,87 @@
+# Do / Don't Quick Reference
+
+> Terse checklist of Kubernetes best practices organized by category. Each line is
+> a standalone rule. Default security posture is PSS "restricted" profile.
+
+---
+
+## Security Contexts
+
+- DO set `runAsNonRoot: true` and explicit `runAsUser`/`runAsGroup` on every pod.
+- DO set `allowPrivilegeEscalation: false` on every container.
+- DO set `readOnlyRootFilesystem: true` and mount writable paths as emptyDir.
+- DO set `capabilities.drop: ["ALL"]` and only add back specific caps if required.
+- DO set `seccompProfile.type: RuntimeDefault` at the pod level.
+- DON'T set `privileged: true` unless the workload genuinely requires it (CNI plugins, node agents).
+- DON'T omit the security context and rely on cluster defaults.
+
+## RBAC
+
+- DO use namespace-scoped Role + RoleBinding for workloads that operate in one namespace.
+- DO grant only the specific verbs, API groups, and resources needed.
+- DO use `resourceNames` to scope access to specific objects when possible.
+- DON'T bind to `cluster-admin` for application workloads.
+- DON'T use ClusterRoleBinding when RoleBinding is sufficient.
+- DON'T grant `*` (wildcard) verbs or resources.
+- DON'T leave `automountServiceAccountToken: true` on pods that do not call the Kubernetes API.
+
+## Resource Management
+
+- DO set `requests` for both CPU and memory on every container.
+- DO set `limits.memory` to prevent OOM from killing other workloads.
+- DO set ResourceQuota and LimitRange on every namespace.
+- DO leave CPU limits unset or generous to avoid CPU throttling.
+- DON'T omit resource requests -- the scheduler cannot bin-pack without them.
+- DON'T set requests equal to limits unless you need Guaranteed QoS class intentionally.
+
+## Networking
+
+- DO create a default-deny NetworkPolicy in every namespace.
+- DO allow DNS egress (UDP/TCP 53 to kube-dns) in every allow-list policy.
+- DO use `ingressClassName` instead of the deprecated `kubernetes.io/ingress.class` annotation.
+- DO use `networking.k8s.io/v1` for Ingress and NetworkPolicy resources.
+- DON'T expose Services as `type: LoadBalancer` without understanding cost and security implications.
+- DON'T use `type: NodePort` in production without firewall rules.
+
+## Probes and Rollouts
+
+- DO set a readiness probe on every container that serves traffic.
+- DO set a liveness probe that checks only the process's own health.
+- DO set `initialDelaySeconds` to account for application startup time.
+- DO set `revisionHistoryLimit` to a small number (3-5) to reduce etcd storage.
+- DO use `maxUnavailable: 0` with `maxSurge: 1` for zero-downtime rolling updates.
+- DON'T point liveness probes at external dependencies.
+- DON'T set liveness and readiness probes to the same endpoint and thresholds without understanding the difference.
+- DON'T set `failureThreshold: 1` on liveness probes -- one slow response kills the pod.
+
+## Image Management
+
+- DO use immutable image tags (`v1.2.3`) or digests (`@sha256:...`).
+- DO set `imagePullPolicy: IfNotPresent` with immutable tags.
+- DO reference images from a private registry with `imagePullSecrets`.
+- DON'T use `:latest` -- it is mutable, breaks rollback, and causes inconsistent replicas.
+- DON'T omit the image tag entirely -- it implicitly defaults to `:latest`.
+
+## Storage
+
+- DO verify the storage class supports the requested access mode before creating a PVC.
+- DO use `ReadWriteOnce` for block storage (EBS, Persistent Disk).
+- DO use StatefulSet with `volumeClaimTemplates` for per-replica storage.
+- DON'T request `ReadWriteMany` with block storage classes (gp3, pd-ssd).
+- DON'T use `hostPath` volumes in production workloads.
+
+## Configuration
+
+- DO store credentials in Secrets, not ConfigMaps.
+- DO use ExternalSecrets or Sealed Secrets so plain-text credentials never enter version control.
+- DO use ConfigMap/Secret hash-based naming (Kustomize generator, Helm sha annotation) to trigger rolling updates on config change.
+- DON'T embed passwords in connection string environment variables inside ConfigMaps.
+- DON'T commit raw Secret manifests to Git.
+
+## Namespaces and Isolation
+
+- DO apply PSA labels (`pod-security.kubernetes.io/enforce: restricted`) to every namespace.
+- DO create ResourceQuota in every namespace to prevent noisy-neighbor resource exhaustion.
+- DO use separate namespaces for separate trust boundaries.
+- DON'T deploy application workloads in `default`, `kube-system`, or `kube-public`.
+- DON'T assume namespace isolation provides network isolation -- it does not without NetworkPolicies.