Agent Skills Framework Extension

Kubernetes StatefulSet Patterns Skill

When to Use This Skill

Use this skill when implementing k8s statefulset patterns patterns in your codebase.

How to Use This Skill

1. Review the patterns and examples below
2. Apply the relevant patterns to your implementation
3. Follow the best practices outlined in this skill

Production StatefulSet patterns for persistent workloads, ordered deployment, and state management.

Core Capabilities

1. StatefulSet Design - Stable network identity, ordered operations
2. Persistent Storage - PVCs, StorageClasses, volume management
3. Database Clustering - PostgreSQL, MongoDB, Redis clusters
4. Backup/Recovery - State backup, disaster recovery
5. Scaling Patterns - Ordered scaling, data rebalancing

StatefulSet with PostgreSQL

# k8s/postgres-statefulset.yaml
apiVersion: v1
kind: Service
metadata:
  name: postgres-headless
  labels:
    app: postgres
spec:
  type: ClusterIP
  clusterIP: None  # Headless service for stable network identity
  ports:
    - port: 5432
      targetPort: 5432
      name: postgres
  selector:
    app: postgres
---
apiVersion: apps/v1
kind: StatefulSet
metadata:
  name: postgres
spec:
  serviceName: postgres-headless
  replicas: 3
  selector:
    matchLabels:
      app: postgres

  podManagementPolicy: OrderedReady
  updateStrategy:
    type: RollingUpdate

  template:
    metadata:
      labels:
        app: postgres
    spec:
      affinity:
        podAntiAffinity:
          preferredDuringSchedulingIgnoredDuringExecution:
            - weight: 100
              podAffinityTerm:
                labelSelector:
                  matchExpressions:
                    - key: app
                      operator: In
                      values: [postgres]
                topologyKey: kubernetes.io/hostname

      containers:
        - name: postgres
          image: postgres:15
          ports:
            - containerPort: 5432

          env:
            - name: PGDATA
              value: /var/lib/postgresql/data/pgdata

          volumeMounts:
            - name: postgres-data
              mountPath: /var/lib/postgresql/data

          resources:
            requests:
              memory: "2Gi"
              cpu: "1000m"

  volumeClaimTemplates:
    - metadata:
        name: postgres-data
      spec:
        accessModes: ["ReadWriteOnce"]
        storageClassName: "fast-ssd"
        resources:
          requests:
            storage: 100Gi

Backup CronJob

apiVersion: batch/v1
kind: CronJob
metadata:
  name: postgres-backup
spec:
  schedule: "0 2 * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
            - name: backup
              image: postgres:15
              command:
                - sh
                - -c
                - |
                  pg_dump -h postgres-0.postgres-headless \
                    -U postgres -F c -f /backup/backup-$(date +%Y%m%d).dump
              volumeMounts:
                - name: backup
                  mountPath: /backup
          volumes:
            - name: backup
              persistentVolumeClaim:
                claimName: postgres-backup
          restartPolicy: OnFailure

Usage Examples

Deploy StatefulSet

Apply k8s-statefulset-patterns skill to deploy PostgreSQL cluster with replication

Backup Strategy

Apply k8s-statefulset-patterns skill to implement automated backup with CronJob

Success Output

When successful, this skill MUST output:

✅ SKILL COMPLETE: k8s-statefulset-patterns

Completed:
- [x] StatefulSet manifest created/updated
- [x] Headless service configured
- [x] PersistentVolumeClaim templates defined
- [x] Pod anti-affinity rules applied
- [x] Backup CronJob configured (if applicable)
- [x] Configuration validated

Outputs:
- k8s/postgres-statefulset.yaml (or equivalent)
- k8s/backup-cronjob.yaml (if applicable)
- Verification: kubectl get statefulset,pvc,pod

Completion Checklist

Before marking this skill as complete, verify:

• StatefulSet manifest includes serviceName and podManagementPolicy
• Headless service created with clusterIP: None
• volumeClaimTemplates configured with appropriate storage class
• Resource requests/limits defined for containers
• Pod anti-affinity rules prevent co-location on same node
• Ordered deployment verified (pods created sequentially)
• PVCs bound successfully to persistent volumes
• Backup strategy implemented (CronJob or equivalent)
• All manifests applied to cluster: kubectl apply -f
• Pods running and healthy: kubectl get pods

Failure Indicators

This skill has FAILED if:

• ❌ StatefulSet pods stuck in Pending state (check PVC binding)
• ❌ Multiple pods scheduled on same node (anti-affinity not working)
• ❌ Pods created out of order (podManagementPolicy misconfigured)
• ❌ Data loss on pod restart (PVC not properly configured)
• ❌ Storage class not found or not provisioned
• ❌ Headless service not resolving individual pod DNS names
• ❌ Backup CronJob fails to connect to database
• ❌ Rolling update deletes all pods simultaneously

When NOT to Use

Do NOT use k8s-statefulset-patterns when:

• Stateless applications - Use Deployments instead (simpler, faster scaling)
• No persistent storage needed - StatefulSets add unnecessary complexity
• Order-independent workloads - Deployments provide better performance
• Temporary/ephemeral data - Use Deployments with emptyDir volumes
• Single instance only - Consider simpler Deployment with 1 replica
• Cloud-managed databases - Use managed services (Cloud SQL, RDS) instead
• Serverless workloads - Consider Knative or serverless platforms
• Development/testing environments - Use simpler local databases

Use Deployments when: Application is stateless or can tolerate pod replacement Use managed databases when: Production workload benefits from managed backup/HA Use local storage when: Development environment or non-critical data

Anti-Patterns (Avoid)

Anti-Pattern	Problem	Solution
No resource limits	Pods consume all node resources	Define requests/limits for memory and CPU
Missing anti-affinity	All replicas on same node (single point of failure)	Use podAntiAffinity with hostname topology
No backup strategy	Data loss on cluster failure	Implement CronJob for regular backups to external storage
Parallel pod management	All pods restart simultaneously during update	Use OrderedReady podManagementPolicy
Generic storage class	Performance issues or cost inefficiency	Use fast-ssd for databases, standard for logs
Missing health checks	Kubernetes routes traffic to unhealthy pods	Define readiness and liveness probes
Hardcoded credentials	Security vulnerability	Use Kubernetes Secrets or external secret managers
No volume snapshot policy	Cannot restore to point-in-time	Enable VolumeSnapshots in storage class

Principles

This skill embodies the following CODITECT principles:

#2 First Principles Thinking:

• Understand WHY StatefulSets exist: ordered deployment, stable network identity, persistent storage
• Apply only when workload truly requires statefulness

#3 Keep It Simple:

• Use Deployments for stateless apps (simpler)
• Only add StatefulSet complexity when necessary

#5 Eliminate Ambiguity:

• Clear pod naming: postgres-0, postgres-1, postgres-2
• Stable DNS: postgres-0.postgres-headless.namespace.svc.cluster.local

#6 Clear, Understandable, Explainable:

• Explicit pod management policy (OrderedReady vs Parallel)
• Clear storage class requirements (fast-ssd vs standard)

#8 No Assumptions:

• Verify storage class exists before deployment
• Check node capacity can support anti-affinity requirements

Full Standard: CODITECT-STANDARD-AUTOMATION.md

Integration Points

• cloud-infrastructure-patterns - Cloud storage integration
• deployment-strategy-patterns - Rolling updates
• database-design-patterns - Schema management