/azure-kubernetes-app-deploy

Django Knowledge Pack

Applies to: Projects detected with requirements.txt, pyproject.toml, or Pipfile containing django, or presence of manage.py

Quick Reference

Health Endpoints

Django does not provide health endpoints out of the box. Use the django-health-check package:

Installation

pip install django-health-check

Configuration in settings.py

INSTALLED_APPS = [
    # ...existing apps...
    "health_check",
    "health_check.db",
    "health_check.cache",
    "health_check.storage",
    "health_check.contrib.migrations",
]

URL configuration in urls.py

from django.urls import include, path

urlpatterns = [
    # ...existing urls...
    path("health/", include("health_check.urls")),
]

The /health/ endpoint returns HTTP 200 when all checks pass and HTTP 500 with details when any check fails.

Probe configuration in Deployment manifest

livenessProbe:
  httpGet:
    path: /health/
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 15
  timeoutSeconds: 3
  failureThreshold: 3
readinessProbe:
  httpGet:
    path: /health/
    port: 8000
  initialDelaySeconds: 10
  periodSeconds: 10
  timeoutSeconds: 3
  failureThreshold: 3

Note: initialDelaySeconds: 10 is sufficient for most Django apps.

Database Profiles

Django does not have a built-in profile system like Spring Boot. Database configuration is driven by settings.py with environment variables:

Environment variables for PostgreSQL on AKS

env:
  - name: DATABASE_URL
    value: "postgres://{{IDENTITY_NAME}}@{{PG_SERVER_NAME}}.postgres.database.azure.com:5432/{{DB_NAME}}?sslmode=require"
  - name: SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: {{APP_NAME}}-secrets
        key: secret-key

Important: SECRET_KEY must never be in a ConfigMap or hardcoded. Always store it in a Kubernetes Secret (or Key Vault via Workload Identity).

ConfigMap pattern

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{APP_NAME}}-config
data:
  DJANGO_SETTINGS_MODULE: "config.settings.production"
  DJANGO_ALLOWED_HOSTS: "{{INGRESS_HOSTNAME}}"
  DATABASE_URL: "postgres://{{IDENTITY_NAME}}@{{PG_SERVER_NAME}}.postgres.database.azure.com:5432/{{DB_NAME}}?sslmode=require"

Writable Paths (DS012 Compliance)

When readOnlyRootFilesystem: true is set, Django apps need /tmp writable and optionally /app/staticfiles:

• /tmp — required for file uploads (FILE_UPLOAD_TEMP_DIR defaults to /tmp), session data when using file-based sessions, and temporary processing
• /app/staticfiles — optional, only needed if serving collected static files at runtime from the local filesystem (when not using WhiteNoise or a CDN)

Volume mount configuration

volumes:
  - name: tmp
    emptyDir: {}
  - name: staticfiles
    emptyDir: {}
containers:
  - name: app
    volumeMounts:
      - name: tmp
        mountPath: /tmp
      - name: staticfiles
        mountPath: /app/staticfiles

If static files are baked into the image at build time via collectstatic and served by WhiteNoise, the staticfiles volume can be omitted — only /tmp is required.

Resource Sizing

Django with Gunicorn runs multiple worker processes. Size for the number of workers (default: 2-4).

Port Configuration

• Default port: 8000
• CLI flag: --bind 0.0.0.0:8000 passed to gunicorn
• Env var override: PORT (read via gunicorn --bind 0.0.0.0:$PORT or int(os.environ.get("PORT", 8000)))
• Workers formula: 2 * CPU_CORES + 1 (e.g. --workers 3 for a 1-vCPU container)
• WSGI module path varies by project scaffold: config.wsgi:application, myproject.wsgi:application, or app.wsgi:application — check wsgi.py location

Gunicorn logs the port on startup: Listening at: http://0.0.0.0:8000

Build Commands

Important: Database migrations must run as an init container, not during the Docker build. The build stage has no access to the production database, and running migrations in the entrypoint creates race conditions when multiple replicas start simultaneously.

Init container for migrations

initContainers:
  - name: migrate
    image: {{ACR_NAME}}.azurecr.io/{{APP_NAME}}:{{TAG}}
    command: ["python", "manage.py", "migrate", "--noinput"]
    envFrom:
      - configMapRef:
          name: {{APP_NAME}}-config
      - secretRef:
          name: {{APP_NAME}}-secrets

Common Issues on AKS