@synapta/skills 0.1.1 → 0.2.0

package/skills/deploy-k8s/references/examples-bad.md

@@ -0,0 +1,282 @@
+# Bad Examples -- Common LLM Anti-Patterns
+
+> These are manifests that LLMs frequently generate. Each one compiles and appears
+> valid but has serious issues in production. Study the annotations to understand
+> what is wrong and why.
+
+---
+
+## 1. Deployment Running as Root with No Security Context
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: my-app
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: my-app
+  template:
+    metadata:
+      labels:
+        app: my-app
+    spec:
+      containers:
+        - name: my-app
+          image: my-app:latest
+          ports:
+            - containerPort: 8080
+```
+
+**What is wrong:**
+- No `securityContext` at pod or container level -- container runs as root by default.
+- Missing `runAsNonRoot: true`, `allowPrivilegeEscalation: false`, `readOnlyRootFilesystem: true`.
+- Missing `capabilities.drop: ["ALL"]` -- container retains all Linux capabilities.
+- No `seccompProfile` -- fails PSS restricted profile.
+- No resource requests or limits -- can consume unbounded node resources.
+- No probes -- Kubernetes cannot detect if the app is healthy or ready.
+- No standard `app.kubernetes.io/*` labels.
+- Uses `:latest` tag (see anti-pattern 5).
+
+## 2. Service with Selector That Matches No Pods
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: web-frontend
+spec:
+  selector:
+    matchLabels:
+      app: web-frontend
+  template:
+    metadata:
+      labels:
+        app: web-frontend
+        version: v2
+    spec:
+      containers:
+        - name: web
+          image: ghcr.io/org/web:v2.0.0
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: web-frontend
+spec:
+  selector:
+    app: web-frontend
+    version: v1            # <-- MISMATCH: pods have version: v2
+  ports:
+    - port: 80
+      targetPort: 8080
+```
+
+**What is wrong:**
+- Service selector includes `version: v1` but pods have `version: v2`.
+- Kubernetes does not warn about selector mismatches -- the Service silently has zero endpoints.
+- This is a frequent LLM mistake when updating version labels on the Deployment without updating the Service.
+- Debug with `kubectl get endpoints web-frontend` -- it will show an empty subset.
+
+## 3. ClusterRoleBinding with cluster-admin for a Single-Namespace App
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: my-app
+  namespace: my-app
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: ClusterRoleBinding
+metadata:
+  name: my-app-admin
+subjects:
+  - kind: ServiceAccount
+    name: my-app
+    namespace: my-app
+roleRef:
+  kind: ClusterRole
+  name: cluster-admin
+  apiGroup: rbac.authorization.k8s.io
+```
+
+**What is wrong:**
+- `cluster-admin` grants unrestricted access to the entire cluster: every namespace, every resource, every verb.
+- A single-namespace application needs only a namespace-scoped Role with specific verbs.
+- If this service account token is compromised, the attacker owns the entire cluster.
+- Use a namespace-scoped `Role` + `RoleBinding` with only the specific API groups, resources, and verbs needed.
+
+## 4. Liveness Probe Checking External Database
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-server
+spec:
+  selector:
+    matchLabels:
+      app: api-server
+  template:
+    metadata:
+      labels:
+        app: api-server
+    spec:
+      containers:
+        - name: api
+          image: ghcr.io/org/api:v1.0.0
+          livenessProbe:
+            exec:
+              command:
+                - /bin/sh
+                - -c
+                - "pg_isready -h postgres.db.svc -p 5432"
+            periodSeconds: 10
+            failureThreshold: 3
+```
+
+**What is wrong:**
+- Liveness probe depends on an external database. If the database is briefly unavailable, Kubernetes kills all API pods.
+- This causes cascading failure: database blip -> all pods restart -> thundering herd reconnects -> database overloaded further.
+- Liveness probes must check only the process's own health (e.g., `/healthz` that returns 200 if the HTTP server is responsive).
+- Use readiness probes (not liveness) to check dependency connectivity, so the pod is removed from Service endpoints but not killed.
+
+## 5. Deployment with :latest Tag and No imagePullPolicy
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: worker
+spec:
+  replicas: 3
+  selector:
+    matchLabels:
+      app: worker
+  template:
+    metadata:
+      labels:
+        app: worker
+    spec:
+      containers:
+        - name: worker
+          image: org/worker:latest
+```
+
+**What is wrong:**
+- `:latest` is a mutable tag. Different nodes may pull different versions, causing inconsistent behavior across replicas.
+- When `imagePullPolicy` is not set and the tag is `:latest`, Kubernetes defaults to `Always`. But if the tag is anything else, it defaults to `IfNotPresent`.
+- Rollbacks are impossible because every revision points to `:latest`.
+- No way to audit which exact image is running.
+- Use immutable tags (`v1.2.3`) or digests (`@sha256:abc...`). Set `imagePullPolicy: IfNotPresent` with immutable tags.
+
+## 6. Ingress Using Removed API Version
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: extensions/v1beta1
+kind: Ingress
+metadata:
+  name: app-ingress
+  annotations:
+    kubernetes.io/ingress.class: nginx
+spec:
+  rules:
+    - host: app.example.com
+      http:
+        paths:
+          - path: /
+            backend:
+              serviceName: frontend
+              servicePort: 80
+```
+
+**What is wrong:**
+- `extensions/v1beta1` Ingress was removed in Kubernetes 1.22. This manifest fails on any modern cluster.
+- The `kubernetes.io/ingress.class` annotation is deprecated; use `spec.ingressClassName: nginx`.
+- The backend syntax (`serviceName`/`servicePort`) is the old format. The `networking.k8s.io/v1` API uses `service.name` and `service.port.number`.
+- Missing `pathType` field, which is required in `networking.k8s.io/v1`.
+- LLMs frequently generate this because training data contains many examples of the old API.
+
+## 7. Secret Data in a ConfigMap
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: app-config
+  namespace: my-app
+data:
+  DATABASE_URL: "postgres://admin:s3cretP@ssw0rd@postgres:5432/mydb"
+  API_KEY: "sk-live-abc123def456"
+  AWS_SECRET_ACCESS_KEY: "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY"
+  config.yaml: |
+    smtp:
+      username: noreply@company.com
+      password: emailP@ss123
+```
+
+**What is wrong:**
+- ConfigMaps are stored unencrypted in etcd and are readable by anyone with `get` access to the namespace.
+- ConfigMap data appears in plain text in `kubectl describe`, in logs, and in version control if committed.
+- Credentials, API keys, and passwords must be in Secrets (which are at least base64-encoded and can be encrypted at rest).
+- Better: use ExternalSecrets or Sealed Secrets so credentials never appear in manifests at all.
+- Connection strings with embedded passwords are especially dangerous because they are easily overlooked in review.
+
+## 8. PVC with ReadWriteMany on an Unsupported Provider
+
+```yaml
+# BAD -- DO NOT USE
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: shared-data
+spec:
+  accessModes:
+    - ReadWriteMany
+  storageClassName: gp3
+  resources:
+    requests:
+      storage: 50Gi
+---
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: workers
+spec:
+  replicas: 5
+  selector:
+    matchLabels:
+      app: workers
+  template:
+    metadata:
+      labels:
+        app: workers
+    spec:
+      containers:
+        - name: worker
+          image: ghcr.io/org/worker:v1.0.0
+          volumeMounts:
+            - name: shared
+              mountPath: /data
+      volumes:
+        - name: shared
+          persistentVolumeClaim:
+            claimName: shared-data
+```
+
+**What is wrong:**
+- `gp3` (AWS EBS) does not support `ReadWriteMany`. The PVC will be stuck in `Pending` state with no clear error in pod events.
+- EBS volumes are `ReadWriteOnce` only -- they can be attached to a single node.
+- For RWX access, use EFS (`efs-sc`), NFS, or a distributed storage solution like Longhorn or Rook-Ceph.
+- LLMs frequently pair `ReadWriteMany` with block storage classes because they do not track provider-specific storage capabilities.
+- If only one pod needs write access, use `ReadWriteOnce` and a StatefulSet instead of a Deployment.

package/skills/deploy-k8s/references/examples-good.md

@@ -0,0 +1,440 @@
+# Good Examples -- Production-Ready Patterns
+
+> Annotated production-ready Kubernetes manifests. Every example follows the PSS
+> "restricted" profile, includes proper labels, and sets explicit resource
+> constraints.
+
+---
+
+## 1. Minimal Production Deployment
+
+Full security context, resource bounds, probes, topology spread, and standard labels.
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: api-server
+  labels:
+    app.kubernetes.io/name: api-server
+    app.kubernetes.io/version: "1.4.2"
+    app.kubernetes.io/component: backend
+    app.kubernetes.io/managed-by: kubectl
+spec:
+  replicas: 3
+  revisionHistoryLimit: 5
+  selector:
+    matchLabels:
+      app.kubernetes.io/name: api-server
+  template:
+    metadata:
+      labels:
+        app.kubernetes.io/name: api-server
+        app.kubernetes.io/version: "1.4.2"
+    spec:
+      automountServiceAccountToken: false
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 65534
+        runAsGroup: 65534
+        fsGroup: 65534
+        seccompProfile:
+          type: RuntimeDefault
+      topologySpreadConstraints:
+        - maxSkew: 1
+          topologyKey: kubernetes.io/hostname
+          whenUnsatisfiable: DoNotSchedule
+          labelSelector:
+            matchLabels:
+              app.kubernetes.io/name: api-server
+      containers:
+        - name: api-server
+          image: ghcr.io/org/api-server:v1.4.2
+          imagePullPolicy: IfNotPresent
+          ports:
+            - name: http
+              containerPort: 8080
+              protocol: TCP
+          securityContext:
+            allowPrivilegeEscalation: false
+            readOnlyRootFilesystem: true
+            capabilities:
+              drop: ["ALL"]
+          resources:
+            requests:
+              cpu: 100m
+              memory: 128Mi
+            limits:
+              memory: 256Mi
+          livenessProbe:
+            httpGet:
+              path: /healthz
+              port: http
+            initialDelaySeconds: 10
+            periodSeconds: 15
+            failureThreshold: 3
+          readinessProbe:
+            httpGet:
+              path: /readyz
+              port: http
+            initialDelaySeconds: 5
+            periodSeconds: 5
+          volumeMounts:
+            - name: tmp
+              mountPath: /tmp
+      volumes:
+        - name: tmp
+          emptyDir: {}
+```
+
+Key points: readOnlyRootFilesystem requires a writable `/tmp` via emptyDir. Both pod-level and container-level securityContext are set. Topology spread prevents all replicas landing on one node.
+
+## 2. Default-Deny NetworkPolicy
+
+Block all traffic first, then allow only what is needed.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: default-deny-all
+  namespace: my-app
+spec:
+  podSelector: {}
+  policyTypes:
+    - Ingress
+    - Egress
+---
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: allow-api-traffic
+  namespace: my-app
+spec:
+  podSelector:
+    matchLabels:
+      app.kubernetes.io/name: api-server
+  policyTypes:
+    - Ingress
+    - Egress
+  ingress:
+    - from:
+        - namespaceSelector:
+            matchLabels:
+              kubernetes.io/metadata.name: ingress-nginx
+          podSelector:
+            matchLabels:
+              app.kubernetes.io/name: ingress-nginx-controller
+      ports:
+        - protocol: TCP
+          port: 8080
+  egress:
+    - to:
+        - podSelector:
+            matchLabels:
+              app.kubernetes.io/name: postgres
+      ports:
+        - protocol: TCP
+          port: 5432
+    - to:  # DNS
+        - namespaceSelector: {}
+          podSelector:
+            matchLabels:
+              k8s-app: kube-dns
+      ports:
+        - protocol: UDP
+          port: 53
+        - protocol: TCP
+          port: 53
+```
+
+Key points: default-deny with empty `podSelector` applies to every pod in the namespace. Always allow DNS egress or name resolution breaks. Combine `namespaceSelector` and `podSelector` to be specific.
+
+## 3. Scoped RBAC for CI Deployer
+
+Minimal permissions for a CI pipeline that deploys to a single namespace.
+
+```yaml
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: ci-deployer
+  namespace: my-app
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: ci-deployer
+  namespace: my-app
+rules:
+  - apiGroups: ["apps"]
+    resources: ["deployments"]
+    verbs: ["get", "list", "watch", "patch", "update"]
+  - apiGroups: [""]
+    resources: ["configmaps", "secrets"]
+    verbs: ["get", "list", "create", "update", "patch"]
+  - apiGroups: [""]
+    resources: ["services"]
+    verbs: ["get", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: ci-deployer
+  namespace: my-app
+subjects:
+  - kind: ServiceAccount
+    name: ci-deployer
+    namespace: my-app
+roleRef:
+  kind: Role
+  name: ci-deployer
+  apiGroup: rbac.authorization.k8s.io
+```
+
+Key points: namespace-scoped Role, not ClusterRole. Only the verbs needed for deployment. No `delete` verb unless the pipeline needs it.
+
+## 4. CronJob with Lifecycle Controls
+
+Proper concurrency policy, deadline, history limits, and backoff.
+
+```yaml
+apiVersion: batch/v1
+kind: CronJob
+metadata:
+  name: db-backup
+  labels:
+    app.kubernetes.io/name: db-backup
+    app.kubernetes.io/component: maintenance
+spec:
+  schedule: "30 2 * * *"
+  timeZone: "UTC"
+  concurrencyPolicy: Forbid
+  startingDeadlineSeconds: 300
+  successfulJobsHistoryLimit: 3
+  failedJobsHistoryLimit: 5
+  jobTemplate:
+    spec:
+      backoffLimit: 2
+      activeDeadlineSeconds: 3600
+      ttlSecondsAfterFinished: 86400
+      template:
+        spec:
+          restartPolicy: Never
+          automountServiceAccountToken: false
+          securityContext:
+            runAsNonRoot: true
+            runAsUser: 65534
+            seccompProfile:
+              type: RuntimeDefault
+          containers:
+            - name: backup
+              image: ghcr.io/org/db-backup:v2.0.1
+              imagePullPolicy: IfNotPresent
+              securityContext:
+                allowPrivilegeEscalation: false
+                readOnlyRootFilesystem: true
+                capabilities:
+                  drop: ["ALL"]
+              resources:
+                requests:
+                  cpu: 250m
+                  memory: 256Mi
+                limits:
+                  memory: 512Mi
+              env:
+                - name: DB_HOST
+                  value: "postgres.my-app.svc"
+                - name: DB_PASSWORD
+                  valueFrom:
+                    secretKeyRef:
+                      name: db-credentials
+                      key: password
+```
+
+Key points: `concurrencyPolicy: Forbid` prevents overlapping runs. `startingDeadlineSeconds` skips if the schedule window is missed. `activeDeadlineSeconds` kills jobs that hang. `ttlSecondsAfterFinished` auto-cleans completed pods.
+
+## 5. Ingress with TLS and Path-Based Routing
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: app-ingress
+  annotations:
+    nginx.ingress.kubernetes.io/ssl-redirect: "true"
+    nginx.ingress.kubernetes.io/force-ssl-redirect: "true"
+spec:
+  ingressClassName: nginx
+  tls:
+    - hosts:
+        - app.example.com
+      secretName: app-tls-cert
+  rules:
+    - host: app.example.com
+      http:
+        paths:
+          - path: /api
+            pathType: Prefix
+            backend:
+              service:
+                name: api-server
+                port:
+                  number: 8080
+          - path: /
+            pathType: Prefix
+            backend:
+              service:
+                name: frontend
+                port:
+                  number: 3000
+```
+
+Key points: uses `networking.k8s.io/v1` (not the removed beta). `ingressClassName` replaces the deprecated `kubernetes.io/ingress.class` annotation. TLS secret must exist in the same namespace. More specific paths listed first.
+
+## 6. HPA with Scale-Down Stabilization
+
+```yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: api-server
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: api-server
+  minReplicas: 3
+  maxReplicas: 20
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+        - type: Percent
+          value: 25
+          periodSeconds: 60
+    scaleUp:
+      stabilizationWindowSeconds: 0
+      policies:
+        - type: Percent
+          value: 100
+          periodSeconds: 30
+        - type: Pods
+          value: 4
+          periodSeconds: 30
+      selectPolicy: Max
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+    - type: Resource
+      resource:
+        name: memory
+        target:
+          type: Utilization
+          averageUtilization: 80
+```
+
+Key points: `scaleDown.stabilizationWindowSeconds: 300` prevents flapping. Scale-down limited to 25% per minute. Scale-up is aggressive with no stabilization. `autoscaling/v2` gives access to behavior configuration.
+
+## 7. Namespace with Quota, LimitRange, and PSA Labels
+
+```yaml
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: my-app
+  labels:
+    pod-security.kubernetes.io/enforce: restricted
+    pod-security.kubernetes.io/audit: restricted
+    pod-security.kubernetes.io/warn: restricted
+---
+apiVersion: v1
+kind: ResourceQuota
+metadata:
+  name: compute-quota
+  namespace: my-app
+spec:
+  hard:
+    requests.cpu: "4"
+    requests.memory: 8Gi
+    limits.cpu: "8"
+    limits.memory: 16Gi
+    pods: "20"
+    services: "10"
+    persistentvolumeclaims: "5"
+---
+apiVersion: v1
+kind: LimitRange
+metadata:
+  name: default-limits
+  namespace: my-app
+spec:
+  limits:
+    - type: Container
+      default:
+        cpu: 200m
+        memory: 256Mi
+      defaultRequest:
+        cpu: 50m
+        memory: 64Mi
+      max:
+        cpu: "2"
+        memory: 4Gi
+      min:
+        cpu: 10m
+        memory: 16Mi
+```
+
+Key points: PSA labels enforce the restricted profile at the namespace level. ResourceQuota caps total resource consumption. LimitRange provides defaults for containers that omit resource specs and prevents unreasonable single-container requests.
+
+## 8. ExternalSecret for Vault Integration
+
+```yaml
+apiVersion: external-secrets.io/v1beta1
+kind: SecretStore
+metadata:
+  name: vault-backend
+  namespace: my-app
+spec:
+  provider:
+    vault:
+      server: "https://vault.internal:8200"
+      path: "secret"
+      version: "v2"
+      auth:
+        kubernetes:
+          mountPath: "kubernetes"
+          role: "my-app"
+          serviceAccountRef:
+            name: my-app
+---
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: app-secrets
+  namespace: my-app
+spec:
+  refreshInterval: 1h
+  secretStoreRef:
+    name: vault-backend
+    kind: SecretStore
+  target:
+    name: app-secrets
+    creationPolicy: Owner
+    deletionPolicy: Retain
+  data:
+    - secretKey: db-password
+      remoteRef:
+        key: my-app/database
+        property: password
+    - secretKey: api-key
+      remoteRef:
+        key: my-app/external-api
+        property: key
+```
+
+Key points: SecretStore is namespace-scoped (use ClusterSecretStore only when multiple namespaces share the same Vault path). `refreshInterval` controls sync frequency. `deletionPolicy: Retain` keeps the Kubernetes Secret if the ExternalSecret is deleted, preventing accidental data loss.