@synapta/skills 0.1.0 → 0.1.2

package/skills/deploy-k8s/docs/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "kubernetes-skill-docs",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "build": "honkit build",
+    "serve": "honkit serve"
+  },
+  "devDependencies": {
+    "honkit": "^6.1.6",
+    "gitbook-plugin-search-pro": "^2.0.2"
+  }
+}

package/skills/deploy-k8s/references/api-drift.md

@@ -0,0 +1,298 @@
+# API Drift
+
+**Directive:** When generating any Kubernetes manifest, Helm chart, or Kustomize overlay, ALWAYS use the current stable API version for the target cluster version. Never assume an API version is correct from training data -- verify it. LLMs hallucinate deprecated and removed API versions frequently.
+
+## When to use
+
+Consult this reference whenever the task involves:
+- Generating any Kubernetes manifest from scratch
+- Upgrading manifests for a newer cluster version
+- Writing or reviewing Helm templates
+- Writing or reviewing Kustomize overlays and patches
+- Validating manifests before applying to a cluster
+
+## Symptoms of API drift
+
+| Symptom | Cause |
+|---|---|
+| `error: unable to recognize: no matches for kind "Ingress" in version "extensions/v1beta1"` | Using a removed apiVersion |
+| `Warning: policy/v1beta1 PodDisruptionBudget is deprecated` | Using deprecated but not yet removed apiVersion |
+| Fields silently ignored after upgrade | Field existed in beta, removed or renamed in stable |
+| `unknown field "spec.hard"` in `kubectl apply` | Structural schema validation rejects unknown fields in stable APIs |
+| Helm template renders but `kubectl apply` fails | Template produces syntactically valid YAML with wrong apiVersion |
+
+## Root causes
+
+1. LLM training data contains outdated manifests from blog posts, Stack Overflow, and old documentation.
+2. Copy-paste from tutorials written for Kubernetes 1.18-1.21 era.
+3. Helm charts pinned to old API versions without `Capabilities` checks.
+4. Not running schema validation against the target cluster version.
+5. Confusing "deprecated" (still works, prints warning) with "removed" (hard failure).
+
+## The API deprecation lifecycle
+
+Kubernetes follows a predictable pattern:
+
+1. **Beta API introduced** (e.g., `extensions/v1beta1 Ingress` in 1.1)
+2. **Stable API introduced** (e.g., `networking.k8s.io/v1 Ingress` in 1.19)
+3. **Beta API deprecated** (same release as stable introduction, or one release later)
+4. **Beta API removed** (usually 2-3 minor versions after deprecation, per policy)
+
+Once removed, the API server rejects manifests using that version. There is no graceful fallback.
+
+## Major API migrations LLMs frequently get wrong
+
+### Ingress: extensions/v1beta1 and networking.k8s.io/v1beta1 -> networking.k8s.io/v1
+
+- Removed in: **Kubernetes 1.22**
+- Key structural changes in v1:
+  - `spec.backend` renamed to `spec.defaultBackend`
+  - `serviceName` and `servicePort` replaced with `service.name` and `service.port.number` (or `service.port.name`)
+  - `pathType` is now **required** on every path (was optional in beta)
+  - `ingressClassName` replaces the `kubernetes.io/ingress.class` annotation
+
+### PodDisruptionBudget: policy/v1beta1 -> policy/v1
+
+- Removed in: **Kubernetes 1.25**
+- Key changes in v1:
+  - `spec.selector` is now immutable after creation
+  - Unhealthy pod eviction policy field added (`spec.unhealthyPodEvictionPolicy`)
+
+### HorizontalPodAutoscaler: autoscaling/v2beta1 and v2beta2 -> autoscaling/v2
+
+- v2beta1 removed in: **Kubernetes 1.25**
+- v2beta2 removed in: **Kubernetes 1.26**
+- Key changes in v2:
+  - `targetAverageUtilization` moved under `target.averageUtilization`
+  - `metrics[].type` uses `ContainerResource` for per-container scaling
+  - `behavior` field for scale-up/scale-down policies is stable
+
+### FlowSchema/PriorityLevelConfiguration: flowcontrol.apiserver.k8s.io/v1beta1 -> v1beta3 -> v1
+
+- v1beta1 removed in: **Kubernetes 1.26**
+- v1beta2 removed in: **Kubernetes 1.29**
+- v1beta3 removed in: **Kubernetes 1.32**
+
+### Other common migrations
+
+| Resource | Old API | Current Stable API | Removed in |
+|---|---|---|---|
+| CronJob | batch/v1beta1 | batch/v1 | 1.25 |
+| EndpointSlice | discovery.k8s.io/v1beta1 | discovery.k8s.io/v1 | 1.25 |
+| CSIDriver, CSINode | storage.k8s.io/v1beta1 | storage.k8s.io/v1 | 1.22 |
+| CertificateSigningRequest | certificates.k8s.io/v1beta1 | certificates.k8s.io/v1 | 1.22 |
+| TokenReview | authentication.k8s.io/v1beta1 | authentication.k8s.io/v1 | 1.22 |
+
+## API version quick reference (current stable)
+
+| Resource | apiVersion |
+|---|---|
+| Deployment, ReplicaSet, StatefulSet, DaemonSet | apps/v1 |
+| Service, ConfigMap, Secret, Pod, Namespace | v1 |
+| Ingress | networking.k8s.io/v1 |
+| NetworkPolicy | networking.k8s.io/v1 |
+| HorizontalPodAutoscaler | autoscaling/v2 |
+| PodDisruptionBudget | policy/v1 |
+| CronJob, Job | batch/v1 |
+| ServiceAccount | v1 |
+| Role, ClusterRole, RoleBinding, ClusterRoleBinding | rbac.authorization.k8s.io/v1 |
+| PersistentVolumeClaim, PersistentVolume | v1 |
+| StorageClass | storage.k8s.io/v1 |
+| IngressClass | networking.k8s.io/v1 |
+| EndpointSlice | discovery.k8s.io/v1 |
+| ValidatingWebhookConfiguration | admissionregistration.k8s.io/v1 |
+
+## Schema validation
+
+### Structural vs semantic validity
+
+A manifest can be valid YAML and even match the general shape of a Kubernetes resource while still being wrong:
+- **Structural validity**: "Does this YAML parse? Do the fields exist in the schema?" -- caught by `kubeconform` or `--dry-run=server`.
+- **Semantic validity**: "Does this make sense? Does the referenced Service exist? Is the port correct?" -- only caught at apply time or with policy tools.
+
+### kubeconform usage
+
+```bash
+# Validate against a specific Kubernetes version
+kubeconform -kubernetes-version 1.29.0 -strict manifests/
+
+# Validate with CRD schemas (e.g., from datreeio/CRDs-catalog)
+kubeconform -kubernetes-version 1.29.0 \
+  -schema-location default \
+  -schema-location 'https://raw.githubusercontent.com/datreeio/CRDs-catalog/main/{{.Group}}/{{.ResourceKind}}_{{.ResourceAPIVersion}}.json' \
+  manifests/
+
+# Validate Helm output
+helm template my-release ./chart | kubeconform -kubernetes-version 1.29.0 -strict
+```
+
+### kubectl dry-run
+
+- `--dry-run=client`: validates locally against the client's built-in schema. Fast but may be outdated.
+- `--dry-run=server`: sends the request to the API server for validation without persisting. More accurate -- catches unknown fields, CRD validation, admission webhooks.
+
+```bash
+# Server-side dry-run (preferred)
+kubectl apply -f manifest.yaml --dry-run=server
+
+# Client-side dry-run (no cluster needed)
+kubectl apply -f manifest.yaml --dry-run=client
+```
+
+## Helm-specific drift errors
+
+- **Broken Go templates**: `{{ .Values.replicas }}` fails if `replicas` is not defined in `values.yaml`. Always use `{{ .Values.replicas | default 3 }}` or check with `{{ if .Values.replicas }}`.
+- **API version in templates**: Use `Capabilities.APIVersions` to branch on cluster version:
+
+```yaml
+{{- if .Capabilities.APIVersions.Has "networking.k8s.io/v1" }}
+apiVersion: networking.k8s.io/v1
+{{- else }}
+apiVersion: networking.k8s.io/v1beta1
+{{- end }}
+```
+
+- **Missing Chart.yaml fields**: `apiVersion: v2` is required for Helm 3. `type: application` (default) or `type: library` must be valid.
+
+## Kustomize-specific drift errors
+
+- **Invalid patch target**: the `target` in a strategic merge patch must specify the correct `group`, `version`, `kind`. A wrong API group silently fails to match.
+- **Wrong resource in kustomization.yaml**: listing a file with a removed apiVersion causes `kustomize build` to fail.
+
+## Patterns and examples
+
+### GOOD: Manifest with correct current apiVersions
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: web-ingress
+  namespace: frontend
+spec:
+  ingressClassName: nginx                       # not annotation
+  rules:
+    - host: app.example.com
+      http:
+        paths:
+          - path: /
+            pathType: Prefix                    # required in v1
+            backend:
+              service:
+                name: web-frontend
+                port:
+                  number: 8080                  # nested under service.port
+---
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: web-frontend-hpa
+  namespace: frontend
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: web-frontend
+  minReplicas: 3
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+```
+
+### BAD: Manifest mixing deprecated and removed apiVersions
+
+```yaml
+# DO NOT DO THIS
+apiVersion: extensions/v1beta1           # REMOVED in 1.22
+kind: Ingress
+metadata:
+  name: web-ingress
+  annotations:
+    kubernetes.io/ingress.class: nginx   # replaced by spec.ingressClassName
+spec:
+  backend:                               # renamed to defaultBackend in v1
+    serviceName: web-frontend            # flat fields replaced by nested service block
+    servicePort: 8080
+  rules:
+    - host: app.example.com
+      http:
+        paths:
+          - path: /
+                                         # missing pathType (required in v1)
+            backend:
+              serviceName: web-frontend
+              servicePort: 8080
+---
+apiVersion: autoscaling/v2beta1          # REMOVED in 1.25
+kind: HorizontalPodAutoscaler
+metadata:
+  name: web-frontend-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: web-frontend
+  minReplicas: 3
+  maxReplicas: 20
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        targetAverageUtilization: 70     # moved to target.averageUtilization in v2
+```
+
+## LLM mistake checklist
+
+Before finalizing any Kubernetes manifest, verify each item:
+
+- [ ] Every `apiVersion` is checked against the quick reference table above, not generated from memory
+- [ ] Ingress uses `networking.k8s.io/v1`, NOT `extensions/v1beta1` or `networking.k8s.io/v1beta1`
+- [ ] Ingress paths include `pathType` (required in v1)
+- [ ] Ingress backend uses nested `service.name` / `service.port.number`, not flat `serviceName` / `servicePort`
+- [ ] HPA uses `autoscaling/v2`, NOT `v2beta1` or `v2beta2`
+- [ ] PodDisruptionBudget uses `policy/v1`, NOT `policy/v1beta1`
+- [ ] CronJob uses `batch/v1`, NOT `batch/v1beta1`
+- [ ] No `extensions/v1beta1` appears anywhere in the output
+- [ ] If targeting a specific cluster version, all apiVersions are validated against that version
+- [ ] Helm templates use `Capabilities.APIVersions` checks when supporting multiple cluster versions
+- [ ] `kubeconform` or `--dry-run=server` validation is included in the workflow
+
+## Verification commands
+
+```bash
+# Scan for deprecated APIs in manifests using pluto
+pluto detect-files -d manifests/
+pluto detect-helm -owide
+
+# Scan for deprecated APIs in a running cluster
+pluto detect-api-resources --cluster
+
+# Validate manifests against a specific Kubernetes version
+kubeconform -kubernetes-version 1.29.0 -strict -summary manifests/
+
+# Validate Helm-rendered output
+helm template my-release ./chart -f values.yaml | kubeconform -kubernetes-version 1.29.0 -strict
+
+# Check which API versions the current cluster supports
+kubectl api-versions | sort
+
+# Check if a specific API version exists
+kubectl api-versions | grep networking.k8s.io
+
+# Server-side dry-run to validate against live cluster schema
+kubectl apply -f manifest.yaml --dry-run=server --validate=true
+
+# List resources with deprecated API annotations (if using migration tools)
+kubectl get all -A -o json | jq -r '.items[] | select(.apiVersion | test("beta")) | .apiVersion + " " + .kind + " " + .metadata.namespace + "/" + .metadata.name'
+
+# Validate Kustomize output
+kustomize build overlays/production | kubeconform -kubernetes-version 1.29.0 -strict
+```

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

@@ -0,0 +1,70 @@
+# AKS Patterns
+
+**Load this reference when detected:** AKS, Azure Kubernetes Service, Microsoft Entra Workload ID, Azure CNI, Azure CNI Overlay, kubenet, Application Gateway Ingress Controller, AGIC, Azure Disk CSI, Azure Files CSI, Azure Blob CSI, or Azure Policy for AKS.
+
+## Why this matters
+
+AKS has Azure-specific identity, networking, ingress, and storage behavior. Generic Kubernetes YAML often deploys but fails to authenticate, route, or mount volumes correctly. Do not load this file for non-Azure clusters.
+
+## Identity
+
+Prefer Microsoft Entra Workload ID for pod access to Azure resources.
+
+- Enable OIDC issuer and workload identity at the cluster level before relying on pod identity.
+- Add `azure.workload.identity/use: "true"` to pods that require workload identity.
+- Annotate the Kubernetes ServiceAccount with `azure.workload.identity/client-id`.
+- Restart pods after ServiceAccount identity annotation changes.
+- Do not recommend the deprecated Microsoft Entra pod-managed identity path for new work.
+- Never place Azure client secrets in Kubernetes Secrets unless the user explicitly accepts that risk and there is no workload-identity option.
+
+## Networking
+
+Capture AKS network plugin and outbound path before generating network-sensitive manifests.
+
+- Azure CNI Overlay is the strategic path for many new clusters and for kubenet migration.
+- kubenet is scheduled for AKS retirement on March 31, 2028; do not recommend it for new long-lived clusters.
+- NetworkPolicy behavior depends on the selected policy engine and network plugin.
+- For private clusters, verify DNS, egress, and private endpoint assumptions before recommending public endpoints.
+
+## Ingress and Load Balancing
+
+Choose the controller deliberately.
+
+- AGIC and Application Gateway for Containers are Azure-specific; do not use nginx annotations with them.
+- If using AGIC, verify Application Gateway SKU, managed identity permissions, subnet placement, and controller add-on status.
+- Use Service type `LoadBalancer` for L4 exposure, but include internal/public load balancer annotations only when the requirement is explicit.
+- Prefer Ingress or Gateway patterns for HTTP routing rather than exposing every workload through a public LoadBalancer.
+
+## Storage
+
+Choose Azure storage by access pattern.
+
+- Azure Disk CSI: block storage for RWO-style workloads.
+- Azure Files CSI: shared SMB/NFS file storage for RWX workloads.
+- Azure Blob CSI: object-backed mount use cases; do not treat it as a generic database volume.
+- Validate StorageClass names from the cluster instead of inventing them.
+
+## Validation
+
+- `kubectl apply --dry-run=server -f <manifest>`
+- `kubectl describe pod <name>` for workload identity webhook injection and projected token issues
+- `kubectl get ingress,svc -A` and controller logs for AGIC/Application Gateway issues
+- `kubectl get storageclass` before selecting Azure Disk/File/Blob classes
+- `az aks show --name <cluster> --resource-group <rg>` when identity, OIDC issuer, or network plugin is unknown
+
+## LLM Mistake Checklist
+
+- Using deprecated pod-managed identity for new AKS work.
+- Missing the required workload identity pod label.
+- Forgetting that ServiceAccount annotation changes require pod restart.
+- Recommending kubenet for new long-lived clusters.
+- Mixing nginx annotations into AGIC-managed Ingress resources.
+- Treating Azure Disk as RWX storage.
+- Assuming StorageClass names without checking the cluster.
+
+## Grounding Sources
+
+- Microsoft Entra Workload ID for AKS: https://learn.microsoft.com/en-us/azure/aks/workload-identity-overview
+- Deploy Workload ID on AKS: https://learn.microsoft.com/en-us/azure/aks/workload-identity-deploy-cluster
+- AKS kubenet retirement notice: https://learn.microsoft.com/en-us/azure/aks/configure-kubenet
+- AKS CSI storage drivers: https://learn.microsoft.com/en-us/azure/aks/azure-blob-csi

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

@@ -0,0 +1,79 @@
+# EKS Patterns
+
+**Load this reference when detected:** EKS, AWS, IRSA, EKS Pod Identity, AWS Load Balancer Controller, AWS VPC CNI, EBS CSI, EFS CSI, Karpenter, or EKS add-ons.
+
+## Why this matters
+
+EKS looks like upstream Kubernetes until identity, load balancing, pod networking, storage, and node provisioning enter the design. Those surfaces are AWS-integrated and high-risk for LLM drift. Do not load this file for non-AWS clusters.
+
+## Identity
+
+Prefer short-lived pod identity over static AWS keys.
+
+- Use one IAM role per workload or controller responsibility.
+- Prefer EKS Pod Identity where the cluster and organization support it; otherwise use IRSA.
+- For IRSA, annotate the Kubernetes ServiceAccount with `eks.amazonaws.com/role-arn`.
+- For EKS Pod Identity, keep the ServiceAccount name and namespace stable because the pod identity association is bound to them.
+- Set `automountServiceAccountToken: false` for workloads that do not call AWS or Kubernetes APIs.
+- Never put AWS access keys in Secrets, ConfigMaps, Helm values, or CI artifacts.
+
+## Load Balancing
+
+Choose the controller by traffic type.
+
+- HTTP/HTTPS: use Ingress or Gateway resources managed by the AWS Load Balancer Controller.
+- L4 TCP/UDP: use `Service` type `LoadBalancer` with NLB-specific annotations only when required.
+- Do not copy nginx, GCE, or AGIC annotations into AWS resources.
+- Verify subnet tags and security group rules when a load balancer is requested but not provisioned.
+- Treat controller annotations as version-sensitive; check the installed controller version before generating advanced annotations.
+
+## Storage
+
+Use the CSI driver that matches access semantics.
+
+- EBS CSI: block storage, normally ReadWriteOnce, tied to zone scheduling.
+- EFS CSI: shared file storage for ReadWriteMany workloads.
+- For StatefulSets using EBS, include topology-aware scheduling expectations and do not assume a pod can move across zones without volume implications.
+- Use `VolumeSnapshot` only when the snapshot CRDs and driver support are installed.
+
+## Networking
+
+AWS VPC CNI assigns pod IPs from the VPC address space.
+
+- Watch subnet/IP exhaustion before increasing replicas or max pods.
+- NetworkPolicy requires a compatible implementation; do not assume policy enforcement solely because the cluster is EKS.
+- Security Groups for Pods change the boundary from node-level to pod-level security; use only when enabled and needed.
+- Private clusters need VPC endpoints for controllers that call AWS APIs.
+
+## Karpenter and Node Provisioning
+
+When Karpenter is detected:
+
+- Use current Karpenter APIs for `NodePool` and provider-specific node classes.
+- Keep workload scheduling constraints explicit: requests, tolerations, node selectors, topology spread, and disruption sensitivity.
+- Set consolidation/disruption behavior deliberately for stateful or latency-sensitive workloads.
+- Do not let Karpenter compensate for missing resource requests; bad requests produce bad capacity decisions.
+
+## Validation
+
+- `kubectl apply --dry-run=server -f <manifest>`
+- `kubectl describe service <name>` or `kubectl describe ingress <name>` for load balancer events
+- `kubectl describe sa <name> -n <namespace>` for IRSA annotation checks
+- `kubectl get pods -o wide` to verify zone/node placement for EBS-backed StatefulSets
+- Check AWS controller logs for IAM denial, subnet discovery, or security group errors
+
+## LLM Mistake Checklist
+
+- Recommending static AWS keys in Kubernetes Secrets.
+- Mixing IRSA annotations with EKS Pod Identity assumptions without naming which mechanism is used.
+- Generating nginx or GCE Ingress annotations for AWS Load Balancer Controller.
+- Treating EBS as ReadWriteMany storage.
+- Omitting resource requests while also recommending Karpenter.
+- Assuming NetworkPolicy is enforced without confirming the CNI/policy engine.
+- Forgetting that ServiceAccount namespace/name changes can break identity bindings.
+
+## Grounding Sources
+
+- AWS EKS identity best practices: https://docs.aws.amazon.com/eks/latest/best-practices/identity-and-access-management.html
+- EKS Pod Identity: https://docs.aws.amazon.com/eks/latest/userguide/pod-identities.html
+- EKS Karpenter best practices: https://docs.aws.amazon.com/eks/latest/best-practices/karpenter.html

package/skills/deploy-k8s/references/conditional/gitops-controllers.md

@@ -0,0 +1,71 @@
+# GitOps Controllers
+
+**Load this reference when detected:** Argo CD, Application, ApplicationSet, sync waves, Flux, GitRepository, Kustomization, HelmRepository, HelmRelease, OCIRepository, GitOps, Config Sync, OpenShift GitOps, or pull-based deployment.
+
+## Why this matters
+
+GitOps controllers continuously reconcile desired state. A manifest that is safe with manual `kubectl apply` can become unsafe when pruning, self-healing, sync ordering, generated Applications, or Helm remediation are enabled. Do not load this file for ordinary one-off YAML unless a GitOps controller is involved.
+
+## Shared GitOps Rules
+
+- Treat Git as the source of truth; avoid manual `kubectl edit` remediation except as an emergency action followed by a Git fix.
+- Separate application source code from environment configuration when auditability matters.
+- Pin chart versions, OCI artifact digests, or Git revisions for production.
+- Keep cluster-scoped resources, CRDs, namespaces, and policy baselines in clearly owned bootstrap layers.
+- Use narrow controller credentials; the controller should not have cluster-admin by default.
+- Pruning and self-healing are powerful; enable them only with rollback and ownership boundaries.
+
+## Argo CD
+
+When generating Argo CD resources:
+
+- Use `argoproj.io` API versions that match the installed Argo CD version.
+- Use sync waves for resource ordering within a sync operation; do not assume they order unrelated independent Applications.
+- Use hooks only for idempotent Jobs or lifecycle actions with deletion policies.
+- Keep `ignoreDifferences` narrow and documented; never hide broad drift to make sync look green.
+- For ApplicationSet, verify generator inputs and destination namespaces before enabling automated sync.
+- Avoid auto-prune for production bootstrap unless ownership is explicit and reviewed.
+
+## Flux
+
+When generating Flux resources:
+
+- Distinguish Flux `Kustomization` CRs from `kustomization.yaml` files.
+- Use `dependsOn` for explicit ordering between Flux Kustomizations or HelmReleases.
+- Configure remediation for Helm install/upgrade failures instead of leaving infinite broken retries.
+- Keep `interval`, `timeout`, `retryInterval`, and `prune` deliberate per environment.
+- Use SOPS or an approved external secret flow for encrypted secrets in Git.
+- Validate source references: `GitRepository`, `OCIRepository`, `HelmRepository`, and chart names.
+
+## Rollout and Drift Controls
+
+- For CRD upgrades, apply CRDs before custom resources and avoid deleting CRDs while CRs exist.
+- For generated namespaces, verify ownership before pruning.
+- For multi-cluster GitOps, make cluster selection explicit and review generator filters.
+- For Helm under GitOps, render locally and validate the rendered manifests before relying on controller reconciliation.
+
+## Validation
+
+- Argo CD: `argocd app diff <app>` and `argocd app get <app>`
+- Argo CD in-cluster: `kubectl get applications,applicationsets -A`
+- Flux: `flux diff kustomization <name> --path <path>` where available
+- Flux: `flux reconcile kustomization <name> --with-source` for controlled reconciliation
+- Generic: render Helm/Kustomize output and run `kubectl apply --dry-run=server`
+
+## LLM Mistake Checklist
+
+- Enabling automated prune/self-heal without ownership boundaries.
+- Assuming sync waves order separate Applications or separate controllers.
+- Creating hooks that are not idempotent.
+- Using broad `ignoreDifferences` to mask real drift.
+- Confusing Flux `Kustomization` CRs with Kustomize files.
+- Omitting `dependsOn` for Flux resources that require ordering.
+- Putting plaintext secrets in Git because GitOps needs declarative state.
+
+## Grounding Sources
+
+- Argo CD best practices: https://argo-cd.readthedocs.io/en/stable/user-guide/best_practices/
+- Argo CD sync phases and waves: https://argo-cd.readthedocs.io/en/stable/user-guide/sync-waves/
+- Argo CD ApplicationSet progressive syncs: https://argo-cd.readthedocs.io/en/stable/operator-manual/applicationset/Progressive-Syncs/
+- Flux concepts: https://fluxcd.io/flux/concepts/
+- Flux Helm controller: https://fluxcd.io/docs/components/helm/

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

@@ -0,0 +1,74 @@
+# GKE Patterns
+
+**Load this reference when detected:** GKE, Google Kubernetes Engine, Autopilot, Standard, Workload Identity Federation for GKE, GKE Dataplane V2, GCE Ingress, Cloud Load Balancing, Filestore CSI, Persistent Disk CSI, or Config Sync.
+
+## Why this matters
+
+GKE guidance changes depending on Standard versus Autopilot, identity mode, dataplane, and Google Cloud load-balancing integration. Do not load this file for non-Google clusters.
+
+## Cluster Mode
+
+Capture whether the cluster is Standard or Autopilot.
+
+- Autopilot enforces stronger platform constraints and may reject or mutate unsupported pod settings.
+- Avoid host access, privileged workloads, and node-level assumptions for Autopilot unless the user explicitly confirms support.
+- In Standard clusters, node pools, taints, and workload placement are user-managed; include scheduling and upgrade safety controls.
+- Do not generate DaemonSet or privileged-agent patterns for Autopilot without checking compatibility.
+
+## Workload Identity
+
+Prefer Workload Identity Federation for GKE over service account JSON keys.
+
+- Bind Kubernetes service accounts to Google Cloud IAM identities using the project and namespace/service account boundary.
+- Never mount service account key files into pods for normal cloud API access.
+- When NetworkPolicy is used with GKE Dataplane V2 and the workload needs Google Cloud auth, ensure egress to the metadata server is allowed.
+- Keep ServiceAccount names stable because IAM bindings and manifests depend on them.
+
+## Networking and Ingress
+
+Controller-specific behavior matters.
+
+- Do not copy nginx, AWS ALB, or AGIC annotations into GCE Ingress resources.
+- For Google Cloud Load Balancing, verify Service, backend, health check, and NEG expectations.
+- Prefer Gateway API only when the target cluster has the required GKE Gateway controller and CRDs.
+- For Dataplane V2, validate NetworkPolicy behavior against GKE documentation rather than assuming another CNI's semantics.
+
+## Storage
+
+Choose storage by access pattern.
+
+- Persistent Disk CSI: block storage for RWO-style workloads; account for zone or regional topology.
+- Filestore CSI: shared file storage for RWX workloads.
+- Do not assume volume snapshots are available until snapshot CRDs and the relevant CSI driver support are present.
+- For StatefulSets, combine storage with topology spread and disruption controls.
+
+## Config Sync and Fleet Policy
+
+When Config Sync or Anthos/Fleet policy is detected:
+
+- Treat Git as the source of truth for managed resources.
+- Avoid imperative `kubectl edit` or manual drift fixes in generated runbooks.
+- Keep namespace and cluster-scoped resources in the repository structure expected by the platform team.
+
+## Validation
+
+- `kubectl apply --dry-run=server -f <manifest>`
+- `kubectl describe ingress <name>` for Google load balancer events
+- `kubectl describe networkpolicy <name>` plus connectivity tests for Dataplane V2 behavior
+- `kubectl get storageclass` before choosing PD or Filestore classes
+- `gcloud container clusters describe <cluster> --region <region>` when cluster mode or Workload Identity status is unknown
+
+## LLM Mistake Checklist
+
+- Recommending service account JSON keys instead of Workload Identity Federation.
+- Generating privileged/host-level workloads for Autopilot without compatibility checks.
+- Mixing nginx or AWS ALB annotations into GCE Ingress.
+- Forgetting metadata-server egress when restrictive NetworkPolicies and GCP auth are both present.
+- Treating zonal Persistent Disks as freely movable across zones.
+- Assuming Gateway API support without confirming installed controller/CRDs.
+
+## Grounding Sources
+
+- Workload Identity Federation for GKE: https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity
+- GKE Dataplane V2: https://cloud.google.com/kubernetes-engine/docs/how-to/dataplane-v2
+- Config Sync GitOps best practices: https://docs.cloud.google.com/kubernetes-engine/config-sync/docs/concepts/gitops-best-practices