Deploy a flask application with nginx on kubernetes

Create directory structure

Run the following commands to create the directories structure that is necessary for our project. We'll populate all of them later.

mkdir -p app/gulp/assets/{css,images,js}
mkdir -p app/gulp/assets/js/modules
mkdir -p docker/{flask,nginx}
mkdir -p kube
mkdir -p templates

Download images

Run the following command to download an image that you'll display in the website

wget https://images5.1000ps.net/images_bikekat/2022/7-BMW/9500-R_1250_GS/006-637607432443050778-bmw-r-1250-gs.jpg -O app/gulp/assets/images/bmw-r-1250-gs.jpg

Create Flask application

As a first step, we'll create the flask application and once it is running we'll add all other functionalities

./requirements.txt

This is the file that stores the dependencies necessary for our small application

click==8.0.3
Flask==2.0.2
gunicorn==20.1.0
itsdangerous==2.0.1
Jinja2==3.0.3
MarkupSafe==2.0.1
Werkzeug==2.0.2

./app.py

This is the main flask application that holds the rules for our website.

#!/bin/env python3

import os
from flask import Flask, render_template

app = Flask(__name__)

@app.route("/")
def homepage():
    return render_template("homepage.html", content="Hello world")

if __name__ == '__main__':
    app.run(
        host=os.getenv('FLASK_IP', '0.0.0.0'),
        port=os.getenv('FLASK_PORT', 5000),
        debug=bool(os.getenv('FLASK_DEBUG', True))
    )

./templates/homepage.html

Let's just write a dummy html code that will be displayed by flask application. Don't worry about the missing css and js files yet. They'll be added later.

<!doctype html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <title>Document</title>
    <link rel="stylesheet" href="/css/external.css">
    <link rel="stylesheet" href="/css/app.css">
</head>
<body>

<h1>Hello world</h1>
<h3>welcome to my page</h3>

<img src="/images/bmw-r-1250-gs.jpg" width="500" alt="BMW R1250GS" />
<img src="/images/bmw-r-1250-gs.jpg" width="500" alt="BMW R1250GS" />
<img src="/images/bmw-r-1250-gs.jpg" width="500" alt="BMW R1250GS" />

<script src="/js/external.js"></script>
<script src="/js/app.js"></script>
</body>
</html>

Before we run our application, we'll have to create a virtual environment:

python3 -m venv myv
source myv/bin/activate

Then, let's install the dependencies for our little project:

pip install -r requirements.txt

Now, let's start our project and view it in the browser:

python app.py

Open the browser at url localhost:5000 and you should see the text from our html page, but you won't be able to see the image displayed three times.

The reason why you don't see the colored text and images is that they are not existing in the public directory and you don't have any server configured to serve those files. We'll configure nginx inside a docker container a little bit later.

Create nodejs assets

To compile the assets files (css, js and images) we'll use gulp and a small npm package that I wrote to make life easier when it comes to frontend dependencies: kisphp-assets

If you haven't used gulp before, have a look at the gulp documentation.

Create the following files:

./app/gulp/gulpfile.js

This will be the main gulpfile.js file where you configure what tasks you want to run by gulp for your project.

const { task, series } = require('gulp');

const config = require('../../gulp-config');

function requireUncached(module) {
    delete require.cache[require.resolve(module)];
    return require(module);
}

const js = require('kisphp-assets/tasks/javascripts')(config.js.external);
const bsrf = requireUncached('kisphp-assets/tasks/browserify')(config.js.project);
const css = require('kisphp-assets/tasks/css')(config.css.external);
const incss = requireUncached('kisphp-assets/tasks/css')(config.css.project);
const files = require('kisphp-assets/tasks/copy_files')(config.files);

task('default', series(
    files.copy_files,
    css.css,
    incss.css,
    js.javascripts,
    bsrf.browserify,
));

./app/gulp/assets/css/main.css

Just a small styling for your page so you can see how it interacts with your application

h1 {
    color: #9C1A1C;
}

h3 {
    color: #3A7734;
}

./app/gulp/assets/js/modules/demo.js

This js file will not do much, but it will show you how to add custom js code. All you have to do, is to create a file per use case and have init function for the exported object. You also can create functions, classes or everything you need in that file.

The files will be compiled by gulp with browserify plugin.

module.exports = {
    init: function() {
        console.log('file loaded');
    }
}

./app/gulp/assets/js/app.js

Here is the main javascript file for your application and will load all modules inside a document.ready jquery object.

$(document).ready(function(){
    require('./modules/demo').init();
    // add here more files that do one thing (Single Responsibility Principle)
});

./package.json

Let's create the dependencies list for our assets

{
  "scripts": {
    "build": "gulp --gulpfile app/gulp/gulpfile.js --cwd ."
  },
  "dependencies": {
    "bootstrap": "^5.1.3",
    "jquery": "^3.6.0",
    "kisphp-assets": "^0.6.0"
  }
}

./gulp-config.js

The purpose of this file is to have the list for which files will be compiled by gulp tasks. You'll have the following configurations:

  • js.external -> combine external javascript dependencies and combine them all into one external.js file
  • js.project -> local javascript files written in require.js format and compiled by browserify into one app.js file
  • css.external -> combine external css dependencies and save them into one external.css file
  • css.project -> build local css files and save them into app.css file. Here you can use css, stylus or scss sources.
  • files.xxxx -> here is the definition of the files you want to copy from dependencies to public directory. Usually you will copy images and fonts.
const settings = function(){
  this.root_path = __dirname;
  this.project_assets = __dirname + "/app/gulp/";

  this.settings = {
    "name": "kisphp demo",
    "root_path": this.root_path,
    "project_assets": this.project_assets,

    "js": {
      "external": {
        "sources": [
          'node_modules/jquery/dist/jquery.min.js',
          'node_modules/bootstrap/dist/js/bootstrap.min.js',
        ],
        "output_filename": "external.js",
        "output_dirname": "public/js/",
      },
      "project": {
        "sources": [
          this.project_assets + '/assets/js/app.js',
        ],
        "output_filename": "app.js",
        "output_dirname": "public/js/",
      }
    },
    "css": {
      "external": {
        "sources": [
          'node_modules/bootstrap/dist/css/bootstrap.min.css',
        ],
        "output_filename": "external.css",
        "output_dirname": "public/css/",
      },
      "project": {
        "sources": [
          this.project_assets + '/assets/css/main.css'
        ],
        "output_filename": "app.css",
        "output_dirname": "public/css/",
      }
    },
    "files": {
      "fonts": {
        "sources": [
          'node_modules/bootstrap/fonts/*.*',
        ],
        "output_dirname": "public/fonts"
      },
      "images": {
        "sources": [
          this.project_assets + '/assets/images/**/*.*'
        ],
        "output_dirname": "public/images"
      }
    }
  };

  return this.settings;
};

module.exports = settings();

Now that you have all these files created, let's install the dependencies:

npm install

Then let's generate our public directory with all required files in it:

npm run build

At this point, you should have a flask application and a generated public directory with two css files, two javascript files and one image

Again, if you run python app.py you still won't be able to load the assets files and the image. We'll do this in the next step.

Create Docker configuration

This file is optional but it will not add the generated directories into the docker context while you build the docker images

.dockerignore

myv
public

As you will see, I like to follow the convention of keeping the docker files inside the docker directory, even if I have one or mode docker images per project. This helps me to have the projects a little bit more structured and clean.

./docker/flask/Dockerfile

Let's create the dockerfile for the flask application. The installation of nodejs here is necessary only for the kubernetes use case which will be later.

FROM python:3.9 as base

COPY requirements.txt /requirements.txt

RUN pip install --upgrade pip \
&& pip install -r /requirements.txt


FROM base

COPY . /app/

RUN cp /usr/share/zoneinfo/Europe/Berlin /etc/localtime \
&& apt-get update \
&& apt-get install -y curl gcc g++ make \
&& curl -fsSL https://deb.nodesource.com/setup_16.x | bash - \
&& apt-get install -y nodejs

WORKDIR /app

CMD ["gunicorn", "--workers=2", "--chdir=.", "--bind", "0.0.0.0:5000", "--access-logfile=-", "--error-logfile=-", "app:app"]

./docker/nginx/Dockerfile

This is the dockerfile for the nginx container

FROM node:16 as base

COPY . /app

WORKDIR /app

RUN npm install --no-interaction
RUN npm run build


FROM nginx

COPY --from=base /app/public /app/public

COPY docker/nginx/proxy.conf /etc/nginx/conf.d/default.conf

./docker/nginx/proxy.conf

This is the nginx configuration for our application

server {
    listen 80;

    server_name _;

    location ~ \.(css|js|jpg|png|jpeg|webp|gif|svg) {
        root /app/public;
    }

    location / {
        proxy_set_header Host $host ;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto: http;

        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";

        proxy_pass http://flask-app:5000;
        proxy_read_timeout 10;
    }
}

./docker-compose.yml

Here you configure your flask and nginx containers to work together and serve your application in the browser

version: "3"
services:
  flask-app:
    build:
      dockerfile: docker/flask/Dockerfile
      context: .
    ports:
      - 5000
    volumes:
      - ./:/app
      - ./public:/app/public

  flask-nginx:
    image: nginx
    volumes:
      - ./docker/nginx/proxy.conf:/etc/nginx/conf.d/default.conf
      - ./public:/app/public
    ports:
      - 80:80

Well, in this point, if you still have flask application running, press CTRL + C to stop it.

You should have docker and docker-compose installed on your computer already. If not, install them before going further.

Run the following command to build and start the docker containers:

docker-compose up

If there is any error and you need to rebuild the docker images again, run the following command:

docker-compose up --build

When the command finishes, you should see logs from both containers. Open the following url in your browser, http://localhost.

And SUCCESS !!!. At this point you should have the application running with the images and styled text shown.

Create kubernetes configuration

Now, that we have the application running on local, let's configure kubernetes.

For tests, we'll use minikube

Start minikube

minikube start

Make sure you have the following plugins installed and enabled:

  • dns
  • ingress
  • registry
  • storage-provisioner
  • metrics-server

List addons:

minikube addons list

Enable plugins if they are not enabled already

minikube addons enable registry 
minikube addons enable metrics-server 
minikube addons enable ingress 
minikube addons enable ingress-dns
minikube addons enable storage-provisioner

Let's go further and create our kubernetes manifests:

./kube/deployment.yaml

This is the deployment manifest where you configure the pods that will run the application. In this setup, we'll create a pod with two containers (flask and nginx) and one initcontainer that will generate the fils in the public directory which will be defined as a shared volume between the containers.

apiVersion: apps/v1
kind: Deployment
metadata:
  name: flask
  labels:
    app: flask
spec:
  replicas: 2
  progressDeadlineSeconds: 120
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 1
  selector:
    matchLabels:
      app: flask
  template:
    metadata:
      name: flask
      labels:
        app: flask
    spec:
      restartPolicy: Always
      containers:
        - name: flask
          image: localhost:5000/flask:__VERSION__
          imagePullPolicy: Always
          ports:
            - containerPort: 5000
          envFrom:
            - configMapRef:
                name: flask
          volumeMounts:
            - mountPath: /app/public
              name: public-dir
          livenessProbe:
            exec:
              command:
                - cat
                - /app/public/ready
            initialDelaySeconds: 5
            periodSeconds: 5
          readinessProbe:
            exec:
              command:
                - cat
                - /app/public/ready
            initialDelaySeconds: 5
            periodSeconds: 5
        - name: nginx
          image: nginx
          imagePullPolicy: Always
          ports:
            - containerPort: 80
          volumeMounts:
            - mountPath: /etc/nginx/conf.d
              name: nginx-config
            - mountPath: /app/public
              name: public-dir
          livenessProbe:
            exec:
              command:
                - cat
                - /app/public/ready
            initialDelaySeconds: 5
            periodSeconds: 5
          readinessProbe:
            exec:
              command:
                - cat
                - /app/public/ready
            initialDelaySeconds: 5
            periodSeconds: 5
      initContainers:
        - name: npm
          image: localhost:5000/flask:__VERSION__
          imagePullPolicy: Always
          workingDir: /app
          command:
            - bash
          args:
            - build.sh
          volumeMounts:
            - mountPath: /app/public
              name: public-dir
      volumes:
        - name: nginx-config
          configMap:
            name: flask-nginx
        - name: public-dir
          emptyDir: {}

./kube/config-map.yaml

We create two configurations maps. One for the flask application and one for the nginx container. I think you have already noticed that in the deployment file, we don't use the a custom nginx container. We could and that would have been easier, but let's do it like this so we don't create a docker image with static files.

apiVersion: v1
kind: ConfigMap
metadata:
  name: flask
  namespace: default
data:
  FLASK_PORT: "5000"
  FLASK_DEBUG: "0"
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: flask-nginx
  namespace: default
data:
  default.conf: |
    server {
        listen 80;

        server_name _;

        location ~ \.(css|js|jpg|png|jpeg|webp|gif|svg) {
            root /app/public;
        }

        location / {
            proxy_set_header Host $host ;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-Proto: http;

            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection "upgrade";

            proxy_pass http://127.0.0.1:5000;
            proxy_read_timeout 10;
        }
    }

./kube/ingress.yaml

The ingress configuration will be used to access our application in the browser under the http://dev.k8s/ url

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: flask
  namespace: default
spec:
  rules:
    - host: dev.k8s
      http:
        paths:
          - path: /
            pathType: ImplementationSpecific
            backend:
              service:
                name: flask
                port:
                  number: 80

For this run the following command in your terminal to add the minikube ip to your /etc/hosts:

sudo bash -c "echo \"$(minikube ip) dev.k8s\" >> /etc/hosts"

Then, if you run cat /etc/hosts you should see on the last line your minikube ip and dev.k8s

./kube/service.yaml

We'll create a service of type ClusterIP for our application that will connect to the port 80 on the nginx container in the deployment pod.

apiVersion: v1
kind: Service
metadata:
  name: flask
  namespace: default
spec:
  type: ClusterIP
  selector:
    app: flask
  ports:
    - port: 80
      targetPort: 80

For a better understanding of what happens here, when you make a request to the url http://dev.k8s/, the browser will make a request to the minikube instance and will match the ingress with the url defined earlier which will connect to the flask service which will connect to the nginx container in the running pod of the flask application.

For the requests to the css, js or images files, nginx will directly deliver them, but for other types of requests, the nginx will proxy to the python application.

./Makefile

We'll use this makefile to simulate a real deployment to a real kubernetes cluster

.PHONY: run up svc

version = $(shell date +%H%M%S)

run:
	python3 app.py

up: dependencies
up:
	docker build -f docker/flask/Dockerfile -t localhost:5000/flask:$(version) .
	docker push localhost:5000/flask:$(version)
	cat kube/deployment.yaml | sed "s/__VERSION__/$(version)/g" | kubectl apply -f -

svc: dependencies
svc:
	cat kube/deployment.yaml | sed "s/__VERSION__/214714/g" | kubectl apply -f -

dependencies:
	kubectl apply -f kube/config-map.yaml
	kubectl apply -f kube/service.yaml
	kubectl apply -f kube/ingress.yaml

clean:
	docker images | grep localhost | awk '{print $$3}' | uniq | xargs docker rmi -f
Please note that in makefiles, you MUST use tabs for the commands bellow every stage and not spaces

./build.sh

This file is used by the init container to generate the content of the public directory

#!/bin/bash

npm install --no-interaction
npm run build

touch public/ready

At this point, if you open the url http://dev.k8s/ in your browser, you should see a 404 Page Not Found error, which is fine.

Our setup, will use a private/local registry for the docker images and that is running on the minikube virtual machine.

Let's stop and delete the local docker containers that we used earlier:

docker stop $(docker ps -q)
docker rm $(docker ps -q)

Run the following command to connect to the minikube docker

eval $(minikube docker-env)

To make sure you are using the docker from minikube, run docker images and you should see k8s docker images listed.

Run the following command to build the docker image, push it to the registry and deploy all resources to minikube kubernetes:

make up

While the process from makefile is running, open a new terminal window and run the following command:

watch -n 1 kubectl get po -n default --show-kind

The output of the command will be like this after the deployment file is applied to kubernetes:

NAME                       READY   STATUS     RESTARTS   AGE   IP           NODE       NOMINATED NODE   READINESS GATES
pod/flask-9f5f88c8-l4jpp   0/2     Init:0/1   0          12s   172.17.0.7   minikube   <none>           <none>
pod/flask-9f5f88c8-zfc2h   0/2     Init:0/1   0          12s   172.17.0.8   minikube   <none>           <none>

If this is a new minikube installation, you should not have any pod running in the default namespace. Wait until make command finishes and your pods will appear there. It might take a few minutes longer to build everything and deploy.

If you open the url http://dev.k8s/ in your browser, you might see a 503 error page. This is correct at this point since the config-map, service and ingress were deployed but not the deployment with the pods. Once the make command finishes, the pods should appear in the list and soon you should see the application running in your browser.

When the initialization has finished and the pods are running, you should see an output similar to this one:

NAME                       READY   STATUS    RESTARTS   AGE    IP           NODE       NOMINATED NODE   READINESS GATES
pod/flask-9f5f88c8-l4jpp   2/2     Running   0          119s   172.17.0.7   minikube   <none>           <none>
pod/flask-9f5f88c8-zfc2h   2/2     Running   0          119s   172.17.0.8   minikube   <none>           <none>
Note that instead of 9f5f88c8 and l4jpp and zfc2h you will have different values

If the application is running, and you can see the image three times and the colored text, then CONGRATULATIONS !*. You have completed the task and your flask application is running on kubernetes

Cleanup

To delete all the resources you have created, run the following commands:

# delete resources from minikube
kubectl delete configmap/flask-nginx configmap/flask service/flask ingress.networking.k8s.io/flask deployment.apps/flask

# disconnect from minikube docker
eval $(minikube docker-env --unset)

# delete minikube cluster
minikube delete

# delete docker images created for docker-compose
docker images | grep flask | awk '{print $3}' | uniq | xargs docker rmi -f