Deploy FastAPI Applications to Kubernetes

Introduction

A FastAPI app running on your laptop is not production. This guide takes the Dockerized image from earlier tutorials and ships it to Kubernetes with proper health checks, config, secrets, autoscaling and a zero-downtime rollout.

For the Java equivalent, see Deploy Spring Boot to Kubernetes.

Key takeaways

• Always set resource requests + limits, or the scheduler can't reason about you.
• Wire up /healthz (liveness) and /readyz (readiness) — they have different meanings.
• Roll out with maxUnavailable: 0 for zero downtime.
• Use ConfigMap for non-secret config, Secret for credentials.
• Use HorizontalPodAutoscaler on CPU + custom metrics, not just CPU.

Health endpoints in FastAPI

```python
@app.get("/healthz")
async def healthz(): return {"ok": True}

@app.get("/readyz") async def readyz(): try: await db.execute("SELECT 1") return {"ok": True} except Exception: raise HTTPException(503, "db not ready") ```

Deployment

apiVersion: apps/v1
kind: Deployment
metadata: { name: api }
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate: { maxSurge: 1, maxUnavailable: 0 }
  selector: { matchLabels: { app: api } }
  template:
    metadata: { labels: { app: api } }
    spec:
      securityContext: { runAsNonRoot: true, runAsUser: 10001 }
      containers:
        - name: api
          image: ghcr.io/org/api:1.4.2
          ports: [{ containerPort: 8000 }]
          envFrom:
            - configMapRef: { name: api-config }
            - secretRef:    { name: api-secrets }
          resources:
            requests: { cpu: "200m", memory: "256Mi" }
            limits:   { cpu: "1",    memory: "512Mi" }
          readinessProbe:
            httpGet: { path: /readyz, port: 8000 }
            initialDelaySeconds: 5
            periodSeconds: 5
          livenessProbe:
            httpGet: { path: /healthz, port: 8000 }
            initialDelaySeconds: 20
            periodSeconds: 10

Service + Ingress

apiVersion: v1
kind: Service
metadata: { name: api }
spec:
  selector: { app: api }
  ports: [{ port: 80, targetPort: 8000 }]
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: api
  annotations:
    cert-manager.io/cluster-issuer: letsencrypt-prod
spec:
  tls: [{ hosts: [api.example.com], secretName: api-tls }]
  rules:
    - host: api.example.com
      http:
        paths:
          - path: /
            pathType: Prefix
            backend: { service: { name: api, port: { number: 80 } } }

Config + Secrets

apiVersion: v1
kind: ConfigMap
metadata: { name: api-config }
data:
  LOG_LEVEL: "INFO"
  WORKERS: "4"
---
apiVersion: v1
kind: Secret
metadata: { name: api-secrets }
type: Opaque
stringData:
  DATABASE_URL: postgresql+asyncpg://app:****@pg/app
  JWT_SECRET: ****

Autoscaling

apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata: { name: api }
spec:
  scaleTargetRef: { apiVersion: apps/v1, kind: Deployment, name: api }
  minReplicas: 3
  maxReplicas: 20
  metrics:
    - type: Resource
      resource: { name: cpu, target: { type: Utilization, averageUtilization: 70 } }

Production best practices

• Run migrations as a Job with backoffLimit: 0, not inside the app pod.
• Set PodDisruptionBudget minAvailable: 2 to survive node drains.
• Add a preStop sleep of ~5s so in-flight requests drain before SIGTERM.
• Pin images by SHA digest in prod, not floating tags.

Common mistakes

• Using /healthz for both liveness and readiness — a slow DB causes pod restarts.
• No resource limits — one pod with a memory leak crashes its node.
• Deploying :latest — no clean rollback.

Tools used in this tutorial

The setup below uses the following tools. Versions matter less than the role each one plays, so swap freely as long as you keep the responsibilities the same.

• Python 3.12+
• FastAPI
• Uvicorn / Gunicorn
• Pydantic v2
• SQLAlchemy 2.x
• Docker
• Kubernetes

Real-world production context

In production, a Python backend like this rarely runs as a single uvicorn process on a laptop. Teams build the app into a container image, push it to a registry, and run it behind a managed load balancer with autoscaling, health checks and centralized logging. Async FastAPI services typically use multiple Uvicorn workers managed by Gunicorn, a managed Postgres for state, Redis for cache and rate-limit counters, and an object store for uploads. The reason cloud hosting becomes a hard requirement is operational: zero-downtime rollouts, log aggregation, metrics, and TLS at the edge are not optional once real users depend on the API.

Recommended tools & deployment options

Once the tutorial works on your machine, the next question is *where do I run this for real?* These are the platforms most Python backend teams reach for:

• DigitalOcean — the simplest path from a working FastAPI container to a public URL. App Platform deploys directly from a Dockerfile, managed Postgres and Redis are one click away, and pricing is predictable. A common way to deploy the setup in this tutorial is using a cloud provider like DigitalOcean when you want to ship quickly without learning a full cloud SDK.
• AWS — the default for enterprise workloads. ECS Fargate or EKS run containers without you managing servers, RDS handles Postgres, and CloudWatch covers logs and metrics.
• Docker — the packaging format every modern deploy target understands. Build once, run the same image locally, in CI and in production.
• Kubernetes (managed: EKS, DOKS, GKE) — the right choice once you have more than a handful of services, need rolling updates, autoscaling and policy-driven networking.

A VPS or managed cloud service is required to run this architecture end-to-end — uvicorn --reload is for development, not for serving traffic.

FAQ

Helm or raw manifests? Raw manifests + Kustomize scale far. Reach for Helm when you publish charts for others.

Next steps & related tutorials

Keep the momentum going with the next tutorial in this learning path:

• Next: Dockerizing a FastAPI Application
• Next: CI/CD Pipeline for FastAPI
• Next: FastAPI Microservices Architecture