Imported from szebest/taitube-platform (
infra/k8s/AGENTS.md). Install upstream withnpx skills add szebest/taitube-platform --skill k8s. Copyright stays with the author.
AGENTS.md — infra/k8s (Kubernetes & KEDA Orchestration)
Instructions for any coding agent working on Kubernetes manifests and autoscaling (infra/k8s).
1. Scope & Topology
infra/k8s contains the declarative Kubernetes resources organized using Kustomize:
infra/k8s/base/: Common manifests for API Deployments, Service definitions, Ingress, Worker Deployments (probe,transcode-1080p,transcode-720p,transcode-480p,thumbnail,package,notify), and KEDAScaledObjectresources.infra/k8s/overlays/local/: Local k3d/kind overlay with in-cluster dependencies and nodePort/hostPort mappings.infra/k8s/overlays/cloud/: Production cloud overlay targeting external managed services (Neon PostgreSQL, Cloudflare R2, SOPS-encrypted secrets).infra/k8s/helm-values/: Configuration values for cluster addons (KEDA, Traefik).
2. Invariants & Rules
- KEDA Queue Autoscaling: Worker Deployments autoscale based on BullMQ queue depth (
waiting + active) using KEDAScaledObjecttriggers.- Scale-to-zero: Workers scale to 0 when queues are empty.
- Scale-in Protection: Grace periods (
terminationGracePeriodSeconds: 300) must allow in-flight video transcodes to finish.
- Resource Boundaries: Every container MUST specify explicit
resources.requestsandresources.limitsfor CPU and memory. - Kustomize Discipline: Never duplicate manifest definitions; place base specs in
base/and apply transformations in overlays (kustomization.yaml). - Validation: All manifests must validate against Kubernetes schemas via
scripts/validate-k8s.sh.
3. Dedicated Skills
vp-keda-queue-autoscaling: KEDA trigger definitions and autoscaling mechanics.
4. Local Commands
# Create local k3d cluster with Helm addons
make k3d-up
# Deploy application and workers via Kustomize
make k3d-deploy
# Validate manifests against kubeconform
scripts/validate-k8s.sh
# Tear down local k3d cluster
make k3d-down