The Complete Production SOP: How to Deploy and Run Kubernetes Topology Spread Constraints & Affinity in Autonomous AI Agents

Autonomous AI agents search workspace dot-folders or global configuration paths (~/.agents/skills, .claude/skills, or .cursor/rules) to discover deterministic capability definitions. By saving this SKILL.md into your workspace, runtimes inspect the YAML frontmatter triggers such as 'configure topologyspreadconstraints' and 'spread pods across availability zones' to load the SOP into active agent memory upon matching user queries.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: payments-service
  labels:
    app.kubernetes.io/name: payments
spec:
  replicas: 6
  selector:
    matchLabels:
      app.kubernetes.io/name: payments
  template:
    metadata:
      labels:
        app.kubernetes.io/name: payments
    spec:
      topologySpreadConstraints:
        - maxSkew: 1
          topologyKey: topology.kubernetes.io/zone
          whenUnsatisfiable: DoNotSchedule
          labelSelector:
            matchLabels:
              app.kubernetes.io/name: payments
      containers:
        - name: app
          image: internal.ecr.aws/fintech/payments:v2.4.1
          resources:
            limits:
              cpu: "500m"
              memory: "512Mi"
            requests:
              cpu: "250m"
              memory: "256Mi"

Topology spread constraints rely heavily on standardized node labels (topology.kubernetes.io/zone and kubernetes.io/hostname). While the agent operates with shell_exec: false and net_access: false for safety, it must validate local cluster schemas and linting configurations. Verify that linters like kube-linter or yamllint are configured in the repository root so the agent can request automated validations.

customChecks:
  - name: require-topology-spread
    template: required-annotation-or-spec
    params:
      path: spec.template.spec.topologySpreadConstraints
checks:
  include:
    - require-topology-spread

When invoking Codex, Claude Code, or Cursor, begin the instruction with one of the skill's declared triggers ('configure topologyspreadconstraints', 'spread pods across availability zones', or 'set k8s maxskew'). This activates the procedural SOP, preventing the LLM from outputting legacy podAntiAffinity configurations that incur high CPU penalties on kube-scheduler.

Before committing changes generated by the AI agent, execute offline dry-run and linting validations. The agent's generated manifest must satisfy maxSkew logic, ensure the labelSelector strictly mirrors template metadata, and confirm the topologyKey exists across targeted node pools.

#!/usr/bin/env bash
set -euo pipefail

echo "Validating generated deployment manifests against kube-scheduler schema..."
kubectl apply --dry-run=client -f k8s/base/deployment.yaml

# Assert topologySpreadConstraints block is present
if ! grep -q "topologyKey: topology.kubernetes.io/zone" k8s/base/deployment.yaml; then
  echo "FAILED: topology.kubernetes.io/zone missing from deployment.yaml" >&2
  exit 1
fi
echo "Topology spread validation passed successfully."