# Kubernetes -- Core Manifest Examples

> Deployments, Services, Ingress, ConfigMaps, Secrets, Namespaces, and Kustomize overlays. Reference from [SKILL.md](../SKILL.md).

**Related examples:**

- [helm.md](helm.md) - Helm chart structure, values, templates, helpers
- [operations.md](operations.md) - HPA, RBAC, health checks, resource limits, PDB, NetworkPolicy

---

## Example 1: Complete Application Stack

A production Deployment with matching Service, Ingress, ConfigMap, and Namespace.

### Namespace with Pod Security

```yaml
apiVersion: v1
kind: Namespace
metadata:
  name: app
  labels:
    pod-security.kubernetes.io/enforce: restricted
    pod-security.kubernetes.io/audit: restricted
    pod-security.kubernetes.io/warn: restricted
```

### Deployment

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
  namespace: app
  labels:
    app.kubernetes.io/name: api-server
    app.kubernetes.io/component: backend
    app.kubernetes.io/part-of: my-platform
spec:
  replicas: 3
  revisionHistoryLimit: 5
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
      maxSurge: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: api-server
  template:
    metadata:
      labels:
        app.kubernetes.io/name: api-server
        app.kubernetes.io/component: backend
      annotations:
        # Force rollout when ConfigMap changes
        checksum/config: '{{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}'
    spec:
      serviceAccountName: api-server
      automountServiceAccountToken: false
      terminationGracePeriodSeconds: 30
      securityContext:
        runAsNonRoot: true
        runAsUser: 1000
        runAsGroup: 1000
        fsGroup: 2000
        seccompProfile:
          type: RuntimeDefault
      containers:
        - name: api-server
          image: registry.example.com/api-server:v1.2.3
          imagePullPolicy: IfNotPresent
          ports:
            - name: http
              containerPort: 3000
              protocol: TCP
          envFrom:
            - configMapRef:
                name: api-config
          env:
            - name: DATABASE_URL
              valueFrom:
                secretKeyRef:
                  name: api-secrets
                  key: DATABASE_URL
          securityContext:
            allowPrivilegeEscalation: false
            readOnlyRootFilesystem: true
            runAsNonRoot: true
            capabilities:
              drop: ["ALL"]
          resources:
            requests:
              cpu: 250m
              memory: 256Mi
            limits:
              cpu: "1"
              memory: 512Mi
          livenessProbe:
            httpGet:
              path: /healthz
              port: http
            initialDelaySeconds: 15
            periodSeconds: 20
            timeoutSeconds: 5
            failureThreshold: 3
          readinessProbe:
            httpGet:
              path: /ready
              port: http
            initialDelaySeconds: 5
            periodSeconds: 10
            timeoutSeconds: 3
            failureThreshold: 3
          startupProbe:
            httpGet:
              path: /healthz
              port: http
            failureThreshold: 30
            periodSeconds: 10
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir: {}
```

**Why good:** Restricted pod security context, dedicated service account with token disabled, three probe types, `emptyDir` for `/tmp` (needed because `readOnlyRootFilesystem: true`), named port for probe references, ConfigMap checksum annotation triggers rollout on config changes, rolling update strategy with explicit bounds

### Service

```yaml
apiVersion: v1
kind: Service
metadata:
  name: api-server
  namespace: app
  labels:
    app.kubernetes.io/name: api-server
spec:
  type: ClusterIP
  selector:
    app.kubernetes.io/name: api-server
  ports:
    - name: http
      port: 80
      targetPort: http
      protocol: TCP
```

### ConfigMap and Secret

```yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: api-config
  namespace: app
data:
  LOG_LEVEL: "info"
  NODE_ENV: "production"
  MAX_CONNECTIONS: "100"
---
apiVersion: v1
kind: Secret
metadata:
  name: api-secrets
  namespace: app
type: Opaque
stringData:
  DATABASE_URL: "postgresql://user:pass@db-svc:5432/app"
  API_KEY: "sk-live-abc123"
```

### Ingress with TLS

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api-ingress
  namespace: app
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "true"
    nginx.ingress.kubernetes.io/proxy-body-size: "10m"
spec:
  ingressClassName: nginx
  tls:
    - hosts:
        - api.example.com
      secretName: api-tls
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /api
            pathType: Prefix
            backend:
              service:
                name: api-server
                port:
                  number: 80
          - path: /health
            pathType: Exact
            backend:
              service:
                name: api-server
                port:
                  number: 80
```

**Why good:** `ingressClassName` field (not deprecated `kubernetes.io/ingress.class` annotation), TLS with secret reference, mixed `pathType` (Prefix for API routes, Exact for health)

---

## Example 2: Service Types

### NodePort (Development / Testing)

```yaml
apiVersion: v1
kind: Service
metadata:
  name: api-nodeport
  namespace: dev
spec:
  type: NodePort
  selector:
    app.kubernetes.io/name: api-server
  ports:
    - port: 80
      targetPort: 3000
      nodePort: 30080
```

### LoadBalancer (External Traffic)

```yaml
apiVersion: v1
kind: Service
metadata:
  name: api-lb
  namespace: app
  annotations:
    # Cloud-provider-specific annotations go here
    service.beta.kubernetes.io/aws-load-balancer-scheme: internet-facing
spec:
  type: LoadBalancer
  selector:
    app.kubernetes.io/name: api-server
  ports:
    - port: 443
      targetPort: 3000
      protocol: TCP
```

### Headless Service (StatefulSet Discovery)

```yaml
apiVersion: v1
kind: Service
metadata:
  name: db-headless
  namespace: app
spec:
  type: ClusterIP
  clusterIP: None
  selector:
    app.kubernetes.io/name: database
  ports:
    - port: 5432
      targetPort: 5432
```

**Why headless:** Each pod gets a DNS record like `db-0.db-headless.app.svc.cluster.local`, enabling direct pod addressing for StatefulSets.

---

## Example 3: ConfigMap Injection Patterns

### envFrom (All Keys)

```yaml
containers:
  - name: app
    envFrom:
      - configMapRef:
          name: api-config
      - secretRef:
          name: api-secrets
```

### Selective env (Specific Keys)

```yaml
containers:
  - name: app
    env:
      - name: DB_HOST
        valueFrom:
          configMapKeyRef:
            name: api-config
            key: DB_HOST
      - name: DB_PASSWORD
        valueFrom:
          secretKeyRef:
            name: api-secrets
            key: DB_PASSWORD
```

### Volume Mount (Config Files)

```yaml
containers:
  - name: app
    volumeMounts:
      - name: config-volume
        mountPath: /etc/app/config
        readOnly: true
volumes:
  - name: config-volume
    configMap:
      name: app-file-config
      items:
        - key: app.conf
          path: app.conf
        - key: logging.conf
          path: logging.conf
```

---

## Example 4: Kustomize Base/Overlay

### Base

```yaml
# k8s/base/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - deployment.yaml
  - service.yaml
  - configmap.yaml
commonLabels:
  app.kubernetes.io/name: api-server
```

### Staging Overlay

```yaml
# k8s/overlays/staging/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
namespace: staging
patches:
  - path: replica-patch.yaml
configMapGenerator:
  - name: api-config
    behavior: merge
    literals:
      - LOG_LEVEL=debug
      - NODE_ENV=staging
```

```yaml
# k8s/overlays/staging/replica-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 1
```

### Production Overlay

```yaml
# k8s/overlays/production/kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
  - ../../base
  - hpa.yaml
  - pdb.yaml
namespace: production
patches:
  - path: resource-patch.yaml
configMapGenerator:
  - name: api-config
    behavior: merge
    literals:
      - LOG_LEVEL=warn
      - NODE_ENV=production
secretGenerator:
  - name: api-secrets
    envs:
      - secrets.env
```

```yaml
# k8s/overlays/production/resource-patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: api-server
          resources:
            requests:
              cpu: 500m
              memory: 512Mi
            limits:
              cpu: "2"
              memory: 1Gi
```

**Why good:** Base manifests are valid YAML (no template syntax), overlays contain only diffs, `configMapGenerator` appends content hash to name (auto-triggers rollouts), `secretGenerator` keeps secrets out of base manifests

**Apply:** `kubectl apply -k k8s/overlays/production/`

---

## Anti-Patterns

### Bad: Missing Security Context

```yaml
# BAD: No security context -- runs as root by default
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  template:
    spec:
      containers:
        - name: api-server
          image: api-server:latest
          ports:
            - containerPort: 3000
```

**Why bad:** Runs as root (default), no resource limits (can consume all node resources), `:latest` tag (non-deterministic), no probes (unmonitored health), no service account (uses default with API access)

### Bad: Overly Permissive RBAC

```yaml
# BAD: Wildcard permissions
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: app-role
rules:
  - apiGroups: ["*"]
    resources: ["*"]
    verbs: ["*"]
```

**Why bad:** Grants cluster-admin equivalent access, violates least privilege, any compromised pod has full cluster control

### Bad: Deprecated API Version

```yaml
# BAD: extensions/v1beta1 removed in Kubernetes 1.22
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: api-ingress
  annotations:
    kubernetes.io/ingress.class: nginx
```

**Why bad:** `extensions/v1beta1` removed since v1.22, `kubernetes.io/ingress.class` annotation deprecated in favor of `ingressClassName` field, missing `pathType` (required in v1)

# Kubernetes -- Helm Chart Examples

> Helm chart structure, values.yaml, templates, helpers, dependencies, and multi-environment releases. Reference from [SKILL.md](../SKILL.md).

**Related examples:**

- [core.md](core.md) - Deployments, Services, Ingress, ConfigMaps, Secrets
- [operations.md](operations.md) - HPA, RBAC, health checks, resource limits, PDB

---

## Example 1: Complete Helm Chart

### Chart.yaml

```yaml
apiVersion: v2
name: my-app
description: A Helm chart for my application
type: application
version: 0.1.0
appVersion: "1.0.0"
maintainers:
  - name: team-platform
dependencies:
  - name: postgresql
    version: "~15.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
```

**Why good:** `apiVersion: v2` (Helm 3), dependencies inline (not separate `requirements.yaml`), `condition` enables toggling sub-charts, SemVer for both chart version and appVersion

### values.yaml

```yaml
# -- Number of replicas (ignored when HPA enabled)
replicaCount: 3

image:
  repository: registry.example.com/my-app
  tag: "" # Defaults to chart appVersion
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: nginx
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix
  tls: []

resources:
  requests:
    cpu: 250m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi

autoscaling:
  enabled: false
  minReplicas: 2
  maxReplicas: 10
  targetCPUUtilization: 70

securityContext:
  runAsNonRoot: true
  runAsUser: 1000
  allowPrivilegeEscalation: false
  readOnlyRootFilesystem: true
  capabilities:
    drop: ["ALL"]

podSecurityContext:
  fsGroup: 2000
  seccompProfile:
    type: RuntimeDefault

probes:
  liveness:
    path: /healthz
    initialDelaySeconds: 15
    periodSeconds: 20
  readiness:
    path: /ready
    initialDelaySeconds: 5
    periodSeconds: 10

serviceAccount:
  create: true
  automountServiceAccountToken: false
  annotations: {}

postgresql:
  enabled: true
```

**Why good:** Grouped by concern, comments explain non-obvious defaults, security values mirror restricted Pod Security Standards, HPA and Ingress conditionally enabled, image tag defaults to appVersion

### templates/\_helpers.tpl

```yaml
{{/*
Expand the name of the chart.
*/}}
{{- define "my-app.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Create a fully qualified app name.
*/}}
{{- define "my-app.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{/*
Common labels
*/}}
{{- define "my-app.labels" -}}
helm.sh/chart: {{ include "my-app.chart" . }}
{{ include "my-app.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Selector labels -- immutable after first deployment
*/}}
{{- define "my-app.selectorLabels" -}}
app.kubernetes.io/name: {{ include "my-app.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/*
Chart label
*/}}
{{- define "my-app.chart" -}}
{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
{{- end }}

{{/*
Service account name
*/}}
{{- define "my-app.serviceAccountName" -}}
{{- if .Values.serviceAccount.create }}
{{- default (include "my-app.fullname" .) .Values.serviceAccount.name }}
{{- else }}
{{- default "default" .Values.serviceAccount.name }}
{{- end }}
{{- end }}
```

**Why good:** Selector labels separated from common labels (selectors are immutable), names truncated to 63 chars (Kubernetes limit), `fullname` avoids redundant chart name in release name

### templates/deployment.yaml

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  {{- if not .Values.autoscaling.enabled }}
  replicas: {{ .Values.replicaCount }}
  {{- end }}
  revisionHistoryLimit: 5
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      serviceAccountName: {{ include "my-app.serviceAccountName" . }}
      automountServiceAccountToken: {{ .Values.serviceAccount.automountServiceAccountToken }}
      securityContext:
        {{- toYaml .Values.podSecurityContext | nindent 8 }}
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - name: http
              containerPort: 3000
              protocol: TCP
          securityContext:
            {{- toYaml .Values.securityContext | nindent 12 }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
          livenessProbe:
            httpGet:
              path: {{ .Values.probes.liveness.path }}
              port: http
            initialDelaySeconds: {{ .Values.probes.liveness.initialDelaySeconds }}
            periodSeconds: {{ .Values.probes.liveness.periodSeconds }}
          readinessProbe:
            httpGet:
              path: {{ .Values.probes.readiness.path }}
              port: http
            initialDelaySeconds: {{ .Values.probes.readiness.initialDelaySeconds }}
            periodSeconds: {{ .Values.probes.readiness.periodSeconds }}
          volumeMounts:
            - name: tmp
              mountPath: /tmp
      volumes:
        - name: tmp
          emptyDir: {}
```

**Why good:** Replicas conditionally omitted when HPA enabled, image tag falls back to `appVersion`, security contexts injected from values via `toYaml`, `emptyDir` for tmp (readOnlyRootFilesystem), `nindent` handles YAML indentation correctly

### templates/service.yaml

```yaml
apiVersion: v1
kind: Service
metadata:
  name: { { include "my-app.fullname" . } }
  labels: { { - include "my-app.labels" . | nindent 4 } }
spec:
  type: { { .Values.service.type } }
  selector: { { - include "my-app.selectorLabels" . | nindent 4 } }
  ports:
    - name: http
      port: { { .Values.service.port } }
      targetPort: http
      protocol: TCP
```

### templates/ingress.yaml (Conditional)

```yaml
{{- if .Values.ingress.enabled -}}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
  {{- with .Values.ingress.annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  ingressClassName: {{ .Values.ingress.className }}
  {{- if .Values.ingress.tls }}
  tls:
    {{- range .Values.ingress.tls }}
    - hosts:
        {{- range .hosts }}
        - {{ . | quote }}
        {{- end }}
      secretName: {{ .secretName }}
    {{- end }}
  {{- end }}
  rules:
    {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
          {{- range .paths }}
          - path: {{ .path }}
            pathType: {{ .pathType }}
            backend:
              service:
                name: {{ include "my-app.fullname" $ }}
                port:
                  number: {{ $.Values.service.port }}
          {{- end }}
    {{- end }}
{{- end }}
```

**Why good:** Entire resource conditional on `ingress.enabled`, `ingressClassName` field (not deprecated annotation), `$` used for root context inside range loops, hosts quoted for safety

### templates/hpa.yaml (Conditional)

```yaml
{{- if .Values.autoscaling.enabled }}
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: {{ include "my-app.fullname" . }}
  minReplicas: {{ .Values.autoscaling.minReplicas }}
  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: {{ .Values.autoscaling.targetCPUUtilization }}
{{- end }}
```

---

## Example 2: Multi-Environment Values

### values-staging.yaml

```yaml
replicaCount: 1

image:
  tag: "staging-latest"

ingress:
  enabled: true
  hosts:
    - host: staging.example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 256Mi

postgresql:
  enabled: true
```

### values-production.yaml

```yaml
replicaCount: 3

ingress:
  enabled: true
  hosts:
    - host: app.example.com
      paths:
        - path: /
          pathType: Prefix
  tls:
    - hosts:
        - app.example.com
      secretName: app-tls

autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 20
  targetCPUUtilization: 60

resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "2"
    memory: 1Gi
```

**Deploy:** `helm upgrade --install my-app ./my-app -f values-production.yaml -n production`

---

## Anti-Patterns

### Bad: Complex Logic in Templates

```yaml
# BAD: Business logic in template
{{- if and .Values.autoscaling.enabled (gt (int .Values.autoscaling.maxReplicas) 5) (not .Values.maintenance.enabled) }}
{{- if or (eq .Values.environment "production") (eq .Values.environment "staging") }}
replicas: {{ mul .Values.replicaCount 2 | add 1 }}
{{- end }}
{{- end }}
```

**Why bad:** Complex conditionals belong in `_helpers.tpl` as named templates or in application logic, not inlined in resource templates

### Bad: Hardcoded Values in Templates

```yaml
# BAD: Values that change between environments hardcoded
containers:
  - name: app
    image: "myregistry.io/app:v1.0.0"
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
```

**Why bad:** Image and resource values hardcoded in template instead of parameterized through `values.yaml` -- every environment gets the same config

### Bad: Missing Conditional for HPA + Replicas

```yaml
# BAD: replicas always set even when HPA manages scaling
spec:
  replicas: { { .Values.replicaCount } }
```

**Why bad:** When HPA is active, Helm resets replicas to the manifest value on every upgrade, overriding HPA's scaling decisions. Wrap in `{{- if not .Values.autoscaling.enabled }}`

# Kubernetes -- Operations Examples

> HPA autoscaling, RBAC, health checks, resource limits, PodDisruptionBudget, NetworkPolicy, and Pod Security. Reference from [SKILL.md](../SKILL.md).

**Related examples:**

- [core.md](core.md) - Deployments, Services, Ingress, ConfigMaps, Secrets
- [helm.md](helm.md) - Helm chart structure, values, templates, helpers

---

## Example 1: HPA with Multiple Metrics and Scaling Behavior

```yaml
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: api-server
  namespace: app
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: api-server
  minReplicas: 2
  maxReplicas: 20
  metrics:
    - type: Resource
      resource:
        name: cpu
        target:
          type: Utilization
          averageUtilization: 70
    - type: Resource
      resource:
        name: memory
        target:
          type: Utilization
          averageUtilization: 80
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 60
      policies:
        - type: Pods
          value: 4
          periodSeconds: 60
        - type: Percent
          value: 100
          periodSeconds: 60
      selectPolicy: Max
    scaleDown:
      stabilizationWindowSeconds: 300
      policies:
        - type: Pods
          value: 1
          periodSeconds: 120
      selectPolicy: Min
```

**Why good:** Uses stable `autoscaling/v2` with `metrics` array, both CPU and memory targets, scale-up allows aggressive burst (max of 4 pods or 100% increase per minute), scale-down is conservative (1 pod every 2 minutes, 5-minute stabilization) to prevent flapping

**Gotcha:** Remove `spec.replicas` from the Deployment when HPA is active -- otherwise `helm upgrade` or `kubectl apply` resets the replica count on every deployment.

---

## Example 2: RBAC Patterns

### Namespaced Role (Preferred)

```yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  name: api-server
  namespace: app
automountServiceAccountToken: false
---
apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  name: api-server-role
  namespace: app
rules:
  - apiGroups: [""]
    resources: ["configmaps"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["secrets"]
    verbs: ["get"]
    resourceNames: ["api-secrets"] # Restrict to specific secret
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  name: api-server-binding
  namespace: app
subjects:
  - kind: ServiceAccount
    name: api-server
    namespace: app
roleRef:
  kind: Role
  name: api-server-role
  apiGroup: rbac.authorization.k8s.io
```

**Why good:** Namespaced Role (not ClusterRole), specific resources and verbs (not wildcards), `resourceNames` further restricts secret access to named resources, `automountServiceAccountToken: false` prevents unnecessary API access

### ClusterRole (When Required)

Use ClusterRole only when a workload genuinely needs cluster-wide access (e.g., operators, controllers, monitoring agents).

```yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: namespace-reader
rules:
  - apiGroups: [""]
    resources: ["namespaces"]
    verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: monitoring-namespace-reader
subjects:
  - kind: ServiceAccount
    name: monitoring
    namespace: monitoring
roleRef:
  kind: ClusterRole
  name: namespace-reader
  apiGroup: rbac.authorization.k8s.io
```

**When to use ClusterRole:**

- Reading namespaces or nodes (cluster-scoped resources)
- Custom operators that watch resources across namespaces
- Monitoring/logging agents that collect from all namespaces

---

## Example 3: Health Check Patterns

### HTTP Probes (Most Common)

```yaml
containers:
  - name: api-server
    livenessProbe:
      httpGet:
        path: /healthz
        port: 3000
      initialDelaySeconds: 15
      periodSeconds: 20
      timeoutSeconds: 5
      failureThreshold: 3
    readinessProbe:
      httpGet:
        path: /ready
        port: 3000
      initialDelaySeconds: 5
      periodSeconds: 10
      timeoutSeconds: 3
      failureThreshold: 3
    startupProbe:
      httpGet:
        path: /healthz
        port: 3000
      failureThreshold: 30
      periodSeconds: 10
```

**Probe design:**

- `/healthz` (liveness) -- Is the process alive? Check basic responsiveness only. Do NOT check external dependencies (database, Redis). A false-negative restarts a healthy pod.
- `/ready` (readiness) -- Can this pod serve traffic? Check that connections to required dependencies are established.
- Startup probe -- Gives slow-starting apps time to initialize. Blocks liveness/readiness until successful. `failureThreshold * periodSeconds` = max startup time (300s here).

### TCP Probe (Non-HTTP Services)

```yaml
containers:
  - name: database
    livenessProbe:
      tcpSocket:
        port: 5432
      periodSeconds: 20
    readinessProbe:
      tcpSocket:
        port: 5432
      periodSeconds: 10
```

### Exec Probe (Custom Check)

```yaml
containers:
  - name: worker
    livenessProbe:
      exec:
        command:
          - /bin/sh
          - -c
          - "test -f /tmp/healthy"
      periodSeconds: 30
```

### gRPC Probe (gRPC Services)

```yaml
containers:
  - name: grpc-service
    livenessProbe:
      grpc:
        port: 50051
      periodSeconds: 20
    readinessProbe:
      grpc:
        port: 50051
      periodSeconds: 10
```

---

## Example 4: Resource Limits and QoS

### Guaranteed QoS (Critical Services)

```yaml
# requests == limits = Guaranteed QoS class
# Highest priority, never evicted under memory pressure
containers:
  - name: payment-service
    resources:
      requests:
        cpu: 500m
        memory: 512Mi
      limits:
        cpu: 500m
        memory: 512Mi
```

### Burstable QoS (Typical Workloads)

```yaml
# requests < limits = Burstable QoS class
# Can burst above requests when resources available
containers:
  - name: api-server
    resources:
      requests:
        cpu: 250m
        memory: 256Mi
      limits:
        cpu: "1"
        memory: 512Mi
```

**Sizing guidance:**

- Set memory requests at 90th percentile of observed usage
- Set memory limits at 150-200% of requests to allow spikes without OOMKill
- Set CPU requests based on sustained usage, limits based on peak
- CPU throttling (hitting limit) causes latency spikes but NOT kills
- Memory exceeding limits causes OOMKill -- the container is terminated and restarted

---

## Example 5: PodDisruptionBudget

Ensures minimum availability during voluntary disruptions (node drain, cluster upgrade, rolling update).

```yaml
apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: api-server
  namespace: app
spec:
  minAvailable: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: api-server
```

**Alternative: maxUnavailable**

```yaml
spec:
  maxUnavailable: 1
  selector:
    matchLabels:
      app.kubernetes.io/name: api-server
```

**When to use which:**

- `minAvailable: N` -- Use when you know the minimum pod count for service health
- `maxUnavailable: N` -- Use when you want to limit disruption rate (better for larger deployments)
- Cannot set both `minAvailable` and `maxUnavailable`
- PDB only protects against **voluntary** disruptions (drain, upgrade) -- not OOMKill or node failure

---

## Example 6: NetworkPolicy

Restrict pod-to-pod traffic. By default, all pods can communicate with all other pods.

### Allow Only Specific Ingress

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: api-server-policy
  namespace: app
spec:
  podSelector:
    matchLabels:
      app.kubernetes.io/name: api-server
  policyTypes:
    - Ingress
    - Egress
  ingress:
    # Allow traffic from ingress controller
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: ingress-nginx
      ports:
        - port: 3000
          protocol: TCP
    # Allow traffic from frontend pods
    - from:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: frontend
      ports:
        - port: 3000
          protocol: TCP
  egress:
    # Allow DNS
    - to:
        - namespaceSelector: {}
      ports:
        - port: 53
          protocol: UDP
        - port: 53
          protocol: TCP
    # Allow database
    - to:
        - podSelector:
            matchLabels:
              app.kubernetes.io/name: database
      ports:
        - port: 5432
          protocol: TCP
```

**Why good:** Explicit ingress sources (ingress controller and frontend only), explicit egress (DNS and database only), all other traffic implicitly denied once a NetworkPolicy selects a pod

**Gotcha:** NetworkPolicy requires a CNI plugin that supports it (Calico, Cilium, Weave). The default kubenet CNI ignores NetworkPolicy.

### Default Deny All (Namespace-Level)

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-all
  namespace: app
spec:
  podSelector: {}
  policyTypes:
    - Ingress
    - Egress
```

**Why useful:** Apply as baseline, then add allow policies for specific communication paths. Empty `podSelector` selects all pods in the namespace.

---

## Example 7: Pod Security Context (Restricted Profile)

The complete restricted security context that satisfies the Pod Security Standards restricted level.

### Pod Level

```yaml
spec:
  securityContext:
    runAsNonRoot: true
    runAsUser: 1000
    runAsGroup: 1000
    fsGroup: 2000
    seccompProfile:
      type: RuntimeDefault
```

### Container Level

```yaml
containers:
  - name: app
    securityContext:
      allowPrivilegeEscalation: false
      readOnlyRootFilesystem: true
      runAsNonRoot: true
      capabilities:
        drop: ["ALL"]
```

### Handling readOnlyRootFilesystem

Apps that write to `/tmp`, `/var/cache`, or similar directories need `emptyDir` volume mounts:

```yaml
containers:
  - name: app
    securityContext:
      readOnlyRootFilesystem: true
    volumeMounts:
      - name: tmp
        mountPath: /tmp
      - name: cache
        mountPath: /var/cache
volumes:
  - name: tmp
    emptyDir: {}
  - name: cache
    emptyDir:
      sizeLimit: 100Mi
```

---

## Anti-Patterns

### Bad: Liveness Probe Checks External Dependencies

```yaml
# BAD: Liveness probe checks database connectivity
livenessProbe:
  httpGet:
    path: /health # Returns 500 if database is down
    port: 3000
```

**Why bad:** If the database goes down, ALL pods fail their liveness probe and get restarted simultaneously. The pods are healthy -- they just can't reach the database. This turns a dependency outage into a cascading failure. Check external dependencies in readiness probe only.

### Bad: No PDB with Multiple Replicas

```yaml
# BAD: 3 replicas but no PDB -- node drain can take all 3 down
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-server
spec:
  replicas: 3
  # No PodDisruptionBudget defined
```

**Why bad:** During a cluster upgrade or node drain, all 3 pods could be evicted simultaneously if they happen to be on the same node or on nodes being drained in sequence. Always pair multi-replica Deployments with a PDB.