@synapta/skills 0.1.1 → 0.2.0

package/skills/deploy-k8s/docs/guides/kustomize-patterns.md

@@ -0,0 +1,65 @@
+# Kustomize Patterns
+
+Kustomize provides template-free customization of Kubernetes manifests using overlays and patches. KubeShark follows these conventions when generating or reviewing Kustomize configurations. For full YAML examples and the LLM mistake checklist, see [references/kustomize-patterns.md](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/kustomize-patterns.md).
+
+## Base/Overlay Structure
+
+Organize manifests in a standard directory layout:
+
+- **base/** -- contains the core `kustomization.yaml`, Deployment, Service, and Namespace manifests shared across all environments
+- **overlays/dev/**, **overlays/staging/**, **overlays/production/** -- environment-specific customizations that reference the base
+- **components/** -- reusable cross-cutting features (e.g., monitoring, network policies) that any overlay can include
+
+Every `kustomization.yaml` must declare `apiVersion: kustomize.config.k8s.io/v1beta1`, `kind: Kustomization`, and a `resources` list. Use `resources` (not the deprecated `bases` field) for base references.
+
+## Patches
+
+**Strategic Merge Patch** -- merge into an existing resource structure. Best for adding or overriding specific fields like replica count or resource limits. The patch must include `metadata.name` to match the target resource.
+
+**JSON Patch** -- add, remove, or replace at a specific path. Required for array element manipulation. Use `/-` to append to arrays, explicit indices to target known positions. Applied via inline `patch` blocks with a `target` selector.
+
+## Generators
+
+`configMapGenerator` and `secretGenerator` create ConfigMaps and Secrets with an automatic content hash appended to the name. This hash-based naming triggers rolling updates when configuration changes -- a significant advantage over manually managed ConfigMaps.
+
+When overriding a base generator in an overlay, use `behavior: merge` to extend existing values rather than creating a duplicate resource.
+
+## Components
+
+Components use `apiVersion: kustomize.config.k8s.io/v1alpha1` and `kind: Component`. They package reusable features (ServiceMonitor resources, Prometheus scrape annotations, sidecar injections) that any overlay can opt into via the `components` field.
+
+## Common Transformers
+
+Kustomize provides several built-in transformers for cross-cutting modifications:
+
+- **`namePrefix` / `nameSuffix`** -- add prefixes or suffixes to all resource names
+- **`commonLabels`** -- add labels to all resources and their selectors (use with caution on mutable resources; see LLM mistakes)
+- **`commonAnnotations`** -- add annotations to all resources
+- **`namespace`** -- set the namespace on all resources in the kustomization
+
+## Image Transformer
+
+Override image references without patching the Deployment directly:
+
+- Use `newTag` for tag overrides during development
+- Use `digest` for immutable production references
+- The image transformer matches on the `name` field in container image references, so the name must match exactly
+
+## When to Use Kustomize vs Helm
+
+| Scenario | Recommended |
+|---|---|
+| Environment-specific overlays on static manifests | Kustomize |
+| Complex parameterization with many configuration knobs | Helm |
+| Third-party chart consumption | Helm (required) |
+| CRDs and operator-managed resources | Either |
+| Simple internal services with 2-3 environments | Kustomize |
+| Shared library of templates across teams | Helm (library charts) |
+
+## Production Overlay Pattern
+
+A typical production overlay references the base, sets the namespace, applies production labels, patches resource limits, overrides ConfigMap values with `behavior: merge`, pins image tags, and adds production-only resources like HPAs. See the reference file for a complete example.
+
+## Common LLM Mistakes
+
+The most frequent Kustomize-specific errors LLMs produce include: using the deprecated `bases` field, omitting `metadata.name` in strategic merge patches, applying `commonLabels` to resources with immutable selectors, forgetting content hashes in resource references, wrong array indices in JSON patches, and using the wrong `apiVersion` for components. See the full checklist in the [reference file](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/kustomize-patterns.md#llm-mistake-checklist).

package/skills/deploy-k8s/docs/guides/observability.md

@@ -0,0 +1,67 @@
+# Observability
+
+Metrics, logging, tracing, and alerting for Kubernetes workloads. KubeShark treats observability as mandatory for production -- if you cannot measure it, you cannot operate it. For full configuration examples and the LLM mistake checklist, see [references/observability.md](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/observability.md).
+
+## Probes as the Foundation
+
+Liveness, readiness, and startup probes are the most basic form of observability. They tell Kubernetes whether your application is alive, ready to serve traffic, and initialized. Without correct probes, no amount of metrics or logging prevents cascading failures. See [fragile-rollouts](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/fragile-rollouts.md) for detailed probe rules.
+
+## Prometheus Metrics
+
+### Annotations Pattern
+
+Add `prometheus.io/scrape: "true"`, `prometheus.io/port`, and `prometheus.io/path` annotations to the Pod template metadata (not the Deployment metadata). This enables Prometheus auto-discovery without the prometheus-operator.
+
+### ServiceMonitor Pattern
+
+When using prometheus-operator, prefer ServiceMonitor CRDs for type-safe configuration. The ServiceMonitor `selector.matchLabels` must match the Service labels, and the `release` label must match the Prometheus operator selector.
+
+### RED Method
+
+Every service should expose at minimum:
+
+- **Rate** -- request throughput (`http_requests_total` counter)
+- **Errors** -- failed request count (`http_requests_total{status=~"5.."}`)
+- **Duration** -- request latency (`http_request_duration_seconds` histogram)
+
+Align histogram buckets to your SLO thresholds, not arbitrary defaults. For resource-oriented services (queues, databases), add saturation metrics like queue depth and connection pool usage.
+
+## Structured Logging
+
+Applications must log structured JSON to stdout/stderr. Rules:
+
+- Use `timestamp`, `level`, `msg` as standard fields
+- Include `trace_id` and `span_id` for correlation with distributed traces
+- Never log secrets, tokens, PII, or full request bodies
+- Never log to files inside the container -- it defeats node-level collection and fills the writable layer
+
+Log aggregation uses a DaemonSet pattern (Fluent Bit on every node reading `/var/log/containers/`). Use sidecars only when per-pod log transformation is required.
+
+## OpenTelemetry Tracing
+
+### Auto-Instrumentation
+
+The OpenTelemetry Operator injects instrumentation via pod annotations (e.g., `instrumentation.opentelemetry.io/inject-java: "true"`).
+
+### Collector Sidecar
+
+For fine-grained control, run the OTel Collector as a sidecar with gRPC (4317) and HTTP (4318) OTLP receivers. Set resource requests and limits on the sidecar to prevent it from starving the main workload.
+
+### Context Propagation
+
+Propagate trace context (`traceparent` header / W3C Trace Context) across all service boundaries. Without propagation, traces are fragmented and useless.
+
+## Alerting Patterns
+
+Write symptom-based alerts (what the user experiences), not cause-based alerts (what broke internally):
+
+- **HighErrorRate** -- error rate above SLO threshold for a sustained period
+- **HighLatencyP99** -- p99 latency above target for a sustained period
+
+Every PrometheusRule alert must include a `runbook_url` annotation pointing to actionable remediation steps. Alerts without runbooks are noise.
+
+Use Grafana deployment annotations to correlate metric changes with releases. Integrate annotation creation into your CI/CD pipeline as a post-deploy step.
+
+## Common LLM Mistakes
+
+Key observability errors LLMs produce include: placing Prometheus annotations on the Deployment metadata instead of the Pod template, not declaring the metrics port in the container ports list, generating file-based logging instead of structured JSON to stdout, omitting trace context propagation, writing cause-based alerts instead of symptom-based ones, and omitting resource limits on sidecar containers. See the full checklist in the [reference file](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/observability.md#llm-mistake-checklist).

package/skills/deploy-k8s/docs/guides/security-hardening.md

@@ -0,0 +1,59 @@
+# Security Hardening
+
+Defense-in-depth security for Kubernetes clusters, covering supply chain, admission, runtime, and network layers. KubeShark defaults to the PSS restricted profile for all generated workloads. For full configuration examples and the LLM mistake checklist, see [references/security-hardening.md](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/security-hardening.md).
+
+## NSA/CISA Kubernetes Hardening Guide
+
+Key control areas from the NSA/CISA guidance:
+
+- **Pod security** -- use PSS restricted profile, non-root containers, read-only filesystems, drop all capabilities
+- **Network separation** -- default-deny NetworkPolicy per namespace, encrypt traffic with service mesh mTLS
+- **Authentication** -- disable anonymous auth, use short-lived tokens, integrate OIDC for human users
+- **Authorization** -- RBAC with least privilege, no `cluster-admin` for workloads, regular RoleBinding audits
+- **Audit logging** -- API server audit logging at Metadata level minimum, ship logs off-cluster
+- **Threat detection** -- runtime monitoring with Falco or Tetragon for syscall and network anomaly detection
+- **Upgrading** -- keep cluster and nodes within one minor version of latest, patch CVEs promptly
+
+## OWASP Kubernetes Top 10
+
+KubeShark maps each OWASP K8s risk to a specific reference file: insecure workload configurations (K01), supply chain vulnerabilities (K02), overly permissive RBAC (K03), lack of centralized policy enforcement (K04), inadequate logging (K05), broken authentication (K06), missing network segmentation (K07), secrets management failures (K08), misconfigured cluster components (K09), and outdated components (K10). See the full mapping in the reference file.
+
+## CIS Kubernetes Benchmark
+
+Critical checks organized by component:
+
+- **Control plane** -- API server flags: `--anonymous-auth=false`, `--authorization-mode=RBAC,Node`, `--audit-log-path` set
+- **etcd** -- client cert auth enabled, peer TLS enabled, access limited to API server only
+- **Worker nodes** -- kubelet: `--anonymous-auth=false`, `--authorization-mode=Webhook`, `--read-only-port=0`
+- **Policies** -- PSA enforced, NetworkPolicies present, ResourceQuotas applied
+
+## Pod Security Admission (PSA)
+
+Label every namespace with `enforce`, `audit`, and `warn` modes set to `restricted`. Using all three modes together catches violations at different stages. For gradual migration, enforce `baseline` while auditing and warning on `restricted`, then promote once compliant.
+
+## Image Security and Supply Chain
+
+- **Registry restrictions** -- use an admission webhook (Kyverno or Gatekeeper) to restrict image sources to approved registries
+- **Vulnerability scanning** -- scan images in CI with Trivy before pushing, fail on CRITICAL and HIGH severity
+- **Supply chain attestation** -- generate SBOMs with `syft` or `trivy sbom`, sign images with `cosign`, attach SLSA provenance
+
+## Runtime Security
+
+- **Falco** -- watches syscalls at the kernel level; create rules for shell spawns, sensitive file reads, and unexpected network connections
+- **API server audit policy** -- log at `Metadata` level for secrets and configmaps, `RequestResponse` level for exec and attach operations
+
+## etcd Encryption at Rest
+
+Configure `EncryptionConfiguration` with `aescbc` or `secretbox` providers (never `identity`, which is plaintext). Pass `--encryption-provider-config` to the API server. After applying, re-encrypt existing Secrets with `kubectl get secrets -A -o json | kubectl replace -f -`.
+
+## Network-Level Controls Beyond NetworkPolicy
+
+NetworkPolicy provides segmentation but does not encrypt traffic. For in-transit encryption:
+
+- **Service mesh mTLS** (Istio, Linkerd) -- encrypts all pod-to-pod traffic and provides identity-based authorization
+- **DNS policies** -- restrict external DNS resolution to prevent data exfiltration
+- **Egress gateways** -- force all outbound traffic through a controlled proxy for inspection and allowlisting
+
+## Common LLM Mistakes
+
+Key security errors LLMs produce include: setting only `enforce` without `audit` and `warn` PSA labels, using `identity` encryption instead of `aescbc`, omitting audit logging for secrets and exec operations, using cluster-scoped RBAC bindings when namespace-scoped ones suffice, auto-mounting service account tokens on pods that do not call the API, and relying on NetworkPolicy for encryption when mTLS is needed. See the full checklist in the [reference file](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/security-hardening.md#llm-mistake-checklist).

package/skills/deploy-k8s/docs/guides/validation-and-policy.md

@@ -0,0 +1,66 @@
+# Validation and Policy Enforcement
+
+Manifest validation and policy enforcement for Kubernetes, from offline schema checks to admission-time policy engines. For full configuration examples, CI pipeline templates, and the LLM mistake checklist, see [references/validation-and-policy.md](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/validation-and-policy.md).
+
+## Validation Layers
+
+Apply these three layers in order -- each catches different classes of errors:
+
+1. **Client-side schema validation** (kubeconform) -- catches structural YAML errors, unknown fields, wrong types
+2. **Policy enforcement** (Kyverno / OPA Gatekeeper) -- catches organizational rule violations
+3. **Server-side dry-run** (`kubectl --dry-run=server`) -- catches admission webhook rejections, quota violations, naming conflicts
+
+## kubeconform
+
+Fast, offline schema validation against specific Kubernetes versions.
+
+- Always use `-strict` to reject unknown or misspelled fields
+- Pin `-kubernetes-version` to the target cluster version
+- Use CRD schema registries for custom resources; without them, CRDs are silently skipped
+- Validate Helm output: `helm template ... | kubeconform -strict`
+- Validate Kustomize output: `kustomize build ... | kubeconform -strict`
+
+## kubectl Dry-Run
+
+- **`--dry-run=client`** -- basic YAML parsing only, no server contact, catches syntax errors
+- **`--dry-run=server`** -- full admission chain minus persistence, runs through all webhooks and validations
+
+Always use the explicit `=client` or `=server` form. Bare `--dry-run` is deprecated.
+
+## Kyverno
+
+YAML-native policy engine where policies are Kubernetes resources.
+
+- `ClusterPolicy` applies cluster-wide; `Policy` is namespace-scoped
+- `validationFailureAction: Enforce` blocks non-compliant resources; `Audit` only logs
+- Supports validate, mutate, generate, and verifyImages rule types
+- Common policies: require resource limits, require standard labels, restrict image registries
+
+## OPA Gatekeeper
+
+Policy engine using Rego with a two-object model:
+
+- **ConstraintTemplate** -- defines reusable policy logic in Rego
+- **Constraint** -- applies the template with specific match criteria and parameters
+- Always check both `containers` and `initContainers` in Rego rules to prevent bypasses
+
+## Polaris
+
+Score-based configuration auditing, useful for baseline posture assessment:
+
+- `polaris audit --audit-path manifests/` for local checks
+- `polaris audit --set-exit-code-on-danger` for CI gating
+
+## CI Pipeline Integration
+
+Run validations in this order in your CI pipeline:
+
+```
+validate (kubeconform) -> lint (helm lint / kustomize build) -> policy-check (kyverno/polaris) -> dry-run (server)
+```
+
+A GitHub Actions example that chains these steps is available in the [reference file](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/validation-and-policy.md#github-actions-example).
+
+## Common LLM Mistakes
+
+Key validation and policy errors LLMs produce include: using bare `--dry-run` without `=client` or `=server`, omitting CRD schemas in kubeconform (hiding errors), setting Kyverno to `Audit` instead of `Enforce` in production, missing `initContainers` checks in Gatekeeper rules, matching only `Pod` kind (missing workloads created by Deployments), and skipping server-side dry-run in CI. See the full checklist in the [reference file](https://github.com/LukasNiessen/kubernetes-skill/blob/main/references/validation-and-policy.md#llm-mistake-checklist).

package/skills/deploy-k8s/docs/integrations/mcp-integration.md

@@ -0,0 +1,52 @@
+# MCP Integration
+
+Guidance for integrating the Kubernetes skill with the Model Context Protocol (MCP). MCP servers can provide live cluster facts, organizational policies, and registry information that improve manifest generation quality.
+
+## When to Use MCP
+
+MCP integration is valuable when live cluster or organizational context would improve the generated output:
+
+- **Cluster facts** -- query the cluster version, available API groups, installed CRDs, or node topology to avoid API drift failures
+- **Organization policies** -- retrieve namespace naming conventions, required labels, approved image registries, or resource quota limits
+- **Registry information** -- look up available image tags, verify image existence, or check signing status before referencing in manifests
+
+## What NOT to Do with MCP
+
+- **Never retrieve secrets through MCP** -- credentials, tokens, and keys must come from Kubernetes Secrets, ExternalSecrets, or Sealed Secrets, not from MCP context
+- **Never use MCP to bypass authorization** -- MCP data is informational context, not an authorization mechanism; RBAC decisions belong to the cluster
+- **Never treat MCP data as trusted input for security-sensitive fields** -- do not copy MCP-provided values directly into securityContext, RBAC rules, or NetworkPolicy selectors without validation
+
+## Safe Integration Pattern
+
+Follow this three-step pattern when incorporating MCP data:
+
+1. **Query** -- retrieve the specific fact needed (e.g., cluster version, namespace policy)
+2. **Compare** -- validate the MCP response against known constraints (e.g., is the reported version a valid Kubernetes version?)
+3. **Emit assumptions** -- record what MCP data was used and how it influenced the output in the output contract's assumptions section
+
+## Output Hygiene
+
+Never echo raw MCP data directly into manifests. MCP responses may contain unexpected formatting, stale values, or fields that do not belong in Kubernetes resources. Always:
+
+- Extract only the specific values needed
+- Validate format and range before use
+- Document the MCP source in output assumptions
+
+## Example Uses
+
+**Querying cluster version to select the correct apiVersion:**
+If MCP reports the cluster runs Kubernetes 1.28, use `autoscaling/v2` for HPA (not the removed `v2beta2`). Record the assumption: "Cluster version 1.28 reported via MCP; using autoscaling/v2."
+
+**Querying namespace policies:**
+If MCP reports that the `production` namespace enforces PSA restricted and requires the label `cost-center`, include those constraints in generated manifests and note the MCP source.
+
+**Querying approved registries:**
+If MCP reports that only `registry.example.com` is allowed, use that registry prefix for all image references and note the source.
+
+## Failure Handling
+
+If the MCP server is unavailable or returns an error:
+
+- **Do not block manifest generation** -- proceed with reasonable defaults
+- **State assumptions explicitly** -- document that MCP was unavailable and list the defaults used (e.g., "MCP unavailable; assuming Kubernetes 1.29, PSS restricted profile, no registry restrictions")
+- **Flag for review** -- note in the output contract that the assumptions should be verified against the actual cluster before applying