/azure-kubernetes

Flask Knowledge Pack

Applies to: Projects detected with requirements.txt, pyproject.toml, or Pipfile containing flask

Quick Reference

Health Endpoints

Flask does not include health check endpoints — they must be defined explicitly in application code:

Minimal health route

from flask import Flask, jsonify

app = Flask(__name__)

@app.route("/health")
def health():
    return jsonify(status="ok"), 200

Readiness route with database check

from flask import jsonify
from sqlalchemy import text

@app.route("/ready")
def ready():
    try:
        db.session.execute(text("SELECT 1"))
        return jsonify(status="ready"), 200
    except Exception:
        return jsonify(status="not ready"), 503

Probe configuration in Deployment manifest

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

Note: Flask apps behind gunicorn start quickly (typically <3s), so initialDelaySeconds: 5 is sufficient — much lower than JVM-based frameworks.

Database Profiles

Flask does not have a built-in profile system. Database configuration is typically driven by environment variables:

Important: Flask-SQLAlchemy reads the connection string from app.config["SQLALCHEMY_DATABASE_URI"], which is typically set via os.environ.get("SQLALCHEMY_DATABASE_URI") or os.environ.get("DATABASE_URL"). Ensure the env var name matches what the app expects.

Environment variables for PostgreSQL on AKS

env:
  - name: SQLALCHEMY_DATABASE_URI
    value: "postgresql://{{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

Secret for SECRET_KEY

Flask requires SECRET_KEY for session signing, CSRF tokens, and any use of flask.session. Never hardcode it — store it in a Kubernetes Secret:

apiVersion: v1
kind: Secret
metadata:
  name: {{APP_NAME}}-secrets
type: Opaque
stringData:
  secret-key: "<generate-a-random-string>"

ConfigMap pattern

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{APP_NAME}}-config
data:
  SQLALCHEMY_DATABASE_URI: "postgresql://{{IDENTITY_NAME}}@{{PG_SERVER_NAME}}.postgres.database.azure.com:5432/{{DB_NAME}}?sslmode=require"

Workload Identity with azure-identity

See references/workload-identity.md for connection patterns. Requires azure-identity package.

Writable Paths (DS012 Compliance)

When readOnlyRootFilesystem: true is set, Flask apps typically only need /tmp writable:

• Uploaded files use /tmp as the default staging directory for request.files
• Temporary processing may write intermediate results to /tmp

Required volume mount

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

No other writable paths are typically needed for production Flask apps.

Resource Sizing

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

Port Configuration

• Development port: 5000 (flask run default — do not use in production)
• Production port: 8000 (gunicorn convention)
• 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 in app code int(os.environ.get("PORT", 8000)))
• Workers formula: 2 * CPU_CORES + 1 — override at runtime via WEB_CONCURRENCY env var
• Entry point variants: gunicorn "app:app" (module-level) or gunicorn "myapp:create_app()" (application factory)

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

Build Commands

Ensure gunicorn is listed in requirements.txt or pyproject.toml production dependencies.

Common Issues on AKS