Write your first Kubernetes charm for a Flask app¶

Imagine you have a Flask application backed up by a database such as PostgreSQL and need to deploy it. In a traditional setup, this can be quite a challenge, but with Charmcraft you’ll find yourself packaging and deploying your Flask application in no time.

In this tutorial we will build a Kubernetes charm for a Flask application using Charmcraft, so we can have a Flask application up and running with Juju. Let’s get started!

This tutorial should take 90 minutes for you to complete.

Note

If you’re new to the charming world: Flask applications are specifically supported with a template to quickly generate a rock (i.e., a special kind of OCI-compliant container image) and a matching template to quickly generate a charm (i.e., a software operator for cloud operations done with the Juju orchestration engine). The result is Flask applications that can be easily deployed, configured, scaled, integrated, etc., on any Kubernetes cluster.

What you’ll need¶

A local system, e.g., a laptop, with amd64 or arm64 architecture which has sufficient resources to launch a virtual machine with 4 CPUs, 4 GB RAM, and a 50 GB disk.
Familiarity with Linux.

What you’ll do¶

Create a Flask application. Use that to create a rock with rockcraft. Use that to create a charm with charmcraft. Use that to test, deploy, configure, etc., your Flask application on a local Kubernetes cloud, microk8s, with juju. All of that multiple times, mimicking a real development process.

Important

Should you get stuck or notice issues, please get in touch on Matrix or Discourse

Set things up¶

Warning

This tutorial requires version 3.2.0 or later of Charmcraft. Check the version of Charmcraft using charmcraft --version If you have an older version of Charmcraft installed, use sudo snap refresh charmcraft --channel latest/edge to get the latest edge version of Charmcraft.

First, install Multipass.

Create the Flask application¶

Let’s start by creating the “Hello, world” Flask application that will be used for this tutorial.

Create a requirements.txt file using touch requirements.txt. Then, open the file in a text editor using nano requirements.txt, copy the following text into it and then save the file:

requirements.txt¶

Flask
psycopg2-binary

Note

The psycopg2-binary package is needed so the Flask application can connect to PostgreSQL.

Install the packages:

pip install -r requirements.txt

In the same directory, create a file called app.py. Then copy and save the following code into the file:

# initial hello world Flask app

import flask

app = flask.Flask(__name__)

@app.route("/")
def index():
    return "Hello, world!\n"

if __name__ == "__main__":
    app.run()

Run the Flask application locally¶

Now that we have a virtual environment with all the dependencies, let’s run the Flask application to verify that it works:

flask run -p 8000

Test the Flask application by using curl to send a request to the root endpoint. You will need a new terminal for this; use multipass shell charm-dev to open a new terminal in Multipass:

curl localhost:8000

The Flask application should respond with Hello, world!.

The Flask application looks good, so we can stop it for now from the original terminal using Ctrl + C.

Pack the Flask application into a rock¶

First, we’ll need a rockcraft.yaml file. Using the flask-framework profile, Rockcraft will automate the creation of rockcraft.yaml and tailor the file for a Flask application. From the /flask-hello-world directory, initialize the rock:

rockcraft init --profile flask-framework

The rockcraft.yaml file will automatically be created and set the name based on your working directory.

Check out the contents of rockcraft.yaml:

cat rockcraft.yaml

The top of the file should look similar to the following snippet:

Verify that the name is flask-hello-world.

Ensure that platforms includes the architecture of your host. Check the architecture of your system:

dpkg --print-architecture

If your host uses the ARM architecture, open rockcraft.yaml in a text editor and include arm64 under platforms.

Now let’s pack the rock:

rockcraft pack

Depending on your system and network, this step can take several minutes to finish.

Once Rockcraft has finished packing the Flask rock, the terminal will respond with something similar to Packed flask-hello-world_0.1_amd64.rock.

Note

If you are not on the amd64 platform, the name of the .rock file will be different for you.

The rock needs to be copied to the MicroK8s registry, which stores OCI archives so they can be downloaded and deployed in the Kubernetes cluster. Copy the rock:

rockcraft.skopeo --insecure-policy copy --dest-tls-verify=false \
  oci-archive:flask-hello-world_0.1_$(dpkg --print-architecture).rock \
  docker://localhost:32000/flask-hello-world:0.1

Create the charm¶

From the /flask-hello-world directory, let’s create a new directory for the charm and change inside it:

mkdir charm
cd charm

Using the flask-framework profile, Charmcraft will automate the creation of the files needed for our charm, including a charmcraft.yaml, requirements.txt and source code for the charm. The source code contains the logic required to operate the Flask application.

Initialize a charm named flask-hello-world:

charmcraft init --profile flask-framework --name flask-hello-world

The files will automatically be created in your working directory. Let’s pack the charm:

charmcraft pack

Depending on your system and network, this step can take several minutes to finish.

Once Charmcraft has finished packing the charm, the terminal will respond with something similar to Packed flask-hello-world_ubuntu-24.04-amd64.charm.

Note

If you are not on the amd64 platform, the name of the .charm file will be different for you.

Deploy the Flask application¶

A Juju model is needed to handle Kubernetes resources while deploying the Flask application. Let’s create a new model:

juju add-model flask-hello-world

If you are not on a host with the amd64 architecture, you will need to include to include a constraint to the Juju model to specify your architecture.

Set the Juju model constraints with:

juju set-model-constraints -m flask-hello-world arch=$(dpkg --print-architecture)

Now let’s use the OCI image we previously uploaded to deploy the Flask application. Deploy using Juju by specifying the OCI image name with the --resource option:

juju deploy \
  ./flask-hello-world_ubuntu-22.04-$(dpkg --print-architecture).charm \
  flask-hello-world --resource \
  flask-app-image=localhost:32000/flask-hello-world:0.1

It will take a few minutes to deploy the Flask application. You can monitor its progress with:

juju status --watch 2s

It can take a couple of minutes for the app to finish the deployment. Once the status of the App has gone to active, you can stop watching using Ctrl + C.

Configure the Flask application¶

To demonstrate how to provide a configuration to the Flask application, we will make the greeting configurable. We will expect this configuration option to be available in the Flask app configuration under the keyword GREETING. Change back to the /flask-hello-world directory using cd .. and copy the following code into app.py:

# Flask app with a greeting configuration

import flask

app = flask.Flask(__name__)
app.config.from_prefixed_env()


@app.route("/")
def index():
    greeting = app.config.get("GREETING", "Hello, world!")
    return f"{greeting}\n"


if __name__ == "__main__":
    app.run()

Increment the version in rockcraft.yaml to 0.2 such that the top of the rockcraft.yaml file looks similar to the following:

name: flask-hello-world
# see https://documentation.ubuntu.com/rockcraft/en/1.6.0/explanation/bases/
# for more information about bases and using 'bare' bases for chiselled rocks
base: [email protected] # the base environment for this Flask application
version: '0.2' # just for humans. Semantic versioning is recommended
summary: A summary of your Flask application # 79 char long summary
description: |
    This is flask-hello-world's description. You have a paragraph or two to tell the
    most important story about it. Keep it under 100 words though,
    we live in tweetspace and your description wants to look good in the
    container registries out there.
# the platforms this rock should be built on and run on.
# you can check your architecture with `dpkg --print-architecture`
platforms:
    amd64:
    # arm64:
    # ppc64el:
    # s390x:

...

Let’s pack and upload the rock:

rockcraft pack
rockcraft.skopeo --insecure-policy copy --dest-tls-verify=false \
  oci-archive:flask-hello-world_0.2_$(dpkg --print-architecture).rock \
  docker://localhost:32000/flask-hello-world:0.2

Change back into the charm directory using cd charm.

The flask-framework Charmcraft extension supports adding configurations to charmcraft.yaml which will be passed as environment variables to the Flask application. Add the following to the end of the charmcraft.yaml file:

# configuration snippet for Flask application with a configuration

config:
  options:
    greeting:
      description: |
        The greeting to be returned by the Flask application.
      default: "Hello, world!"
      type: string

Note

Configuration options are automatically capitalized and - are replaced by _. A FLASK_ prefix will also be added as a namespace for app configurations.

We can now pack and deploy the new version of the Flask app:

charmcraft pack
juju refresh flask-hello-world \
  --path=./flask-hello-world_ubuntu-22.04-$(dpkg --print-architecture).charm \
  --resource flask-app-image=localhost:32000/flask-hello-world:0.2

After we wait for a bit monitoring juju status the application should go back to active again. Verify that the new configuration has been added using juju config flask-hello-world | grep -A 6 greeting: which should show the configuration option.

Using curl http://flask-hello-world --resolve flask-hello-world:80:127.0.0.1 shows that the response is still Hello, world! as expected.

Now let’s change the greeting:

juju config flask-hello-world greeting='Hi!'

After we wait for a moment for the app to be restarted, using curl http://flask-hello-world --resolve flask-hello-world:80:127.0.0.1 should now return the updated Hi! greeting.

Integrate with a database¶

Now let’s keep track of how many visitors your application has received. This will require integration with a database to keep the visitor count. This will require a few changes:

We will need to create a database migration that creates the visitors table.
We will need to keep track how many times the root endpoint has been called in the database.
We will need to add a new endpoint to retrieve the number of visitors from the database.

Let’s start with the database migration to create the required tables. The charm created by the flask-framework extension will execute the migrate.py script if it exists. This script should ensure that the database is initialized and ready to be used by the application. We will create a migrate.py file containing this logic.

Go back out to the /flask-hello-world directory using cd .., create the migrate.py file, open the file using a text editor and paste the following code into it:

# Adds database to Flask application

import os

import psycopg2


DATABASE_URI = os.environ["POSTGRESQL_DB_CONNECT_STRING"]


def migrate():
    with psycopg2.connect(DATABASE_URI) as conn, conn.cursor() as cur:
        cur.execute("""
            CREATE TABLE IF NOT EXISTS visitors (
                timestamp TIMESTAMP NOT NULL,
                user_agent TEXT NOT NULL
            );
        """)
        conn.commit()


if __name__ == "__main__":
    migrate()

Note

The charm will pass the Database connection string in the POSTGRESQL_DB_CONNECT_STRING environment variable once PostgreSQL has been integrated with the charm.

Increment the version in rockcraft.yaml to 0.3 such that the top of the rockcraft.yaml file looks similar to the following:

name: flask-hello-world
# see https://documentation.ubuntu.com/rockcraft/en/1.6.0/explanation/bases/
# for more information about bases and using 'bare' bases for chiselled rocks
base: [email protected] # the base environment for this Flask application
version: '0.3' # just for humans. Semantic versioning is recommended
summary: A summary of your Flask application # 79 char long summary
description: |
    This is flask-hello-world's description. You have a paragraph or two to tell the
    most important story about it. Keep it under 100 words though,
    we live in tweetspace and your description wants to look good in the
    container registries out there.
# the platforms this rock should be built on and run on.
# you can check your architecture with `dpkg --print-architecture`
platforms:
    amd64:
    # arm64:
    # ppc64el:
    # s390x:

...

The app code also needs to be updated to keep track of the number of visitors and to include a new endpoint to retrieve the number of visitors to the app. Open app.py in a text editor and replace its contents with the following code:

visitors_app.py

# Flask application that keeps track of visitors using a database

import datetime
import os

import flask
import psycopg2

app = flask.Flask(__name__)
app.config.from_prefixed_env()

DATABASE_URI = os.environ["POSTGRESQL_DB_CONNECT_STRING"]


@app.route("/")
def index():
    with psycopg2.connect(DATABASE_URI) as conn, conn.cursor() as cur:
        user_agent = flask.request.headers.get('User-Agent')
        timestamp = datetime.datetime.now()

        cur.execute(
            "INSERT INTO visitors (timestamp, user_agent) VALUES (%s, %s)",
            (timestamp, user_agent)
        )
        conn.commit()


    greeting = app.config.get("GREETING", "Hello, world!")
    return f"{greeting}\n"


@app.route("/visitors")
def visitors():
    with psycopg2.connect(DATABASE_URI) as conn, conn.cursor() as cur:
        cur.execute("SELECT COUNT(*) FROM visitors")
        total_visitors = cur.fetchone()[0]

    return f"{total_visitors}\n"


if __name__ == "__main__":
    app.run()

Let’s pack and upload the rock:

rockcraft pack
rockcraft.skopeo --insecure-policy copy --dest-tls-verify=false \
  oci-archive:flask-hello-world_0.3_$(dpkg --print-architecture).rock \
  docker://localhost:32000/flask-hello-world:0.3

Change back into the charm directory using cd charm.

The Flask app now requires a database which needs to be declared in the charmcraft.yaml file. Open charmcraft.yaml in a text editor and add the following section to the end of the file:

# requires snippet for Flask application with a database

requires:
  postgresql:
    interface: postgresql_client
    optional: false

We can now pack and deploy the new version of the Flask app:

charmcraft pack
juju refresh flask-hello-world \
  --path=./flask-hello-world_ubuntu-22.04-$(dpkg --print-architecture).charm \
  --resource flask-app-image=localhost:32000/flask-hello-world:0.3

Now let’s deploy PostgreSQL and integrate it with the Flask application:

juju deploy postgresql-k8s --trust
juju integrate flask-hello-world postgresql-k8s

Wait for juju status to show that the App is active again. Running curl http://flask-hello-world --resolve flask-hello-world:80:127.0.0.1 should still return the Hi! greeting.

To check the total visitors, use curl http://flask-hello-world/visitors --resolve flask-hello-world:80:127.0.0.1 which should return 1 after the previous request to the root endpoint, This should be incremented each time the root endpoint is requested. If we repeat this process, the output should be as follows:

user@host:~$ curl http://flask-hello-world --resolve flask-hello-world:80:127.0.0.1

Hi!

user@host:~$ curl http://flask-hello-world/visitors --resolve flask-hello-world:80:127.0.0.1

2

Tear things down¶

We’ve reached the end of this tutorial. We went through the entire development process, including:

Creating a Flask application
Deploying the application locally
Packaging the application using Rockcraft
Building the application with Ops code using Charmcraft
Deplyoing the application using Juju
Exposing the application using an ingress
Configuring the application
Integrating the application with a database

If you’d like to reset your working environment, you can run the following in the rock directory /flask-hello-world for the tutorial:

charmcraft clean
# Back out to main directory for cleanup
cd ..
rockcraft clean
# exit and delete the virtual environment
deactivate
rm -rf charm .venv __pycache__
# delete all the files created during the tutorial
rm flask-hello-world_0.1_$(dpkg --print-architecture).rock \
  flask-hello-world_0.2_$(dpkg --print-architecture).rock \
  flask-hello-world_0.3_$(dpkg --print-architecture).rock \
  rockcraft.yaml app.py requirements.txt migrate.py
# Remove the juju model
juju destroy-model flask-hello-world --destroy-storage --no-prompt --force

You can also clean up your Multipass instance. Start by exiting it:

exit

And then you can proceed with its deletion:

multipass delete charm-dev
multipass purge

Next steps¶

By the end of this tutorial you will have built a charm and evolved it in a number of typical ways. But there is a lot more to explore:

If you are wondering…	Visit…
“How do I…?”	How-to guides, Ops \| How-to guides
“How do I debug?”	Charm debugging tools
“How do I get in touch?”	Matrix channel
“What is…?”	Reference, Ops \| Reference, Juju \| Reference
“Why…?”, “So what?”	Ops \| Explanation, Juju \| Explanation