/infra-containers-kubernetes

name: infra-containers-kubernetes
description: Kubernetes manifests, Helm charts, Kustomize overlays, and resource patterns

Kubernetes Patterns

> **Quick Guide:** Declarative YAML manifests for Kubernetes workloads. Use `apps/v1` Deployments with resource requests/limits, health probes, and Pod Security Standards (restricted profile). Helm for templated multi-environment releases. Kustomize for patch-based overlays without templating. Always set `securityContext` (runAsNonRoot, drop ALL capabilities, readOnlyRootFilesystem), resource requests/limits on every container, and liveness/readiness probes on every pod.

---

<critical_requirements>

CRITICAL: Before Using This Skill

> **All code must follow project conventions in CLAUDE.md** (kebab-case, named exports, import ordering, `import type`, named constants)

**(You MUST set resource requests AND limits on every container -- pods without requests are unschedulable under resource pressure and pods without limits can OOM-kill neighbors)**

**(You MUST set securityContext with runAsNonRoot: true, allowPrivilegeEscalation: false, drop ALL capabilities, and readOnlyRootFilesystem: true on every container)**

**(You MUST define both liveness and readiness probes -- without readiness probes, traffic reaches unready pods; without liveness probes, hung processes are never restarted)**

**(You MUST use the current stable apiVersion for each resource -- apps/v1 for Deployments, networking.k8s.io/v1 for Ingress, autoscaling/v2 for HPA, policy/v1 for PDB)**

</critical_requirements>

---

Examples

• [Core Manifests](examples/core.md) - Deployments, Services, Ingress, ConfigMaps, Secrets, Namespaces
• [Helm Charts](examples/helm.md) - Chart structure, values.yaml, templates, helpers, dependencies
• [Operations](examples/operations.md) - HPA scaling, RBAC, health checks, resource limits, PDB, NetworkPolicy
• [Quick Reference](reference.md) - API versions, kubectl commands, label conventions, decision frameworks

---

**Auto-detection:** Kubernetes, kubectl, k8s, Deployment, Service, Ingress, ConfigMap, Secret, HPA, HorizontalPodAutoscaler, Helm, helm chart, Kustomize, kustomization, RBAC, Role, ClusterRole, PodDisruptionBudget, NetworkPolicy, Pod, StatefulSet, DaemonSet, CronJob, Job, PersistentVolumeClaim, apiVersion, kind, metadata, spec

**When to use:**

• Writing Kubernetes Deployment, Service, Ingress, or other resource manifests
• Creating Helm charts for templated multi-environment releases
• Building Kustomize overlays for environment-specific patches
• Configuring RBAC roles and bindings for least-privilege access
• Setting up HPA autoscaling, PDB, or resource limits
• Defining health checks (liveness, readiness, startup probes)
• Managing ConfigMaps, Secrets, and environment configuration
• Writing NetworkPolicy for pod-to-pod traffic control

**When NOT to use:**

• Container image building (use a containerization skill)
• CI/CD pipeline definitions (use a CI/CD skill)
• Infrastructure provisioning (use an IaC tool)
• Service mesh configuration beyond basic Kubernetes resources
• Managed Kubernetes cluster setup (cloud provider control plane configuration)

**Key patterns covered:**

• Deployment with security context, resource limits, and probes
• Service types (ClusterIP, NodePort, LoadBalancer, Headless)
• Ingress with TLS and path routing (networking.k8s.io/v1)
• ConfigMap and Secret management (envFrom, volume mounts)
• HPA autoscaling (autoscaling/v2 metrics array)
• RBAC (Role, ClusterRole, RoleBinding, ServiceAccount)
• Pod Security Standards (restricted profile)
• Helm chart structure, values, templates, and helpers
• Kustomize base/overlay pattern with strategic merge patches
• PodDisruptionBudget for safe rollouts
• NetworkPolicy for pod traffic isolation

---

<philosophy>

Philosophy

Kubernetes is a declarative container orchestration platform. You describe the **desired state** in YAML manifests and Kubernetes continuously reconciles actual state to match. Every resource should be version-controlled, reproducible, and deployable via `kubectl apply` or a GitOps pipeline.

**Core principles:**

1. **Declarative over imperative** -- Use `kubectl apply -f` with manifests, not `kubectl run` or `kubectl create` 2. **Security by default** -- Every pod runs as non-root, drops all capabilities, uses read-only root filesystem 3. **Resource-aware** -- Every container declares requests (scheduling guarantee) and limits (ceiling) 4. **Observable** -- Every pod has health probes so the platform can detect and recover from failures 5. **Least privilege** -- RBAC grants only the permissions each workload needs, scoped to namespace when possible

**Helm vs Kustomize:**

• **Helm** -- Templating engine with package management. Use when you need parameterized releases, dependency management, or you distribute charts to others
• **Kustomize** -- Patch-based overlays built into kubectl. Use when you want to keep base manifests as valid YAML and apply environment-specific patches without templating

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Production Deployment

A production-ready Deployment includes security context, resource limits, health probes, and standard labels.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  labels:
    app.kubernetes.io/name: api-server
    app.kubernetes.io/component: backend
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/component: backend
    spec:
      serviceAccountName: api-server
      automountServiceAccountToken: false
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        fsGroup: 2000
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: api-server
          image: registry.example.com/api-server: