Run FastAPI on Kubernetes

By Khimananda Oli | Last reviewed: August 2026

Deploying Python APIs often fails at the container boundary because developers treat orchestration as an afterthought rather than a core architectural constraint. To successfully run FastAPI on Kubernetes, you must align your application’s asynchronous worker model with cluster resource management, ensuring that liveness probes, graceful shutdowns, and horizontal scaling actually function under load. This guide bridges the gap between local development and production-grade orchestration using verified configurations for 2026.

How do you containerize FastAPI for Kubernetes?

The foundation of any stable Kubernetes deployment is a deterministic, lightweight container image. When you prepare to run FastAPI on Kubernetes, avoid using the official python base image directly; it exceeds 900MB and includes unnecessary build tools that increase your attack surface. Instead, use a multi-stage build pattern that separates compilation dependencies from the runtime environment. This approach keeps final images under 200MB and ensures reproducible deployments across environments.

A common mistake when configuring the entrypoint is running Uvicorn directly without a process manager. While Uvicorn is an excellent ASGI server, it lacks robust process supervision for production containers. Use Gunicorn with the Uvicorn worker class to handle graceful restarts, signal forwarding, and multiple worker processes within a single pod. This combination is currently the industry standard for async Python workloads in orchestrated environments.

# Dockerfile.production
FROM python:3.12-slim-bookworm AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.12-slim-bookworm
RUN useradd --create-home appuser
WORKDIR /home/appuser
COPY --from=builder /install /usr/local
COPY ./app ./app
USER appuser
EXPOSE 8000
CMD ["gunicorn", "app.main:app", "-w", "4", "-k", "uvicorn.workers.UvicornWorker", "--bind", "0.0.0.0:8000"]

For teams managing complex dependency trees or integrating with databases like PostgreSQL, understanding PostgreSQL administration essentials helps prevent connection pool exhaustion when scaling pods. Each replica opens its own set of database connections, so your container strategy must account for backend capacity, not just CPU and memory limits.

What are the correct Kubernetes manifests for FastAPI?

Writing YAML manifests requires precision, especially when defining health checks and resource boundaries. Many engineers struggle to correctly debug a CrashLoopBackOff in Kubernetes because they misconfigure probe timing or fail to distinguish between startup, liveness, and readiness checks. For FastAPI, your probes should target lightweight endpoints that verify both the web server and critical downstream dependencies without executing heavy business logic.

Configuring Health Probes and Resources

Your FastAPI application must expose dedicated health endpoints. The /health/live endpoint should return 200 OK immediately if the process is responsive, while /health/ready should validate database connectivity and cache availability. Setting appropriate initialDelaySeconds prevents premature restarts during cold starts, and periodSeconds determines how quickly the cluster detects failures.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: fastapi-app
spec:
  replicas: 3
  selector:
    matchLabels:
      app: fastapi-app
  template:
    metadata:
      labels:
        app: fastapi-app
    spec:
      containers:
      - name: api
        image: registry.example.com/fastapi-app:v1.4.2
        ports:
        - containerPort: 8000
        resources:
          requests:
            cpu: "250m"
            memory: "256Mi"
          limits:
            cpu: "1000m"
            memory: "512Mi"
        livenessProbe:
          httpGet:
            path: /health/live
            port: 8000
          initialDelaySeconds: 10
          periodSeconds: 15
        readinessProbe:
          httpGet:
            path: /health/ready
            port: 8000
          initialDelaySeconds: 5
          periodSeconds: 10

Resource requests and limits are non-negotiable for Python workloads. Without them, the scheduler cannot make informed placement decisions, and a single memory leak can destabilize an entire node. Always set requests based on observed baseline usage and limits at 2x–4x the request value to accommodate garbage collection spikes. Refer to our guide on Kubernetes resource limits and requests for detailed tuning strategies specific to interpreted languages.

How does autoscaling work for async Python APIs?

Horizontal Pod Autoscaling (HPA) behaves differently for asynchronous frameworks compared to traditional synchronous ones. Because FastAPI handles concurrency via event loops rather than thread-per-request models, CPU utilization often remains low even under high throughput. Relying solely on CPU metrics leads to under-scaling and increased latency. You should implement custom metrics based on active requests or queue depth to trigger scaling events accurately.

To expose custom metrics, integrate Prometheus client libraries into your FastAPI application and configure the Prometheus Adapter in your cluster. Define HPA targets against these metrics rather than generic resource consumption. This ensures your infrastructure responds to real user experience degradation rather than arbitrary system statistics. Remember that scaling also affects downstream services; always coordinate API scaling with database connection pooling and cache layer capacity.

How do you manage secrets and configuration safely?

Hardcoding credentials in Dockerfiles or mounting unencrypted ConfigMaps violates basic security principles and compliance standards like SOC 2. When you run FastAPI on Kubernetes, sensitive values such as database passwords, API keys, and JWT signing secrets must be injected securely at runtime. Native Kubernetes Secrets provide base64 encoding but not encryption at rest by default. For production environments, integrate external secret managers or enable encryption at rest on the etcd datastore.

• Use environment variables for simple configuration toggles and non-sensitive metadata.
• Mount secrets as files rather than env vars to prevent leakage in process listings and crash dumps.
• Implement least-privilege RBAC policies so only specific service accounts can access required secrets.
• Rotate credentials automatically using operators or external sync tools without redeploying pods.
• Audit secret access patterns through centralized logging to detect anomalous behavior early.

For comprehensive guidance on securing sensitive data, review our article on Kubernetes secrets management done right. Proper secret handling is frequently the difference between passing and failing security audits, especially for fintech and healthcare applications operating in regulated markets.

When should you use Ingress versus LoadBalancer?

Exposing your FastAPI service requires choosing the right networking primitive. A LoadBalancer Service provisions a cloud provider's external load balancer per service, which becomes cost-prohibitive beyond two or three services. An Ingress Controller consolidates routing rules behind a single entry point, enabling path-based routing, TLS termination, and rate limiting at the edge. For most production deployments, Ingress is the economically and operationally superior choice.

If you're still evaluating whether Kubernetes is necessary for your current scale, compare it against simpler alternatives discussed in our Kubernetes vs Docker Swarm comparison. Not every FastAPI project needs full orchestration, but once you exceed single-node reliability requirements, Kubernetes provides unmatched operational leverage.

Run FastAPI on Kubernetes With Confidence

Successfully operating async Python APIs in production demands disciplined attention to containerization, probe configuration, metric selection, and secret hygiene. By following the patterns outlined here, you eliminate the most frequent failure modes that plague teams attempting to run FastAPI on Kubernetes for the first time. Start with the multi-stage Dockerfile and validated manifests above, then iterate based on observed performance data rather than assumptions. If your team needs hands-on assistance designing compliant, scalable API infrastructure, reach out to discuss your specific requirements.