@synapta/skills 0.1.1 → 0.2.0

package/skills/deploy-docker/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: deploy-docker
+synapta_original_name: multi-stage-dockerfile
+triggers: [synapta deploy docker, Dockerfile, multi-stage build, container, image push]
+network: allowlist
+source:
+  origin: https://github.com/github/awesome-copilot
+  path: skills/multi-stage-dockerfile
+  commit: 4e4b34c48d3f
+  license: MIT (GitHub, Inc.)
+  adapted: light-touch
+description: 'Create optimized multi-stage Dockerfiles for any language or framework'
+---
+
+Your goal is to help me create efficient multi-stage Dockerfiles that follow best practices, resulting in smaller, more secure container images.
+
+## Multi-Stage Structure
+
+- Use a builder stage for compilation, dependency installation, and other build-time operations
+- Use a separate runtime stage that only includes what's needed to run the application
+- Copy only the necessary artifacts from the builder stage to the runtime stage
+- Use meaningful stage names with the `AS` keyword (e.g., `FROM node:18 AS builder`)
+- Place stages in logical order: dependencies → build → test → runtime
+
+## Base Images
+
+- Start with official, minimal base images when possible
+- Specify exact version tags to ensure reproducible builds (e.g., `python:3.11-slim` not just `python`)
+- Consider distroless images for runtime stages where appropriate
+- Use Alpine-based images for smaller footprints when compatible with your application
+- Ensure the runtime image has the minimal necessary dependencies
+
+## Layer Optimization
+
+- Organize commands to maximize layer caching
+- Place commands that change frequently (like code changes) after commands that change less frequently (like dependency installation)
+- Use `.dockerignore` to prevent unnecessary files from being included in the build context
+- Combine related RUN commands with `&&` to reduce layer count
+- Consider using COPY --chown to set permissions in one step
+
+## Security Practices
+
+- Avoid running containers as root - use `USER` instruction to specify a non-root user
+- Remove build tools and unnecessary packages from the final image
+- Scan the final image for vulnerabilities
+- Set restrictive file permissions
+- Use multi-stage builds to avoid including build secrets in the final image
+
+## Performance Considerations
+
+- Use build arguments for configuration that might change between environments
+- Leverage build cache efficiently by ordering layers from least to most frequently changing
+- Consider parallelization in build steps when possible
+- Set appropriate environment variables like NODE_ENV=production to optimize runtime behavior
+- Use appropriate healthchecks for the application type with the HEALTHCHECK instruction

package/skills/deploy-fly/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: deploy-fly
+synapta_original_name: flyctl
+triggers: [synapta deploy fly, flyctl, Fly.io, fly secrets, fly volumes]
+network: allowlist
+source:
+  origin: https://github.com/yurikoval/dotfiles
+  path: claude/.claude/skills/flyctl
+  commit: 933ff7260f40
+  license: see source repo
+  adapted: light-touch
+description: Use when deploying to Fly.io, managing Fly apps/machines/volumes/secrets, scaling VMs, viewing logs, or running fly CLI commands
+---
+
+# flyctl - Fly.io CLI
+
+## Overview
+
+flyctl is the CLI for Fly.io platform. Deploy apps, manage machines, secrets, volumes, databases, and networking.
+
+## Quick Reference
+
+| Task | Command |
+|------|---------|
+| Create app | `fly launch` |
+| Deploy | `fly deploy` |
+| View status | `fly status` |
+| View logs | `fly logs` |
+| SSH into machine | `fly ssh console` |
+| Set secrets | `fly secrets set NAME=value` |
+| Scale VMs | `fly scale count N` |
+| List machines | `fly machine list` |
+
+## Core Commands
+
+### fly launch
+Create and configure new app from source or Docker image.
+
+```bash
+fly launch                          # Interactive setup
+fly launch --name myapp --region lax --no-deploy
+fly launch --image nginx:latest --now
+fly launch --db mpg                 # With managed Postgres
+```
+
+Key flags: `--name`, `--org`, `--region`, `--image`, `--dockerfile`, `--no-deploy`, `--now`, `--vm-size`, `--vm-memory`, `--db`
+
+### fly deploy
+Deploy app from source or image.
+
+```bash
+fly deploy                          # Deploy current directory
+fly deploy --image myimage:tag
+fly deploy --strategy canary        # canary|rolling|bluegreen|immediate
+fly deploy --local-only             # Build locally (not remote)
+fly deploy -e ENV_VAR=value
+```
+
+Key flags: `--app`, `--config`, `--image`, `--dockerfile`, `--strategy`, `--local-only`, `--remote-only`, `--vm-size`, `--regions`, `--env`, `--detach`
+
+### fly status
+Show app status, instances, regions, deployment details.
+
+```bash
+fly status
+fly status --app myapp
+fly status --watch              # Continuous refresh
+fly status --json
+```
+
+### fly logs
+Stream application logs.
+
+```bash
+fly logs
+fly logs --app myapp
+fly logs --region lax
+fly logs --machine MACHINE_ID
+fly logs --no-tail              # Buffered only, no stream
+fly logs --json
+```
+
+## Secrets
+
+Secrets are injected as environment variables at runtime. Names are case-sensitive.
+
+```bash
+fly secrets set DATABASE_URL="postgres://..." SECRET_KEY="abc123"
+fly secrets list
+fly secrets unset SECRET_NAME
+fly secrets import < .env       # Import from stdin
+```
+
+## Machines
+
+Fly Machines are fast-launching VMs.
+
+```bash
+fly machine list
+fly machine create --app myapp
+fly machine start MACHINE_ID
+fly machine stop MACHINE_ID
+fly machine destroy MACHINE_ID
+fly machine status MACHINE_ID
+fly machine clone MACHINE_ID
+fly machine exec MACHINE_ID -- command
+```
+
+## Scaling
+
+```bash
+fly scale show                  # Current resources
+fly scale count 3               # Set VM count
+fly scale count web=3 worker=1  # Per process group
+fly scale vm shared-cpu-2x      # Change VM size
+fly scale memory 512            # Set memory (MB)
+```
+
+VM sizes: `shared-cpu-1x`, `shared-cpu-2x`, `performance-1x`, `performance-2x`, etc.
+
+## Volumes
+
+Persistent storage for machines.
+
+```bash
+fly volumes create myvolume --region lax --size 10
+fly volumes list
+fly volumes show VOL_ID
+fly volumes extend VOL_ID --size 20
+fly volumes destroy VOL_ID
+fly volumes snapshots list VOL_ID
+```
+
+## SSH & File Transfer
+
+```bash
+fly ssh console                 # Interactive shell
+fly ssh console -C "command"    # Run command
+fly sftp get /remote/path ./local/path
+fly sftp put ./local/path /remote/path
+```
+
+## Postgres
+
+```bash
+fly postgres create             # New cluster
+fly postgres list
+fly postgres connect -a pg-app  # psql console
+fly postgres attach pg-app      # Attach to app
+fly postgres detach pg-app
+fly postgres import pg-app < dump.sql
+```
+
+Note: Unmanaged Postgres is user-operated. Use `fly mpg` for managed Postgres.
+
+## Apps Management
+
+```bash
+fly apps list
+fly apps create myapp
+fly apps destroy myapp
+fly apps restart myapp
+fly apps open                   # Open in browser
+fly apps releases               # List releases
+fly apps move myapp --org neworg
+```
+
+## Networking
+
+```bash
+fly ips list
+fly ips allocate-v4
+fly ips allocate-v6
+fly ips release IP_ADDRESS
+fly certs list
+fly certs add example.com
+fly certs remove example.com
+```
+
+## Global Flags
+
+All commands support:
+- `-a, --app` - App name
+- `-c, --config` - Config file path (default: fly.toml)
+- `-t, --access-token` - API token
+- `--debug` - Debug output
+- `--verbose` - Verbose output
+- `--json` / `-j` - JSON output (where supported)
+
+## Common Workflows
+
+**Initial deployment:**
+```bash
+fly auth login
+fly launch
+# Edit fly.toml as needed
+fly deploy
+```
+
+**Update with secrets:**
+```bash
+fly secrets set NEW_SECRET=value
+fly deploy
+```
+
+**Scale for traffic:**
+```bash
+fly scale count 3 --region lax,ord
+fly scale vm performance-1x
+```
+
+**Debug failing app:**
+```bash
+fly status
+fly logs --no-tail
+fly ssh console
+```
+
+## Config File (fly.toml)
+
+Generated by `fly launch`. Key sections:
+- `app` - App name
+- `primary_region` - Default region
+- `[build]` - Build configuration
+- `[env]` - Environment variables
+- `[http_service]` - HTTP settings
+- `[[services]]` - Service definitions
+- `[[mounts]]` - Volume mounts

package/skills/deploy-k8s/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: deploy-k8s
+description: "Prevent Kubernetes hallucinations by diagnosing and fixing failure modes: insecure workload defaults, resource starvation, network exposure, privilege sprawl, fragile rollouts, and API drift. Use when generating, reviewing, refactoring, or migrating manifests, Helm charts, Kustomize overlays, cluster policies, and platform-specific Kubernetes work for EKS, GKE, AKS, OpenShift, GitOps controllers, or observability stacks."
+triggers: [synapta deploy k8s, Kubernetes, kubectl, helm, kustomize, EKS, GKE]
+network: allowlist
+source:
+  origin: https://github.com/LukasNiessen/kubernetes-skill
+  path: /
+  commit: b7d32502e316
+  license: Lukas Niessen (see LICENSE in source repo)
+  adapted: light-touch
+---
+
+# KubeShark: Failure-Mode Workflow for Kubernetes
+
+Run this workflow top to bottom.
+
+## 1) Capture execution context
+
+Record before writing manifests:
+- cluster version (e.g. 1.30, 1.31) and distribution (EKS, GKE, AKS, k3s, vanilla)
+- target namespace and environment criticality (dev/staging/prod)
+- workload type (Deployment, StatefulSet, Job, CronJob, DaemonSet)
+- deployment method (raw YAML, Helm, Kustomize, operator-managed)
+- policy enforcement (Pod Security Admission level, Kyverno, OPA/Gatekeeper)
+- cloud provider and CNI (affects networking, storage classes, load balancers)
+- platform controllers/add-ons (GitOps, observability, ingress, service mesh, autoscaling)
+
+If unknown, state assumptions explicitly.
+
+## 2) Diagnose likely failure mode(s)
+
+Select one or more based on user intent and risk:
+- insecure workload defaults: missing security contexts, PSS violations, host access
+- resource starvation: missing requests/limits, no PDB, scheduling chaos
+- network exposure: flat networking, missing policies, wrong Service types, DNS issues
+- privilege sprawl: overly permissive RBAC, leaked secrets, excess ServiceAccount rights
+- fragile rollouts: misconfigured probes, mutable tags, unsafe update strategies
+- API drift: wrong apiVersion, deprecated APIs, schema violations, tool-specific errors
+
+## 3) Load only the relevant reference file(s)
+
+Primary failure-mode references:
+- `references/insecure-workload-defaults.md`
+- `references/resource-starvation.md`
+- `references/network-exposure.md`
+- `references/privilege-sprawl.md`
+- `references/fragile-rollouts.md`
+- `references/api-drift.md`
+
+Supplemental references (only when needed):
+- `references/deployment-patterns.md`
+- `references/stateful-patterns.md`
+- `references/job-patterns.md`
+- `references/daemonset-operator-patterns.md`
+- `references/security-hardening.md`
+- `references/observability.md`
+- `references/multi-tenancy.md`
+- `references/storage-and-state.md`
+- `references/helm-patterns.md`
+- `references/kustomize-patterns.md`
+- `references/validation-and-policy.md`
+- `references/examples-good.md`
+- `references/examples-bad.md`
+- `references/do-dont-patterns.md`
+
+Conditional Reference Retrieval (CRR) references (load only when the signal is detected):
+- `references/conditional/eks-patterns.md` for EKS, AWS, IRSA, EKS Pod Identity, AWS Load Balancer Controller, EBS/EFS CSI, Karpenter
+- `references/conditional/gke-patterns.md` for GKE, Autopilot, Workload Identity Federation for GKE, Dataplane V2, GCE Ingress, Config Sync
+- `references/conditional/aks-patterns.md` for AKS, Microsoft Entra Workload ID, Azure CNI, AGIC, Azure Disk/File/Blob CSI
+- `references/conditional/openshift-patterns.md` for OpenShift, OKD, ROSA, ARO, Routes, SCCs, OLM, `oc`
+- `references/conditional/gitops-controllers.md` for Argo CD, ApplicationSet, Flux, GitOps reconciliation, sync waves
+- `references/conditional/observability-stacks.md` for Prometheus Operator, ServiceMonitor, PodMonitor, OpenTelemetry, Loki, Grafana
+
+Do not load multiple CRR files unless the task spans multiple detected platforms/tools.
+
+## 4) Propose fix path with explicit risk controls
+
+For each fix, include:
+- why this addresses the failure mode
+- what could still go wrong at deploy time or runtime
+- guardrails (validation commands, policy checks, rollback path)
+
+## 5) Generate implementation artifacts
+
+When applicable, output:
+- Kubernetes manifests (YAML with security contexts, resource limits, labels)
+- Helm values/templates or Kustomize overlays
+- NetworkPolicies, RBAC resources, PodDisruptionBudgets
+- Policy rules (Kyverno/OPA) and admission controls
+
+## 6) Validate before finalize
+
+Always provide validation steps tailored to deployment method and risk tier:
+- `kubectl apply --dry-run=server` or `kubectl diff`
+- `kubeconform` for schema validation against target cluster version
+- cross-resource consistency check (label/selector/port alignment)
+- policy scan (PSS profile check, Kyverno/OPA audit)
+Never recommend direct production apply without reviewed diff and approval.
+
+## 7) Output contract
+
+Return:
+- assumptions and cluster version floor
+- selected failure mode(s)
+- chosen remediation and tradeoffs
+- validation/test plan
+- rollback/recovery notes (rollout undo, revision history, data safety)

package/skills/deploy-k8s/docs/README.md

@@ -0,0 +1,29 @@
+# Kubernetes Skill for Claude Code — KubeShark
+
+KubeShark is a failure-mode-first Kubernetes skill for Claude Code and Codex. It prevents common LLM hallucinations in Kubernetes manifest generation by diagnosing risks before writing YAML.
+
+## Why use it
+
+- **Prevents hallucinations** -- 6 named failure modes with targeted reference files
+- **Token-efficient** -- ~650 token activation cost, granular references loaded on demand
+- **Production-ready defaults** -- Pod Security Standards restricted profile, proper resource management, cross-resource validation
+- **20 reference files** -- covering security, networking, RBAC, probes, storage, Helm, Kustomize, and more
+
+## Key features
+
+- Failure-mode-first diagnostic workflow (diagnose before generate)
+- Output contracts with assumptions, tradeoffs, and rollback notes
+- LLM mistake checklists in every reference file
+- Cross-resource consistency validation (label/selector/port alignment)
+- Helm and Kustomize pattern guidance
+- Policy engine integration (Kyverno, OPA/Gatekeeper)
+
+## Quick install
+
+```bash
+git clone https://github.com/LukasNiessen/kubernetes-skill.git ~/.claude/skills/kubernetes-skill
+```
+
+## License
+
+MIT -- see [LICENSE](https://github.com/LukasNiessen/kubernetes-skill/blob/main/LICENSE).

package/skills/deploy-k8s/docs/SUMMARY.md

@@ -0,0 +1,56 @@
+# Summary
+
+- [Introduction](README.md)
+
+## Getting Started
+
+- [Installation](getting-started/installation.md)
+- [Quick Start](getting-started/quick-start.md)
+
+## Core Concepts
+
+- [Workflow](core-concepts/workflow.md)
+- [Failure Modes](core-concepts/failure-modes.md)
+- [Philosophy](core-concepts/philosophy.md)
+
+## Failure Mode References
+
+- [Insecure Workload Defaults](failure-modes/insecure-workload-defaults.md)
+- [Resource Starvation](failure-modes/resource-starvation.md)
+- [Network Exposure](failure-modes/network-exposure.md)
+- [Privilege Sprawl](failure-modes/privilege-sprawl.md)
+- [Fragile Rollouts](failure-modes/fragile-rollouts.md)
+- [API Drift](failure-modes/api-drift.md)
+
+## Architecture Guidance
+
+- [Workload Patterns](architecture/workload-patterns.md)
+- [Multi-Tenancy](architecture/multi-tenancy.md)
+- [Storage and State](architecture/storage-and-state.md)
+
+## Operational Guides
+
+- [Helm Patterns](guides/helm-patterns.md)
+- [Kustomize Patterns](guides/kustomize-patterns.md)
+- [Security Hardening](guides/security-hardening.md)
+- [Observability](guides/observability.md)
+- [Validation and Policy](guides/validation-and-policy.md)
+
+## Code Examples
+
+- [Good Patterns](examples/good-patterns.md)
+- [Bad Patterns](examples/bad-patterns.md)
+- [Do/Don't Checklist](examples/do-dont-checklist.md)
+
+## Integrations
+
+- [MCP Integration](integrations/mcp-integration.md)
+
+## Advanced
+
+- [Token Efficiency](advanced/token-efficiency.md)
+
+## Community
+
+- [Contributing](community/contributing.md)
+- [Changelog](community/changelog.md)

package/skills/deploy-k8s/docs/advanced/token-efficiency.md

@@ -0,0 +1,61 @@
+# Token Efficiency
+
+How KubeShark minimizes context window consumption while maximizing manifest generation quality.
+
+## The Problem
+
+Context window space is a finite resource. Every token spent on skill content is a token unavailable for the user's actual manifests, conversation history, and tool results. A monolithic skill file that dumps thousands of lines of Kubernetes guidance wastes context on information irrelevant to the current task. This is not just inefficient -- it degrades output quality by forcing the model to process noise alongside signal.
+
+## KubeShark's Approach
+
+KubeShark is designed around three principles:
+
+### Lean Activation
+
+The core SKILL.md is approximately 85 lines (~650 tokens). It contains no YAML examples, no inline manifests, no tutorial material. It is purely procedural: a 7-step workflow the model follows. This means the skill activates with minimal context cost regardless of the task.
+
+### Granular References
+
+Depth lives in 20 separate reference files organized by concern:
+
+- **6 failure mode files** -- insecure workload defaults, resource starvation, network exposure, privilege sprawl, fragile rollouts, API drift
+- **4 workload pattern files** -- Deployments, StatefulSets, Jobs/CronJobs, DaemonSets and operators
+- **4 cross-cutting concern files** -- security hardening, observability, multi-tenancy, storage and state
+- **3 tooling files** -- Helm patterns, Kustomize patterns, validation and policy
+- **3 pattern bank files** -- good examples, bad examples, do/don't checklist
+
+The model loads only the 1-2 files relevant to the diagnosed failure mode. A query about probe configuration never loads the RBAC guidance. A query about Helm chart structure never loads the NetworkPolicy patterns.
+
+### Selective Loading
+
+Step 3 of the workflow explicitly instructs the model to load only the relevant references. This is not a suggestion -- it is a structural constraint built into the diagnostic flow.
+
+## Content Inclusion Rules
+
+Content enters KubeShark only when at least one condition is met:
+
+- It materially lowers the probability of insecure, unreliable, or invalid manifest generation
+- It prevents common deploy-time or runtime surprises (probe cascades, selector mismatches, OOMKills)
+- It encodes operational guardrails that general model knowledge cannot reliably infer
+
+Content is excluded when:
+
+- It is generic Kubernetes knowledge with low failure impact
+- It is cloud-provider-specific deep configuration that belongs in project docs
+- It duplicates an existing rule without adding a new decision signal
+
+## What Models Need Help With
+
+LLMs have strong general Kubernetes knowledge but consistently fail on specific operational details:
+
+- **Security contexts** -- models frequently omit them entirely, producing root-running containers
+- **Cross-resource consistency** -- label/selector/port alignment across Deployment, Service, Ingress, HPA, PDB
+- **API version currency** -- models generate removed APIs from training data (e.g., `extensions/v1beta1`)
+- **Provider-specific constraints** -- storage class capabilities, CNI behavior, load balancer semantics
+- **Probe design** -- liveness probes that check external dependencies, causing cascading failures
+
+Models generally do not need help with basic YAML syntax, resource kind selection, or standard field names. KubeShark avoids restating what models already know reliably.
+
+## Core Principle
+
+High signal density. Every line in every reference file must earn its token cost by reducing the probability of a specific, named failure mode.

package/skills/deploy-k8s/docs/architecture/multi-tenancy.md

@@ -0,0 +1,96 @@
+# Multi-Tenancy
+
+Running multiple teams, environments, or customers in a single Kubernetes cluster requires defense-in-depth isolation. Namespaces are the primary boundary, but a namespace without quotas, network policies, RBAC scoping, and Pod Security Admission is an open door. This guide covers the five layers of namespace isolation and when to use separate clusters instead.
+
+## Namespace as the Isolation Unit
+
+Every Kubernetes isolation mechanism is scoped to namespaces: RBAC, NetworkPolicy, ResourceQuota, LimitRange, and Pod Security Admission. A well-configured tenant namespace enforces all five simultaneously. An unconfigured namespace provides none of them.
+
+## Layer 1: ResourceQuota
+
+Every tenant namespace must have a ResourceQuota. Without it, a single tenant can consume all cluster CPU, memory, and storage, starving other tenants.
+
+ResourceQuota sets aggregate caps on the namespace: total CPU requests, memory limits, pod count, PVC count, and service types. When a ResourceQuota exists, every pod in the namespace must specify resource `requests` and `limits` or admission is rejected. This enforces resource discipline across all workloads.
+
+Key settings for shared clusters:
+- `services.nodeports: "0"` prevents tenants from claiming node ports that conflict across namespaces.
+- `services.loadbalancers` limits the number of cloud load balancers a tenant can provision.
+- `persistentvolumeclaims` caps storage consumption.
+
+## Layer 2: LimitRange
+
+LimitRange complements ResourceQuota by setting per-container defaults and bounds. Without LimitRange, a pod that omits resource specifications is rejected by the quota (since the quota requires explicit resources). LimitRange provides sensible defaults so that "lazy" deployments still get resource boundaries.
+
+LimitRange also sets min/max bounds per container, preventing a single container from requesting disproportionate resources (e.g., 32Gi memory in a namespace with a 40Gi quota).
+
+## Layer 3: NetworkPolicy
+
+By default, pods in different namespaces can communicate freely. Default-deny NetworkPolicy is the minimum viable network isolation for multi-tenancy.
+
+A complete namespace network baseline consists of three policies:
+1. **Default deny all** -- blocks all ingress and egress for every pod in the namespace.
+2. **Allow DNS** -- permits egress to kube-system on port 53 so service discovery works.
+3. **Allow intra-namespace** -- permits pods within the same namespace to communicate.
+
+Additional policies are added as needed for cross-namespace communication (e.g., allowing the ingress controller namespace to reach application pods).
+
+The AND/OR semantics of NetworkPolicy rules are critical for multi-tenancy: a `namespaceSelector` and `podSelector` in the same `from` entry are AND-ed (both must match). Separate `from` entries are OR-ed. Getting this wrong can either block legitimate traffic or open traffic to the entire cluster.
+
+## Layer 4: RBAC Scoping
+
+Use namespace-scoped `Role` and `RoleBinding` for tenant access. `ClusterRole` and `ClusterRoleBinding` grant access across all namespaces and should be reserved for platform administrators.
+
+Tenant RBAC should follow least privilege:
+- Developers: `get`, `list`, `watch`, `create`, `update`, `patch`, `delete` on workload resources (Deployments, Services, ConfigMaps, Jobs). Read-only on Secrets.
+- CI/CD pipelines: `create`, `update`, `patch` on Deployments and ConfigMaps. No access to Secrets (use external secret management).
+- Monitoring: `get`, `list`, `watch` on pods, events, and metrics endpoints.
+
+Never use wildcards (`verbs: ["*"]`, `resources: ["*"]`) in tenant roles. See the [Privilege Sprawl](../failure-modes/privilege-sprawl.md) deep dive for details.
+
+## Layer 5: Pod Security Admission
+
+Every tenant namespace must have PSA labels enforcing at minimum the `baseline` profile, and preferably `restricted`:
+
+```yaml
+labels:
+  pod-security.kubernetes.io/enforce: restricted
+  pod-security.kubernetes.io/audit: restricted
+  pod-security.kubernetes.io/warn: restricted
+```
+
+Set all three modes (enforce, audit, warn). `enforce` blocks non-compliant pods. `audit` logs violations. `warn` shows warnings to users during `kubectl apply`. Using all three provides defense-in-depth and visibility into violations that audit mode catches but enforce mode has not yet been enabled for.
+
+## Naming Conventions
+
+Consistent namespace naming enables policy automation and cost attribution:
+- **Environment-based:** `prod-payments`, `staging-orders`.
+- **Team-based:** `platform-monitoring`, `alpha-api`.
+- **Tenant-based (SaaS):** `acme-prod`, `acme-staging`.
+
+Pick one pattern and enforce it with admission webhooks. Inconsistent naming makes RBAC, cost allocation, and policy application error-prone.
+
+## What Namespaces Do Not Isolate
+
+Namespaces are a soft boundary. They do not provide:
+- **Node-level isolation.** Pods from different namespaces share the same node kernel. A container escape or noisy neighbor affects all tenants on that node. Use taints/tolerations and dedicated node pools for hard isolation.
+- **Cluster-scoped resources.** ClusterRoles, CRDs, PersistentVolumes, and Nodes are visible cluster-wide.
+- **Network without NetworkPolicy.** Namespaces without NetworkPolicy allow all traffic by default.
+- **Container runtime isolation.** A kernel exploit reaches the host regardless of namespace. Use sandboxed runtimes (gVisor, Kata Containers) for untrusted workloads.
+
+## When to Use Separate Clusters
+
+| Factor | Namespaces | Separate clusters |
+|---|---|---|
+| Blast radius tolerance | Shared risk acceptable | Zero cross-tenant impact required |
+| Compliance | Same regulatory domain | Different requirements (PCI vs non-PCI) |
+| Kubernetes version | Same version for all tenants | Tenants need different versions |
+| Cost | Lower (shared control plane) | Higher but stronger isolation |
+| Noisy neighbor risk | Acceptable with quotas | Unacceptable (latency-sensitive) |
+
+Rule of thumb: use namespaces for internal teams in the same trust domain. Use separate clusters when tenants are external customers, have different compliance requirements, or when the blast radius of a cluster-level failure is unacceptable.
+
+## Further Reading
+
+- [Namespaces](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/)
+- [KubeShark Privilege Sprawl](../failure-modes/privilege-sprawl.md)
+- [KubeShark Network Exposure](../failure-modes/network-exposure.md)