Django on Kubernetes

This is part 2 of our Kubernetes hackday series. You can find Part 1 here which goes over how we spent the day and what the goals and motivations are. For part 2, we’re going to delve into the architecture required for running a Django application on Kubernetes, as well as some of the tooling […]

This is part 2 of our Kubernetes hackday series. You can find Part 1 here which goes over
how we spent the day and what the goals and motivations are.

For part 2, we’re going to delve into the architecture required for running a Django
application on Kubernetes, as well as some of the tooling we used to assist us.

This post will assume some knowledge with deploying and operating a production
web application. I’m not going to spend much time going over the terminology that
Kubernetes uses either. What I hope to do in this post is present enough information
to kickstart your own migration. Kubernetes is big – and knowing what to research now
and what to put off until later is really tricky.

I’m also going to describe this deployment in terms of Amazon EKS rather than Google GKE simply because I was on the EKS team,
and most of our applications are already on AWS.


We’re not yet running any production apps on Kubernetes, but we’ve done
a lot of the analysis, and are comfortable with the high level design. If you’re
looking to migrate yourself, feel free to use this design as a jump start, but know there’ll be a lot more detail to deal with.

Current Django Architecture

Before discussing where we’re going, it’s helpful to know where we are. When
deploying a new Django application, we usually have the following components.

  1. Application server(s) (Gunicorn) fronted by Nginx
  2. Worker server(s) (Celery)
  3. Scheduler server (Celery beat + shell, single instance)
  4. Database (Postgres)
  5. Cache (Redis usually, sometimes Memcache)
  6. Message Server for Celery (Redis or RabbitMQ)
  7. Static content pushed to and served from S3
  8. A CDN in front of the static content on S3

The scheduler server is a single instance that we use for our cron tasks, and
for production engineers to ssh to when they need to do production analysis. It’s
incredibly important for our workflows to maintain this capability when moving to

The Cluster

EKS requires you to setup the VPC and Subnets that’ll be used to host the master
nodes of the cluster. Thankfully, AWS provide CloudFormation templates that do
exactly this.

The Getting Started
section is required reading, and will walk you through the rather complicated
process for setting up a cluster, authentication, the initial worker nodes, and
configuring kubectl so
you can operate the cluster from the command line.

This setup is one area where EKS lags well behind the GKE experience. Creating a
fully operational kubernetes cluster in the GCP console is literally a few clicks.


Minikube is a single-node local
Kubernetes deployment that you can run on your laptop. If you want to experiment
with Kubernetes but don’t want the hassle of spinning up a production-grade cluster
in the cloud, Minikube is an excellent option.

Because EKS took some time to get operational, the rest of the team members worked
exclusively on Minikube until the final hour. Minikube has some limitations, but
was excellent for a development environment.

Kubernetes Design

The very first task we set out to do was to come up with an architecture, in
Kubernetes terms, that would support our application and our desired workflows. The
final design ended up somewhat different from the initial one based on our learnings,
but it gave us a shared language and allowed us to partition the tasks properly.

Architecture Diagram

There are actually two designs. The staging architecture differs from the production
architecture. We can have 10s of staging environments at any time, so being able to
easily bring up and destroy environments is highly desirable.

For this reason, our staging design does not use cloud services like RDS or
ElastiCache, which would require coordinating deployments between Kubernetes
and various cloud provider SDKs. Instead, we deploy Postgres and Redis within
the cluster.

Architecture Diagram - UAT

Note: We love RDS. Properly configuring, backing up, monitoring, and updating
services like Postgres and Redis isn’t trivial. We trust cloud providers to do it
much better than our small team can, especially on Kubernetes where our experience
is, well, very little. But if our Staging database deployment crashes, it’s not a
critical event.

The only real difference between the two environments is that the Services
either point externally to a managed data store, or internally to a datastore. The
applications themselves remain blissfully unaware.

Deployments, Containers, and Services, OH MY

You may have heard of Pods or Services but don’t really understand how all of these
concepts fit together. The docs are dense, and knowing where to begin learning is
half the battle. Let me give a quick run down of the Kubernetes objects we’re
using here.

Namespaces let you group together related components so they can communicate. Namespaces aren’t
(on their own) a security mechanism. Use namespaces to segment apps you trust, or
different environments for a single app.

are like an auto-scaling group for a Pod. A Pod has (usually) a
single container, but may have multiple containers if they are co-dependent.
Containers within a pod share a volume and can communicate directly.

Services are
basically TCP load balancers. They are capable of a lot more, but for our purposes,
that’s what we’re using them for.

can be environment variables or entire files that are injected into a Pod.

Secrets like passwords
are injected into the cluster, and then made available to Deployments at runtime.

I encourage you to read all of the Concepts
documentation in time. But do so after you have a handle on the above types first.
There’s lots you can ignore as implementation details you won’t have to deal with

Application Design

Unless you’re already following Continuous Delivery
it’s likely that your application is going to need to change in some way to be
compatible with a Kubernetes deployment. Here are a few things that we needed
to change.

Static Files

Deploy them to S3? Bundle a copy inside each container? Use Nginx? This choice
can be particularly contentious. Here’s my advice.

Use Whitenoise so that Django is in
charge of serving static content, then put a CDN in front of it. If, for some
reason, you don’t trust Whitenoise then use nginx within the same Pod to serve
the files, and still put a CDN infront of it.

Shared Storage

Maybe you’re using an NFS mount for uploaded media? Stop doing that. Use an object
storage service (like S3) instead.

That said, you’ll still need to tell Kubernetes what type of storage engine it
should use for local volumes. Before Kubernetes 1.11 (EKS), you will need to explicitly
configure a storage class. See Storage Classes
documentation for setting this up.

Config Files

You might have config files for services like New Relic or similar. Deploy these
with ConfigMaps instead.

Secrets / Config Variables

Use Secrets for sensitive material or ConfigMaps otherwise. Consume variables
from environment variables within the app.


You might already have Dockerfiles for development or some other environment. My
advice is to have a separate Dockerfile optimised for development, and another
optimised for Production.

Perhaps you need auto-reloading and NPM in development? Great! Don’t ruin your
production builds and artifacts with cruft that you don’t need. Reduce the size
and build time aggressively for production.

In our design, we have an app server, a celery worker, and a celery beat. Use the
same Dockerfile for all 3 servers, but change the Entrypoint so the right service
is started. We don’t want to be building 3 slightly different containers.

Deploying to Kubernetes

We have a good idea what objects we require. Our application is ready. How does
it all come together?

With YAML. Specifically, having Helm Charts produce YAML.

Helm Charts are packages. You can use Helm to deploy Charts onto Kubernetes. Helm
Charts represent fully running Applications like Postgres, or our own custom
Django application.

Helm Charts can have dependencies. They may also have configuration, and run
time options that change how an application can be deployed. For example, you may
deploy a chart with a STAGING flag set, that additionally deploys a local Postgres
rather than relying on hosted RDS. Sound familiar?

You will spend a lot of time designing your Helm Chart yaml files. They are basically
golang Templates that will render Kubernetes compatible YAML for each object in our
diagram above. We hope to be able to abstract the chart enough where we can deploy
arbitary Django applications based on an image name.

Monitoring and Operations

We’ve covered the the concepts required for setting up a cluster and deploying the application, but it’s harder to find information on monitoring your application and operating it in production. I’ll briefly touch on some of those facets now.


Centralised logging is critical for any large application, but doubly so for one running within Kubernetes. You can’t just hop onto a node and tail log files, and doing any kind of post mortem analysis on dying nodes becomes impossible.

The standard wisdom is to run a logging daemon within each Deployment or Node that takes your logs and sends them to the logging service of your choice. There are helm charts for major logging services that you can reuse.

Logging daemons typically run as DaemonSets, which is another Kubernetes object, but one you probably won’t interact with directly.


Prometheus is the standard monitoring tool used within Kubernetes clusters. Your application (and services) can export metrics that Prometheus will then gather.

We’ll continue to use New Relic for our applications though, as it gives a lot of great insight into your Django app. Within your web/celery startup script, run it with newrelic-admin as normal. Deploy your newrelic.ini as a ConfigMap.


If you’re using AWS Certificate Manager with your Application Load Balancer, then SSL is mostly handled for you. There are also Helm charts for deploying LetsEncrypt into your Kubernetes cluster.


This one is a bit trickier, and I’m not sure we’ve fully landed on a solution at this time. Amazon Route 53 is the managed DNS service, but what is going to provision a new zone for an instance of our application?

There are tools like Pulumi that allow you to program your infrastructure with nice Kubernetes integration. It may make sense to have Pulumi provision the hosted zone, and then deploy your helm chart into Kubernetes.

Auto Scaling

There are two systems that you’re going to need to autoscale now. The nodes that the cluster is running on, and the number of application instances (Pods/Deployments) you want to run.

Helm cluster-autoscaler claims to support scaling the worker nodes. While Kubernetes has support for Horizontal Pod Autoscaler for scaling your application.


I hope the information presented above is useful and answers some questions you might have already had about moving to Kubernetes. We found that working our way through and understanding the concepts behind Kubernetes has lead to a lot more productive conversations about what a migration might look like, and the effort required to make that migration. A full migration is definitely on the cards for this year, and we’ll be documenting our journey as we go.

If there are any corrections needed above, please let us know in the comments. We’d also love to hear about your experiences with your own migration and what some of the sticking points were.

And, as always, if infrastructure is your thing and you think you can help us with the migration to Kubernetes, We’re Hiring!