Kubernetes & orchestration for Django in production
Running Django across many machines: Kubernetes, Helm, GitOps, and Swarm, with migrations and rollouts done safely.
Kubernetes runs Django across a cluster with rolling updates, health checks, and autoscaling. It also adds its own objects to learn and a few Django-specific traps, especially around migrations and probes.
The guides start with a working Deployment and build up to Helm charts, GitOps with Argo CD, and a production checklist.
Set it up
Guides that take this from nothing to running in production.
- Deploy Django on Kubernetes
Deploy Django on Kubernetes with a Deployment, Service, Ingress, Secrets, readiness and liveness probes, and a migration Job that runs before each rollout.
- Deploy Django with Docker Swarm
Deploy Django with Docker Swarm: a stack file with replicas, Docker secrets, rolling start-first updates with automatic rollback, one-off migrations, and Nginx in front.
- Deploy Django to Kubernetes with a Helm Chart
Package Django for Kubernetes with a Helm chart: values per environment, Deployment and Ingress templates, a pre-upgrade migration hook, config checksums, and helm rollback.
- Deploy Django with Argo CD (GitOps)
Deploy Django to Kubernetes with Argo CD: a config repository, an Application with automated sync, PreSync migration hooks, CI-driven image tag updates, and rollback by git revert.
- Run Django Migrations as a Kubernetes Job
Run Django migrations exactly once per release on Kubernetes: a Job per image tag, waiting for completion in CI, lock timeouts, why init containers are risky, and handling failures.
- Deploy Django on Google Kubernetes Engine (GKE)
Deploy Django on GKE Autopilot: push images to Artifact Registry, connect to Cloud SQL with the Auth Proxy sidecar and Workload Identity, expose HTTPS with a Gateway or Ingress and managed certificates, and run migrations as a Job.
- Deploy Django on Amazon EKS
Deploy Django on Amazon EKS: build images in ECR, expose the app through an ALB with the AWS Load Balancer Controller and ACM certificates, connect to RDS, grant AWS access with Pod Identity, sync secrets, and run migrations as Jobs.
- Deploy Django on a Single-Node k3s Cluster
Run Django on a single-node k3s Kubernetes cluster: install k3s, use the bundled Traefik ingress with cert-manager for Let's Encrypt, keep PostgreSQL outside the cluster or back it up properly, and deploy with manifests or Helm.
- Expose Django on Kubernetes With Gateway API or Ingress
Route HTTPS traffic to Django on Kubernetes with the Gateway API or a maintained Ingress controller: HTTPRoutes or Ingress rules, TLS with cert-manager, forwarded headers, body size and timeouts, and moving off the retired ingress-nginx.
- Run Django Scheduled Jobs as Kubernetes CronJobs
Schedule Django management commands on Kubernetes with CronJobs: concurrencyPolicy Forbid, time zones, startingDeadlineSeconds, history limits, resource requests, secrets, and monitoring missed or failed runs, compared with Celery Beat.
- Kubernetes vs Docker Compose for Django
Compare Kubernetes and Docker Compose for running Django in production: single-host simplicity versus multi-node scheduling, rolling updates, autoscaling, secrets, operational cost, and when a team should move from Compose to Kubernetes.
- Deploy Django on DigitalOcean Kubernetes (DOKS)
Deploy a Django app on DigitalOcean Kubernetes: build and push to DigitalOcean Container Registry, connect to Managed PostgreSQL and Valkey, expose it with a load balancer and HTTPS, run migrations as a Job, and store media in Spaces.
- Deploy Django on Azure Kubernetes Service (AKS)
Deploy Django on Azure Kubernetes Service: push images to Azure Container Registry, connect to Azure Database for PostgreSQL with workload identity and Key Vault secrets, expose it through Application Gateway or an ingress, and run migrations as Jobs.
- Deploy Django on Red Hat OpenShift
Deploy Django on OpenShift: build with Source-to-Image or a Dockerfile, run as an arbitrary non-root UID, connect to PostgreSQL, expose the app with a Route and TLS edge termination, run migrations as a Job, and fix permission errors under restricted SCCs.
- Automate HTTPS for Django on Kubernetes With cert-manager
Use cert-manager to issue and renew Let’s Encrypt certificates for a Django app on Kubernetes: install it with Helm, create a ClusterIssuer with HTTP-01 or DNS-01, request certificates through Ingress or Gateway annotations, and troubleshoot stuck challenges.
- Sync Django Secrets Into Kubernetes With External Secrets Operator
Use External Secrets Operator to load Django secrets from AWS Secrets Manager, Google Secret Manager, Azure Key Vault, Vault, or Infisical into Kubernetes Secrets: configure a SecretStore with workload identity, map keys, set refresh intervals, and roll pods on change.
- Manage Django Kubernetes Manifests With Kustomize Overlays
Structure Django Kubernetes manifests with Kustomize: a base with Deployment, Service, and migration Job, overlays for staging and production with replicas, resources, and hosts, image tags set from CI, ConfigMap generators with hash suffixes, and use with Argo CD.
- Serve Django Static Files on Kubernetes
Choose how to serve Django static files on Kubernetes: WhiteNoise inside the app image, an Nginx sidecar sharing an emptyDir, a separate static image, or object storage with a CDN, and avoid shared volumes, stale files, and collectstatic at pod start.
- Autoscale Celery Workers on Kubernetes With KEDA
Scale Celery workers on Kubernetes by queue length with KEDA: install KEDA, define a ScaledObject with the Redis or RabbitMQ scaler, scale to zero for batch queues, and shut workers down gracefully so tasks are not lost.
- Run Django Management Commands in Docker and Kubernetes
Run Django manage.py commands against containerised deployments: docker compose exec versus run, kubectl exec versus one-off Jobs, loading the right settings and secrets, interactive shells, and keeping one-off commands out of web containers.
Run it well
Tuning, reliability, and operations once it works.
- Autoscale Django on Kubernetes With the HPA
Autoscale Django web pods on Kubernetes with the Horizontal Pod Autoscaler: accurate CPU requests, scaling on CPU or requests per second, min and max replicas, scale-down stabilisation, database connection limits, and testing under load.
- Liveness and Readiness Probes for Django on Kubernetes
Configure Kubernetes liveness, readiness, and startup probes for Django: separate cheap liveness and dependency-aware readiness endpoints, ALLOWED_HOSTS and HTTPS redirects, timeouts and thresholds, and avoiding restart storms during database outages.
- Manage Django Settings on Kubernetes With ConfigMaps and Secrets
Deliver Django configuration on Kubernetes: ConfigMaps for non-secret settings, Secrets for credentials, envFrom versus mounted files, rolling pods when values change, encryption at rest, and syncing from external secret managers.
- Keep Django Available During Kubernetes Node Maintenance With PodDisruptionBudgets
Protect a Django deployment from voluntary disruptions on Kubernetes: add PodDisruptionBudgets for web and Celery, spread replicas across nodes and zones, set graceful termination and preStop delays, and avoid budgets that block node drains forever.
- Set Kubernetes CPU and Memory Requests and Limits for Django
Size Kubernetes resources for Django web and Celery pods: measure real usage, set memory requests near the working set and limits above peaks, avoid CPU throttling with sensible CPU limits, match Gunicorn workers to CPU requests, and use VPA recommendations.
- Restrict Django Pod Traffic With Kubernetes NetworkPolicies
Lock down network access for Django on Kubernetes: default-deny ingress and egress, allow the ingress controller to reach web pods, let web and Celery reach PostgreSQL, Redis, and DNS, permit required external APIs, and test policies without breaking the app.
- Zero-Downtime Rolling Updates for Django on Kubernetes
Make Kubernetes rolling updates of Django truly zero-downtime: configure maxSurge and maxUnavailable, readiness probes that reflect real readiness, preStop delays for endpoint propagation, Gunicorn graceful shutdown, backward-compatible migrations, and minReadySeconds.
Check it
Review lists to run before launch or after a change.
- Django Kubernetes Production Checklist
A production checklist for Django on Kubernetes: images, probes, resources, rolling updates, migrations as Jobs, secrets, static and media, Celery and Beat, autoscaling, disruption budgets, and observability.
- Django Kubernetes Security Checklist
A security checklist for Django on Kubernetes: non-root containers with read-only filesystems, Pod Security Standards, minimal RBAC and service account tokens, secrets from a manager, NetworkPolicies, image scanning and signing, patched nodes, and audit logging.
Fix it
Errors and symptoms, each traced to a cause and a fix.
- Fix a Django Pod in CrashLoopBackOff
Fix a Django pod stuck in CrashLoopBackOff on Kubernetes: read logs from the previous container, find missing environment variables and secrets, failing liveness probes, OOMKilled limits, and migrations run at startup.
- Fix Kubernetes Probes Failing With 400 DisallowedHost in Django
Fix Kubernetes readiness and liveness probes that fail with 400 Bad Request because Django rejects the pod IP as a DisallowedHost: add a host header to the probe, exempt the health endpoint safely, or allow the pod network without disabling host checks.
- Fix Kubernetes ImagePullBackOff for a Django Deployment
Fix Kubernetes ImagePullBackOff and ErrImagePull for Django pods: read the pull error, fix image names and tags, add imagePullSecrets for GHCR, ECR, or GitLab, handle expiring ECR tokens and rate limits, and match image architecture to nodes.
- Fix Kubernetes CreateContainerConfigError for Django Pods
Fix Kubernetes CreateContainerConfigError for Django pods: find the missing Secret, ConfigMap, or key in the pod events, create it in the right namespace, fix envFrom and secretKeyRef names, and order resources so deploys do not race their config.