DEV Community: Deon Pillsbury

[Boost]

Deon Pillsbury — Mon, 13 Jan 2025 16:10:06 +0000

"Making a Todo API with FastAPI and MongoDB"

zpillsbury ・ Jan 13

AItoMobile - Build an AI Powered Mobile App ✨📱🚀

Deon Pillsbury — Sun, 17 Mar 2024 19:54:18 +0000

Generative AI continues to be a hot topic in the tech world with very rapid developments as the technology evolves. Google has been at the forefront of AI for a long time and researchers at Google developed the technology behind the latest Generative AI models which they outlined in their “Attention Is All You Need” paper. Over the last year Google has developed and released multiple models and services such as Bard, Palm and their latest offering Gemini and its open source variant Gemma. Gemini has a generous Free Tier of 60 requests per minute (Note they will retain your input data to train their models) which is useful for new apps. Many people utilize their mobile devices for a lot of their computing needs these days so we will explore how to incorporate the Gemini API into an Expo React Native mobile chat app.

⭐️ The complete source code referenced in this guide is available on GitHub https://github.com/dpills/aitomobile

Before getting started, go and generate a Gemini API Key in Google AI Studio.

Backend

We need a backend service to make the calls to the Gemini API so we can use a FastAPI WebSocket setup to facilitate this. Install the FastAPI dependencies along with the Google Generative AI library.

📝 pyproject.toml

[tool.poetry]
name = "aitomobile"
version = "0.1.0"
description = ""
authors = ["dpills"]

[tool.poetry.dependencies]
python = "^3.12"
fastapi = "^0.110.0"
uvicorn = { extras = ["standard"], version = "^0.28.0" }
python-dotenv = "^1.0.1"
google-generativeai = "0.4.1"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Add your generated Gemini API Key to a .env file in the project folder.

📝 .env

GOOGLE_API_KEY=XXXXXXXXXXXXX

Now setup the FastAPI WebSocket server to accept messages, send them to the Gemini API and stream the response back over the WebSocket. You can update the prompt as needed and test different prompts to see what gives you the best output. Reference the Prompt Strategies section of the Google AI docs for additional info.

📝 main.py

import json
import os
import uuid
from typing import AsyncGenerator, NoReturn

import google.generativeai as genai
import uvicorn
from dotenv import load_dotenv
from fastapi import FastAPI, WebSocket

load_dotenv()

genai.configure(api_key=os.getenv("GOOGLE_API_KEY"))
model = genai.GenerativeModel("gemini-pro")

app = FastAPI()

PROMPT = """
You are a helpful assistant, skilled in explaining complex concepts in simple terms.

{message}
"""  # noqa: E501

async def get_ai_response(message: str) -> AsyncGenerator[str, None]:
    """
    Gemini Response
    """
    response = await model.generate_content_async(
        PROMPT.format(message=message), stream=True
    )

    msg_id = str(uuid.uuid4())
    all_text = ""
    async for chunk in response:
        if chunk.candidates:
            for part in chunk.candidates[0].content.parts:
                all_text += part.text
                yield json.dumps({"id": msg_id, "text": all_text})

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket) -> NoReturn:
    """
    Websocket for AI responses
    """
    await websocket.accept()
    while True:
        message = await websocket.receive_text()
        async for text in get_ai_response(message):
            await websocket.send_text(text)

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Thats all there is to it! now start the server so we can connect to it from our app.

$ python3 main.py

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [65258] using WatchFiles
INFO:     Started server process [65260]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

Mobile App

As mentioned we will use Expo to create our React Native mobile app and you can use the create-expo-app utility to bootstrap a Typescript version.

$ yarn dlx create-expo-app -t expo-template-blank-typescript

✔ What is your app named? … AItoMobile
✔ Downloaded and extracted project files.
> yarn install

✅ Your project is ready!

To run your project, navigate to the directory and run one of the following yarn commands.

- cd AItoMobile
- yarn android
- yarn ios
- yarn web

Install these dependencies so we can properly render our chat interface, using expo install will make sure versions compatible with the current expo version will be used.

$ npx expo install react-native-gifted-chat react-native-markdown-display luxon @react-native-async-storage/async-storage

Update your App.tsx file to a basic chat setup which sets up the WebSocket connection to our backend persists previous messages and renders the Markdown responses.

import AsyncStorage from "@react-native-async-storage/async-storage"
import { StatusBar } from "expo-status-bar"
import { DateTime } from "luxon"
import React, { useEffect, useState } from "react"
import { Text, TextStyle, View, ViewStyle } from "react-native"
import { GiftedChat, IMessage } from "react-native-gifted-chat"
import Markdown from "react-native-markdown-display"

export default function App() {
  const [messages, setMessages] = useState<IMessage[]>([])
  const [loading, setLoading] = useState(false)
  const [ws, setWs] = useState<WebSocket>()

  useEffect(() => {
    const newWs = new WebSocket("ws://localhost:8000/ws")

    newWs.onmessage = (event) => {
      const data = JSON.parse(event.data)
      setLoading(false)
      setMessages((previousMessages) =>
        GiftedChat.append(
          previousMessages.filter((m) => m._id !== data.id),
          [
            {
              _id: data.id,
              text: data.text,
              createdAt: new Date(),
              user: { _id: 1 },
              system: true,
            },
          ],
        ),
      )
    }

    async function getMessages() {
      const messageData = await AsyncStorage.getItem("messages")
      const messages: IMessage[] | null = messageData ? JSON.parse(messageData) : null

      setMessages(
        messages
          ? messages
          : [
              {
                _id: 1,
                text: "How can I help?",
                createdAt: new Date(),
                user: { _id: 1 },
                system: true,
              },
            ],
      )
    }

    getMessages()
    setWs(newWs)
    return () => {
      newWs.close()
    }
  }, [])

  useEffect(() => {
    async function saveMessages() {
      try {
        await AsyncStorage.setItem("messages", JSON.stringify(messages))
      } catch (e) {
        console.log(`Failed to save messages: ${e}`)
      }
    }

    saveMessages()
  }, [messages])

  return (
    <View style={$container}>
      <StatusBar style="auto" />
      <GiftedChat
        placeholder="How can I help?"
        messages={messages}
        onSend={(messages) => {
          if (ws && messages && messages.length > 0) {
            const message = messages[0]
            setMessages((previousMessages) => GiftedChat.append(previousMessages, messages))
            setLoading(true)
            ws.send(message.text)
          }
        }}
        user={{ _id: 2 }}
        renderAvatar={null}
        isTyping={loading}
        renderSystemMessage={(props) =>
          props.currentMessage?.text ? (
            <View style={$msgContainer}>
              <View style={$wrapper}>
                <Markdown
                  style={{
                    body: {
                      fontSize: 16,
                    },
                  }}
                >
                  {props.currentMessage?.text}
                </Markdown>
                {props.currentMessage?.createdAt ? (
                  <Text style={$msgTime}>
                    {DateTime.fromJSDate(new Date(props.currentMessage?.createdAt)).toFormat(
                      "h:mm a",
                    )}
                  </Text>
                ) : null}
              </View>
            </View>
          ) : null
        }
      />
    </View>
  )
}

const $container: ViewStyle = {
  flex: 1,
  paddingBottom: 20,
  paddingTop: 60,
}

const $msgContainer: ViewStyle = {
  flex: 1,
  marginTop: 5,
  marginBottom: 10,
  marginHorizontal: 10,
}

const $wrapper: ViewStyle = {
  borderRadius: 15,
  backgroundColor: "#f0f0f0",
  marginRight: 25,
  paddingHorizontal: 10,
  paddingBottom: 5,
  minHeight: 20,
  justifyContent: "flex-start",
}

const $msgTime: TextStyle = {
  fontSize: 10,
  marginTop: 5,
}

Make sure you have an IOS or Android simulator installed with XCode or Android Studio and start the mobile app dev server.

$ yarn ios

Starting Metro Bundler
› Opening exp://192.168.50.102:8081 on iPhone 15 Pro
...
› Metro waiting on exp://192.168.50.102:8081
› Scan the QR code above with Expo Go (Android) or the Camera app (iOS)

› Using Expo Go
› Press s │ switch to development build

› Press a │ open Android
› Press i │ open iOS simulator
› Press w │ open web

› Press j │ open debugger
› Press r │ reload app
› Press m │ toggle menu
› Press o │ open project code in your editor

› Press ? │ show all commands

Logs for your project will appear below. Press Ctrl+C to exit.
iOS Bundled 1375ms (node_modules/expo/AppEntry.js)

You should now see the chat interface in Expo Go and can test out a question!

The response message will stream the update and our backend development server logs should show the client connecting, the question asked and the chunks of the response being sent back.

DEBUG:    = connection is CONNECTING
DEBUG:    < GET /ws HTTP/1.1
DEBUG:    < host: localhost:8000
DEBUG:    < sec-websocket-version: 13
DEBUG:    < upgrade: websocket
DEBUG:    < sec-websocket-key: UzwxQuxXmRR1K/lT6sPYxw==
DEBUG:    < connection: Upgrade
DEBUG:    < origin: http://localhost:8000

INFO:     ('127.0.0.1', 64657) - "WebSocket /ws" [accepted]
DEBUG:    > HTTP/1.1 101 Switching Protocols
DEBUG:    > Upgrade: websocket
DEBUG:    > Connection: Upgrade
DEBUG:    > Sec-WebSocket-Accept: uHRvWGNZ/CCWmy80rcxRax6Fipc=
DEBUG:    > date: Sun, 17 Mar 2024 19:02:52 GMT
DEBUG:    > server: uvicorn

INFO:     connection open
DEBUG:    = connection is OPEN
DEBUG:    < TEXT 'What is the meaning of life?' [28 bytes]
DEBUG:    > TEXT '{"id": "db926495-f85d-40cf-a901-bf92cb953ee7", ...ely among individuals"}' [153 bytes]
DEBUG:    > TEXT '{"id": "db926495-f85d-40cf-a901-bf92cb953ee7", ...r mission assigned by"}' [311 bytes]
DEBUG:    % sending keepalive ping
DEBUG:    > PING 81 e2 c2 99 [binary, 4 bytes]
DEBUG:    < PONG 81 e2 c2 99 [binary, 4 bytes]
DEBUG:    % received keepalive pong
DEBUG:    > TEXT '{"id": "db926495-f85d-40cf-a901-bf92cb953ee7", ...zes the importance of"}' [613 bytes]
DEBUG:    > TEXT '{"id": "db926495-f85d-40cf-a901-bf92cb953ee7", ...d solace in embracing"}' [1249 bytes]
DEBUG:    > TEXT '{"id": "db926495-f85d-40cf-a901-bf92cb953ee7", ...at shape their lives."}' [1908 bytes]
DEBUG:    % sending keepalive ping

This is a small local example but I hope it shows you how simple it can be to add an AI powered chat to a cross-platform mobile application and gives you some basic building blocks to create a great experience for your users! 😊

Create a streaming AI assistant with ChatGPT, FastAPI, WebSockets and React ✨🤖🚀

Deon Pillsbury — Sun, 12 Nov 2023 19:54:29 +0000

A Generative Pre-Trained Transformer (GPT) is a type of Large Language Model (LLM) and they are the hot topic in the technology world this year with many companies scrambling to add this technology to their products. Creating and training these large models can be a very complex, time consuming and expensive. You may think that you cannot use this technology since it is so complex and expensive but companies like OpenAI have done a ton of work to create useful models and setup platforms exposing APIs to use them. If you have ever used an API where you send some data in, it does some magic behind the scenes and you get some data to use in a response, then you can integrate this cutting edge technology into your application. Let’s take a look at how we can setup a Full stack web app which lets us ask questions sent to OpenAI and stream the response.

⭐️ The complete source code referenced in this guide is available on GitHub
https://github.com/dpills/ai-assistant

In order to use the OpenAI API you will need to sign up for an account and then Generate an API Key then add this to a .env file in your new project folder.

📝 .env

OPENAI_API_KEY=sk-YWUedpcl1xiGvGiD4xTwT3TlbkFJx9Sgnt8s0QYNxxxxxxxx

Install the API dependencies along with the openai python library.

📝 pyproject.toml

[tool.poetry]
name = "ai-assistant"
version = "0.1.0"
description = ""
authors = ["dpills"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
openai = "^1.2.3"
python-dotenv = "^1.0.0"
fastapi = "^0.104.1"
uvicorn = { extras = ["standard"], version = "^0.24.0.post1" }
websockets = "^12.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

$ poetry install
...
  • Installing fastapi (0.104.1)
  • Installing openai (1.2.3)
...

Create a python file and import the OpenAI library which will use the OPENAI_API_KEY from the environment variables to authenticate. Within the options set stream to true and use an asynchronous generator to stream the response chunks as they are returned. We are using the GPT-3.5 Turbo model which is available in the free-trial but you can swap this out for a newer model such as GPT-4 if you have access to it.

📝 main.py

from typing import AsyncGenerator

from dotenv import load_dotenv
from openai import AsyncOpenAI

load_dotenv()

client = AsyncOpenAI()

async def get_ai_response(message: str) -> AsyncGenerator[str, None]:
    """
    OpenAI Response
    """
    response = await client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {
                "role": "system",
                "content": (
                    "You are a helpful assistant, skilled in explaining "
                    "complex concepts in simple terms."
                ),
            },
            {
                "role": "user",
                "content": message,
            },
        ],
        stream=True,
    )

    all_content = ""
    async for chunk in response:
        content = chunk.choices[0].delta.content
        if content:
            all_content += content
            yield all_content

That is the basic setup for adding ChatGPT to your application, which is pretty simple! 😃

Now lets add a WebSocket API endpoint with the FastAPI WebSocket support in order to have a persistent bi-directional connection where we can stream the response from ChatGPT to our web app in real-time.

📝 main.py

from typing import AsyncGenerator, NoReturn

import uvicorn
from dotenv import load_dotenv
from fastapi import FastAPI, WebSocket
from openai import AsyncOpenAI

load_dotenv()

app = FastAPI()
client = AsyncOpenAI()

...

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket) -> NoReturn:
    """
    Websocket for AI responses
    """
    await websocket.accept()
    while True:
        message = await websocket.receive_text()
        async for text in get_ai_response(message):
            await websocket.send_text(text)

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Finally, for this simple example we can just have the API serve our Web App with a index.html file on the root route.

📝 main.py

from typing import AsyncGenerator, NoReturn

import uvicorn
from dotenv import load_dotenv
from fastapi import FastAPI, WebSocket
from fastapi.responses import HTMLResponse
from openai import AsyncOpenAI

load_dotenv()

app = FastAPI()
client = AsyncOpenAI()

with open("index.html") as f:
    html = f.read()

async def get_ai_response(message: str) -> AsyncGenerator[str, None]:
    """
    OpenAI Response
    """
    response = await client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[
            {
                "role": "system",
                "content": (
                    "You are a helpful assistant, skilled in explaining "
                    "complex concepts in simple terms."
                ),
            },
            {
                "role": "user",
                "content": message,
            },
        ],
        stream=True,
    )

    all_content = ""
    async for chunk in response:
        content = chunk.choices[0].delta.content
        if content:
            all_content += content
            yield all_content

@app.get("/")
async def web_app() -> HTMLResponse:
    """
    Web App
    """
    return HTMLResponse(html)

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket) -> NoReturn:
    """
    Websocket for AI responses
    """
    await websocket.accept()
    while True:
        message = await websocket.receive_text()
        async for text in get_ai_response(message):
            await websocket.send_text(text)

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Now create the index.html file using the CDN development version of React, transpiled with the standalone Babel version and the React Material UI library. The app connects to the web socket and submits new questions to the WebSocket API which then streams the response as it is generated and renders the markdown.

📝 index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <meta charset="utf-8" />
    <title>AI Assistant 🤓</title>
    <meta name="viewport" content="initial-scale=1, width=device-width" />
    <script src="https://unpkg.com/react@latest/umd/react.development.js" crossorigin="anonymous"></script>
    <script src="https://unpkg.com/react-dom@latest/umd/react-dom.development.js"></script>
    <script src="https://unpkg.com/@mui/material@latest/umd/material-ui.development.js"
        crossorigin="anonymous"></script>
    <script src="https://unpkg.com/@babel/standalone@latest/babel.min.js" crossorigin="anonymous"></script>
    <script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
    <link rel="preconnect" href="https://fonts.googleapis.com" />
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
    <link rel="stylesheet"
        href="https://fonts.googleapis.com/css2?family=Roboto:wght@300;400;500;600;700&display=swap" />
    <link rel="stylesheet" href="https://fonts.googleapis.com/icon?family=Material+Icons" />
</head>

<body>
    <div id="root"></div>
    <script type="text/babel">
        const {
            colors,
            CssBaseline,
            ThemeProvider,
            Typography,
            TextField,
            Container,
            createTheme,
            Box,
            Skeleton,
        } = MaterialUI;

        const theme = createTheme({
            palette: {
                mode: 'dark'
            },
        });
        const WS = new WebSocket("ws://localhost:8000/ws");

        function App() {
            const [response, setResponse] = React.useState("");
            const [question, setQuestion] = React.useState("");
            const [loading, setLoading] = React.useState(false);

            React.useEffect(() => {
                WS.onmessage = (event) => {
                    setLoading(false);
                    setResponse(marked.parse(event.data));
                };
            }, []);

            return (
                <Container maxWidth="lg">
                    <Box sx={{ my: 4 }}>
                        <Typography variant="h4" component="h1" gutterBottom>
                            AI Assistant 🤓
                        </Typography>
                        <TextField
                            id="outlined-basic"
                            label="Ask me Anything"
                            variant="outlined"
                            style={{ width: '100%' }}
                            value={question}
                            disabled={loading}
                            onChange={e => {
                                setQuestion(e.target.value)
                            }}
                            onKeyUp={e => {
                                setLoading(false)
                                if (e.key === "Enter") {
                                    setResponse('')
                                    setLoading(true)
                                    WS.send(question);
                                }
                            }}
                        />
                    </Box>
                    {!response && loading && (<>
                        <Skeleton />
                        <Skeleton animation="wave" />
                        <Skeleton animation={false} /></>)}
                    {response && <Typography dangerouslySetInnerHTML={{ __html: response }} />}
                </Container>
            );
        }

        ReactDOM.createRoot(document.getElementById('root')).render(
            <ThemeProvider theme={theme}>
                <CssBaseline />
                <App />
            </ThemeProvider>,
        );
    </script>
</body>

</html>

Now we are ready to test it out! Run the python script which will start the API and serve the Web App.

$ python3 main.py
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
DEBUG:    = connection is CONNECTING
DEBUG:    < GET /ws HTTP/1.1
DEBUG:    < user-agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/119.0.0.0 Safari/537.36
DEBUG:    < upgrade: websocket
DEB**UG:    < origin: http://localhost:8000**
DEBUG:    < sec-websocket-version: 13
DEBUG:    < cookie: ajs_anonymous_id=57154c91-3ec5-4308-beaa-25a353f3ce66
DEBUG:    < sec-websocket-key: BQOnRY2biub2alMCN7ax+w==
DEBUG:    < sec-websocket-extensions: permessage-deflate; client_max_window_bits
INFO:     ('127.0.0.1', 54308) - "WebSocket /ws" [accepted]
DEBUG:    > date: Sun, 12 Nov 2023 19:00:20 GMT
DEBUG:    > server: uvicorn
INFO:     connection open
DEBUG:    = connection is OPEN

Navigate to http://localhost:8000, type in a question and hit enter.

Our question gets sent to the API through the WebSocket, then to OpenAI which generates a response which is streamed back through the WebSocket and rendered in the web app! 🎉

We can see that it takes around 30 seconds for ChatGPT to generate the full response which is a long time to wait for any application. But since we are taking advantage of streaming the response over the WebSocket it makes it feel very responsive. The response data is rendered on the screen faster than the average person can read it which leads to a better user experience. 🙂

I hope this shows you how easy it is to add AI enhancements to any application and gives you some basic building blocks to create a great experience for your users! 😊

Python Secure Password Management: Hashing and Encryption #️⃣🔐✨

Deon Pillsbury — Sun, 05 Nov 2023 15:55:50 +0000

When building an application that validates user passwords or needs to store tokens for future use it is critical to not store these values anywhere in clear text. If there is a security breach you want to be confident that your user’s data is protected. Hashing and Encryption are a couple of techniques which can be used to achieve this and we will take a look at how to implement these with Python.

Hashing

If your application needs to allow users to register an account and create a password then you need to store the values they singed up with in order to authenticate them later. Rather than storing the passwords in clear text, this is where a hashing algorithm should be used. Hashing algorithms are one-way functions which produce the same result for the input data but given the output data are nearly impossible to reverse. There are many types of hash algorithms but SHA-256 is a strong and NIST Approved modern algorithm that fits the need of most applications in terms of strength and performance.

Create a simple Python script file to take an input and generate the SHA-256 hash with the hashlib standard library.

📝 hash.py

import hashlib

password = input("Password: ")
password_hash = hashlib.sha256(password.encode("utf-8")).hexdigest()
print(f"Password Hash: {password_hash}")

Run the script and give it a few password inputs.

$ python3 hash.py
Password: test123
Password Hash: ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae

$ python3 hash.py
Password: test123
Password Hash: ecd71870d1963316a97e3ac3408c9835ad8cf0f3c1bc703527c30265534f75ae

$ python3 hash.py
Password: test1234
Password Hash: 937e8d5fbb48bd4949536cd65b8d35c426b80d2f830c5c308e2cdec422ae2244

We can see that the same input produces the same hash result but any change such as an additional character completely changes it. The resulting hash value is what you should store in your database to later validate the user’s password.

Encryption

Hashing is a great option when you do not need use the password value. For use cases where you need to use the actual password value such as storing a long term access token to authenticate on the user’s behalf to an external application then encryption is the best option. Encryption allows you to store the values securely and decrypt them in memory when you need to use them. Python has the cryptography library which includes Fernet Symmetric Encryption to achieve this. Symmetric encryption means we will have a secret key which we can store in our environment variables and use to decrypt stored values.

Install the cryptography and dotenv library.

$ poetry add cryptography python-dotenv
Using version ^41.0.5 for cryptography
Using version ^1.0.0 for python-dotenv

Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 4 installs, 0 updates, 0 removals

  • Installing pycparser (2.21)
  • Installing cffi (1.16.0)
  • Installing cryptography (41.0.5)
  • Installing python-dotenv (1.0.0)

Run an inline python command to generate the Fernet secret key.

$ python3 -c "from cryptography.fernet import Fernet; print(Fernet.generate_key())"
b'XvYvP_c4gBDLCLbjgz6Hc47ND_BcoMYt3Cz5pAKx1qQ='

Add this value to a .env file.

📝 .env

SECRET_KEY=XvYvP_c4gBDLCLbjgz6Hc47ND_BcoMYt3Cz5pAKx1qQ=

Create a new python script which will load our secret key from the environment variables, instantiate the Fernet client with the key, and allow a new password to be encrypted and stored in a simple text file or print out the decrypted value of an existing stored password.

📝 encrypt.py

import os
import sys

from cryptography.fernet import Fernet
from dotenv import load_dotenv

load_dotenv()

SECRET_KEY = os.getenv("SECRET_KEY")
assert SECRET_KEY
FERNET = Fernet(SECRET_KEY)

if len(sys.argv) > 1 and sys.argv[1] == "decrypt":
    with open("pw.txt") as f:
        stored_password = f.read()

    stored_dec_password = FERNET.decrypt(stored_password).decode()
    print(f"Decrypted Password: {stored_dec_password}")
else:
    new_password = input("New Password: ")
    new_enc_password = FERNET.encrypt(new_password.encode()).decode()

    with open("pw.txt", "w") as f:
        f.write(new_enc_password)

    print(f"Encrypted Password Stored: {new_enc_password}")

Test it out to validate it is working as expected.

$ python3 encrypt.py
New Password: Test123!!
Encrypted Password Stored: gAAAAABlR7V0TLTZMT_ZHEoPtqbW3B9LYgohYdUNG6Lukx9M2NSLgrFN6MUZKCNPP3Hq_KuuEPpJPPqqIktUkZTBh3qenKnQAA==

$ python3 encrypt.py decrypt
Decrypted Password: Test123!!

Awesome! 🎉 This shows the core concepts of encrypting/decrypting values and in a production environment rather than storing them in a simple text file you would just store and retrieve the values from a database.

I hope you have found this article helpful for building your next amazing (and secure) application! 😊

Master Helm, Chart the Kubernetes Seas 🌊🧭🏴‍☠️

Deon Pillsbury — Wed, 01 Nov 2023 21:45:23 +0000

Using Helm Charts
App with K8s configuration files
- Application setup
- Standard Kubernetes Configuration
App with a Helm Chart

Kubernetes is an amazing technology for managing large scale distributed applications. Its YAML configuration files make it easy to tune an application to fit your needs but Kubernetes has a lot of different objects and therefor a lot of different configuration files to maintain. For example, a production application could have a Deployment, Service, Secret, Config Map and Persistent Volume Claim for each of its components such as a Web App, API, Database, bot, etc. This is a lot of configuration files to maintain and they would be difficult to package if you are building an application which users need to download and run in their own environment. This is where Helm Charts come in to the picture, they group all of the configuration files needed to run an application into a single package called a Chart. Helm Charts templatize the configuration files, allow you to manage them with a global configuration and make it easy to publish your entire infrastructure as a single package. Lets take a look at some examples of using and building helm charts.

💡 Refer to Kubernetes Quick Start Guide ☁️⚡️🚀 for an in-depth Kubernetes tutorial

Using Helm Charts

Make sure you have Minikube setup and running and install Helm. After helm is installed we need to add a helm chart repository. Artifact Hub can be referenced to find helm repositories. A popular repository which offers production grade version of most of the popular open source applications is Bitnami.

Add the Bitnami repository and run the helm repo update command to make sure we have the latest versions.

$ helm repo add bitnami https://charts.bitnami.com/bitnami
"bitnami" has been added to your repositories

$ helm repo update
Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "bitnami" chart repository
Update Complete. ⎈Happy Helming!⎈

Search the configured helm repositories to look for applications we may want to use, in this case search for a Redis chart.

$ helm search repo redis
NAME                    CHART VERSION   APP VERSION DESCRIPTION
bitnami/redis           18.2.0          7.2.2       Redis(R) is an open source, advanced key-value ...
bitnami/redis-cluster   9.0.13          7.2.2       Redis(R) is an open source, scalable, distribut...

💡 The full details of helm charts can be referenced in their associated GitHub Repository.

Install the standard Redis chart.

$ helm install mydb bitnami/redis
NAME: mydb
LAST DEPLOYED: Mon Oct 30 07:43:01 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: redis
CHART VERSION: 18.2.0
APP VERSION: 7.2.2

** Please be patient while the chart is being deployed **

Redis&reg; can be accessed on the following DNS names from within your cluster:

    mydb-redis-master.default.svc.cluster.local for read/write operations (port 6379)
    mydb-redis-replicas.default.svc.cluster.local for read-only operations (port 6379)

To get your password run:

    export REDIS_PASSWORD=$(kubectl get secret --namespace default mydb-redis -o jsonpath="{.data.redis-password}" | base64 -d)

To connect to your Redis&reg; server:

1. Run a Redis&reg; pod that you can use as a client:

   kubectl run --namespace default redis-client --restart='Never'  --env REDIS_PASSWORD=$REDIS_PASSWORD  --image docker.io/bitnami/redis:7.2.2-debian-11-r0 --command -- sleep infinity

   Use the following command to attach to the pod:

   kubectl exec --tty -i redis-client \
   --namespace default -- bash

2. Connect using the Redis&reg; CLI:
   REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-master
   REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-replicas

To connect to your database from outside the cluster execute the following commands:

    kubectl port-forward --namespace default svc/mydb-redis-master 6379:6379 &
    REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h 127.0.0.1 -p 6379

Verify the helm chart is deployed and Redis is running on the Kubernetes cluster.

$ helm ls
NAME    NAMESPACE   REVISION    UPDATED                                 STATUS      CHART           APP VERSION
mydb    default     1           2023-10-30 07:43:01.730917 -0400 EDT    deployed    redis-18.2.0    7.2.2

$ kubectl get all
NAME                        READY   STATUS    RESTARTS   AGE
pod/mydb-redis-master-0     1/1     Running   0          4m4s
pod/mydb-redis-replicas-0   1/1     Running   0          4m4s
pod/mydb-redis-replicas-1   1/1     Running   0          3m23s
pod/mydb-redis-replicas-2   1/1     Running   0          3m1s

NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/kubernetes            ClusterIP   10.96.0.1       <none>        443/TCP    2d22h
service/mydb-redis-headless   ClusterIP   None            <none>        6379/TCP   4m4s
service/mydb-redis-master     ClusterIP   10.106.79.115   <none>        6379/TCP   4m4s
service/mydb-redis-replicas   ClusterIP   10.106.46.152   <none>        6379/TCP   4m4s

NAME                                   READY   AGE
statefulset.apps/mydb-redis-master     1/1     4m4s
statefulset.apps/mydb-redis-replicas   3/3     4m4s

Follow the post installation prompt and verify that Redis is working correctly.

$ export REDIS_PASSWORD=$(kubectl get secret --namespace default mydb-redis -o jsonpath="{.data.redis-password}" | base64 -d)
$ kubectl run --namespace default redis-client --restart='Never'  --env REDIS_PASSWORD=$REDIS_PASSWORD  --image docker.io/bitnami/redis:7.2.2-debian-11-r0 --command -- sleep infinity
pod/redis-client created

$ kubectl exec --tty -i redis-client --namespace default -- bash
I have no name!@redis-client:/$ REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-master

mydb-redis-master:6379> SET key value
OK
mydb-redis-master:6379> GET key
"value"

Helm charts are a great way to run popular applications like Databases since the helm chart implements many of the best practices for you and allows you to just provide higher level tuning.

Delete the Redis helm chart.

$ helm delete mydb
release "mydb" uninstalled

$ helm ls
NAME    NAMESPACE   REVISION    UPDATED STATUS  CHART   APP VERSION

Helm utilizes a values.yaml file for its configuration, here is the Bitnami Redis values.yaml as a reference and a custom values.yaml file can be passed to the helm install command to override any of the values.

Create a custom values.yaml file to override the password and replica count.

📝 values.yaml

auth:
  password: myDbSecret123

replica:
  replicaCount: 4

Install Redis again but now pass in the updated configuration.

$ helm install mydb bitnami/redis -f values.yaml
NAME: mydb
LAST DEPLOYED: Tue Oct 31 06:57:24 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: redis
CHART VERSION: 18.2.0
APP VERSION: 7.2.2

** Please be patient while the chart is being deployed **

Redis&reg; can be accessed on the following DNS names from within your cluster:

    mydb-redis-master.default.svc.cluster.local for read/write operations (port 6379)
    mydb-redis-replicas.default.svc.cluster.local for read-only operations (port 6379)

To get your password run:

    export REDIS_PASSWORD=$(kubectl get secret --namespace default mydb-redis -o jsonpath="{.data.redis-password}" | base64 -d)

To connect to your Redis&reg; server:

1. Run a Redis&reg; pod that you can use as a client:

   kubectl run --namespace default redis-client --restart='Never'  --env REDIS_PASSWORD=$REDIS_PASSWORD  --image docker.io/bitnami/redis:7.2.2-debian-11-r0 --command -- sleep infinity

   Use the following command to attach to the pod:

   kubectl exec --tty -i redis-client \
   --namespace default -- bash

2. Connect using the Redis&reg; CLI:
   REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-master
   REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-replicas

To connect to your database from outside the cluster execute the following commands:

    kubectl port-forward --namespace default svc/mydb-redis-master 6379:6379 &
    REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h 127.0.0.1 -p 6379

Validate that the new configuration has been applied correctly, you should see the new password set in the secret and 4 replicas running.

$ helm ls
NAME    NAMESPACE   REVISION    UPDATED                                 STATUS      CHART           APP VERSION
mydb    default     1           2023-10-31 06:57:24.661346 -0400 EDT    deployed    redis-18.2.0    7.2.2

$ kubectl get all
NAME                        READY   STATUS    RESTARTS   AGE
pod/mydb-redis-master-0     1/1     Running   0          3m51s
pod/mydb-redis-replicas-0   1/1     Running   0          3m51s
pod/mydb-redis-replicas-1   1/1     Running   0          3m16s
pod/mydb-redis-replicas-2   1/1     Running   0          2m51s
pod/mydb-redis-replicas-3   1/1     Running   0          2m30s

NAME                          TYPE        CLUSTER-IP      EXTERNAL-IP   PORT(S)    AGE
service/kubernetes            ClusterIP   10.96.0.1       <none>        443/TCP    3d21h
service/mydb-redis-headless   ClusterIP   None            <none>        6379/TCP   3m51s
service/mydb-redis-master     ClusterIP   10.102.17.165   <none>        6379/TCP   3m51s
service/mydb-redis-replicas   ClusterIP   10.111.189.75   <none>        6379/TCP   3m51s

NAME                                   READY   AGE
statefulset.apps/mydb-redis-master     1/1     3m51s
statefulset.apps/mydb-redis-replicas   4/4     3m51s

$ echo $(kubectl get secret --namespace default mydb-redis -o jsonpath="{.data.redis-password}" | base64 -d)
myDbSecret123

$ helm delete mydb
release "mydb" uninstalled

Helm also allows you to override values by passing them in with the --set flag which can be used to pass in sensitive values such as secrets. In production this method is used to set the secrets of a helm chart using environment variables within the CI/CD Pipeline.

💡 Refer to DevOps CI/CD Quick Start Guide with GitHub Actions 🛠️🐙⚡️ for a Guide on creating CI/CD Pipelines

Remove the password from the values.yaml file.

📝 values.yaml

replica:
  replicaCount: 4

Now pass in the password from the command line with the --set flag.

$ helm install mydb bitnami/redis --set auth.password=myDbSecret123 -f values.yaml
NAME: mydb
LAST DEPLOYED: Tue Oct 31 07:10:39 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
CHART NAME: redis
CHART VERSION: 18.2.0
APP VERSION: 7.2.2

** Please be patient while the chart is being deployed **

Redis&reg; can be accessed on the following DNS names from within your cluster:

    mydb-redis-master.default.svc.cluster.local for read/write operations (port 6379)
    mydb-redis-replicas.default.svc.cluster.local for read-only operations (port 6379)

To get your password run:

    export REDIS_PASSWORD=$(kubectl get secret --namespace default mydb-redis -o jsonpath="{.data.redis-password}" | base64 -d)

To connect to your Redis&reg; server:

1. Run a Redis&reg; pod that you can use as a client:

   kubectl run --namespace default redis-client --restart='Never'  --env REDIS_PASSWORD=$REDIS_PASSWORD  --image docker.io/bitnami/redis:7.2.2-debian-11-r0 --command -- sleep infinity

   Use the following command to attach to the pod:

   kubectl exec --tty -i redis-client \
   --namespace default -- bash

2. Connect using the Redis&reg; CLI:
   REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-master
   REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h mydb-redis-replicas

To connect to your database from outside the cluster execute the following commands:

    kubectl port-forward --namespace default svc/mydb-redis-master 6379:6379 &
    REDISCLI_AUTH="$REDIS_PASSWORD" redis-cli -h 127.0.0.1 -p 6379

Verify the password has been set correctly then delete the chart.

$ echo $(kubectl get secret --namespace default mydb-redis -o jsonpath="{.data.redis-password}" | base64 -d)
myDbSecret123

$ helm delete mydb
release "mydb" uninstalled

Nice! This is the basics for using helm charts and there are charts available for nearly every popular application, this gives us a simple way to get production grade instances of them running. Now lets take a look at creating a Kubernetes application.

App with K8s configuration files

⭐️ The complete source code referenced in this guide is available on GitHub
https://github.com/dpills/helm-quick-start

Application setup

Create a small FastAPI app which will use a secret static token to authenticate the endpoint.

💡 Refer to FastAPI Production Setup Guide 🏁⚡️🚀 for a full Python FastAPI Guide

Install the necessary dependencies with Poetry.

📝 pyproject.toml

[tool.poetry]
name = "helm-api"
version = "0.1.0"
description = ""
authors = ["dpills"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.104.1"
uvicorn = { extras = ["standard"], version = "^0.23.2" }
pydantic-settings = "^2.0.3"

[tool.poetry.group.dev.dependencies]
ruff = "^0.1.3"
black = "^23.10.1"
mypy = "^1.6.1"

[tool.black]
line-length = 88

[tool.ruff]
select = ["E", "F", "I"]
fixable = ["ALL"]
exclude = [".git", ".mypy_cache", ".ruff_cache"]
line-length = 88

[tool.mypy]
disallow_any_generics = true
disallow_subclassing_any = true
disallow_untyped_calls = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_return_any = true
strict_equality = true
disallow_untyped_decorators = false
ignore_missing_imports = true
implicit_reexport = true
plugins = "pydantic.mypy"

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true
warn_untyped_fields = true

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

$ poetry install
Installing dependencies from lock file

No dependencies to install or update

Create the API code.

📝 main.py

import uvicorn
from fastapi import FastAPI, HTTPException, Security
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from pydantic import BaseModel
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    static_token: str
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()
app = FastAPI()
security = HTTPBearer()

class Data(BaseModel):
    item: str

@app.get("/data", response_model=Data)
async def get_data(
    access_token: HTTPAuthorizationCredentials = Security(security),
) -> Data:
    """
    Get Data
    """
    if access_token.credentials != settings.static_token:
        raise HTTPException(status_code=401, detail="Unauthorized")

    return Data(item="helm")

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Add a .env file for local testing.

📝 .env

STATIC_TOKEN=MY_SECRET_TOKEN_123

Make sure the API is working as expected locally, it should only allow the API call to be made when the secret static token is sent in the Authorization Bearer token header.

$ poetry run python3 main.py
INFO:     Will watch for changes in these directories: ['/Users/dpills/articles/helm-quick-start/api']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [13765] using WatchFiles
INFO:     Started server process [13771]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     127.0.0.1:51135 - "GET /data HTTP/1.1" 403 Forbidden
INFO:     127.0.0.1:51136 - "GET /data HTTP/1.1" 200 OK

$ curl -v http://localhost:8000/data
< HTTP/1.1 403 Forbidden
{"detail":"Not authenticated"}

$ curl -v http://localhost:8000/data -H 'Authorization: Bearer MY_SECRET_TOKEN_123'
< HTTP/1.1 200 OK
{"item":"helm"}

Now that we know it is working as expected, containerize it with a Dockerfile.

📝 Dockerfile

FROM python:3.11-slim-bookworm as requirements-stage

RUN pip install poetry
COPY ./pyproject.toml ./poetry.lock /
RUN poetry export -f requirements.txt --output requirements.txt --without-hashes --without=dev

FROM python:3.11-slim-bookworm

COPY --from=requirements-stage /requirements.txt /requirements.txt
COPY ./app /app

RUN python3 -m pip install --no-cache-dir --upgrade -r requirements.txt
EXPOSE 8000

ENTRYPOINT ["uvicorn", "--host", "0.0.0.0", "--port", "8000", "main:app"]

💡 Refer to Containers Demystified 🐳🤔 for a Docker container guide

Build and push the container image to Docker Hub.

$ docker build . -t dpills/helm-api:v1.0.0 --push
[+] Building 40.7s (13/13) FINISHED                                               docker:desktop-linux
...
 => [requirements-stage 2/4] RUN pip install poetry                                              19.6s
 => [requirements-stage 3/4] COPY ./pyproject.toml ./poetry.lock /                                0.0s 
 => [requirements-stage 4/4] RUN poetry export -f requirements.txt --output requirements.txt --w  0.5s 
 => [stage-1 2/4] COPY --from=requirements-stage /requirements.txt /requirements.txt              0.0s 
 => [stage-1 3/4] COPY ./main.py /main.py                                                         0.0s 
 => [stage-1 4/4] RUN python3 -m pip install --no-cache-dir --upgrade -r requirements.txt         6.4s 
...
 => => naming to docker.io/dpills/helm-api:v1.0.0                                                 0.0s 
 => pushing dpills/helm-api:v1.0.0 with docker                                                   11.2s

Standard Kubernetes Configuration

Now that we have our application container image built, we need to create the Kubernetes configuration files to deploy it.

Create a secret for our STATIC_TOKEN environment variable.

📝 k8s/secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: helm-guide-api-secret
data:
  STATIC_TOKEN: TVlfU0VDUkVUX1RPS0VOXzEyMw==

💡 This can be generated from the .env file with kubectl . Secret files are just base64 encodings of the values.

$ kubectl create secret generic helm-guide-api-secret --from-env-file=.env --dry-run=client -o yaml
apiVersion: v1
data:
  STATIC_TOKEN: TVlfU0VDUkVUX1RPS0VOXzEyMw==
kind: Secret
metadata:
  creationTimestamp: null
  name: helm-guide-api-secret

$ echo TVlfU0VDUkVUX1RPS0VOXzEyMw== | base64 -d
MY_SECRET_TOKEN_123

Create a deployment with the new API container image and map the secret to the environment variables.

📝 k8s/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: helm-guide-api
  name: helm-guide-api
spec:
  replicas: 1 # One Instance
  selector:
    matchLabels:
      app: helm-guide-api
  template:
    metadata:
      labels:
        app: helm-guide-api
    spec:
      containers:
        - name: helm-guide-api
          image: dpills/helm-api:v1.0.0 # API Image
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8000
              protocol: TCP
          envFrom:
            - secretRef:
                name: helm-guide-api-secret # Secret Mapping
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: "1"
              memory: 1Gi

Finally, create a service to expose the API.

📝 k8s/service.yaml

apiVersion: v1
kind: Service
metadata:
  labels:
    app: helm-guide-api
  name: helm-guide-api-svc
spec:
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: helm-guide-api

Apply the Kubernetes configuration.

$ kubectl apply -f k8s
deployment.apps/helm-guide-api created
secret/helm-guide-api-secret created
service/helm-guide-api-svc created

Connect to the service with Minikube.

$ minikube service helm-guide-api-svc --url
😿  service default/helm-guide-api-svc has no node port
http://127.0.0.1:51476
❗  Because you are using a Docker driver on darwin, the terminal needs to be open to run it.

Validate it is working as expected with the exposed Minikube port from the last command.

$ curl -v http://localhost:51476/data
< HTTP/1.1 403 Forbidden
{"detail":"Not authenticated"}

$ curl -v http://localhost:51476/data -H 'Authorization: Bearer MY_SECRET_TOKEN_123'
< HTTP/1.1 200 OK
{"item":"helm"}

Awesome! this is great but if we look at the Kubernetes configuration files we can see that the root application name helm-guide-api needs to be constantly referenced throughout the configuration and there is a lot of boilerplate which will never change. The main items we will update often will be the image version and potentially replica count. Also with following Infrastructure as Code (IaC) best practices and committing all of our configuration files, we are exposing our application secret. Being able to template these files and create variables for the portions that we need to change or keep secret is what Helm allows us to do.

App with a Helm Chart

Create the new helm chart with the helm create command. You can take a look at the default bootstrapped helm chart example created by this command to see a lot of the functionality which we will not fully cover in this article.

$ helm create infra
Creating infra

Update the Chart.yaml with a description and version.

📝 infra/Chart.yaml

apiVersion: v2
name: helm-guide-api
description: Helm API
type: application
version: 1.0.0
appVersion: "1.0.0"

Now delete all of the bootstrapped files in the templates folder and copy the deployment.yaml , service.yaml and secret.yaml configuration files into the templates folder.

The file structure should look like this.

Update the service to use the helm release name for the application name using the double curly brace helm templating syntax.

📝 infra/templates/service.yaml

apiVersion: v1
kind: Service
metadata:
  labels:
    app: {{ .Release.Name }}
  name: {{ .Release.Name }}-svc
spec:
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: {{ .Release.Name }}

For the deployment file we need to pass in the replica count and container image and as we saw in the start of this article the values.yaml file is used to pass in values. Update the values.yaml file with an API configuration defining these two values.

📝 infra/values.yaml

api:
  image: dpills/helm-api:v1.0.0
  replicas: 1

Update the deployment template to use the release name, api image and replica count. For the replica count, cast the type to make sure it is an integer.

📝 infra/templates/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: {{ .Release.Name }}
  name: {{ .Release.Name }}
spec:
  replicas: {{ int .Values.api.replicas }}
  selector:
    matchLabels:
      app: {{ .Release.Name }}
  template:
    metadata:
      labels:
        app: {{ .Release.Name }}
    spec:
      containers:
        - name: {{ .Release.Name }}
          image: {{ .Values.api.image }}
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8000
              protocol: TCP
          envFrom:
            - secretRef:
                name: {{ .Release.Name }}-secret
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: "1"
              memory: 1Gi

For the secret we need to pass in the static token and base64 encode it but we should not commit the secret to our source code. Add an entry will a null value to the values.yaml file which will be passed in with the helm install --set flag.

📝 infra/values.yaml

api:
  image: dpills/helm-api:v1.0.0
  replicas: 1
  static_token: null # Pass this in with --set static_token=XXX

Update the secret to to use the release name, validate that a static token value has been passed in with the required keyword and base64 encode it by piping to the b64enc function.

📝 infra/templates/secret.yaml

apiVersion: v1
kind: Secret
metadata:
  name: {{ .Release.Name }}-secret
data:
  STATIC_TOKEN: {{ required "A static token is required" .Values.api.static_token | b64enc }}

The NOTES.txt is what is printed out after installing the chart, update this to some simple text for this example.

📝 infra/templates/NOTES.txt

Helm API Example!

This should now be fully setup, delete the standard Kubernetes configuration deployment if it is still running and run the application with the helm chart instead.

$ kubectl delete -f k8s
deployment.apps "helm-guide-api" deleted
secret "helm-guide-api-secret" deleted
service "helm-guide-api-svc" deleted

$ helm install helm-api ./infra --set api.static_token=MY_SECRET_TOKEN_123
NAME: helm-api
LAST DEPLOYED: Wed Nov  1 08:44:37 2023
NAMESPACE: default
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
Helm API Example!

Validate the application is working as expected.

$ helm ls
NAME            NAMESPACE       REVISION        UPDATED                                 STATUS          CHART                   APP VERSION
helm-api        default         1               2023-11-01 08:44:37.222599 -0400 EDT    deployed        helm-guide-api-1.0.0    1.0.0

$ kubectl get all
NAME                            READY   STATUS    RESTARTS   AGE
pod/helm-api-79877dcfc6-8rv47   1/1     Running   0          61s

NAME                   TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)    AGE
service/helm-api-svc   ClusterIP   10.109.109.197   <none>        8000/TCP   61s
service/kubernetes     ClusterIP   10.96.0.1        <none>        443/TCP    4d23h

NAME                       READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/helm-api   1/1     1            1           61s

NAME                                  DESIRED   CURRENT   READY   AGE
replicaset.apps/helm-api-79877dcfc6   1         1         1       61s

$ minikube service helm-api-svc --url
😿  service default/helm-api-svc has no node port
http://127.0.0.1:51778
❗  Because you are using a Docker driver on darwin, the terminal needs to be open to run it.

$ curl -v http://localhost:51778/data
< HTTP/1.1 403 Forbidden
{"detail":"Not authenticated"}

$ curl -v http://localhost:51778/data -H 'Authorization: Bearer MY_SECRET_TOKEN_123'
< HTTP/1.1 200 OK
{"item":"helm"}

Congrats you just created a helm chart! 🎉 We can see that the release name that we passed in to the helm install command has been used for all of the object names. The primary configuration file is greatly simplified with the values.yaml file and our secret configuration is committed to our source code but the sensitive value is no longer exposed. The Helm Chart Documentation can be referenced for a full overview of the syntax and features. Utilizing helm charts to manage Kubernetes applications has been very useful for me and I hope this guide helps you build your next amazing application! 😊

DevOps CI/CD Quick Start Guide with GitHub Actions 🛠️🐙⚡️

Deon Pillsbury — Fri, 27 Oct 2023 16:40:08 +0000

DevOps is the combination of Development which builds applications and Operations who manage the deployments and various runtime environments. In order to do the development and operations of an application you need to automate every part of the process you can and that is where CI/CD pipelines come into the picture. CI/CD stands for Continuous Integration and Continuous Delivery. Continuous Integration is used to automate the verification of qualitative standards (linting, formatting, static type checking), security (vulnerability scanning) and testing of code as it is committed to a code repository. This creates code that is high quality and leads to Continuous Delivery which automates the build and release of new application versions.

https://www.eficode.com/blog/ci-cd-vulnerability-scanning-how-to-begin-your-devsecops-journey

GitHub Repository Setup

💡 The complete source code referenced in this guide is available on GitHub
https://github.com/dpills/devops-quick-start-guide

GitHub is the most popular Source Code Management system and they offer an integrated CI/CD solution GitHub Actions which we will be using to setup our CI/CD Pipeline. Other popular CI/CD tools include CircleCI, TravisCI, Gitlab CI, Jenkins, and many others.

Create a new repository in GitHub and setup a small Python FastAPI app.

💡 Refer to FastAPI Production Setup Guide 🏁⚡️🚀 for a full Python FastAPI Guide

$ poetry init

This command will guide you through creating your pyproject.toml config.

Package name [devops-quick-start-guide]:  
Version [0.1.0]:  
Description []:  
Author [dpills, n to skip]:  dpills
License []:  
Compatible Python versions [^3.11]:  

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file

[tool.poetry]
name = "devops-quick-start-guide"
version = "0.1.0"
description = ""
authors = ["dpills"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Do you confirm generation? (yes/no) [yes]

Add the production and development dependencies.

$ poetry add fastapi 'uvicorn[standard]' httpx
...
Package operations: 21 installs, 0 updates, 0 removals

$ poetry add -G dev ruff black mypy pytest coverage
...
Package operations: 11 installs, 0 updates, 0 removals

Add the linting, formatting and static type checking rules to the pyproject.toml.

📝 pyproject.toml

[tool.poetry]
name = "devops-quick-start-guide"
version = "0.1.0"
description = ""
authors = ["dpills"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.104.0"
uvicorn = { extras = ["standard"], version = "^0.23.2" }
httpx = "^0.25.0"

[tool.poetry.group.dev.dependencies]
ruff = "^0.1.2"
black = "^23.10.1"
mypy = "^1.6.1"
pytest = "^7.4.3"
coverage = "^7.3.2"

[tool.black]
line-length = 88

[tool.ruff]
select = ["E", "F", "I"]
fixable = ["ALL"]
exclude = [".git", ".mypy_cache", ".ruff_cache"]
line-length = 88

[tool.mypy]
disallow_any_generics = true
disallow_subclassing_any = true
disallow_untyped_calls = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_return_any = true
strict_equality = true
disallow_untyped_decorators = false
ignore_missing_imports = true
implicit_reexport = true
plugins = "pydantic.mypy"

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true
warn_untyped_fields = true

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Add an app folder with an empty __init__.py file and a main.py file with the following contents.

📝 app/main.py

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Data(BaseModel):
    item: str

@app.get("/data", response_model=Data)
async def get_data() -> Data:
    """
    Get Data
    """
    return Data(item="devops")

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

GitHub Actions Workflow

GitHub Actions are configured with YAML Workflow files which determine on what events should something run and what should be ran. Create the .github/workflows/ci.yml folders/file within the root of the repository and setup our first job.

Lint

📝 .github/workflows/ci.yml

name: CI
on:
  push:
    branches: ["main"]
    tags: ["*"]
  pull_request:
    branches: ["main"]

jobs:
  qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install poetry
        run: pipx install poetry
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: "poetry"
      - name: Install Dependencies
        run: poetry install --no-root --no-interaction

      - name: Formatting
        run: poetry run black --check app
      - name: Linting
        run: poetry run ruff --output-format=github app
      - name: Static Type Checking
        run: poetry run mypy app

This workflow will run on commits and pull requests on the main branch and any tags pushed to the repository. It then runs the qa job which checks out the code, installs poetry in a Python 3.11 environment and installs the app dependencies. Finally, it runs the quality checks to make sure the code is formatted, passes static linting and type checking.

Git add, commit and push all of these files to your repository.

$ git add .
$ git commit -m "CI setup"
[main 74afe32] CI setup
 7 files changed, 1108 insertions(+)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 .gitignore
 create mode 100644 LICENSE
 create mode 100644 app/__init__.py
 create mode 100644 app/main.py
 create mode 100644 poetry.lock
 create mode 100644 pyproject.toml
$ git push
Enumerating objects: 13, done.
Counting objects: 100% (13/13), done.
Delta compression using up to 10 threads
Compressing objects: 100% (9/9), done.
Writing objects: 100% (12/12), 30.21 KiB | 15.10 MiB/s, done.
Total 12 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:dpills/devops-quick-start-guide.git
   aa11374..74afe32  main -> main

Under the Actions tab in the GitHub repo, we can see the details of the qa job which should pass all of the checks.

Update the main.py file to intentionally break the script with an undefined_variable to make sure the job properly catches it.

📝 app/main.py

import uvicorn
from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Data(BaseModel):
    item: str

@app.get("/data", response_model=Data)
async def get_data() -> Data:
    """
    Get Data
    """
    undefined_variable

    return Data(item="devops")

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Push this breaking change to the repository and it should now fail the linting check.

Remove the Undefined variable so the workflow passes again.

Test

Add a test_main.py file to the app folder with a unit test so we can run a test suite and generate a coverage report.

📝 app/test_main.py

from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)

def test_get_data() -> None:
    """
    Test getting data
    """
    r = client.get("/data")
    assert r.status_code == 200

Verify the test setup is working as expected locally.

$ poetry run coverage run --source ./app -m pytest

=========================================== test session starts ============================================
platform darwin -- Python 3.11.4, pytest-7.4.3, pluggy-1.3.0
rootdir: /Users/dpills/articles/devops-quick-start-guide
plugins: anyio-3.7.1
collected 1 item                                                                                           

app/test_main.py .                                                                                   [100%]

============================================ 1 passed in 0.93s =============================================

Add a new testing job under jobs in the workflow YAML file with the same repo and python setup as the qa job. Add the test coverage command and the commands to generate a coverage report.

📝 .github/workflows/ci.yml

jobs:
...
  testing:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install poetry
        run: pipx install poetry
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: "poetry"
      - name: Install Dependencies
        run: poetry install --no-root --no-interaction

      - name: Test & Coverage
        run: poetry run coverage run --source ./app -m pytest
      - name: Coverage Report
        run: |
          poetry run coverage xml
          poetry run coverage report -m

Push these changes to the repository and we can now see both of the jobs being ran in parallel.

💡 If you use VS Code there is a useful GitHub Actions Plugin which you can enable to view the pipelines directly in your editor.

The code coverage is printed out in the Coverage Report step but it is useful to track code coverage over time and have a repository badge which shows the current coverage percentage. There are many different code coverage and testing applications but we will use CodeCov.

Setup a CodeCov account and link your GitHub so you are able to see your repositories. Click Setup repo which will show you how to setup GitHub Actions.

This will utilize a repository secret which is used to store sensitive information such as passwords. Navigate back to your GitHub repository settings and add the CODECOV_TOKEN as a new Actions secret.

Now add the Codecov step to the testing job and use the secret with the ${{ secrets.CODECOV_TOKEN }} syntax.

📝 .github/workflows/ci.yml

jobs:
...
  testing:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install poetry
        run: pipx install poetry
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: "poetry"
      - name: Install Dependencies
        run: poetry install --no-root --no-interaction

      - name: Test & Coverage
        run: poetry run coverage run --source ./app -m pytest
      - name: Coverage Report
        run: |
          poetry run coverage xml
          poetry run coverage report -m
      - name: Upload coverage reports to Codecov
        uses: codecov/codecov-action@v3
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

Commit these changes and after the workflow runs we can see the coverage metrics in codecov.

The codecov settings tab has the Markdown to add to our README file to show a live coverage percentage badge.

Copy the Markdown and add it to the README.md file for your repository.

📝 README.md

# DevOps Quick Start Guide

DevOps CI/CD Quick Start Guide with GitHub Actions 🛠️🐙⚡️

[![codecov](https://codecov.io/gh/dpills/devops-quick-start-guide/graph/badge.svg?token=jwraAw5pYK)](https://codecov.io/gh/dpills/devops-quick-start-guide)

Push the changes and we can now see our Code Coverage badge on our repo!

Build

Now that the app has passed static analysis and testing it is time to work on the Continuous Delivery starting with building the application package. For this Python API we can build and package it as a container image.

💡 Refer to Containers Demystified 🐳🤔 for a Docker container guide

Add a Dockerfile to the root of the repository.

📝 Dockerfile

FROM python:3.11-slim-bookworm as requirements-stage

RUN pip install poetry
COPY ./pyproject.toml ./poetry.lock /
RUN poetry export -f requirements.txt --output requirements.txt --without-hashes --without=dev

FROM python:3.11-slim-bookworm

COPY --from=requirements-stage /requirements.txt /requirements.txt
COPY ./app /app

RUN python3 -m pip install --no-cache-dir --upgrade -r requirements.txt
EXPOSE 8000

ENTRYPOINT ["uvicorn", "--host", "0.0.0.0", "--port", "8000", "app.main:app"]

Create a new repository in DockerHub and generate a Personal Access Token.

Add your DockerHub username and personal access token as an Actions secret in GitHub.

Now we are ready to add a new build workflow job. We need to make sure the qa and testing jobs are successful before executing a new build so we can indicate this with the needs entry. Additionally, we will only want to create new builds for new application versions and we can set the version of the app using git tags such as v1.0.0 . We can specify that this job should only run when a new tag is added to the repository with the if: github.ref_type == 'tag' entry. The DockerHub secrets are used to login to DockerHub and finally the new tag name is used as the Docker image tag.

📝 .github/workflows/ci.yml

jobs:
...
  build:
    runs-on: ubuntu-latest
    needs: # Make sure qa and testing jobs pass first
      - qa
      - testing
    if: github.ref_type == 'tag' # Only run on new tags
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: Build and Push Image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64 # Multi-Arch build for AMD and ARM CPUs
          push: true
          tags: dpills/devops-quick-start-guide:${{ github.ref_name }} # Use git tag

Commit these changes and then push a new tag to the repository.

$ git tag v1.0.0 && git push origin -u v1.0.0
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:dpills/devops-quick-start-guide.git
 * [new tag]         v1.0.0 -> v1.0.0

The workflow runs for the new tag and the qa and testing steps are executed and validated prior to the build step.

After the build step completes we can check the DockerHub repository where we can see the new image tag which has been built for the AMD64 and ARM64 architectures!

Deploy with a Self-Hosted Runner

Now that the image is built we are ready to deploy the API. Since we are using containers, a great option for production deployments is Kubernetes and we can use MiniKube to deploy this on our local computer.

Refer to Kubernetes Quick Start Guide ☁️⚡️🚀 for an in-depth Kubernetes tutorial

Make sure Minikube is running.

$ minikube start --driver=docker
😄  minikube v1.31.2 on Darwin 14.0 (arm64)
✨  Using the docker driver based on user configuration
📌  Using Docker Desktop driver with root privileges
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🔥  Creating docker container (CPUs=2, Memory=4000MB) ...
🐳  Preparing Kubernetes v1.27.4 on Docker 24.0.4 ...
    ▪ Generating certificates and keys ...
    ▪ Booting up control plane ...
    ▪ Configuring RBAC rules ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

$ kubectl get all -A
NAMESPACE     NAME                                   READY   STATUS    RESTARTS   AGE
kube-system   pod/coredns-5d78c9869d-8pcln           1/1     Running   0          2s
kube-system   pod/etcd-minikube                      1/1     Running   0          15s
kube-system   pod/kube-apiserver-minikube            1/1     Running   0          15s
kube-system   pod/kube-controller-manager-minikube   1/1     Running   0          15s
kube-system   pod/kube-proxy-j4q8m                   1/1     Running   0          3s
kube-system   pod/kube-scheduler-minikube            1/1     Running   0          15s
kube-system   pod/storage-provisioner                1/1     Running   0          14s

NAMESPACE     NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)                  AGE
default       service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP                  17s
kube-system   service/kube-dns     ClusterIP   10.96.0.10   <none>        53/UDP,53/TCP,9153/TCP   15s

NAMESPACE     NAME                        DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
kube-system   daemonset.apps/kube-proxy   1         1         1       1            1           kubernetes.io/os=linux   15s

NAMESPACE     NAME                      READY   UP-TO-DATE   AVAILABLE   AGE
kube-system   deployment.apps/coredns   1/1     1            1           15s

NAMESPACE     NAME                                 DESIRED   CURRENT   READY   AGE
kube-system   replicaset.apps/coredns-5d78c9869d   1         1         1       3s

Add the Kubernetes Deployment and Service manifest files to the repository in a k8s folder.

📝 k8s/deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: devops-quick-start-guide
  name: devops-quick-start-guide
spec:
  replicas: 1
  selector:
    matchLabels:
      app: devops-quick-start-guide
  template:
    metadata:
      labels:
        app: devops-quick-start-guide
    spec:
      containers:
        - name: devops-quick-start-guide
          image: dpills/devops-quick-start-guide:v1.0.0
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8000
              protocol: TCP
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
            requests:
              cpu: "1"
              memory: 1Gi

📝 k8s/service.yaml

apiVersion: v1
kind: Service
metadata:
  labels:
    app: devops-quick-start-guide
  name: devops-quick-start-guide-svc
spec:
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: devops-quick-start-guide

Deploy the initial version and verify that it is running.

$ kubectl apply -f k8s
deployment.apps/devops-quick-start-guide created
service/devops-quick-start-guide-svc created

$ kubectl get deploy -o wide
NAME                       READY   UP-TO-DATE   AVAILABLE   AGE    CONTAINERS                 IMAGES                                   SELECTOR
devops-quick-start-guide   1/1     1            1           2m4s   devops-quick-start-guide   dpills/devops-quick-start-guide:v1.0.0   app=devops-quick-start-guide

Since we are using Minikube on our local computer, it is not Internet accessible for the GitHub Hosted Runners which we have been using so far indicated with the runs-on: ubuntu-latest portion of the jobs. To address situations where you are on a closed network Github Actions allows you to use Self-Hosted Runners. Navigate to the GitHub repository setting under Actions > Runners and add a New self-hosted runner

Select your operating system, architecture, go through the setup steps and get it running.

$ mkdir actions-runner && cd actions-runner
$ curl -o actions-runner-osx-arm64-2.311.0.tar.gz -L https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-osx-arm64-2.311.0.tar.gz
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 98.1M  100 98.1M    0     0  20.0M      0  0:00:04  0:00:04 --:--:-- 23.5M

$ echo "fa2f107dbce709807bae014fb3121f5dbe106211b6bbe3484c41e3b30828d6b2  actions-runner-osx-arm64-2.311.0.tar.gz" | shasum -a 256 -c
actions-runner-osx-arm64-2.311.0.tar.gz: OK
$ tar xzf ./actions-runner-osx-arm64-2.311.0.tar.gz

❯ ./config.sh --url https://github.com/dpills/devops-quick-start-guide --token AGDCRGCMZWN34QIVISIO5XXXXXX

--------------------------------------------------------------------------------
|        ____ _ _   _   _       _          _        _   _                      |
|       / ___(_) |_| | | |_   _| |__      / \   ___| |_(_) ___  _ __  ___      |
|      | |  _| | __| |_| | | | | '_ \    / _ \ / __| __| |/ _ \| '_ \/ __|     |
|      | |_| | | |_|  _  | |_| | |_) |  / ___ \ (__| |_| | (_) | | | \__ \     |
|       \____|_|\__|_| |_|\__,_|_.__/  /_/   \_\___|\__|_|\___/|_| |_|___/     |
|                                                                              |
|                       Self-hosted runner registration                        |
|                                                                              |
--------------------------------------------------------------------------------

# Authentication

√ Connected to GitHub

# Runner Registration

Enter the name of the runner group to add this runner to: [press Enter for Default]

Enter the name of runner: [press Enter for dpills-mac]

This runner will have the following labels: 'self-hosted', 'macOS', 'ARM64'
Enter any additional labels (ex. label-1,label-2): [press Enter to skip]

√ Runner successfully added
√ Runner connection is good

# Runner settings

Enter name of work folder: [press Enter for _work]

√ Settings Saved.

❯ ./run.sh

√ Connected to GitHub

Current runner version: '2.311.0'
2023-10-27 13:32:16Z: Listening for Jobs

The runner should now show up in the settings with an idle status indicating that it is ready to pick up new jobs.

Finally we can update the workflow config to include the deploy step which uses the self-hosted runner, waits for the build step to finish, only triggers on new tags and updates the Kubernetes deployment image to the new container image.

📝 .github/workflows/ci.yml

name: CI
on:
  push:
    branches: ["main"]
    tags: ["*"]
  pull_request:
    branches: ["main"]

jobs:
  qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install poetry
        run: pipx install poetry
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: "poetry"
      - name: Install Dependencies
        run: poetry install --no-root --no-interaction

      - name: Formatting
        run: poetry run black --check app
      - name: Linting
        run: poetry run ruff --output-format=github app
      - name: Static Type Checking
        run: poetry run mypy app

  testing:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install poetry
        run: pipx install poetry
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"
          cache: "poetry"
      - name: Install Dependencies
        run: poetry install --no-root --no-interaction

      - name: Test & Coverage
        run: poetry run coverage run --source ./app -m pytest
      - name: Coverage Report
        run: |
          poetry run coverage xml
          poetry run coverage report -m
      - name: Upload coverage reports to Codecov
        uses: codecov/codecov-action@v3
        env:
          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

  build:
    runs-on: ubuntu-latest
    needs:
      - qa
      - testing
    if: github.ref_type == 'tag'
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Login to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      - name: Build and Push Image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/amd64,linux/arm64
          push: true
          tags: dpills/devops-quick-start-guide:${{ github.ref_name }}

  deploy:
    runs-on: self-hosted
    needs:
      - build
    if: github.ref_type == 'tag'
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Update Deployment
        run: kubectl set image deployment/devops-quick-start-guide devops-quick-start-guide=dpills/devops-quick-start-guide:${{ github.ref_name }}

Commit these changes and push a new version tag to the repository.

$ git tag v1.0.1 && git push origin -u v1.0.1
Total 0 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:dpills/devops-quick-start-guide.git
 * [new tag]         v1.0.1 -> v1.0.1

All of the steps are now executed in order.

We can see that the self-hosted runner has ran the job.

$ ./run.sh

√ Connected to GitHub

Current runner version: '2.311.0'
2023-10-27 14:20:42Z: Listening for Jobs
2023-10-27 14:23:50Z: Running job: deploy
2023-10-27 14:23:57Z: Job deploy completed with result: Succeeded

Verify that the new image has been updated in the Kubernetes deployment. We should now see the v1.0.1 image being used.

$ kubectl get deploy -o wide
NAME                       READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS                 IMAGES                                   SELECTOR
devops-quick-start-guide   1/1     1            1           42m   devops-quick-start-guide   dpills/devops-quick-start-guide:v1.0.1   app=devops-quick-start-guide

Congrats! 🎉 You have fully automated the quality, testing, build and deployment of your application and can now use the time you are saving to deliver more amazing features to your users. 😊 You should now have the basic knowledge to continue to build out the CI/CD setup. Some additional things you may want to add is stage build/deployment steps, security scanning, additional testing, tracking, etc. I hope you have found this article useful and good luck on your next project!

FastAPI Production Setup Guide 🏁⚡️🚀

Deon Pillsbury — Wed, 18 Oct 2023 21:59:39 +0000

Setup
CRUD with MongoDB
- Environment Setup
- Create
- Read
- Update
- Delete
- Full CRUD Functionality
Utilities
- Metadata
- Logging
- Middleware
- CRUD APIs With Utilities
Organization
- APIRouters
- Project Structure
Security
- GitHub Oauth Setup
- Oauth Callback
- Validating an Access Token
- Add Bearer Token Authorization to Endpoints
- Integrate User Info
Testing
- Test Environment Setup
- Adding Tests
Production Deployment
- Containerization
- Docker Compose
- Kubernetes

Python has a handful of popular frameworks for building APIs such as Flask and Django but the framework we will be taking a look at which has become one of the most popular in the last 5 years is FastAPI. FastAPI is built with modern Python features such as asynchronous programming with an event loop, utilizes Pydantic for data validation and generates standard OpenAPI specs from the Python metadata which allows you to build a well documented production grade API very quickly. Lets dive in.

💡 The complete source code referenced in this guide is available on GitHub
https://github.com/dpills/fastapi-prod-guide

Setup

Make sure that you have Python3 and Poetry installed which we will use for package management.

$ python3 --version
Python 3.11.4

$ poetry --version
Poetry (version 1.6.1)

Create your project folder and initialize the project.

$ poetry init

This command will guide you through creating your pyproject.toml config.

Package name [fastapi-quick-start-guide]:
Version [0.1.0]:
Description []:
Author [dpills, n to skip]:  dpills
License []:
Compatible Python versions [^3.11]:

Would you like to define your main dependencies interactively? (yes/no) [yes] no
Would you like to define your development dependencies interactively? (yes/no) [yes] no
Generated file

[tool.poetry]
name = "fastapi-quick-start-guide"
version = "0.1.0"
description = ""
authors = ["dpills"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Do you confirm generation? (yes/no) [yes]

Install the core FastAPI dependencies.

$ poetry add fastapi 'uvicorn[standard]'
Creating virtualenv fastapi-quick-start-guide-KBe0UMIg-py3.11 in /Users/dpills/Library/Caches/pypoetry/virtualenvs
Using version ^0.103.2 for fastapi
Using version ^0.23.2 for uvicorn

Updating dependencies
Resolving dependencies... (1.1s)

Package operations: 18 installs, 0 updates, 0 removals

  • Installing idna (3.4)
  • Installing sniffio (1.3.0)
  • Installing typing-extensions (4.8.0)
  • Installing annotated-types (0.6.0)
  • Installing anyio (3.7.1)
  • Installing pydantic-core (2.10.1)
  • Installing click (8.1.7)
  • Installing h11 (0.14.0)
  • Installing httptools (0.6.0)
  • Installing pydantic (2.4.2)
  • Installing python-dotenv (1.0.0)
  • Installing pyyaml (6.0.1)
  • Installing starlette (0.27.0)
  • Installing uvloop (0.18.0)
  • Installing watchfiles (0.21.0)
  • Installing websockets (11.0.3)
  • Installing fastapi (0.103.2)
  • Installing uvicorn (0.23.2)

Writing lock file

Whenever I start a new project I like to maintain quality standards and using automated quality tools makes it easy. Lets go ahead and install mypy for static type checking, black for formatting, and ruff for linting. Add these to the dev dependencies.

$ poetry add -G dev ruff black mypy
Using version ^0.0.292 for ruff
Using version ^23.9.1 for black
Using version ^1.6.0 for mypy

Updating dependencies
Resolving dependencies... (0.3s)

Package operations: 7 installs, 0 updates, 0 removals

  • Installing mypy-extensions (1.0.0)
  • Installing packaging (23.2)
  • Installing pathspec (0.11.2)
  • Installing platformdirs (3.11.0)
  • Installing black (23.9.1)
  • Installing mypy (1.6.0)
  • Installing ruff (0.0.292)

Writing lock file

Add the configurations for these quality tools to the pyproject.toml file which should now look similar to this.

📝 pyproject.toml

[tool.poetry]
name = "fastapi-quick-start-guide"
version = "0.1.0"
description = ""
authors = ["dpills"]
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.11"
fastapi = "^0.103.2"
uvicorn = { extras = ["standard"], version = "^0.23.2" }

[tool.poetry.group.dev.dependencies]
ruff = "^0.0.292"
black = "^23.9.1"
mypy = "^1.6.0"

[tool.black]
line-length = 88

[tool.ruff]
select = ["E", "F", "I"]
fixable = ["ALL"]
exclude = [".git", ".mypy_cache", ".ruff_cache"]
line-length = 88

[tool.mypy]
disallow_any_generics = true
disallow_subclassing_any = true
disallow_untyped_calls = true
disallow_untyped_defs = true
disallow_incomplete_defs = true
check_untyped_defs = true
no_implicit_optional = true
warn_redundant_casts = true
warn_unused_ignores = true
warn_return_any = true
strict_equality = true
disallow_untyped_decorators = false
ignore_missing_imports = true
implicit_reexport = true
plugins = "pydantic.mypy"

[tool.pydantic-mypy]
init_forbid_extra = true
init_typed = true
warn_required_dynamic_aliases = true
warn_untyped_fields = true

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Now that we have our dependencies installed, add the main python file and the basic FastAPI example.

📝 main.py

import uvicorn
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root() -> dict[str, str]:
    """
    Hello World
    """
    return {"Hello": "World"}

@app.get("/items/{item_id}")
async def read_item(item_id: str) -> dict[str, str]:
    """
    Get an Item
    """
    return {"item_id": item_id}

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Run the file with python and open your web browser to http://localhost:8000/docs

$ poetry shell
Spawning shell within /Users/dpills/Library/Caches/pypoetry/virtualenvs/fastapi-quick-start-guide-KBe0UMIg-py3.11

$ python3 main.py
INFO:     Will watch for changes in these directories: ['/Users/dpills/articles/fastapi-quick-start-guide']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [28609] using WatchFiles
INFO:     Started server process [28611]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     127.0.0.1:50323 - "GET /docs HTTP/1.1" 200 OK
INFO:     127.0.0.1:50323 - "GET /openapi.json HTTP/1.1" 200 OK
INFO:     127.0.0.1:50332 - "GET /items/test123 HTTP/1.1" 200 OK

ℹ️ FastAPI automatically generates an OpenAPI spec from the python metadata and runs a Swagger UI for interactive documentation.

Congrats you just created a simple API! You should see the interactive documentation in your web browser and you can test making an API call. As we make changes to the code and save the server will auto-reload but you may need to refresh the webpage if the documentation has changed.

CRUD with MongoDB

Now that we have our environment setup and API running lets take a look at implementing full CRUD (Create, Read, Update, Delete) functionality by creating some Todo APIs backed by a Mongo Database. Delete the initial read_root and read_item example endpoint functions.

Environment Setup

💡 Refer to Containers Demystified 🐳🤔 for a Docker container guide
and MongoDB Quick Start Guide 🍃⚡️ for a MongoDB Guide

Create a .env file to store our secrets so they are not exposed in our source code.

📝 .env

MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD=mySecureDbPassword1
MONGO_URI=mongodb://root:mySecureDbPassword1@localhost:27017/

Add the docker compose spec for the MongoDB.

📝 docker-compose.yml

services:
  db:
    image: mongo:7.0.1
    container_name: myAPIdb
    restart: always
    ports:
      - 27017:27017
    env_file:
      - .env
    volumes:
      - type: volume
        source: my_api_db_data
        target: /data/db

volumes:
  my_api_db_data:

Run the MongoDB with Docker Compose.

$ docker-compose up -d
[+] Building 0.0s (0/0)                               docker-container:unruffled_shockley
[+] Running 3/3
 ✔ Network fastapi-quick-start-guide_default          Created
 ✔ Volume "fastapi-quick-start-guide_my_api_db_data"  Created
 ✔ Container myAPIdb                                  Started

$ docker ps
CONTAINER ID   IMAGE         COMMAND                  CREATED         STATUS         PORTS                      NAMES
dfa4bbee67d3   mongo:7.0.1   "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes   0.0.0.0:27017->27017/tcp   myAPIdb

Now that we have our MongoDB running lets add the python dependencies to use the environment variables and connect to the MongoDB.

$ poetry add python-dotenv pydantic-settings motor
Using version ^1.0.0 for python-dotenv
Using version ^2.0.3 for pydantic-settings
Using version ^3.3.1 for motor

Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 4 installs, 0 updates, 0 removals

  • Installing dnspython (2.4.2)
  • Installing pymongo (4.5.0)
  • Installing motor (3.3.1)
  • Installing pydantic-settings (2.0.3)

Writing lock file

$ poetry add -G dev motor-types
Using version ^1.0.0b3 for motor-types

Updating dependencies
Resolving dependencies... (0.1s)

Package operations: 1 install, 0 updates, 0 removals

  • Installing motor-types (1.0.0b3)

Use Pydantic settings to load the Mongo URI from the .env environment variables and setup the connection to the MongoDB using Motor which is an asynchronous driver since we will be using async functions.

📝 main.py

import uvicorn
from fastapi import FastAPI
from motor.motor_asyncio import AsyncIOMotorClient
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    mongo_uri: str
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

db_client = AsyncIOMotorClient(settings.mongo_uri)
db = db_client.todoDb

app = FastAPI()

...

Create

The HTTP POST method is used to indicate that a user is creating something. Setup a POST route to create new todo entries. FastAPI is model driven and uses Pydantic Models which are Python classes to define and validate data types.

📝 main.py

from datetime import datetime
from pydantic import BaseModel
...

class Todo(BaseModel):
    title: str
    completed: bool = False

class TodoId(BaseModel):
    id: str

@app.post("/todos", response_model=TodoId)
async def create_todo(payload: Todo) -> TodoId:
    """
    Create a new Todo
    """
    now = datetime.utcnow()
    insert_result = await db.todos.insert_one(
        {
            "title": payload.title,
            "completed": payload.completed,
            "created_date": now,
            "updated_date": now,
        }
    )

    return TodoId(id=str(insert_result.inserted_id))

In the Swagger documentation we can see the new endpoint we just wrote along with the schemas which were derived from the Pydantic models. Test it out to make sure the todo item is inserted successfully and we should see the Todo ID returned in the response.

Read

The HTTP GET method is used to indicate that a user is requesting data from the server. Lets setup two GET routes one for fetching a list of records and one for fetching a single record. For the response data model TodoRecord we can use inheritance to use the fields from the TodoId and Todo models.

📝 main.py

...
class Todo(BaseModel):
    title: str
    completed: bool = False

class TodoId(BaseModel):
    id: str

class TodoRecord(TodoId, Todo):
    created_date: datetime
    updated_date: datetime

@app.get("/todos", response_model=list[TodoRecord])
async def get_todos() -> list[TodoRecord]:
    """
    Get Todos
    """
    todos: list[TodoRecord] = []
    async for doc in db.todos.find():
        todos.append(
            TodoRecord(
                id=str(doc["_id"]),
                title=doc["title"],
                completed=doc["completed"],
                created_date=doc["created_date"],
                updated_date=doc["updated_date"],
            )
        )

    return todos
...

For fetching a single record we will need to take in the todo id from a user and since this will be a Mongo ObjectId we will need to make sure it is valid when it is passed in. FastAPI and Pydantic offer a few field type objects to add additional metadata and validation. In this case we can use Path which allows us to give a description as well as add regex validation to make sure it is in valid ObjectId format.

📝 main.py

...
MONGO_ID_REGEX = r"^[a-f\d]{24}$"

@app.get("/todos/{id}", response_model=TodoRecord)
async def get_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX)
) -> TodoRecord:
    """
    Get a Todo
    """
    doc = await db.todos.find_one({"_id": ObjectId(id)})

    return TodoRecord(
        id=str(doc["_id"]),
        title=doc["title"],
        completed=doc["completed"],
        created_date=doc["created_date"],
        updated_date=doc["updated_date"],
    )
...

HTTP has well defined response codes that are returned to indicate the status of a request. Typically a code in the 200s is successful, 400s is handled exceptions and 500s are server side errors or unhandled exceptions. FastAPI includes HTTPException which allows known exceptions to be caught and a valid status code and helpful error message to be returned to the user. In this case when an ID is provided but not found in the database we can return an HTTP 404 Not Found status with some details indicating that a Todo with the provided ID does not exist.

📝 main.py

from fastapi import FastAPI, HTTPException, Path
...

class NotFoundException(BaseModel):
    detail: str = "Not Found"

MONGO_ID_REGEX = r"^[a-f\d]{24}$"

@app.get(
    "/todos/{id}",
    response_model=TodoRecord,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def get_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX)
) -> TodoRecord:
    """
    Get a Todo
    """
    doc = await db.todos.find_one({"_id": ObjectId(id)})
    if not doc:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoRecord(
        id=str(doc["_id"]),
        title=doc["title"],
        completed=doc["completed"],
        created_date=doc["created_date"],
        updated_date=doc["updated_date"],
    )

Validate this is working as expected with a valid id and an unknown id.

Update

The HTTP PUT and PATCH methods are used to update data. PUT requires the full payload record to be sent for the update where as PATCH allows partial updates. Lets add a PUT route which combines the functionality from the get one todo with passing the Todo Id in the path along with the create todo where we provide a body payload with our updates.

📝 main.py

@app.put(
    "/todos/{id}",
    response_model=TodoId,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def update_todo(
    payload: Todo,
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> TodoId:
    """
    Update a Todo
    """
    now = datetime.utcnow()
    update_result = await db.todos.update_one(
        {"_id": ObjectId(id)},
        {
            "$set": {
                "title": payload.title,
                "completed": payload.completed,
                "updated_date": now,
            }
        },
    )

    if update_result.matched_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoId(id=id)

Delete

The HTTP DELETE method is used to delete data and follows the same pattern with using the ID within the URL path.

📝 main.py

@app.delete(
    "/todos/{id}",
    response_model=bool,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def delete_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> bool:
    """
    Delete a Todo
    """
    delete_result = await db.todos.delete_one({"_id": ObjectId(id)})

    if delete_result.deleted_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return True

Full CRUD Functionality

This covers full CRUD (Create, Read, Update, Delete) functionality for working with our todo data and our python file should now look like this.

📝 main.py

from datetime import datetime

import uvicorn
from bson import ObjectId
from fastapi import FastAPI, HTTPException, Path
from motor.motor_asyncio import AsyncIOMotorClient
from pydantic import BaseModel
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    mongo_uri: str
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

db_client = AsyncIOMotorClient(settings.mongo_uri)
db = db_client.todoDb
app = FastAPI()

MONGO_ID_REGEX = r"^[a-f\d]{24}$"

class Todo(BaseModel):
    title: str
    completed: bool = False

class TodoId(BaseModel):
    id: str

class TodoRecord(TodoId, Todo):
    created_date: datetime
    updated_date: datetime

class NotFoundException(BaseModel):
    detail: str = "Not Found"

@app.post("/todos", response_model=TodoId)
async def create_todo(payload: Todo) -> TodoId:
    """
    Create a new Todo
    """
    now = datetime.utcnow()
    insert_result = await db.todos.insert_one(
        {
            "title": payload.title,
            "completed": payload.completed,
            "created_date": now,
            "updated_date": now,
        }
    )

    return TodoId(id=str(insert_result.inserted_id))

@app.get(
    "/todos/{id}",
    response_model=TodoRecord,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def get_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX)
) -> TodoRecord:
    """
    Get a Todo
    """
    doc = await db.todos.find_one({"_id": ObjectId(id)})
    if not doc:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoRecord(
        id=str(doc["_id"]),
        title=doc["title"],
        completed=doc["completed"],
        created_date=doc["created_date"],
        updated_date=doc["updated_date"],
    )

@app.get("/todos", response_model=list[TodoRecord])
async def get_todos() -> list[TodoRecord]:
    """
    Get Todos
    """
    todos: list[TodoRecord] = []
    async for doc in db.todos.find():
        todos.append(
            TodoRecord(
                id=str(doc["_id"]),
                title=doc["title"],
                completed=doc["completed"],
                created_date=doc["created_date"],
                updated_date=doc["updated_date"],
            )
        )

    return todos

@app.put(
    "/todos/{id}",
    response_model=TodoId,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def update_todo(
    payload: Todo,
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> TodoId:
    """
    Update a Todo
    """
    now = datetime.utcnow()
    update_result = await db.todos.update_one(
        {"_id": ObjectId(id)},
        {
            "$set": {
                "title": payload.title,
                "completed": payload.completed,
                "updated_date": now,
            }
        },
    )

    if update_result.matched_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoId(id=id)

@app.delete(
    "/todos/{id}",
    response_model=bool,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def delete_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> bool:
    """
    Delete a Todo
    """
    delete_result = await db.todos.delete_one({"_id": ObjectId(id)})

    if delete_result.deleted_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return True

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Utilities

Metadata

The Swagger OpenAPI docs that we have been working with are what people will reference when using our API so it is useful to have it display relevant information. With the base FastAPI app object we can set the API title, version and description which supports markdown and update the Docs location which we will change to the base path /. Additionally a root_path can be set in case your API is behind a reverse proxy at a subpath such as /api but in this case we will be running the API directly and it will be at the root path.

📝 main.py

...
class Settings(BaseSettings):
    mongo_uri: str
    root_path: str = ""
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

db_client = AsyncIOMotorClient(settings.mongo_uri)
db = db_client.todoDb

description = """
This is a fancy API built with [FastAPI🚀](https://fastapi.tiangolo.com/)

📝 [Source Code](https://github.com/dpills/fastapi-prod-guide)  
🐞 [Issues](https://github.com/dpills/fastapi-prod-guide/issues) 
"""
app = FastAPI(
    title="My Todo App",
    description=description,
    version="1.0.0",
    docs_url="/",
    root_path=settings.root_path,
)
...

Open your browser to http://localhost:8000/ since we changed the docs_url and we now see our metadata show up!

Logging

All applications require logging to properly troubleshoot issues and it is a good idea to use the python logging module or a logging library. We can set the format and make use of logging levels which we can set via our environment variable settings so we can adjust it without changing our source code in different environments.

📝 main.py

import logging
import sys
...
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    mongo_uri: str
    root_path: str = ""
    logging_level: str = "INFO"
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

logging.basicConfig(
    stream=sys.stdout,
    level=settings.logging_level,
    format="[%(asctime)s] %(levelname)s [%(name)s.%(funcName)s:%(lineno)d] %(message)s",  # noqa: E501
    datefmt="%d/%b/%Y %H:%M:%S",
)
logger = logging.getLogger("my-todos")
...

Middleware

Middleware in APIs is useful to avoid duplicating logic required on every endpoint such as CORS, performance metadata or request logging.

Enabling CORS (Cross Origin Resource Sharing) on APIs is required when you want to allow a website hosted on another domain to directly call your API from their Website. For example If I hosted a Frontend React Web App on my-app.com and wanted it to call my API hosted on my-api.com then I would need to add my-app.com to the Allowed Origins. Luckily this is a very common middleware and FastAPI includes support for it out of the box.

📝 main.py

from fastapi.middleware.cors import CORSMiddleware
...
app = FastAPI(
    title="My Todo App",
    description=description,
    version="1.0.0",
    docs_url="/",
    root_path=settings.root_path,
)
app.add_middleware(
    CORSMiddleware,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    allow_origins=[
        "http://localhost:3000",
    ],
)

Middleware can also run before and after an API function executes which allows us to track the performance and return it in the response header along with logging the request information to the console which can be later be used for troubleshooting and metrics.

📝 main.py

import time
...
from typing import Any, Callable, TypeVar
...
from fastapi import FastAPI, HTTPException, Path, Request, Response
...

F = TypeVar("F", bound=Callable[..., Any])

@app.middleware("http")
async def process_time_log_middleware(request: Request, call_next: F) -> Response:
    """
    Add API process time in response headers and log calls
    """
    start_time = time.time()
    response: Response = await call_next(request)
    process_time = str(round(time.time() - start_time, 3))
    response.headers["X-Process-Time"] = process_time

    logger.info(
        "Method=%s Path=%s StatusCode=%s ProcessTime=%s",
        request.method,
        request.url.path,
        response.status_code,
        process_time,
    )

    return response
...

We now see our middleware logging when making calls.

INFO:     127.0.0.1:60005 - "GET /todos HTTP/1.1" 200 OK
[15/Oct/2023 09:31:52] INFO [my-todos.process_time_log_middleware:91] Method=GET Path=/todos StatusCode=200 ProcessTime=0.004

💡 Refer to How to rate limit FastAPI with Redis 📈 to see how to add rate limiting middleware

CRUD APIs With Utilities

📝 main.py

import logging
import sys
import time
from datetime import datetime
from typing import Any, Callable, TypeVar

import uvicorn
from bson import ObjectId
from fastapi import FastAPI, HTTPException, Path, Request, Response
from fastapi.middleware.cors import CORSMiddleware
from motor.motor_asyncio import AsyncIOMotorClient
from pydantic import BaseModel
from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    mongo_uri: str
    root_path: str = ""
    logging_level: str = "INFO"
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

logging.basicConfig(
    stream=sys.stdout,
    level=settings.logging_level,
    format="[%(asctime)s] %(levelname)s [%(name)s.%(funcName)s:%(lineno)d] %(message)s",  # noqa: E501
    datefmt="%d/%b/%Y %H:%M:%S",
)
logger = logging.getLogger("my-todos")

db_client = AsyncIOMotorClient(settings.mongo_uri)
db = db_client.todoDb

description = """
This is a fancy API built with [FastAPI🚀](https://fastapi.tiangolo.com/)

📝 [Source Code](https://github.com/dpills/fastapi-prod-guide)  
🐞 [Issues](https://github.com/dpills/fastapi-prod-guide/issues) 
"""
app = FastAPI(
    title="My Todo App",
    description=description,
    version="1.0.0",
    docs_url="/",
    root_path=settings.root_path,
)
app.add_middleware(
    CORSMiddleware,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    allow_origins=[
        "http://localhost:3000",
    ],
)

MONGO_ID_REGEX = r"^[a-f\d]{24}$"
F = TypeVar("F", bound=Callable[..., Any])

class Todo(BaseModel):
    title: str
    completed: bool = False

class TodoId(BaseModel):
    id: str

class TodoRecord(TodoId, Todo):
    created_date: datetime
    updated_date: datetime

class NotFoundException(BaseModel):
    detail: str = "Not Found"

@app.middleware("http")
async def process_time_log_middleware(request: Request, call_next: F) -> Response:
    """
    Add API process time in response headers and log calls
    """
    start_time = time.time()
    response: Response = await call_next(request)
    process_time = str(round(time.time() - start_time, 3))
    response.headers["X-Process-Time"] = process_time

    logger.info(
        "Method=%s Path=%s StatusCode=%s ProcessTime=%s",
        request.method,
        request.url.path,
        response.status_code,
        process_time,
    )

    return response

@app.post("/todos", response_model=TodoId)
async def create_todo(payload: Todo) -> TodoId:
    """
    Create a new Todo
    """
    now = datetime.utcnow()
    insert_result = await db.todos.insert_one(
        {
            "title": payload.title,
            "completed": payload.completed,
            "created_date": now,
            "updated_date": now,
        }
    )

    return TodoId(id=str(insert_result.inserted_id))

@app.get(
    "/todos/{id}",
    response_model=TodoRecord,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def get_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX)
) -> TodoRecord:
    """
    Get a Todo
    """
    doc = await db.todos.find_one({"_id": ObjectId(id)})
    if not doc:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoRecord(
        id=str(doc["_id"]),
        title=doc["title"],
        completed=doc["completed"],
        created_date=doc["created_date"],
        updated_date=doc["updated_date"],
    )

@app.get("/todos", response_model=list[TodoRecord])
async def get_todos() -> list[TodoRecord]:
    """
    Get Todos
    """
    todos: list[TodoRecord] = []
    async for doc in db.todos.find():
        todos.append(
            TodoRecord(
                id=str(doc["_id"]),
                title=doc["title"],
                completed=doc["completed"],
                created_date=doc["created_date"],
                updated_date=doc["updated_date"],
            )
        )

    return todos

@app.put(
    "/todos/{id}",
    response_model=TodoId,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def update_todo(
    payload: Todo,
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> TodoId:
    """
    Update a Todo
    """
    now = datetime.utcnow()
    update_result = await db.todos.update_one(
        {"_id": ObjectId(id)},
        {
            "$set": {
                "title": payload.title,
                "completed": payload.completed,
                "updated_date": now,
            }
        },
    )

    if update_result.matched_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoId(id=id)

@app.delete(
    "/todos/{id}",
    response_model=bool,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def delete_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> bool:
    """
    Delete a Todo
    """
    delete_result = await db.todos.delete_one({"_id": ObjectId(id)})

    if delete_result.deleted_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return True

if __name__ == "__main__":
    uvicorn.run(
        "main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Organization

As we continue to add features to our API and adding functions and routes is has made our single main.py file difficult to manage. Un-organized and low quality standards on code make it difficult to maintain in the long term so we will take a look at adding better standards and organization to our API.

APIRouters

For larger projects FastAPI includes the concept of routers to create sections of an API, The main change is within the subsection you create the an router object and then the routes use @router.get syntax instead of @app.get. Then the router for a section can be imported and included in the app with a tag category and prefix. We will use this pattern to restructure our API.

Project Structure

Move all environment variables to the central config file.

📝 app/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    mongo_uri: str
    root_path: str = ""
    logging_level: str = "INFO"
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

Add global static values that may be re-used in multiple places of the API.

📝 app/static_values.py

MONGO_ID_REGEX = r"^[a-f\d]{24}$"

Move the database connection object creation and logging handler to the utilities folder

📝 app/utilities/db.py

from motor.motor_asyncio import AsyncIOMotorClient

from app.config import settings

db_client = AsyncIOMotorClient(settings.mongo_uri)
db = db_client.todoDb

📝 app/utilities/logger.py

import logging
import sys

from app.config import settings

logging.basicConfig(
    stream=sys.stdout,
    level=settings.logging_level,
    format="[%(asctime)s] %(levelname)s [%(name)s.%(funcName)s:%(lineno)d] %(message)s",  # noqa: E501
    datefmt="%d/%b/%Y %H:%M:%S",
)
logger = logging.getLogger("my-todos")

Move models into their own file in the associated todos API route.

📝 app/routers/todos/models.py

from datetime import datetime

from pydantic import BaseModel

class Todo(BaseModel):
    title: str
    completed: bool = False

class TodoId(BaseModel):
    id: str

class TodoRecord(TodoId, Todo):
    created_date: datetime
    updated_date: datetime

class NotFoundException(BaseModel):
    detail: str = "Not Found"

Move all of the todo related functions into their router files. We will switch to using routers with the @router syntax and also adjust the paths so we can add /v1/todos prefixes when we include the router in the main app.

📝 app/routers/todos/todos.py

from datetime import datetime

from bson import ObjectId
from fastapi import APIRouter, HTTPException, Path

from app.static_values import MONGO_ID_REGEX
from app.utilities.db import db

from .models import NotFoundException, Todo, TodoId, TodoRecord

router = APIRouter()

@router.post("", response_model=TodoId)
async def create_todo(payload: Todo) -> TodoId:
    """
    Create a new Todo
    """
    now = datetime.utcnow()
    insert_result = await db.todos.insert_one(
        {
            "title": payload.title,
            "completed": payload.completed,
            "created_date": now,
            "updated_date": now,
        }
    )

    return TodoId(id=str(insert_result.inserted_id))

@router.get(
    "/{id}",
    response_model=TodoRecord,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def get_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX)
) -> TodoRecord:
    """
    Get a Todo
    """
    doc = await db.todos.find_one({"_id": ObjectId(id)})
    if not doc:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoRecord(
        id=str(doc["_id"]),
        title=doc["title"],
        completed=doc["completed"],
        created_date=doc["created_date"],
        updated_date=doc["updated_date"],
    )

@router.get("", response_model=list[TodoRecord])
async def get_todos() -> list[TodoRecord]:
    """
    Get Todos
    """
    todos: list[TodoRecord] = []
    async for doc in db.todos.find():
        todos.append(
            TodoRecord(
                id=str(doc["_id"]),
                title=doc["title"],
                completed=doc["completed"],
                created_date=doc["created_date"],
                updated_date=doc["updated_date"],
            )
        )

    return todos

@router.put(
    "/{id}",
    response_model=TodoId,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def update_todo(
    payload: Todo,
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> TodoId:
    """
    Update a Todo
    """
    now = datetime.utcnow()
    update_result = await db.todos.update_one(
        {"_id": ObjectId(id)},
        {
            "$set": {
                "title": payload.title,
                "completed": payload.completed,
                "updated_date": now,
            }
        },
    )

    if update_result.matched_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return TodoId(id=id)

@router.delete(
    "/{id}",
    response_model=bool,
    responses={
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def delete_todo(
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> bool:
    """
    Delete a Todo
    """
    delete_result = await db.todos.delete_one({"_id": ObjectId(id)})

    if delete_result.deleted_count == 0:
        raise HTTPException(status_code=404, detail="Not Found")

    return True

Finally we will import our API router and include them in our FastAPI App and adjust our uvicorn run function to point to our new app path app.main:app.

📝 app/main.py

import time
from typing import Any, Callable, TypeVar

import uvicorn
from fastapi import FastAPI, Request, Response
from fastapi.middleware.cors import CORSMiddleware

from app.config import settings
from app.routers.todos import todos
from app.utilities.logger import logger

description = """
This is a fancy API built with [FastAPI🚀](https://fastapi.tiangolo.com/)

📝 [Source Code](https://github.com/dpills/fastapi-prod-guide)  
🐞 [Issues](https://github.com/dpills/fastapi-prod-guide/issues) 
"""
app = FastAPI(
    title="My Todo App",
    description=description,
    version="1.0.0",
    docs_url="/",
    root_path=settings.root_path,
)
app.add_middleware(
    CORSMiddleware,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
    allow_origins=[
        "http://localhost:3000",
    ],
)

F = TypeVar("F", bound=Callable[..., Any])

@app.middleware("http")
async def process_time_log_middleware(request: Request, call_next: F) -> Response:
    """
    Add API process time in response headers and log calls
    """
    start_time = time.time()
    response: Response = await call_next(request)
    process_time = str(round(time.time() - start_time, 3))
    response.headers["X-Process-Time"] = process_time

    logger.info(
        "Method=%s Path=%s StatusCode=%s ProcessTime=%s",
        request.method,
        request.url.path,
        response.status_code,
        process_time,
    )

    return response

app.include_router(
    todos.router,
    prefix="/v1/todos",
    tags=["todos"],
)

if __name__ == "__main__":
    uvicorn.run(
        "app.main:app",
        host="0.0.0.0",
        port=8000,
        log_level="debug",
        reload=True,
    )

Now that we have updated our project structure we can run our app from the base project folder using the -m python flag.

$ python3 -m app.main
INFO:     Will watch for changes in these directories: ['/Users/dpills/articles/fastapi-quick-start-guide']
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [96492] using WatchFiles
INFO:     Started server process [96494]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

The API documentation now include the /v1/todos prefixes along with the todos category section thanks to the router tags.

Security

Up until this point our API has not had any authentication or authorization built in which leaves it vulnerable and makes it to where all usage is anonymous and we cannot differentiate per user actions. It is important to build in modern auth mechanisms with a common option being Oauth2 using Bearer tokens. There are many different Oauth2 identity providers and depending on how you deploy your application you can take advantage of integrated auth services, you could have a reverse proxy like NGINX in front of your API which handles the auth or you can build the auth directly into your application code. We will be building the auth directly into our API utilizing Github Oauth and an Authorization Code flow.

https://blog.oauth.io/introduction-oauth2-flow-diagrams/

GitHub Oauth Setup

Navigate to the GitHub Oauth Apps developer settings at https://github.com/settings/developers and create a new oauth app.

Then generate the secret after the app creation.

Add the client id and secret to our .env file.

📝 .env

MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD=mySecureDbPassword1
MONGO_URI=mongodb://root:mySecureDbPassword1@localhost:27017/
GITHUB_OAUTH_CLIENT_ID=0ec7d96992836a5fbb98
GITHUB_OAUTH_CLIENT_SECRET=e813b0cdb4d402d55d5d09cfd08dfd06xxxxxxxx

As well as the config settings so we can use them in our API.

📝 app/config.py

...
class Settings(BaseSettings):
    mongo_uri: str
    github_oauth_client_id: str
    github_oauth_client_secret: str
    root_path: str = ""
    logging_level: str = "INFO"
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
...

Oauth Callback

We will need to make HTTP calls to Github to get a users access token and username. The most popular HTTP Python library is Requests but since we are using asynchronous functions we will use the HTTPX library which has async support.

$ poetry add httpx
Using version ^0.25.0 for httpx

Updating dependencies
Resolving dependencies... (0.2s)

No dependencies to install or update

Writing lock file

Add a new auth router folder and setup the oauth callback endpoint.

Users will need to navigate to https://github.com/login/oauth/authorize?client_id=GITHUB_OAUTH_CLIENT_ID&redirect_uri=http://localhost:8000/v1/auth/callback with your apps client id in order to authorize it to receive their access token and get their identity. It will redirect back to our endpoint with a code in the URL parameter /v1/auth/callback?code=xxxx and we can use this code to get the user’s access token and username. We can then add the user to our database with a secure SHA-256 hash of their access token which we can use to lookup the user in the future.

📝 app/routers/auth/models.py

from pydantic import BaseModel

class OauthException(BaseModel):
    detail: str

class OauthToken(BaseModel):
    access_token: str

The Oauth code will be sent back to our endpoint

📝 app/routers/auth/auth.py

import hashlib
from datetime import datetime

import httpx
from fastapi import APIRouter, HTTPException, Query

from app.config import settings
from app.utilities.db import db

from .models import OauthException, OauthToken

router = APIRouter()

@router.get(
    "/callback",
    response_model=OauthToken,
    responses={
        400: {"description": "Oauth Error", "model": OauthException},
    },
)
async def oauth_callback(
    code: str = Query(description="Authorization Code"),
) -> OauthToken:
    """
    GitHub Oauth Integration Callback
    """
    async with httpx.AsyncClient() as client:
        token_result = await client.post(
            "https://github.com/login/oauth/access_token",
            json={
                "client_id": settings.github_oauth_client_id,
                "client_secret": settings.github_oauth_client_secret,
                "code": code,
                "redirect_uri": "http://localhost:8000/v1/auth/callback",
            },
            headers={"Accept": "application/json"},
        )
        data = token_result.json()
        error = data.get("error")
        if error:
            raise HTTPException(
                status_code=400,
                detail=f"{data.get('error')}: {data.get('error_description')}",
            )

        access_token: str = data.get("access_token")
        user_result = await client.get(
            "https://api.github.com/user",
            headers={"Authorization": f"Bearer {access_token}"},
        )
        user_data = user_result.json()
        user = user_data.get("login")

    await db.tokens.insert_one(
        {
            "user": user,
            "access_token_hash": hashlib.sha256(access_token.encode()).hexdigest(),
            "created_date": datetime.utcnow(),
        },
    )

    return OauthToken(access_token=access_token)

Include the new auth router in our [main.py](http://main.py) file and include the Github authorization link in our API description.

📝 app/main.py

...
from app.routers.auth import auth
...

description = f"""
This is a fancy API built with [FastAPI🚀](https://fastapi.tiangolo.com/)

Authorize to get an Access Token from GitHub at <https://github.com/login/oauth/authorize?client_id={settings.github_oauth_client_id}&redirect_uri=http://localhost:8000/v1/auth/callback>

📝 [Source Code](https://github.com/dpills/fastapi-prod-guide)  
🐞 [Issues](https://github.com/dpills/fastapi-prod-guide/issues) 
"""

...

app.include_router(
    auth.router,
    prefix="/v1/auth",
    tags=["auth"],
)
...

You can now test navigating to the Github authorization link in the API description and validate that a Access Token is returned.

{
  "access_token": "gho_aBplc0MVRPFeeyE95UJPg209LRSp7V1xxxxx"
}

Validating an Access Token

Create a function in the auth file to take in an access token check our DB cache if we know the user else validate it against the Github API and if it is still invalid raise a 401 error.

📝 app/routers/auth/auth.py

from typing import Annotated
...
from fastapi import APIRouter, Depends, HTTPException, Query
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
...

router = APIRouter()
security = HTTPBearer()
...

async def validate_access_token(
    access_token: Annotated[HTTPAuthorizationCredentials, Depends(security)]
) -> str:
    """
    Validate an access token
    Returns the username or raises a 401 HTTPException
    """
    access_token_hash = hashlib.sha256(access_token.credentials.encode()).hexdigest()
    cached_token = await db.tokens.find_one({"access_token_hash": access_token_hash})

    if cached_token:
        user: str | None = cached_token.get("user")
        if user:
            return user

    async with httpx.AsyncClient() as client:
        user_result = await client.get(
            "https://api.github.com/user",
            headers={"Authorization": f"Bearer {access_token.credentials}"},
        )

        if user_result.status_code == 200:
            user_data = user_result.json()
            user = user_data.get("login")
            if user:
                await db.tokens.insert_one(
                    {
                        "user": user,
                        "access_token_hash": access_token_hash,
                        "created_date": datetime.utcnow(),
                    },
                )
                return user

    raise HTTPException(
        status_code=401,
        detail="Unauthorized",
    )

Since we will be looking up access token hashes in the MongoDB we can use a mongosh shell to add a unique index to that field to make it more performant. We can also add a TTL Index so that we on only cache tokens for 24 hours.

> use todoDb
switched to db todoDb

> db.tokens.createIndex( { "access_token_hash": 1 }, { unique: true } )
access_token_hash_1

> db.tokens.createIndex( { "created_date": 1 }, { expireAfterSeconds: 86400 } )
created_date_1

💡 Refer to MongoDB Quick Start Guide 🍃⚡️ for a MongoDB Guide

Add Bearer Token Authorization to Endpoints

Add the Bearer token auth and the validate_access_token function to the todos endpoints.

📝 app/routers/todos/todos.py

...
from typing import Annotated
...
from fastapi import APIRouter, Depends, HTTPException, Path
from fastapi.security import (
    HTTPAuthorizationCredentials,
    HTTPBearer,
)

from app.routers.auth.auth import validate_access_token
from app.routers.auth.models import UnauthorizedException
...

security = HTTPBearer()

@router.post(
    "",
    response_model=TodoId,
    responses={
        401: {"description": "Unauthorized", "model": UnauthorizedException},
    },
)
async def create_todo(
    access_token: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    user: Annotated[str, Depends(validate_access_token)],
    payload: Todo,
) -> TodoId:
...

@router.get(
    "/{id}",
    response_model=TodoRecord,
    responses={
        401: {"description": "Unauthorized", "model": UnauthorizedException},
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def get_todo(
    access_token: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    user: Annotated[str, Depends(validate_access_token)],
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> TodoRecord:
...

@router.get(
    "",
    response_model=list[TodoRecord],
    responses={
        401: {"description": "Unauthorized", "model": UnauthorizedException},
    },
)
async def get_todos(
    access_token: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    user: Annotated[str, Depends(validate_access_token)],
) -> list[TodoRecord]:
...

@router.put(
    "/{id}",
    response_model=TodoId,
    responses={
        401: {"description": "Unauthorized", "model": UnauthorizedException},
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def update_todo(
    access_token: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    user: Annotated[str, Depends(validate_access_token)],
    payload: Todo,
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> TodoId:
...

@router.delete(
    "/{id}",
    response_model=bool,
    responses={
        401: {"description": "Unauthorized", "model": UnauthorizedException},
        404: {"description": "Not Found", "model": NotFoundException},
    },
)
async def delete_todo(
    access_token: Annotated[HTTPAuthorizationCredentials, Depends(security)],
    user: Annotated[str, Depends(validate_access_token)],
    id: str = Path(description="Todo ID", pattern=MONGO_ID_REGEX),
) -> bool:
...

Validate that the auth is working correctly.

$ curl -v http://localhost:8000/v1/todos
< HTTP/1.1 403 Forbidden
{
  "detail": "Not authenticated"
}

$ curl -v http://localhost:8000/v1/todos -H 'Authorization: Bearer BAD_TOKEN'
< HTTP/1.1 401 Unauthorized
{
  "detail": "Unauthorized"
}

$ curl -v http://localhost:8000/v1/todos -H 'Authorization: Bearer gho_aBplc0MVRPFeeyE95UJPg209LRSp7V1xxxxx'
< HTTP/1.1 200 OK
[
  {
    "title": "Create CRUD APIs",
    "completed": true,
    "id": "652bddc9a09fc3e748c3d5e7",
    "created_date": "2023-10-15T12:40:41.191000",
    "updated_date": "2023-10-15T12:42:19.153000"
  }
]

The todo endpoints will show a lock icon in the swagger does now as well.

Integrate User Info

Up until this point we have been storing our todo records without usernames which is fine for a single user but in order to support multiple users we need to track which user owns a record. Then we can also odd in logic into our Read, Update and Delete endpoints to allow users to only fetch, modify and delete their own todos.

📝 app/routers/todos/models.py

...
class TodoRecord(TodoId, Todo):
    user: str
    created_date: datetime
    updated_date: datetime
...

📝 app/routers/todos/todos.py

...
async def create_todo(
...
    insert_result = await db.todos.insert_one(
        {
            "title": payload.title,
            "completed": payload.completed,
            "user": user,
            "created_date": now,
            "updated_date": now,
        }
    )
...

async def get_todo(
...
    doc = await db.todos.find_one({"_id": ObjectId(id), "user": user})
        ...
    return TodoRecord(
        id=str(doc["_id"]),
        title=doc["title"],
        completed=doc["completed"],
        user=doc["user"],
        created_date=doc["created_date"],
        updated_date=doc["updated_date"],
    )
...

async def get_todos(
...
    async for doc in db.todos.find({"user": user}):
        todos.append(
            TodoRecord(
                id=str(doc["_id"]),
                title=doc["title"],
                completed=doc["completed"],
                user=doc["user"],
                created_date=doc["created_date"],
                updated_date=doc["updated_date"],
            )
        )
...

async def update_todo(
...
    update_result = await db.todos.update_one(
        {"_id": ObjectId(id), "user": user},
        {
            "$set": {
                "title": payload.title,
                "completed": payload.completed,
                "updated_date": now,
            }
        },
    )
...

async def delete_todo(
...
    delete_result = await db.todos.delete_one({"_id": ObjectId(id), "user": user})
...

Delete any existing todo entries from the database and test out creating and fetching a new todo record.

Since we are doing Mongo lookups with the new user field, add indexes for that field so it is more performant.

> use todoDb
switched to db todoDb

> db.todos.createIndex( { "user": 1 })
user_1

> db.todos.createIndex( { "_id": 1, "user": 1 })
_id_1_user_1

Testing

Testing is critical to make sure your API or Application is working correctly and setting up automated testing before merging or deploying updates gives you the confidence that nothing has broken which allows you to push releases more frequently. There are many different categories of testing but we will take a look at implementing unit tests and integration tests and verifying our code coverage.

Test Environment Setup

Add the test, coverage and mock libraries.

$ poetry add -G dev pytest coverage mongomock-motor pytest_httpx pytest-asyncio
Using version ^7.4.2 for pytest
Using version ^7.3.2 for coverage
Using version ^0.0.21 for mongomock-motor
Using version ^0.21.1 for pytest-asyncio

Updating dependencies
Resolving dependencies... (0.3s)

Package operations: 9 installs, 0 updates, 0 removals

  • Installing iniconfig (2.0.0)
  • Installing pluggy (1.3.0)
  • Installing sentinels (1.0.0)
  • Installing mongomock (4.1.2)
  • Installing pytest (7.4.2)
  • Installing coverage (7.3.2)
  • Installing mongomock-motor (0.0.21)
  • Installing pytest-asyncio (0.21.1)

Add a testing boolean to the settings so we can indicate we are running tests within the app.

📝 app/config.py

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    mongo_uri: str
    github_oauth_client_id: str
    github_oauth_client_secret: str
    root_path: str = ""
    logging_level: str = "INFO"
    testing: bool = False
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")

settings = Settings()

Update the Database file to use the testing setting to indicate whether we should load our mock in-memory MongoDB or the actual MongoDB connection.

📝 app/utilities/db.py

from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase

from app.config import settings

def get_db() -> AsyncIOMotorDatabase:
    """
    Get MongoDB
    """
    if settings.testing:
        from mongomock_motor import AsyncMongoMockClient

        mock_db: AsyncIOMotorDatabase = AsyncMongoMockClient().todoDb
        return mock_db
    else:
        return AsyncIOMotorClient(settings.mongo_uri).todoDb

db = get_db()

Add a conftest.py file which is used for global testing configs, we will setup the event loop, instantiate our test client and add a test user to our mock database so we can properly test authenticated endpoints.

📝 app/conftest.py

import asyncio
import hashlib
from datetime import datetime
from typing import Any, Generator

import pytest
from httpx import AsyncClient

from app.main import app
from app.utilities.db import db

async def add_db_test_user() -> None:
    """
    Add test user to Database
    """
    await db.tokens.update_one(
        {"user": "tester"},
        {
            "$set": {
                "access_token_hash": hashlib.sha256("GOOD_TOKEN".encode()).hexdigest(),
                "created_date": datetime.utcnow(),
            }
        },
        upsert=True,
    )

    return None

@pytest.fixture(scope="session")
def event_loop() -> Generator[asyncio.AbstractEventLoop, Any, None]:
    """
    Override Event Loop
    """
    try:
        loop = asyncio.get_running_loop()
    except RuntimeError:
        loop = asyncio.new_event_loop()

    # Add test user to DB
    loop.run_until_complete(add_db_test_user())

    yield loop
    loop.close()

@pytest.fixture()
def test_client() -> AsyncClient:
    """
    Create an instance of the client
    """
    return AsyncClient(app=app, base_url="http://test", follow_redirects=True)

Adding Tests

We can now add tests to our todo endpoints.

📝 app/routers/todos/test_todos.py

import pytest
from httpx import AsyncClient

pytestmark = pytest.mark.asyncio
AUTH_HEADER = {"Authorization": "Bearer GOOD_TOKEN"}

async def test_create_todo(test_client: AsyncClient) -> None:
    """
    Test Creating a todo
    """
    # No Bearer Token
    r = await test_client.post("/v1/todos", json={"title": "test", "completed": False})
    assert r.status_code == 403

    # Invalid Bearer Token
    r = await test_client.post(
        "/v1/todos",
        json={"title": "test", "completed": False},
        headers={"Authorization": "Bearer BAD_TOKEN"},
    )
    assert r.status_code == 401

    # Valid Bearer Token
    r = await test_client.post(
        "/v1/todos",
        json={"title": "create_test", "completed": False},
        headers=AUTH_HEADER,
    )
    assert r.status_code == 200
    assert r.json().get("id")

async def test_get_todos(test_client: AsyncClient) -> None:
    """
    Test Fetching todos
    """
    # Get all Todos
    r = await test_client.get("/v1/todos", headers=AUTH_HEADER)
    assert r.status_code == 200
    results = r.json()
    assert results

    # Get single Todo
    todo_id = results[0].get("id")
    r = await test_client.get(f"/v1/todos/{todo_id}", headers=AUTH_HEADER)
    assert r.status_code == 200

    # Unknown Todo ID
    r = await test_client.get("/v1/todos/652d729bb8da04810695a943", headers=AUTH_HEADER)
    assert r.status_code == 404

async def test_update_todo(test_client: AsyncClient) -> None:
    """
    Test updating a todo
    """
    # Get all Todos
    r = await test_client.get("/v1/todos", headers=AUTH_HEADER)
    assert r.status_code == 200
    results = r.json()
    assert results

    # Update a Todo
    todo_id = results[0].get("id")
    r = await test_client.put(
        f"/v1/todos/{todo_id}",
        json={"title": "update_test", "completed": True},
        headers=AUTH_HEADER,
    )
    assert r.status_code == 200

    # Unknown Todo ID
    r = await test_client.put(
        "/v1/todos/652d729bb8da04810695a943",
        json={"title": "update_test", "completed": True},
        headers=AUTH_HEADER,
    )
    assert r.status_code == 404

async def test_delete_todo(test_client: AsyncClient) -> None:
    """
    Test deleting a todo
    """
    # Get all Todos
    r = await test_client.get("/v1/todos", headers=AUTH_HEADER)
    assert r.status_code == 200
    results = r.json()
    assert results

    # Delete a Todo
    todo_id = results[0].get("id")
    r = await test_client.delete(
        f"/v1/todos/{todo_id}",
        headers=AUTH_HEADER,
    )
    assert r.status_code == 200

    # Unknown Todo ID
    r = await test_client.delete(
        "/v1/todos/652d729bb8da04810695a943",
        headers=AUTH_HEADER,
    )
    assert r.status_code == 404

Run the test suite with the coverage and pytest command to generate coverage output. Make sure to set the TESTING environment variable at the start.

$ export TESTING=true && poetry run coverage run --source ./app -m pytest --disable-warnings
==================================================== test session starts =====================================================
platform darwin -- Python 3.11.4, pytest-7.4.2, pluggy-1.3.0
rootdir: /Users/depillsb/articles/fastapi-quick-start-guide
plugins: httpx-0.26.0, asyncio-0.21.1, anyio-3.7.1
asyncio: mode=Mode.STRICT
collected 4 items                                                                                                            

app/routers/todos/test_todos.py ....                                                                                   [100%]

================================================ 4 passed, 1 warning in 1.23s ================================================

$ poetry run coverage html
Wrote HTML report to htmlcov/index.html

Opening the generated htmlcov/index.html in a web browser shows the coverage percentage for the app and our todo endpoints should now be 100% covered!

Production Deployment

In development we have been using uvicorn which runs a single instance of our API but in production we can handle more load if we run multiple instances and load balance traffic against them and this is what gunicorn allows us to do. We can run gunicorn specifying the number of workers we want running and tell it to use uvicorn for the workers.

Install gunicorn and add a gunicorn_conf.py file to the project.

$ poetry add gunicorn
Using version ^21.2.0 for gunicorn

Updating dependencies
Resolving dependencies... (0.2s)

Package operations: 1 install, 0 updates, 0 removals

  • Installing gunicorn (21.2.0)

Writing lock file

📝 gunicorn_conf.py

import json
import multiprocessing
import os

workers_per_core_str = os.getenv("WORKERS_PER_CORE", "1")
max_workers_str = os.getenv("MAX_WORKERS", "10")
use_max_workers = None

if max_workers_str:
    use_max_workers = int(max_workers_str)

web_concurrency_str = os.getenv("WEB_CONCURRENCY", None)
host = os.getenv("HOST", "0.0.0.0")
port = os.getenv("PORT", "8000")
bind_env = os.getenv("BIND", None)
use_loglevel = os.getenv("LOG_LEVEL", "info")

if bind_env:
    use_bind = bind_env
else:
    use_bind = f"{host}:{port}"

cores = multiprocessing.cpu_count()
workers_per_core = float(workers_per_core_str)
default_web_concurrency = workers_per_core * cores

if web_concurrency_str:
    web_concurrency = int(web_concurrency_str)
    assert web_concurrency > 0
else:
    web_concurrency = max(int(default_web_concurrency), 2)
    if use_max_workers:
        web_concurrency = min(web_concurrency, use_max_workers)

accesslog_var = os.getenv("ACCESS_LOG", "-")
use_accesslog = accesslog_var or None
errorlog_var = os.getenv("ERROR_LOG", "-")
use_errorlog = errorlog_var or None
graceful_timeout_str = os.getenv("GRACEFUL_TIMEOUT", "60")
timeout_str = os.getenv("TIMEOUT", "60")
keepalive_str = os.getenv("KEEP_ALIVE", "5")

# Gunicorn config variables
worker_class = "app.workers.ConfigurableWorker"
loglevel = use_loglevel
workers = web_concurrency
bind = use_bind
errorlog = use_errorlog
worker_tmp_dir = "/tmp/shm"
accesslog = use_accesslog
graceful_timeout = int(graceful_timeout_str)
timeout = int(timeout_str)
keepalive = int(keepalive_str)

# For debugging and testing
log_data = {
    "loglevel": loglevel,
    "workers": workers,
    "bind": bind,
    "graceful_timeout": graceful_timeout,
    "timeout": timeout,
    "keepalive": keepalive,
    "errorlog": errorlog,
    "accesslog": accesslog,
    # Additional, non-gunicorn variables
    "workers_per_core": workers_per_core,
    "use_max_workers": use_max_workers,
    "host": host,
    "port": port,
}

print(json.dumps(log_data))

Running the app with Gunicorn runs 10 instances of the API and load balances across them.

$ gunicorn -k uvicorn.workers.UvicornWorker -c gunicorn_conf.py app.main:app
{"loglevel": "info", "workers": 10, "bind": "0.0.0.0:8000", "graceful_timeout": 60, "timeout": 60, "keepalive": 5, "errorlog": "-", "accesslog": "-", "workers_per_core": 1.0, "use_max_workers": 10, "host": "0.0.0.0", "port": "8000"}
[2023-10-15 14:51:23 -0400] [37562] [INFO] Starting gunicorn 21.2.0
[2023-10-15 14:51:23 -0400] [37562] [INFO] Listening at: http://0.0.0.0:8000 (37562)
[2023-10-15 14:51:23 -0400] [37562] [INFO] Using worker: uvicorn.workers.UvicornWorker
[2023-10-15 14:51:23 -0400] [37563] [INFO] Booting worker with pid: 37563
[2023-10-15 14:51:23 -0400] [37566] [INFO] Booting worker with pid: 37566
[2023-10-15 14:51:23 -0400] [37567] [INFO] Booting worker with pid: 37567
[2023-10-15 14:51:23 -0400] [37568] [INFO] Booting worker with pid: 37568
[2023-10-15 14:51:23 -0400] [37569] [INFO] Booting worker with pid: 37569
[2023-10-15 14:51:23 -0400] [37570] [INFO] Booting worker with pid: 37570
[2023-10-15 14:51:23 -0400] [37571] [INFO] Booting worker with pid: 37571
[2023-10-15 14:51:23 -0400] [37572] [INFO] Booting worker with pid: 37572
[2023-10-15 14:51:24 -0400] [37573] [INFO] Booting worker with pid: 37573
[2023-10-15 14:51:24 -0400] [37574] [INFO] Booting worker with pid: 37574
[2023-10-15 14:51:24 -0400] [37563] [INFO] Started server process [37563]
[2023-10-15 14:51:24 -0400] [37563] [INFO] Waiting for application startup.
[2023-10-15 14:51:24 -0400] [37563] [INFO] Application startup complete.
[2023-10-15 14:51:24 -0400] [37567] [INFO] Started server process [37567]
[2023-10-15 14:51:24 -0400] [37567] [INFO] Waiting for application startup.
[2023-10-15 14:51:24 -0400] [37567] [INFO] Application startup complete.
[2023-10-15 14:51:24 -0400] [37566] [INFO] Started server process [37566]
[2023-10-15 14:51:24 -0400] [37566] [INFO] Waiting for application startup.
[2023-10-15 14:51:24 -0400] [37566] [INFO] Application startup complete.
[2023-10-15 14:51:24 -0400] [37569] [INFO] Started server process [37569]
[2023-10-15 14:51:24 -0400] [37569] [INFO] Waiting for application startup.
[2023-10-15 14:51:24 -0400] [37569] [INFO] Application startup complete.
[2023-10-15 14:51:24 -0400] [37568] [INFO] Started server process [37568]
[2023-10-15 14:51:24 -0400] [37568] [INFO] Waiting for application startup.
[2023-10-15 14:51:24 -0400] [37568] [INFO] Application startup complete.
[2023-10-15 14:51:24 -0400] [37570] [INFO] Started server process [37570]
[2023-10-15 14:51:24 -0400] [37570] [INFO] Waiting for application startup.
[2023-10-15 14:51:24 -0400] [37570] [INFO] Application startup complete.
[2023-10-15 14:51:25 -0400] [37571] [INFO] Started server process [37571]
[2023-10-15 14:51:25 -0400] [37571] [INFO] Waiting for application startup.
[2023-10-15 14:51:25 -0400] [37571] [INFO] Application startup complete.
[2023-10-15 14:51:25 -0400] [37572] [INFO] Started server process [37572]
[2023-10-15 14:51:25 -0400] [37572] [INFO] Waiting for application startup.
[2023-10-15 14:51:25 -0400] [37572] [INFO] Application startup complete.
[2023-10-15 14:51:25 -0400] [37574] [INFO] Started server process [37574]
[2023-10-15 14:51:25 -0400] [37574] [INFO] Waiting for application startup.
[2023-10-15 14:51:25 -0400] [37574] [INFO] Application startup complete.
[2023-10-15 14:51:25 -0400] [37573] [INFO] Started server process [37573]
[2023-10-15 14:51:25 -0400] [37573] [INFO] Waiting for application startup.
[2023-10-15 14:51:25 -0400] [37573] [INFO] Application startup complete.
[2023-10-15 14:51:26 -0400] [37562] [INFO] Handling signal: winch

Containerization

Now lets containerize this application so it is easier to use and so it can be deployed to a cloud environment. Add a Dockerfile in the base project folder where we will use a Python 3.11 version, use a multi-stage build to omit the poetry dependencies, copy over our code, install our requirements and run our API or port 8000 with 10 workers.

📝 Dockerfile

FROM python:3.11-slim-bookworm as requirements-stage

RUN pip install poetry
COPY ./pyproject.toml ./poetry.lock /
RUN poetry export -f requirements.txt --output requirements.txt --without-hashes --without=dev

FROM python:3.11-slim-bookworm

COPY --from=requirements-stage /requirements.txt /requirements.txt
COPY ./pyproject.toml ./gunicorn_conf.py /
COPY ./app /app

RUN python3 -m pip install --no-cache-dir --upgrade -r requirements.txt

RUN mkdir -p /tmp/shm && mkdir /.local

ENV PORT 8000
EXPOSE 8000

ENTRYPOINT ["gunicorn", "-k", "uvicorn.workers.UvicornWorker", "-c", "gunicorn_conf.py", "app.main:app"]

Build the container image

$ docker build . -t fastapi-todos:1.0.0
[+] Building 29.1s (14/14) FINISHED                                                                                                       docker:desktop-linux
 => [internal] load build definition from Dockerfile                                                                                                      0.0s
 => => transferring dockerfile: 614B                                                                                                                      0.0s
 => [internal] load .dockerignore                                                                                                                         0.0s
 => => transferring context: 2B                                                                                                                           0.0s
 => [internal] load metadata for docker.io/library/python:3.11-slim-bookworm                                                                              1.8s
 => [auth] library/python:pull token for registry-1.docker.io                                                                                             0.0s
 => [internal] load build context                                                                                                                         0.0s
 => => transferring context: 132.09kB                                                                                                                     0.0s
 => [requirements-stage 1/4] FROM docker.io/library/python:3.11-slim-bookworm@sha256:fda05d00fc47a4133a1b65bdd89007facf4ec0fa5fb737a35652699b18029830     3.5s
 => => resolve docker.io/library/python:3.11-slim-bookworm@sha256:fda05d00fc47a4133a1b65bdd89007facf4ec0fa5fb737a35652699b18029830                        0.0s
 => => sha256:5f658eaeb6f6b3d1c7e64402784a96941bb104650e33f18675d8a9aea28cfab2 3.33MB / 3.33MB                                                            0.3s
 => => sha256:3a21992ae6ea870866a08c3130aeedc758053117776270e79ce8f50c2d5ecb36 12.81MB / 12.81MB                                                          0.7s
 => => sha256:fda05d00fc47a4133a1b65bdd89007facf4ec0fa5fb737a35652699b18029830 1.65kB / 1.65kB                                                            0.0s
 => => sha256:b26e46d3c77da193a5057346b362bcb1db25ea53fda4e66c34655c1e7c838984 1.37kB / 1.37kB                                                            0.0s
 => => sha256:e35901feb1c144a36a7e654cb313632ff45bb290a031fd98a41845722872b86e 6.95kB / 6.95kB                                                            0.0s
 => => sha256:1bc163a14ea6a886d1d0f9a9be878b1ffd08a9311e15861137ccd85bb87190f9 29.18MB / 29.18MB                                                          1.0s
 => => sha256:94f5f9f3c96b32388cb097a0adee2086ff4e0a298e5812c4389265c6eaac9bae 244B / 244B                                                                0.5s
 => => sha256:82d03286152357f66ff0e02abec8a43980f8f73065d8ea9d122de8fa46e1e31a 3.39MB / 3.39MB                                                            0.8s
 => => extracting sha256:1bc163a14ea6a886d1d0f9a9be878b1ffd08a9311e15861137ccd85bb87190f9                                                                 1.5s
 => => extracting sha256:5f658eaeb6f6b3d1c7e64402784a96941bb104650e33f18675d8a9aea28cfab2                                                                 0.1s
 => => extracting sha256:3a21992ae6ea870866a08c3130aeedc758053117776270e79ce8f50c2d5ecb36                                                                 0.5s
 => => extracting sha256:94f5f9f3c96b32388cb097a0adee2086ff4e0a298e5812c4389265c6eaac9bae                                                                 0.0s
 => => extracting sha256:82d03286152357f66ff0e02abec8a43980f8f73065d8ea9d122de8fa46e1e31a                                                                 0.2s
 => [requirements-stage 2/4] RUN pip install poetry                                                                                                      12.9s
 => [requirements-stage 3/4] COPY ./pyproject.toml ./poetry.lock /                                                                                        0.0s 
 => [requirements-stage 4/4] RUN poetry export -f requirements.txt --output requirements.txt --without-hashes --without=dev                               0.6s 
 => [stage-1 2/5] COPY --from=requirements-stage /requirements.txt /requirements.txt                                                                      0.0s 
 => [stage-1 3/5] COPY ./pyproject.toml ./gunicorn_conf.py /                                                                                              0.0s 
 => [stage-1 4/5] COPY ./app /app                                                                                                                         0.0s 
 => [stage-1 5/5] RUN python3 -m pip install --no-cache-dir --upgrade -r requirements.txt                                                                 9.8s 
 => exporting to image                                                                                                                                    0.3s
 => => exporting layers                                                                                                                                   0.3s
 => => writing image sha256:a6b09ad14d165189a8c9cbdb9b1dfffc525907ff71c053af60b37701852138c2                                                              0.0s 
 => => naming to docker.io/library/fastapi-todos:1.0.0                                                                                                    0.0s

Test running the image locally

$ docker run -p 8000:8000 --env-file .env fastapi-todos:1.0.0
[2023-10-15 19:02:23 +0000] [1] [INFO] Starting gunicorn 21.2.0
[2023-10-15 19:02:23 +0000] [1] [INFO] Listening at: http://0.0.0.0:8000 (1)
[2023-10-15 19:02:23 +0000] [1] [INFO] Using worker: uvicorn.workers.UvicornWorker
[2023-10-15 19:02:23 +0000] [7] [INFO] Booting worker with pid: 7
[2023-10-15 19:02:23 +0000] [8] [INFO] Booting worker with pid: 8
[2023-10-15 19:02:23 +0000] [9] [INFO] Booting worker with pid: 9
[2023-10-15 19:02:23 +0000] [10] [INFO] Booting worker with pid: 10
[2023-10-15 19:02:23 +0000] [11] [INFO] Booting worker with pid: 11
[2023-10-15 19:02:23 +0000] [12] [INFO] Booting worker with pid: 12
[2023-10-15 19:02:23 +0000] [13] [INFO] Booting worker with pid: 13
[2023-10-15 19:02:23 +0000] [7] [INFO] Started server process [7]
[2023-10-15 19:02:23 +0000] [7] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [7] [INFO] Application startup complete.
[2023-10-15 19:02:23 +0000] [15] [INFO] Booting worker with pid: 15
[2023-10-15 19:02:23 +0000] [8] [INFO] Started server process [8]
[2023-10-15 19:02:23 +0000] [8] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [8] [INFO] Application startup complete.
[2023-10-15 19:02:23 +0000] [17] [INFO] Booting worker with pid: 17
[2023-10-15 19:02:23 +0000] [18] [INFO] Booting worker with pid: 18
[2023-10-15 19:02:23 +0000] [9] [INFO] Started server process [9]
[2023-10-15 19:02:23 +0000] [9] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [9] [INFO] Application startup complete.
[2023-10-15 19:02:23 +0000] [10] [INFO] Started server process [10]
[2023-10-15 19:02:23 +0000] [10] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [10] [INFO] Application startup complete.
[2023-10-15 19:02:23 +0000] [11] [INFO] Started server process [11]
[2023-10-15 19:02:23 +0000] [11] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [11] [INFO] Application startup complete.
[2023-10-15 19:02:23 +0000] [12] [INFO] Started server process [12]
[2023-10-15 19:02:23 +0000] [12] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [12] [INFO] Application startup complete.
[2023-10-15 19:02:23 +0000] [13] [INFO] Started server process [13]
[2023-10-15 19:02:23 +0000] [13] [INFO] Waiting for application startup.
[2023-10-15 19:02:23 +0000] [13] [INFO] Application startup complete.
[2023-10-15 19:02:24 +0000] [15] [INFO] Started server process [15]
[2023-10-15 19:02:24 +0000] [15] [INFO] Waiting for application startup.
[2023-10-15 19:02:24 +0000] [15] [INFO] Application startup complete.
[2023-10-15 19:02:24 +0000] [17] [INFO] Started server process [17]
[2023-10-15 19:02:24 +0000] [17] [INFO] Waiting for application startup.
[2023-10-15 19:02:24 +0000] [17] [INFO] Application startup complete.
[2023-10-15 19:02:24 +0000] [18] [INFO] Started server process [18]
[2023-10-15 19:02:24 +0000] [18] [INFO] Waiting for application startup.
[2023-10-15 19:02:24 +0000] [18] [INFO] Application startup complete.
{"loglevel": "info", "workers": 10, "bind": "0.0.0.0:8000", "graceful_timeout": 60, "timeout": 60, "keepalive": 5, "errorlog": "-", "accesslog": "-", "workers_per_core": 1.0, "use_max_workers": 10, "host": "0.0.0.0", "port": "8000"}
[17/Oct/2023 19:02:46] INFO [my-todos.process_time_log_middleware:51] Method=GET Path=/ StatusCode=200 ProcessTime=0.002
192.168.65.1:20858 - "GET / HTTP/1.1" 200
[17/Oct/2023 19:02:47] INFO [my-todos.process_time_log_middleware:51] Method=GET Path=/openapi.json StatusCode=200 ProcessTime=0.026
192.168.65.1:20859 - "GET /openapi.json HTTP/1.1" 200

This image can be pushed to a central container repository like DockerHub so it can be pulled down by any server.

$ docker image tag fastapi-todos:1.0.0 dpills/fastapi-todos:1.0.0

$ docker push dpills/fastapi-todos:1.0.0
The push refers to repository [docker.io/dpills/fastapi-todos]
28d44516d23e: Pushed 
d3adbb568b7a: Pushed 
7690ae0fc4d3: Pushed 
1e5a71ad08c2: Pushed 
e3f2fdf4ed2c: Pushed 
801b21c3331c: Mounted from library/python 
e02fcdad509e: Mounted from library/python 
4e7e2e312a26: Mounted from library/python 
fd887e1d7390: Mounted from library/python 
32f2ee38f285: Mounted from library/python 
1.0.0: digest: sha256:f346ee76439cc1ca8dfed2e5d369be855ced730b7542fb2c663e1c3454757976 size: 2412

Docker Compose

We have already been using a compose spec to run our local mongo database but now we can update it to also run our API.

📝 docker-compose.yml

services:
  db:
    image: mongo:7.0.1
    container_name: myAPIdb
    restart: always
    ports:
      - 27017:27017
    env_file:
      - .env
    volumes:
      - type: volume
        source: my_api_db_data
        target: /data/db
  api:
    image: dpills/fastapi-todos:1.0.0
    container_name: fastapi-todos
    restart: always
    ports:
      - 8000:8000
    env_file:
      - .env
    depends_on:
      - db

volumes:
  my_api_db_data:

You will need to update the mongo URI in the .env file to use the compose service name instead of localhost when running with Docker Comose.

📝 .env

...
MONGO_URI=mongodb://root:mySecureDbPassword1@db:27017/
...

$ docker-compose up

[+] Building 0.0s (0/0)                                             docker-container:unruffled_shockley
[+] Running 3/3
 ✔ Network fastapi-quick-start-guide_default  Creat...                                             0.0s 
 ✔ Container myAPIdb                          Created                                              0.0s 
 ✔ Container fastapi-todos                    Created                                              0.0s 
Attaching to fastapi-todos, myAPIdb

If you want to run this only on a single node with HTTPS, NGINX can be used to terminate the HTTPS connection and reverse proxy to the API. A certificate needs to be provisioned and added into the /etc/ssl/certs directory for this to work properly.

📝 nginx.conf

worker_processes 3;
error_log /dev/stdout info;
events {
    worker_connections 2048;
}
http {
    include /etc/nginx/mime.types;

    server {
        listen 443 ssl;
        server_name todo.com;

        ssl_certificate /etc/ssl/certs/todos.pem;
        ssl_certificate_key /etc/ssl/certs/todos.key;

        location / {
            proxy_pass http://api:8000;
        }
    }
}

📝 docker-compose.yml

services:
  db:
    image: mongo:7.0.1
    container_name: myAPIdb
    restart: always
    ports:
      - 27017:27017
    env_file:
      - .env
    volumes:
      - type: volume
        source: my_api_db_data
        target: /data/db
  api:
    image: dpills/fastapi-todos:1.0.0
    container_name: fastapi-todos
    restart: always
    ports:
      - 8000:8000
    env_file:
      - .env
    depends_on:
      - db
  server:
    image: nginx:1.25-alpine
    container_name: nginx
    restart: always
    ports:
      - 443:443
    volumes:
      - type: bind
        read_only: true
        source: /host/path/nginx.conf
        target: /etc/nginx/nginx.conf
      - type: bind
        read_only: true
        source: /etc/ssl/certs
        target: /etc/ssl/certs
    depends_on:
      - api

volumes:
  my_api_db_data:

This is now a secure single-node containerized API setup! 🎉

Kubernetes

Refer to Kubernetes Quick Start Guide ☁️⚡️🚀 for an in-depth Kubernetes tutorial

If you need to handle a large scale of requests then you will want to use multiple instances of the container running on multiple nodes. Kubernetes is the industry standard for large scale container orchestration. The mongoDB can be setup through a DataBase as a Service (DBaaS) offering such as Mongo Atlas or deployed to the Kubernetes cluster with a Helm Chart such as the Bitnami MongoDB Helm Chart. In order to deploy the API to a Kubernetes environment it needs to have a deployment, service and secret to map the environment variables to the container.

📝 deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: my-todos-api
  name: my-todos-api
spec:
  replicas: 3 # Scale up to 3 instances of the container
  selector:
    matchLabels:
      app: my-todos-api
  template:
    metadata:
      labels:
        app: my-todos-api
    spec:
      containers:
        - name: my-todos-api
          image: dpills/fastapi-todos:1.0.0
          imagePullPolicy: IfNotPresent
          ports:
            - containerPort: 8000
              protocol: TCP
          envFrom:
            - secretRef:
                name: my-todos-api-secret
          resources:
            limits:
              cpu: "2"
              memory: 2Gi
            requests:
              cpu: "1"
              memory: 1Gi

📝 service.yaml

apiVersion: v1
kind: Service
metadata:
  labels:
    app: my-todos-api
  name: my-todos-api-svc
spec:
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 8000
  selector:
    app: my-todos-api

The Kubernetes secret can be created with kubectl using the .env file. Remove the --dry-run=client -o yaml portion at the end to actually create the secret on a cluster.

$ kubectl create secret generic my-todos-api-secret --from-env-file=.env --dry-run=client -o yaml

apiVersion: v1
data:
  GITHUB_OAUTH_CLIENT_ID: MGVjN2Q5Njk5MjgzNmE1ZmJiOTc=
  GITHUB_OAUTH_CLIENT_SECRET: ZTgxM2IwY2RiNGQ0MDJkNTVkNWQwOWNmZDA4ZGZkMDZjZjVmYzZlYw==
  MONGO_INITDB_ROOT_PASSWORD: bXlTZWN1cmVEYlBhc3N3b3JkMQ==
  MONGO_INITDB_ROOT_USERNAME: cm9vdA==
  MONGO_URI: bW9uZ29kYjovL3Jvb3Q6bXlTZWN1cmVEYlBhc3N3b3JkMUBkYjoyNzAxNy8=
kind: Secret
metadata:
  creationTimestamp: null
  name: my-todos-api-secret

We now have a highly-scalable cloud-native API setup! 🎉

Kubernetes Quick Start Guide ☁️⚡️🚀

Deon Pillsbury — Tue, 10 Oct 2023 12:33:20 +0000

Local Setup
Compute
- Pod
- Deployment
- Managing Deployments
Networking
- Service
- Ingress Controller
Configuration
- Config Map
- Secret
Storage
- Persistent Volume
- Persistent Volume Claim
Production Kubernetes Providers

Containers are great for isolating software environments and making them easy to package. Docker and Docker Compose are great tools for running one or more containers on a single server but say we need to run 100 different containers. This now becomes very difficult to manage and we may need more resources than a single server has available so we need to create a new server to run some of the containers on. We would want to take into account the resources available on each server so we balance the load across them. As an application or multiple applications continue to scale and more servers are required this becomes more and more difficult to orchestrate. This is where Kubernetes comes into the picture as the industry standard container orchestration solution. Kubernetes manages large clusters of servers anywhere from 1 to 5000 and automatically schedules containers to run on servers with the most resources or the ones best suited for the job. You just need to tell it which containers to run and how many replicas of each container you want. Replicas are just the number of instances or processes of the container you want running and Kubernetes will load balance traffic across them. Kubernetes works with a master or control plane node which schedules the containers to run on worker nodes.

💡 Refer to Containers Demystified 🐳🤔 for a full Docker container guide

https://phoenixnap.com/kb/understanding-kubernetes-architecture-diagrams

Local Setup

Make sure you have Docker Desktop installed and Install kubectl which is the command line for interacting with Kubernetes clusters. Then install minikube to run a local Kubernetes instance on your computer.

$ kubectl version -o=yaml
clientVersion:
  buildDate: "2023-05-17T14:20:07Z"
  compiler: gc
  gitCommit: 7f6f68fdabc4df88cfea2dcf9a19b2b830f1e647
  gitTreeState: clean
  gitVersion: v1.27.2
  goVersion: go1.20.4
  major: "1"
  minor: "27"
  platform: darwin/arm64
kustomizeVersion: v5.0.1
serverVersion:
  buildDate: "2023-07-19T12:14:49Z"
  compiler: gc
  gitCommit: fa3d7990104d7c1f16943a67f11b154b71f6a132
  gitTreeState: clean
  gitVersion: v1.27.4
  goVersion: go1.20.6
  major: "1"
  minor: "27"
  platform: linux/arm64

$ minikube start --driver=docker
😄  minikube v1.31.2 on Darwin 14.0 (arm64)
✨  Using the docker driver based on user configuration
📌  Using Docker Desktop driver with root privileges
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
💾  Downloading Kubernetes v1.27.4 preload ...
    > preloaded-images-k8s-v18-v1...:  327.74 MiB / 327.74 MiB  100.00% 21.54 M
    > gcr.io/k8s-minikube/kicbase...:  404.50 MiB / 404.50 MiB  100.00% 21.34 M
🔥  Creating docker container (CPUs=2, Memory=4000MB) ...
🐳  Preparing Kubernetes v1.27.4 on Docker 24.0.4 ...
    ▪ Generating certificates and keys ...
    ▪ Booting up control plane ...
    ▪ Configuring RBAC rules ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
🔎  Verifying Kubernetes components...
    ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

Enable the dashboard, metrics server and ingress add-ons.

$ minikube addons enable dashboard
💡  dashboard is an addon maintained by Kubernetes. For any concerns contact minikube on GitHub.
You can view the list of minikube maintainers at: https://github.com/kubernetes/minikube/blob/master/OWNERS
    ▪ Using image docker.io/kubernetesui/dashboard:v2.7.0
    ▪ Using image docker.io/kubernetesui/metrics-scraper:v1.0.8
🌟  The 'dashboard' addon is enabled

$ minikube addons enable metrics-server
💡  metrics-server is an addon maintained by Kubernetes. For any concerns contact minikube on GitHub.
You can view the list of minikube maintainers at: https://github.com/kubernetes/minikube/blob/master/OWNERS
    ▪ Using image registry.k8s.io/metrics-server/metrics-server:v0.6.4
🌟  The 'metrics-server' addon is enabled

$ minikube addons enable ingress
💡  ingress is an addon maintained by Kubernetes. For any concerns contact minikube on GitHub.
You can view the list of minikube maintainers at: https://github.com/kubernetes/minikube/blob/master/OWNERS
💡  After the addon is enabled, please run "minikube tunnel" and your ingress resources would be available at "127.0.0.1"
    ▪ Using image registry.k8s.io/ingress-nginx/kube-webhook-certgen:v20230407
    ▪ Using image registry.k8s.io/ingress-nginx/controller:v1.8.1
    ▪ Using image registry.k8s.io/ingress-nginx/kube-webhook-certgen:v20230407
🔎  Verifying ingress addon...
🌟  The 'ingress' addon is enabled

Verify that kubectl is connected to the Minikube context.

💡 If you work with multiple Kubernetes clusters you will want to make sure you are using the minikube context. If you have never used kubectl before then it should already be selected and the only option.

$ kubectl config current-context
minikube

$ kubectl config get-contexts
CURRENT   NAME             CLUSTER           AUTHINFO          NAMESPACE
          docker-desktop   docker-desktop    docker-desktop    default
*         minikube         minikube          minikube          default

$ kubectl config use-context minikube
Switched to context "minikube".

The K8s server should be up and running and we can verify this by looking at its resources.

$ kubectl get all -A
NAMESPACE              NAME                                             READY   STATUS      RESTARTS      AGE
ingress-nginx          pod/ingress-nginx-admission-create-hb4rq         0/1     Completed   0             11m
ingress-nginx          pod/ingress-nginx-admission-patch-hz9hq          0/1     Completed   2             11m
ingress-nginx          pod/ingress-nginx-controller-7799c6795f-cnj8n    1/1     Running     0             11m
kube-system            pod/coredns-5d78c9869d-qjw4m                     1/1     Running     0             13m
kube-system            pod/etcd-minikube                                1/1     Running     0             14m
kube-system            pod/kube-apiserver-minikube                      1/1     Running     0             14m
kube-system            pod/kube-controller-manager-minikube             1/1     Running     0             14m
kube-system            pod/kube-proxy-52gbh                             1/1     Running     0             13m
kube-system            pod/kube-scheduler-minikube                      1/1     Running     0             14m
kube-system            pod/metrics-server-7746886d4f-xjbwl              1/1     Running     0             11m
kube-system            pod/storage-provisioner                          1/1     Running     1 (13m ago)   14m
kubernetes-dashboard   pod/dashboard-metrics-scraper-5dd9cbfd69-qq9qm   1/1     Running     0             11m
kubernetes-dashboard   pod/kubernetes-dashboard-5c5cfc8747-zs4nx        1/1     Running     0             11m

NAMESPACE              NAME                                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE
default                service/kubernetes                           ClusterIP   10.96.0.1        <none>        443/TCP                      14m
ingress-nginx          service/ingress-nginx-controller             NodePort    10.106.129.227   <none>        80:30736/TCP,443:31016/TCP   11m
ingress-nginx          service/ingress-nginx-controller-admission   ClusterIP   10.97.6.50       <none>        443/TCP                      11m
kube-system            service/kube-dns                             ClusterIP   10.96.0.10       <none>        53/UDP,53/TCP,9153/TCP       14m
kube-system            service/metrics-server                       ClusterIP   10.110.217.32    <none>        443/TCP                      11m
kubernetes-dashboard   service/dashboard-metrics-scraper            ClusterIP   10.106.106.157   <none>        8000/TCP                     11m
kubernetes-dashboard   service/kubernetes-dashboard                 ClusterIP   10.102.109.102   <none>        80/TCP                       11m

NAMESPACE     NAME                        DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR            AGE
kube-system   daemonset.apps/kube-proxy   1         1         1       1            1           kubernetes.io/os=linux   14m

NAMESPACE              NAME                                        READY   UP-TO-DATE   AVAILABLE   AGE
ingress-nginx          deployment.apps/ingress-nginx-controller    1/1     1            1           11m
kube-system            deployment.apps/coredns                     1/1     1            1           14m
kube-system            deployment.apps/metrics-server              1/1     1            1           11m
kubernetes-dashboard   deployment.apps/dashboard-metrics-scraper   1/1     1            1           11m
kubernetes-dashboard   deployment.apps/kubernetes-dashboard        1/1     1            1           11m

NAMESPACE              NAME                                                   DESIRED   CURRENT   READY   AGE
ingress-nginx          replicaset.apps/ingress-nginx-controller-7799c6795f    1         1         1       11m
kube-system            replicaset.apps/coredns-5d78c9869d                     1         1         1       13m
kube-system            replicaset.apps/metrics-server-7746886d4f              1         1         1       11m
kubernetes-dashboard   replicaset.apps/dashboard-metrics-scraper-5dd9cbfd69   1         1         1       11m
kubernetes-dashboard   replicaset.apps/kubernetes-dashboard-5c5cfc8747        1         1         1       11m

NAMESPACE       NAME                                       COMPLETIONS   DURATION   AGE
ingress-nginx   job.batch/ingress-nginx-admission-create   1/1           16s        11m
ingress-nginx   job.batch/ingress-nginx-admission-patch    1/1           31s        11m

We can see that the kubernetes-dashboard pod is running so we can also view the resources in the Kubernetes Dashboard web app since we installed the dashboard add-on.

$ minikube dashboard
🤔  Verifying dashboard health ...
🚀  Launching proxy ...
🤔  Verifying proxy health ...
🎉  Opening http://127.0.0.1:55388/api/v1/namespaces/kubernetes-dashboard/services/http:kubernetes-dashboard:/proxy/ in your default browser...

Now lets take a look at what all of this stuff means.

Compute

Pod

The building block of Kubernetes is a Pod and most of the time a pod runs a single container and can be loosely thought of as just a container.

💡 Pods do allow for multiple containers to be ran and the main use case I have used is a sidecar container that collects logging from the main container but multi-container pods are rare in practice.

The main use case for running pods directly is if you want to exec into the shell of a container running in the Kubernetes environment to test networking or issues related to the Kubernetes environment.

$ kubectl run my-shell --rm -i --tty --image busybox -- /bin/sh
If you don't see a command prompt, try pressing enter.
/ #
/ # ls
bin    dev    etc    home   lib    lib64  proc   root   sys    tmp    usr    var
/ # exit
Session ended, resume using 'kubectl attach my-shell -c my-shell -i -t' command when the pod is running
pod "my-shell" deleted

Pods are never ran independently in production, the main resource used that controls pods is called a Deployment.

Deployment

Deployments are used to define which pods/containers to run and how many replicas you want running. Once a deployment is created, this creates a replica-set which is responsible for making sure the correct number of pods are running. Each time a deployment is updated say with a new container version a new replica-set is created and the previous one is retained which allows us to quickly rollback to a previous version in case an update breaks our application.

Create the following deployment spec to create a single (only 1 replica) container using the NGINX 1.24 running on Alpine Linux docker image.

📝 nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-server
  labels:
    app: my-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-server
  template:
    metadata:
      labels:
        app: my-server
    spec:
      containers:
        - name: my-server
          image: nginx:1.24-alpine
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: 500Mi
              cpu: 500m
            requests:
              memory: 100Mi
              cpu: 100m

Create the deployment, verify the resources have been created and check the logs of the pod container.

$ kubectl apply -f nginx-deployment.yaml
deployment.apps/my-server created

$ kubectl get deployments
NAME        READY   UP-TO-DATE   AVAILABLE   AGE
my-server   1/1     1            1           68s

$ kubectl get pods
NAME                        READY   STATUS    RESTARTS   AGE
my-server-74465678c-776qx   1/1     Running   0          72s

$ kubectl get replicasets
NAME                  DESIRED   CURRENT   READY   AGE
my-server-74465678c   1         1         1       82s

$ kubectl get all
NAME                            READY   STATUS    RESTARTS   AGE
pod/my-server-74465678c-776qx   1/1     Running   0          87s

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   67m

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/my-server   1/1     1            1           88s

NAME                                  DESIRED   CURRENT   READY   AGE
replicaset.apps/my-server-74465678c   1         1         1       87s

$ kubectl logs my-server-74465678c-776qx
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
/docker-entrypoint.sh: Launching /docker-entrypoint.d/10-listen-on-ipv6-by-default.sh
10-listen-on-ipv6-by-default.sh: info: Getting the checksum of /etc/nginx/conf.d/default.conf
10-listen-on-ipv6-by-default.sh: info: Enabled listen on IPv6 in /etc/nginx/conf.d/default.conf
/docker-entrypoint.sh: Launching /docker-entrypoint.d/20-envsubst-on-templates.sh
/docker-entrypoint.sh: Launching /docker-entrypoint.d/30-tune-worker-processes.sh
/docker-entrypoint.sh: Configuration complete; ready for start up
2023/10/07 15:31:39 [notice] 1#1: using the "epoll" event method
2023/10/07 15:31:39 [notice] 1#1: nginx/1.24.0
2023/10/07 15:31:39 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r4)
2023/10/07 15:31:39 [notice] 1#1: OS: Linux 6.4.16-linuxkit
2023/10/07 15:31:39 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2023/10/07 15:31:39 [notice] 1#1: start worker processes
2023/10/07 15:31:39 [notice] 1#1: start worker process 30
2023/10/07 15:31:39 [notice] 1#1: start worker process 31
2023/10/07 15:31:39 [notice] 1#1: start worker process 32
2023/10/07 15:31:39 [notice] 1#1: start worker process 33
2023/10/07 15:31:39 [notice] 1#1: start worker process 34
2023/10/07 15:31:39 [notice] 1#1: start worker process 35
2023/10/07 15:31:39 [notice] 1#1: start worker process 36
2023/10/07 15:31:39 [notice] 1#1: start worker process 37
2023/10/07 15:31:39 [notice] 1#1: start worker process 38
2023/10/07 15:31:39 [notice] 1#1: start worker process 39

Managing Deployments

When a new version of an application we are running is released we can update our deployment spec to use the new image and apply the updates the same way, in this case we can update to the NGINX 1.25 image.

📝 nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-server
  labels:
    app: my-server
spec:
  replicas: 1
  selector:
    matchLabels:
      app: my-server
  template:
    metadata:
      labels:
        app: my-server
    spec:
      containers:
        - name: my-server
          image: nginx:1.25-alpine # Update image
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: 500Mi
              cpu: 500m
            requests:
              memory: 100Mi
              cpu: 100m

Apply the updated config.

$ kubectl apply -f nginx-deployment.yaml
deployment.apps/my-server configured

💡 The kubectl get command offers the -o option to print information in different formats. We can use the wide option to show some extra metadata such as image versions in this case.
$ kubectl get --help
Display one or many resources.
...
    -o, --output='':
    Output format. One of: (json, yaml, name, go-template, go-template-file, template, templatefile, jsonpath,
    jsonpath-as-json, jsonpath-file, custom-columns, custom-columns-file, wide).

We can verify that our deployment is updated with the new image, a new replica-set and pod are created and the previous replica-set for the 1.24 image is saved. This is what allows Kubernetes to quickly Rollback versions if there are any issues with an update.

$ kubectl get all -o wide
NAME                            READY   STATUS    RESTARTS   AGE     IP            NODE       NOMINATED NODE   READINESS GATES
pod/my-server-6449d849b-cg8hz   1/1     Running   0          2m15s   10.244.0.11   minikube   <none>           <none>

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE   SELECTOR
service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   81m   <none>

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES              SELECTOR
deployment.apps/my-server   1/1     1            1           15m   my-server    nginx:1.25-alpine   app=my-server

NAME                                  DESIRED   CURRENT   READY   AGE     CONTAINERS   IMAGES              SELECTOR
replicaset.apps/my-server-6449d849b   1         1         1       2m15s   my-server    nginx:1.25-alpine   app=my-server,pod-template-hash=6449d849b
replicaset.apps/my-server-74465678c   0         0         0       15m     my-server    nginx:1.24-alpine   app=my-server,pod-template-hash=74465678c

Running a single container is a great place to start but as an application increases usage it will need to be scaled up to handle more load and this is where Kubernetes really shines. We simply increase the replicas count on our deployment spec and in a production cluster Kubernetes will automatically schedule the container to run on the best node available. Lets increase our NGINX deployment to 3 replicas.

📝 nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-server
  labels:
    app: my-server
spec:
  replicas: 3 # Run with 3 instances
  selector:
    matchLabels:
      app: my-server
  template:
    metadata:
      labels:
        app: my-server
    spec:
      containers:
        - name: my-server
          image: nginx:1.25-alpine
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: 500Mi
              cpu: 500m
            requests:
              memory: 100Mi
              cpu: 100m

Apply this configuration and we can verify that we see 3 pods/containers running

$ kubectl apply -f nginx-deployment.yaml
deployment.apps/my-server configured

$ kubectl get all -o wide
NAME                            READY   STATUS    RESTARTS   AGE     IP            NODE       NOMINATED NODE   READINESS GATES
pod/my-server-6449d849b-69c66   1/1     Running   0          3s      10.244.0.12   minikube   <none>           <none>
pod/my-server-6449d849b-cg8hz   1/1     Running   0          7m31s   10.244.0.11   minikube   <none>           <none>
pod/my-server-6449d849b-xs74r   1/1     Running   0          3s      10.244.0.13   minikube   <none>           <none>

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE   SELECTOR
service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   86m   <none>

NAME                        READY   UP-TO-DATE   AVAILABLE   AGE   CONTAINERS   IMAGES              SELECTOR
deployment.apps/my-server   3/3     3            3           20m   my-server    nginx:1.25-alpine   app=my-server

NAME                                  DESIRED   CURRENT   READY   AGE     CONTAINERS   IMAGES              SELECTOR
replicaset.apps/my-server-6449d849b   3         3         3       7m31s   my-server    nginx:1.25-alpine   app=my-server,pod-template-hash=6449d849b
replicaset.apps/my-server-74465678c   0         0         0       20m     my-server    nginx:1.24-alpine   app=my-server,pod-template-hash=74465678c

For some applications which are just backend workers this may be all that is needed but for NGINX which is a web server and reverse proxy it will need to be accessible via the network.

Networking

Service

Kubernetes uses services to connect to running pods, the service is accessible on every node and load balances traffic across the pods/containers wherever they are running.

💡 svc is an abbreviation for service

$ kubectl get svc
NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   122m

$ kubectl get service
NAME         TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   122m

By default services will be created with the type ClusterIP which means it will only be accessible inside the cluster, via the cluster IP and typically will be used in conjunction with a load balancer like HAProxy or a cloud service provided load balancer. In order to directly access a service via any node's IP address, the NodePort type should be used and this will map a node port between 30000-32767 to the service. The service uses a label selector to figure out which pods to connect to, in this case our deployment is using app: my-server and it connects to the pod/container targetPort which is set to containerPort: 80 then exposes its own port: 8000.

📝 nginx-svc.yaml

apiVersion: v1
kind: Service
metadata:
  labels:
    app: my-server
  name: my-server-svc
spec:
  type: NodePort
  ports:
    - name: http
      port: 8000
      protocol: TCP
      targetPort: 80
  selector:
    app: my-server # Attach to pods with the same label

Create the service and verify.

$ kubectl apply -f nginx-svc.yaml
service/my-server-svc created

$ kubectl get svc -o wide
NAME            TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)          AGE    SELECTOR
kubernetes      ClusterIP   10.96.0.1      <none>        443/TCP          134m   <none>
my-server-svc   NodePort    10.100.20.14   <none>        8000:30444/TCP   32s    app=my-server

This service would now be accessible on port 30444 of any node in a production Kubernetes cluster but since we are using Minikube we will need to use the Minikube server command to expose it locally.

$ minikube service my-server-svc --url
http://127.0.0.1:57578
❗  Because you are using a Docker driver on darwin, the terminal needs to be open to run it.

Open your web browser to the printed address and you should now see the NGINX welcome page and traffic will be load balanced across the 3 containers as the page is loaded up.

Ingress Controller

In a production environment there will be a load balancer setup with an Ingress Controller, Service Mesh or some type of Custom Router. This allows all traffic to be sent to the single load balancer IP address and then route the traffic to a service based on the Domain name or subpath. We are using a NGINX ingress controller but service meshes like Istio have been becoming the most popular solution to use as they offer more segmentation, security and granular control.

💡 Kubernetes has namespaces to separate and organize applications, we have just been using the default namespace so far but the NGINX controller is setup in the ingress-nginx namespace and to view or access its resource the namespace flag -n ingress-nginx will need to be provided on commands.

$ kubectl -n ingress-nginx get all
NAME                                            READY   STATUS      RESTARTS   AGE
pod/ingress-nginx-admission-create-hb4rq        0/1     Completed   0          23h
pod/ingress-nginx-admission-patch-hz9hq         0/1     Completed   2          23h
pod/ingress-nginx-controller-7799c6795f-cnj8n   1/1     Running     0          23h

NAME                                         TYPE        CLUSTER-IP       EXTERNAL-IP   PORT(S)                      AGE
service/ingress-nginx-controller             NodePort    10.106.129.227   <none>        80:30736/TCP,443:31016/TCP   23h
service/ingress-nginx-controller-admission   ClusterIP   10.97.6.50       <none>        443/TCP                      23h

NAME                                       READY   UP-TO-DATE   AVAILABLE   AGE
deployment.apps/ingress-nginx-controller   1/1     1            1           23h

NAME                                                  DESIRED   CURRENT   READY   AGE
replicaset.apps/ingress-nginx-controller-7799c6795f   1         1         1       23h

NAME                                       COMPLETIONS   DURATION   AGE
job.batch/ingress-nginx-admission-create   1/1           16s        23h
job.batch/ingress-nginx-admission-patch    1/1           31s        23h

We have already enabled the ingress add-on for minikube which sets up an ingress controller so now we can create an ingress definition to route traffic to our service when a user goes to the /myApp sub route.

📝 nginx-ingress.yaml

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: my-server-ingress
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /
spec:
  rules:
    - http:
        paths:
          - path: /myApp
            pathType: Prefix
            backend:
              service:
                name: my-server-svc # Service to route to
                port:
                  number: 80

Apply the ingress definition and verify.

$ kubectl apply -f nginx-ingress.yaml
ingress.networking.k8s.io/my-server-ingress created

$ kubectl get ingress
NAME                CLASS   HOSTS   ADDRESS   PORTS   AGE
my-server-ingress   nginx   *                 80      12s

Since we are using Minikube locally we need to use minikube tunnel to access the ingress controller.

$ minikube tunnel
✅  Tunnel successfully started

📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...

❗  The service/ingress my-server-ingress requires privileged ports to be exposed: [80 443]
🔑  sudo permission will be asked for it.
🏃  Starting tunnel for service my-server-ingress.
Password:

Navigate to http://localhost/myApp in your web browser and we see that the ingress controller has mapped the /myApp route to our NGINX application!

Configuration

Our default NGINX server is working great but in real world applications you will need to modify the configuration with config files, variables and secrets.

Config Map

Config maps are useful for configurations which do not contain sensitive information. There are two common ways to use them, either adding key value pairs to inject simple environment variables, such as key: value or full configuration files mapped to a single key such as a nginx.conf config. Create a new config map for our NGINX server which contains a nginx.conf file config. The key: value entry will not actually be used by the server but it is just included to show how simple key value entries work.

📝 nginx-cm.yaml

apiVersion: v1
kind: ConfigMap
metadata:
  name: my-server-cm
data:
  key: value
  nginx.conf: |
    worker_processes 3;
    error_log /dev/stdout info;
    events {
        worker_connections 2048;
    }
    http {
        include /etc/nginx/mime.types;

        server {
            listen 80;

            location / {
                root /www/data;
                try_files $uri /index.html;
            }
        }
    }

Create and verify this config.

$ kubectl apply -f nginx-cm.yaml
configmap/my-server-cm created

$ kubectl get configmaps
NAME               DATA   AGE
kube-root-ca.crt   1      24h
my-server-cm       1      8s

$ kubectl get configmap my-server-cm -o yaml
apiVersion: v1
data:
  key: value
  nginx.conf: |
    worker_processes 3;
    error_log /dev/stdout info;
    events {
        worker_connections 2048;
    }
    http {
        include /etc/nginx/mime.types;

        server {
            listen 80;

            location / {
                root /www/data;
                try_files $uri /index.html;
            }
        }
    }
kind: ConfigMap
metadata:
  annotations:
    kubectl.kubernetes.io/last-applied-configuration: |
      {"apiVersion":"v1","data":{"key":"value","nginx.conf":"worker_processes 3;\nerror_log /dev/stdout info;\nevents {\n    worker_connections 2048;\n}\nhttp {\n    include /etc/nginx/mime.types;\n\n    server {\n        listen 80;\n\n        location / {\n            root /www/data;\n            try_files $uri /index.html;\n        }\n    }\n}\n"},"kind":"ConfigMap","metadata":{"annotations":{},"name":"my-server-cm","namespace":"default"}}
  creationTimestamp: "2023-10-08T14:35:18Z"
  name: my-server-cm
  namespace: default
  resourceVersion: "46978"
  uid: 41dc8ab0-44cf-4ecc-9514-0330eb2ddd90

We can now use this configuration on our NGINX deployment. Environment variable key value config types can be added with envFrom and configuration file types will use volumeMounts to be mounted as a Volume with a mount path to make it available as a file in the container.

📝 nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-server
  labels:
    app: my-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-server
  template:
    metadata:
      labels:
        app: my-server
    spec:
      containers:
        - name: my-server
          image: nginx:1.25-alpine
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: 500Mi
              cpu: 500m
            requests:
              memory: 100Mi
              cpu: 100m
          envFrom: # Add CM key/values to environment variables
            - configMapRef:
                name: my-server-cm
          volumeMounts:
            - name: nginx-conf # Maps to file type CM name
              mountPath: /etc/nginx/nginx.conf
              subPath: nginx.conf
              readOnly: true
      volumes:
        - name: nginx-conf # File type CM
          configMap:
            name: my-server-cm
            items:
              - key: nginx.conf
                path: nginx.conf

Apply the updated deployment config.

$ kubectl apply -f nginx-deployment.yaml
deployment.apps/my-server configured

Secret

Secrets are similar to config maps other than they are intended for sensitive values like passwords. The main difference in the spec is the values are Base64 encoded. kubectl commands have support for .env files and are useful for generating secrets with the proper Base64 encoding. Including the --dry-run=client -o yaml options will only print out the spec to the command line and not create the secret, if these options are omitted it will create the secret on Kubernetes.

📝 .env

MY_SECRET=SuperSecret123

$ kubectl create secret generic example-secret --from-env-file=.env --dry-run=client -o yaml
apiVersion: v1
data:
  MY_SECRET: U3VwZXJTZWNyZXQxMjM=
kind: Secret
metadata:
  creationTimestamp: null
  name: example-secret

After creating a secret, it can be mapped to a deployment the same way as a config map but just using secretRef instead of configMapRef

envFrom:
  - secretRef:
      name: my-secret

Storage

Persistent Volume

Persistent Volumes are how you map persisted file storage to a container, similar to volumes in Docker but it will be through some type of network attached storage to allow for the distributed setup. The persistent volume definition is the actual storage medium itself which is typically provided by cloud providers. A common bare metal solution is to use an NFS server. Here are all of the Types of Persistent Volumes. A storage provisioner is already enabled in Minikube so we can go ahead and take a look at how to use PVs with deployments.

Persistent Volume Claim

Persistent Volume Claims are how you claim available storage and attach it to your pod/container to use. The most important pieces to look at are how much storage space is needed and how will the storage be used or its Access Mode and Kubernetes allows a handful of Access Modes.

ReadWriteOnce (RWO) - the volume can be mounted as read-write by a single node. ReadWriteOnce access mode still can allow multiple pods to access the volume when the pods are running on the same node.
ReadOnlyMany (ROX) - the volume can be mounted as read-only by many nodes.
ReadWriteMany (RWX) - the volume can be mounted as read-write by many nodes.
ReadWriteOncePod (RWOP) - the volume can be mounted as read-write by a single Pod. Use ReadWriteOncePod access mode if you want to ensure that only one pod across whole cluster can read that PVC or write to it. This is only supported for CSI volumes and Kubernetes version 1.22+.

A PVC can be created to store HTML files for our NGINX deployment instead of the default test page. There are 3 pods running and each will need to read the HTML files from disk but we also want to be able to copy data to the storage through a pod so our best option will be to use a ReadWriteMany access mode and 1 Gigabyte of storage should be more than enough.

📝 nginx-pvc.yaml

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: my-server-pvc
spec:
  accessModes:
    - ReadWriteMany
  volumeMode: Filesystem
  resources:
    requests:
      storage: 1Gi

Create and verify this config.

$ kubectl apply -f nginx-pvc.yaml
persistentvolumeclaim/my-server-pvc created

$ kubectl get pv,pvc
NAME                                                        CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS   CLAIM                   STORAGECLASS   REASON   AGE
persistentvolume/pvc-0ab341dd-3d4a-478f-b39b-1c5f88638419   1Gi        RWX            Delete           Bound    default/my-server-pvc   standard                6s

NAME                                  STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
persistentvolumeclaim/my-server-pvc   Bound    pvc-0ab341dd-3d4a-478f-b39b-1c5f88638419   1Gi        RWX            standard       7s

Update the NGINX deployment and attach the persistent volume to the /www/data directory defined in the NGINX config.

📝 nginx-deployment.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-server
  labels:
    app: my-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-server
  template:
    metadata:
      labels:
        app: my-server
    spec:
      containers:
        - name: my-server
          image: nginx:1.25-alpine
          ports:
            - containerPort: 80
          resources:
            limits:
              memory: 500Mi
              cpu: 500m
            requests:
              memory: 100Mi
              cpu: 100m
          envFrom:
            - configMapRef:
                name: my-server-cm
          volumeMounts:
            - name: nginx-conf
              mountPath: /etc/nginx/nginx.conf
              subPath: nginx.conf
              readOnly: true
            - name: data # Maps to PVC name
              mountPath: /www/data
              subPath: data
      volumes:
        - name: nginx-conf
          configMap:
            name: my-server-cm
            items:
              - key: nginx.conf
                path: nginx.conf
        - name: data # PVC
          persistentVolumeClaim:
            claimName: my-server-pvc

Apply the updated deployment config.

$ kubectl apply -f nginx-deployment.yaml
deployment.apps/my-server configured

Now that we have our volume bound to the container we can use the kubectl cp command to add a basic index.html file to the server and this can be copied through any of the NGINX pods since they all map to the same volume.

$ kubectl get pods
NAME                         READY   STATUS    RESTARTS   AGE
my-server-5556d46697-dstnp   1/1     Running   0          10m
my-server-5556d46697-hlst4   1/1     Running   0          10m
my-server-5556d46697-kwtcf   1/1     Running   0          10m

$ kubectl cp index.html my-server-5556d46697-dstnp:/www/data

Make sure your Minikube tunnel is still running, otherwise restart it.

$ minikube tunnel
✅  Tunnel successfully started

📌  NOTE: Please do not close this terminal as this process must stay alive for the tunnel to be accessible ...

❗  The service/ingress my-server-ingress requires privileged ports to be exposed: [80 443]
🔑  sudo permission will be asked for it.
🏃  Starting tunnel for service my-server-ingress.
Password:

Navigate back to http://localhost/myApp in your web browser and we can see that our custom HTML website is now being served! 🎉

Production Kubernetes Providers

These are the core concepts for building Kubernetes cloud applications but a real application will not be ran on your local computer with Minikube. Here are the most popular cloud providers who offer managed Kubernetes clusters to deploy production applications.

Innovator Principles ✨

Deon Pillsbury — Mon, 09 Oct 2023 14:41:26 +0000

Experience Obsession

People’s experiences are what keep them motivated and fulfilled. Customers or Employees who have great experiences with products, services or support tend to buy, use, and promote them more. Developers who have great experiences with APIs or tooling advocate for them and drive adoption. People who have great team and work experiences will be more committed, work better together and build better products.

Bias for Action

Avoid paralysis by analysis, it is impossible to predict every issue which may arise, so start executing early and make adjustments based on actual issues instead of hypothetical ones.

Simplify and Automate Everything

Always be thinking about how you can make things simpler to use, more intuitive and whether it can be automated. Whenever a new manual task is proposed: updating a release version, adding a quality scanner, tracking a status of something, etc. the first analysis that should be made is do we actually need it and if so, can we automate it.

Continuous Improvement and Evolution

Always be improving and evolving the things you build, your skillset and yourself. There is constantly new technologies and products arising as market leaders so if you do not keep up with the changes, you will be left behind.

Failure is Required, Just do it Fast

Someone who has never failed has never tried, or at least has not tried very hard. Failure is a requirement, expect and encourage failure. Just make sure to get comfortable calling out, accepting and learning from failure quickly. A culture where everyone is expected and encouraged to fail will take risks on innovative solutions which can make or break a product.

Just In Time and Continuous Learning

You do not need to know everything about a topic to get started, usually a simple google search and a few articles or documentation can get you up and running with any technology. Learn just enough to build what you need and you can add more depth in the future, trust your ability to learn as you go.

Prioritize Customer Feedback

When we consider what makes projects successful, it ultimately comes down to popularity: how many people use it and/or are willing to pay for it. The only reason people will do this is if the product provides them with enough value directly or by solving a problem they have in their life. Because the success of a product is entirely dependent on its customers, it is critical to prioritize strong feedback mechanisms and integrate them into your product roadmap. Never assume that you know more about what your users want than they do, and do not hesitate to ask for their opinion early in the design phase.

Put First things First and Stay Focused

There is always many different things going on at any given time with many different asks from people. If you do not prioritize what is important then you will lack strong direction and can waste your time on things which do not help you meet your goals. Take the time to write out what is important and prioritize what will help you achieve them. Execute on this plan and stay focused.

Build your Community and Win your Champions

Build your community by providing them with value, creating a support room, discussing and implementing their feedback and having a closed-loop feedback system a.k.a following back up with them once feedback is being worked on and implemented. This will show your users that you take their ideas and feedback into account and promote community discussion on how things should be implemented. Through this process, you will have users who participate the most and become your product champions who will answer other users questions, provide the most feedback and defend and promote your product to others.

Embrace your Strengths

Projects involve many different components, such as architecture, programming languages, tooling, infrastructure, DevOps, design, marketing, and more. You may discover that you have great talent and passion in a particular area. Embrace your strengths, as they will differentiate you and ultimately lead you to a project that you enjoy working on, which often tends to be the most successful ones.

Stand your Ground and Be Resilient

Many successful projects, products or companies will tell you about how people thought they were crazy or tried to challenge them or shut them down early on and if they had listened then they never would have been successful. In the corporate world everyone has efforts they are trying to drive and your project may disrupt or inconvenience their effort and they may try to shut it down or convince you not to pursue it but stand your ground for what you believe in and be resilient.

Mentor and Give Back

Most of what you know was probably learned from other people, whether that was in person, through videos, books, blogs, or other resources. Without them, you would not be where you are today. Pay this forward, mentor people who you believe in and give back to your community by sharing your knowledge.

MongoDB Quick Start Guide 🍃⚡️

Deon Pillsbury — Fri, 06 Oct 2023 15:48:45 +0000

Types of Databases
Local Setup
Define your Data Model
- One-to-One
- One-to-Few
Common Operations using Python
- Insert a Document
- List Documents
- Update a Document
- Delete a Document
Indexes
- Single Field Index
- Unique Index
- TTL Index
- Compound Index
- Get Collection Indexes

Types of Databases

There are two main types of databases that can be used in applications and these include NoSQL databases and SQL databases. SQL databases are relational and structured and usually consist of tables of rows and columns. NoSQL databases come in the following types Key-Value, Wide-Column, Graph, and Document but we will mainly be taking a look at document databases specifically MongoDB, which store data in documents that are grouped together in collections. SQL databases are built to vertically scale which means they are ran on a single server and to handle more load you need to increase the CPU and Memory on that server. On the other hand, NoSQL databases are built to horizontally scale and are typically deployed with multiple servers in a replica-set, so handling more load is as simple as adding a new server. Databases are evaluated on their ACID Compliance (Atomicity, Consistency, Isolation, Durability) which is a standard set of properties that guarantee database transactions are processed reliably. Most SQL Databases are ACID compliant by default where NoSQL databases can sacrifice ACID compliance for performance and scalability. Although most of the NoSQL databases offer a solution to achieve ACID compliance if it is needed.

https://starship-knowledge.com/when-to-choose-nosql-over-sql

Local Setup

MongoDB is an open source NoSQL Document database which horizontally scales utilizing clustered servers in replica-sets. A great option for testing and performing local development with MongoDB is using Docker and Docker Compose. The following docker compose spec will create a local docker container running MongoDB with the data persisted to a docker volume.

📝 docker-compose.yml

services:
  db:
    image: mongo:7.0.1
    container_name: myDataBase
    restart: always
    ports:
      - 27017:27017
    environment:
      MONGO_INITDB_ROOT_USERNAME: root
      MONGO_INITDB_ROOT_PASSWORD: mySecureDbPassword1!
    volumes:
      - type: volume
        source: my_db_data
        target: /data/db

volumes:
  my_db_data:

💡 Refer to Containers Demystified 🐳🤔 for a full Docker container guide

Start the container as a detached background process.

$ docker-compose up -d
[+] Building 0.0s (0/0)                                                                                   docker-container:unruffled_shockley
[+] Running 3/3
 ✔ Network mongo_default      Created                                                                                       
 ✔ Volume "mongo_my_db_data"  Created                                                                                                   
 ✔ Container myDataBase       Started                                                                                                   

$ docker ps
CONTAINER ID   IMAGE         COMMAND                  CREATED         STATUS         PORTS                      NAMES
11bce7e4ab08   mongo:7.0.1   "docker-entrypoint.s…"   2 minutes ago   Up 2 minutes   0.0.0.0:27017->27017/tcp   myDataBase

💡 Mongo uses Collections with BSON Documents and you can loosely think of this as multiple lists of Dictionaries or JSON Objects. The difference with BSON and JSON is BSON supports additional complex types such as DateTime Objects.

Connect to the container with the mongo shell utility mongosh then create our first database (myAppDb), collection (todos) and insert a document.

$ mongosh 'mongodb://root:mySecureDbPassword1!@localhost:27017/'
Current Mongosh Log ID: 651abecd3a009f9bf2b8999c
Connecting to:      mongodb://<credentials>@localhost:27017/?directConnection=true&serverSelectionTimeoutMS=2000&appName=mongosh+2.0.1
Using MongoDB:      7.0.1
Using Mongosh:      2.0.1

test> use myAppDb
switched to db myAppDb

myAppDb> db.todos.insertOne({"title": "Do a thing", "completed": false, "created_date": new Date()})
{
  acknowledged: true,
  insertedId: ObjectId("652009addda6ead56a87d0e5")
}

💡 mongosh is written with JavaScript (NodeJS) so we can insert a DateTime object with new Date()

We can verify the document has been created by listing out the documents in the collection with the find command.

myAppDb> db.todos.find()
[
  {
    _id: ObjectId("652009addda6ead56a87d0e5"),
    title: 'Do a thing',
    completed: false,
    created_date: ISODate("2023-10-06T13:20:45.434Z")
  }
]

If you prefer to use a visual tool with a GUI instead of the command line, MongoDB Compass can be used.

Define your Data Model

Mongo is great because it allows for flexibility with the data you can store in a collection, all of the documents do not need to have all of the same fields. That being said, it is still important to start with defining your data model when you create a new app or add a new feature to make sure you do not have complexity, organization or performance issues later on. The two types of relationship schemas that I use the most are One-to-One and One-to-Few.

💡 Great article on MongoDB Schema Best Practices which covers more schema designs

One-to-One

In the One-to-One relationship each attribute has a single value so the resulting document is flat and we have one document per item. This is the schema of the document we just inserted.

{
    "_id": ObjectId(),
    "title": "string",
    "completed": false,
    "created_date": ISODate()
}

One-to-Few

In the One-to-Few relationship we use a list of nested objects to group all associated items into a single document such as a user record with multiple addresses.

💡 MongoDB has a 16MB max document size

{
    "_id": ObjectId('A'),
    "fist_name": "John",
    "last_name": "Doe",
    "company": "Cisco",
    "addresses": [
        { "street": "7200-11 Kit Creek Rd", "city": "Durham", "state": "NC", "country": "US"},
        { "street": "7200-12 Kit Creek Rd", "city": "Durham", "state": "NC", "country": "US"},
    ]
}

Common Operations using Python

This full example is available on GitHub
https://github.com/dpills/mongo-todos/tree/master

We have used the mongo shell and mongo compass but these tools are usually only used for manual operations or validation of data. MongoDB offers drivers (libraries) in many different programming languages but we will be taking a look at common operations using the Python PyMongo driver for a more realistic application example.

💡 The majority of code is written to interact with the collection of the database and the full list of features can be referenced at the pymongo Collection level operations documentation.

Make sure to install pymongo with a Python package manager to get started.

# Pip
$ python3 -m pip install pymongo
Installing collected packages: dnspython, pymongo
Successfully installed dnspython-2.4.2 pymongo-4.5.0

# Poetry
$ poetry add pymongo
The following packages are already present in the pyproject.toml and will be skipped:

  • pymongo

Create a python file, import pymongo and setup the mongo connection, specifying to use the myAppDb database.

📝 todos.py

import argparse
from datetime import datetime

import pymongo
from bson import ObjectId
from bson.errors import InvalidId

db_client = pymongo.MongoClient("mongodb://root:mySecureDbPassword1!@localhost:27017/")
db = db_client["myAppDb"]

🛑 In a real application make sure to put the URI in an environment variable so it is not exposed in your source code

Insert a Document

Insert the document with the same schema we used earlier using insert_one which includes adding a DateTime object.

📝 todos.py

def create_todo(title: str) -> None:
    """
    Create a todo
    """
    create_result = db.todos.insert_one(
        {"title": title, "completed": False, "created_date": datetime.utcnow()}
    )
    print(f"New Todo ID: {create_result.inserted_id}")

    return None

We can get the Document ID by printing the inserted_id of the create result.

💡 MongoDB generates an ObjectId for each document

ObjectIds are small, likely unique, fast to generate, and ordered. ObjectId values are 12 bytes in length, consisting of:

A 4-byte timestamp, representing the ObjectId's creation, measured in seconds since the Unix epoch.

A 5-byte random value generated once per process. This random value is unique to the machine and process.

A 3-byte incrementing counter, initialized to a random value.

$ python3 todos.py -o create -d 'Write a todo app'
New Todo ID: 65200e33a29c1e7244f7df59

List Documents

We can now loop the existing documents with the find operation and provide a filter so that only the items which are not completed are returned. If we wanted to return all of the items event the completed ones we could just remove the filter db.todos.find() .

💡If you need to find only a single document then find_one can be used

📝 todos.py

def get_todos() -> None:
    """
    Get Todos
    """
    print()
    for document in db.todos.find({"completed": False}):
        for key, value in document.items():
            print(f"{key}: {value}")
        print()

    return None

We see both of our To Do items printed out.

$ python3 todos.py -o read

_id: 652009addda6ead56a87d0e5
title: Do a thing
completed: False
created_date: 2023-10-06 13:20:45.434000

_id: 65200e33a29c1e7244f7df59
title: Write a todo app
completed: False
created_date: 2023-10-06 13:40:03.944000

Update a Document

To update a document update_one can be used, we need to pass a filter as the first argument to say which document to modify, the ObjectId of the todo is used in this case. The second argument is the operation we want to run, I tend to use $set the most which modifies the field value. In this example we can just modify the document to complete the todo item by setting completed to true.

📝 todos.py

def complete_todo(todo_id: str) -> None:
    """
    Complete a todo
    """
    try:
        todo_object_id = ObjectId(todo_id)
    except InvalidId:
        print("Invalid Todo Id")
        return None

    update_result = db.todos.update_one(
        {"_id": todo_object_id}, {"$set": {"completed": True}}
    )

    if update_result.matched_count == 0:
        print("Todo not found")
    else:
        print("Completed todo, nice work! 🎉")

    return None

Complete our initial todo item and verify that we no longer see it when listing out our unfinished todo items.

$ python3 todos.py -o complete -d 652009addda6ead56a87d0e5
Completed todo, nice work! 🎉

$ python3 todos.py -o read

_id: 65200e33a29c1e7244f7df59
title: Write a todo app
completed: False
created_date: 2023-10-06 13:40:03.944000

Delete a Document

Deleting a document is a similar syntax to finding a document where a filter is provided to delete_one to indicate which document to delete.

📝 todos.py

def delete_todo(todo_id: str) -> None:
    """
    Delete a todo
    """
    try:
        todo_object_id = ObjectId(todo_id)
    except InvalidId:
        print("Invalid Todo Id")
        return None

    delete_result = db.todos.delete_one({"_id": todo_object_id})

    if delete_result.deleted_count == 0:
        print("Todo not found")
    else:
        print("Deleted the todo")

    return None

Delete the todo we created and we can see that nothing gets listed when running our read command.

$ python3 todos.py -o delete -d 65200e33a29c1e7244f7df59
Deleted the todo

$ python3 todos.py -o read

Checking from the Mongo shell shows that that document was deleted and we can see that our initial document still exists but has just been marked as completed.

myAppDb> db.todos.find()
[
  {
    _id: ObjectId("652009addda6ead56a87d0e5"),
    title: 'Do a thing',
    completed: true,
    created_date: ISODate("2023-10-06T13:20:45.434Z")
  }
]

Indexes

Indexes are common across most databases and without them database queries can end up scanning every item in a collection in order to find the document or documents required. Indexes are special data structures that store a small portion of the collection's data set in an easy to traverse form. Indexes should be created for fields that are matched in the filters of commands. These are the index types that I use the most but a full list can be reference in the Index Types documentation.

💡 1 = Ascending, -1 = Descending

Single Field Index

Single field index can be used when you need to match a single field. We can apply this one to our todo example since we match on the completed field.

myAppDb> db.todos.createIndex({completed: 1})
completed_1

Unique Index

A unique index ensures that the indexed fields do not store duplicate values; i.e. enforces uniqueness for the indexed fields. By default, MongoDB creates a unique index on the _id field during the creation of a collection.

> db.collection.createIndex( { "unique_id": 1 }, { unique: true } )

TTL Index

TTL indexes are special single-field indexes that MongoDB can use to automatically remove documents from a collection after a certain amount of time. These work on fields that have Date or in Python datetime object types. This is useful for large amounts of data that may only need to be retained for a short or determined period of time.

> db.collection.createIndex( { "created_date": 1 }, { expireAfterSeconds: 3600 } )

Compound Index

Compound indexes can be used when you need to match on multiple fields.

> db.collection.createIndex( { owner: 1, created_date: 1 } )

Get Collection Indexes

Collection Indexes can be viewed with the getIndexes method.

myAppDb> db.todos.getIndexes()
[
  { v: 2, key: { _id: 1 }, name: '_id_' },
  { v: 2, key: { completed: 1 }, name: 'completed_1' }
]

Containers Demystified 🐳🤔

Deon Pillsbury — Thu, 28 Sep 2023 23:09:06 +0000

What is a Container?
Docker Setup
Container Repositories
Using Images
Persistent Storage
- Bind Mounting Files
- Volumes
Docker Compose
- Docker Compose Spec
- Using Docker Compose
- Multiple Services
- Environment Variables
- Compose Spec variable substitution
- Passing variables to containers
Creating Images
- Dockerfile
- Building a Custom Image
- Running a Custom Image
- Pushing an image to a Repository
- Multi-Architecture Images

What is a Container?

Containers virtualize an operating system and connect to the underlying kernel of a computer which allows each container to define system dependencies needed to run the code they contain and isolates them from other containers and the host operating system. This is similar to how Virtual Machines isolate software but VMs utilize a Hypervisor and abstract the hardware layer. This is why a linux VM can run on windows but a linux container needs to run on a device that has a linux kernel. Virtual Machines require more resources, management and are slower to boot up where containers in contrast are very quicker to start and require limited resources to run. In most production setups, Virtual Machines will be provisioned and Containers will be ran on the Virtual Machines which allows for a lot of flexibility.

https://www.docker.com/resources/what-container

Docker Setup

The most popular container solution and one we will be using is Docker and containers are commonly referred to as Dockers even if Docker is not the container runtime. If you are using a Mac or PC you can install Docker Desktop and if you are using a linux server then you can Install Docker and Docker Compose directly. The VS Code Docker Extension is also useful for visualizing docker resources.

🛑 Docker Desktop is free for personal use but requires a paid subscription for enterprises. A free open source alternative is Podman and Podman Compose which uses the same core syntax as the Docker tools and can be used as a near drop-in replacement.

Container Repositories

Much like code is committed to a code repository, container images are committed to a container repository and versioned with tags. The main container repository is DockerHub where most popular software can be found. A good example container repository to take a look at is the popular web server and reverse proxy NGINX which shows an overview of how to use the image along with tags for the various versions. A common pattern for container image tags is appVersion-operationSystem so in the case of NGINX using the image nginx:1.25-alpine indicates we are using NGINX version 1.25 running on an alpine linux image.

Using Images

In order to first interact with an image once you have docker installed you will need to pull it from a container repository.

$ docker pull nginx:1.25-alpine

Digest: sha256:16164a43b5faec40adb521e98272edc528e74f31c1352719132b8f7e53418d70
Status: Downloaded newer image for nginx:1.25-alpine
docker.io/library/nginx:1.25-alpine

Check your local images with the image command.

$ docker image ls

REPOSITORY   TAG           IMAGE ID       CREATED        SIZE
nginx        1.25-alpine   fa0c6bb79540   4 weeks ago    43.4MB

Run the local container image giving it a name and mapping our local computer's port 8080 to the container port 80.

💡 Running with the -d option will run it detached as a background process

$ docker run --name myServer -p 8080:80 nginx:1.25-alpine

2023/09/24 10:50:35 [notice] 1#1: using the "epoll" event method
2023/09/24 10:50:35 [notice] 1#1: nginx/1.25.2
2023/09/24 10:50:35 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r10) 
2023/09/24 10:50:35 [notice] 1#1: OS: Linux 6.3.13-linuxkit
2023/09/24 10:50:35 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2023/09/24 10:50:35 [notice] 1#1: start worker processes
2023/09/24 10:50:35 [notice] 1#1: start worker process 30
2023/09/24 10:50:35 [notice] 1#1: start worker process 31
2023/09/24 10:50:35 [notice] 1#1: start worker process 32
2023/09/24 10:50:35 [notice] 1#1: start worker process 33

Navigate to http://localhost:8080 and you should now see the NGINX welcome page.

The server can be stopped with ctrl+c and the stopped container can be viewed by appending the -a flag.

$ docker ps -a

CONTAINER ID   IMAGE               COMMAND                  CREATED         STATUS                     PORTS                      NAMES
a709dbb8bbce   nginx:1.25-alpine   "/docker-entrypoint.…"   2 minutes ago   Exited (0) 3 seconds ago                              myServer

Before re-running a container with the same name it will need to be removed and you can do this via its Container ID or Name, we will use the name since it is easy to reference.

$ docker rm myServer

myServer

Persistent Storage

Containers are ephemeral and when they are running they may create some files on disk but when they are shutdown and deleted all of those files are also deleted and the next time the container starts they will need to be re-created. The container may also require files when it initially starts such as a configuration file or directory of some sort. This is where persistent storage comes into play for mapping existing files to containers and/or persisting files after a container is shutdown and deleted. The main options that are used are Bind Mounts and Volumes.

https://docs.docker.com/storage

Bind Mounting Files

Running the container like we just did is useful for initial testing but anyone using a web server uses it to host custom files or services. Create the following nginx.conf and index.html files and we will map them from our local filesystem into our container with a Bind Mount.

📝 nginx.conf

worker_processes 3;
error_log /dev/stdout info;
events {
    worker_connections 2048;
}
http {
    include /etc/nginx/mime.types;

    server {
        listen 8000;

        location / {
            root /www/data;
            try_files $uri /index.html;
        }
    }
}

📝 index.html

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
</head>
<body>
    <h1>This is running on a containerized NGINX Server!</h1>
    <p>Hey 👋</p>
</body>
</html>

Run the NGINX container with volume flags -v local_file_path:container_file_path using our custom config and HTML bind mounted to the container.

$ docker run --name myServer \
    -p 8080:8000 \
    -v ./nginx.conf:/etc/nginx/nginx.conf \
    -v ./src/index.html:/www/data/index.html \
    nginx:1.25-alpine

2023/09/24 11:26:59 [notice] 1#1: using the "epoll" event method
2023/09/24 11:26:59 [notice] 1#1: nginx/1.25.2
2023/09/24 11:26:59 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r10) 
2023/09/24 11:26:59 [notice] 1#1: OS: Linux 6.3.13-linuxkit
2023/09/24 11:26:59 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
2023/09/24 11:26:59 [notice] 1#1: start worker processes
2023/09/24 11:26:59 [notice] 1#1: start worker process 30
2023/09/24 11:26:59 [notice] 1#1: start worker process 31
2023/09/24 11:26:59 [notice] 1#1: start worker process 32

192.168.65.1 - - [24/Sep/2023:11:27:30 +0000] "GET / HTTP/1.1" 200 172 "-" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36"

Navigate back to http://localhost:8080 and you should now see our custom HTML page being served!

Volumes

The NGINX container is using bind mounts to map local files to the container but when the container is generating data such as when it is running a database the preferred method to persist data which does not rely on the host file system structure is using Volumes. Volumes are managed by docker and are therefor easier to create without needing to know a good host path to mount to. This is an example of running a MongoDB which uses a Docker volume to persist data.

$ docker run --name myDataBase \
    -p 27017:27017 \
    -v my_db_data:/data/db \
    mongo:7.0.1

{"t":{"$date":"2023-09-24T11:25:58.117+00:00"},"s":"I",  "c":"INDEX",    "id":20345,   "ctx":"LogicalSessionCacheRefresh","msg":"Index build: done building","attr":{"buildUUID":null,"collectionUUID":{"uuid":{"$uuid":"a6160bdf-566c-4c64-b848-a6f889c5634b"}},"namespace":"config.system.sessions","index":"lsidTTLIndex","ident":"index-6-8756480188533464000","collectionIdent":"collection-4-8756480188533464000","commitTimestamp":null}}

Attach an interactive shell to the live container to test adding a document to the database.

$ docker exec -it myDataBase bash

root@c0afb87902e3:/# mongosh

test> use myDb
switched to db myDb

myDb> db.myCollection.insertOne({"a": "b"})
{
  acknowledged: true,
  insertedId: ObjectId("65156478b3f3f1b9c0d3c0a3")
}

The data has been inserted and we can verify that the volume has been created with the docker volume command.

$ docker volume ls

DRIVER    VOLUME NAME
local     my_db_data

Make sure the volume persists data even after we stop, delete and restart it.

$ docker ps -a

CONTAINER ID   IMAGE               COMMAND                  CREATED         STATUS                      PORTS                            NAMES
c0afb87902e3   mongo:7.0.1         "docker-entrypoint.s…"   5 minutes ago   Exited (0) 19 seconds ago                                    myDataBase

$ docker rm myDataBase
myDataBase

$ docker run --name myDataBase \
    -p 27017:27017 \
    -v my_db_data:/data/db \
    mongo:7.0.1

{"t":{"$date":"2023-09-24T11:25:58.117+00:00"},"s":"I",  "c":"INDEX",    "id":20345,   "ctx":"LogicalSessionCacheRefresh","msg":"Index build: done building","attr":{"buildUUID":null,"collectionUUID":{"uuid":{"$uuid":"a6160bdf-566c-4c64-b848-a6f889c5634b"}},"namespace":"config.system.sessions","index":"lsidTTLIndex","ident":"index-6-8756480188533464000","collectionIdent":"collection-4-8756480188533464000","commitTimestamp":null}}

$ docker exec -it myDataBase bash

root@8b78d1da358d:/# mongosh
test> use myDb
switched to db myDb

myDb> db.myCollection.findOne({"a": "b"})
{ _id: ObjectId("65156478b3f3f1b9c0d3c0a3"), a: 'b' }

Docker Compose

Running dockers from the command line with docker run is useful for quick testing but not commonly used in practice. The better way to run one or more dockers on a single server with all of the changes and requirements documented is to use Docker Compose. Docker Compose uses a YAML spec to define which containers to run with their required configurations and aligns with Infrastructure as Code (IaC) best practices since it can be committed to a code repository.

Docker Compose Spec

Create a docker-compose.yml file which will run the same NGINX container setup as the previous docker run command.

📝 docker-compose.yml

services:
  server:
    image: nginx:1.25-alpine
    container_name: myServer
    restart: always
    ports:
      - 8080:8000
    volumes:
      - type: bind
        source: ./nginx.conf
        target: /etc/nginx/nginx.conf
      - type: bind
        source: ./src/index.html
        target: /www/data/index.html

Using Docker Compose

Within the directory you created the docker-compose.yml file run the following command to start the container.

$ docker-compose up

[+] Running 2/0
 ✔ Network containers_default  Created 0.0s 
 ✔ Container myServer          Created 0.0s 
Attaching to myServer

myServer  | 2023/09/24 11:46:02 [notice] 1#1: using the "epoll" event method
myServer  | 2023/09/24 11:46:02 [notice] 1#1: nginx/1.25.2
myServer  | 2023/09/24 11:46:02 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r10) 
myServer  | 2023/09/24 11:46:02 [notice] 1#1: OS: Linux 6.3.13-linuxkit
myServer  | 2023/09/24 11:46:02 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
myServer  | 2023/09/24 11:46:02 [notice] 1#1: start worker processes
myServer  | 2023/09/24 11:46:02 [notice] 1#1: start worker process 30
myServer  | 2023/09/24 11:46:02 [notice] 1#1: start worker process 31
myServer  | 2023/09/24 11:46:02 [notice] 1#1: start worker process 32

Navigate back to http://localhost:8080 and we can see our same custom NGINX server is being ran.

Break the process with ctrl+c and try running the container as a background process.

$ docker-compose up -d

[+] Running 1/1
 ✔ Container myServer  Started

This is now running in the background as a detached process and can be verified with the docker ps command

$ docker ps

CONTAINER ID   IMAGE               COMMAND                  CREATED         STATUS          PORTS                            NAMES
39b33b52f96b   nginx:1.25-alpine   "/docker-entrypoint.…"   2 minutes ago   Up 45 seconds   80/tcp, 0.0.0.0:8080->8000/tcp   myServer

In order to stop a detached docker compose container run the stop command in the same directory that the docker-compose.yml file is in.

$ docker-compose stop

[+] Stopping 1/1
 ✔ Container myServer  Stopped

To stop and remove the container use down.

$ docker-compose down

[+] Running 2/1
 ✔ Container myServer          Removed
 ✔ Network containers_default  Removed

Multiple Services

The Docker Compose spec allows you to define all of your required containers as separate services within the same file. Lets add our previous mongoDb volume example to this same file.

💡 We are using the docker compose long syntax for volumes

📝 docker-compose.yml

services:
  server:
    image: nginx:1.25-alpine
    container_name: myServer
    restart: always
    ports:
      - 8080:8000
    volumes:
      - type: bind
        source: ./nginx.conf
        target: /etc/nginx/nginx.conf
      - type: bind
        source: ./src/index.html
        target: /www/data/index.html
  db:
    image: mongo:7.0.1
    container_name: myDataBase
    restart: always
    ports:
      - 27017:27017
    volumes:
      - type: volume
        source: my_db_data
        target: /data/db

volumes:
  my_db_data:

We can bring both of these containers up with the same one command now.

$ docker-compose up

[+] Running 1/0
 ✔ Container myDataBase  Created
Attaching to myDataBase, myServer

myServer    | 2023/09/24 11:57:11 [notice] 1#1: nginx/1.25.2
myServer    | 2023/09/24 11:57:11 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r10) 
myServer    | 2023/09/24 11:57:11 [notice] 1#1: OS: Linux 6.3.13-linuxkit
myServer    | 2023/09/24 11:57:11 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
myServer    | 2023/09/24 11:57:11 [notice] 1#1: start worker processes
myServer    | 2023/09/24 11:57:11 [notice] 1#1: start worker process 30
myServer    | 2023/09/24 11:57:11 [notice] 1#1: start worker process 31
myServer    | 2023/09/24 11:57:11 [notice] 1#1: start worker process 32

myDataBase  | {"t":{"$date":"2023-09-24T11:57:11.278+00:00"},"s":"I",  "c":"CONTROL",  "id":23285,   "ctx":"main","msg":"Automatically disabling TLS 1.0, to force-enable TLS 1.0 specify --sslDisabledProtocols 'none'"}

If you need to start or stop only one of the containers then you can use the same commands and just add the service name of the container you want to use.

$ docker-compose up server

[+] Running 2/0
 ✔ Network containers_default  Created
 ✔ Container myServer          Created

Attaching to myServer

myServer  | 2023/09/24 11:59:51 [notice] 1#1: using the "epoll" event method
myServer  | 2023/09/24 11:59:51 [notice] 1#1: nginx/1.25.2
myServer  | 2023/09/24 11:59:51 [notice] 1#1: built by gcc 12.2.1 20220924 (Alpine 12.2.1_git20220924-r10) 
myServer  | 2023/09/24 11:59:51 [notice] 1#1: OS: Linux 6.3.13-linuxkit
myServer  | 2023/09/24 11:59:51 [notice] 1#1: getrlimit(RLIMIT_NOFILE): 1048576:1048576
myServer  | 2023/09/24 11:59:51 [notice] 1#1: start worker processes
myServer  | 2023/09/24 11:59:51 [notice] 1#1: start worker process 30
myServer  | 2023/09/24 11:59:51 [notice] 1#1: start worker process 31
myServer  | 2023/09/24 11:59:51 [notice] 1#1: start worker process 32

Environment Variables

Environment variables are used in all applications and they allow you to make applications more flexible to run in multiple environments and keep secrets out of source code where they could become a security risk. There are a few ways to use environment variables with docker compose files, I mainly use a couple to make the compose spec more flexible by using ${VAR} variable substitution syntax or by passing external environment variables directly to the container.

Compose Spec variable substitution

In the previous Mongo example spec we could create a .env file in the same directory and define a TAG environment variable. At this point we can update the spec to use ${TAG} as the version which docker compose will automatically substitute with 6.0.1.

📝 .env

MONGO_TAG=7.0.1

📝 docker-compose.yml

services:
...
  db:
    image: mongo:${MONGO_TAG}
    container_name: myDataBase
    restart: always
    ports:
      - 27017:27017
    volumes:
      - type: volume
        source: my_db_data
        target: /data/db
...

💡 .env is used by default but the --env-file flag can be passed to the docker compose command to specify which env file to use
$ docker-compose --env-file .env.dev up

Passing variables to containers

In the mongo example we are running the database without a login which should never be done in production. So we can set an initial username and password with MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD environment variables. We should not add these into the spec directly since they would be exposed when we commit it to our code repository. This is where we can use the env_file option to tell docker compose to pass the variables from our .env file directly into the Mongo container.

📝 .env

MONGO_TAG=7.0.1
MONGO_INITDB_ROOT_USERNAME=root
MONGO_INITDB_ROOT_PASSWORD=mySecureDbPassword1!

📝 docker-compose.yml

services:
...
  db:
    image: mongo:${MONGO_TAG}
    container_name: myDataBase
    restart: always
    ports:
      - 27017:27017
    env_file:
      - .env
    volumes:
      - type: volume
        source: my_db_data
        target: /data/db
...

Creating Images

We have covered how to use popular docker images such as NGINX and Mongo but for containerizing custom software we will need to create our own docker images.

Dockerfile

The way to define how docker images are created is to use a Dockerfile which typically inherits FROM a base image and then adds our custom code and system dependencies. Lets take a look at how we can create a simple containerized python script which makes an HTTP call with the requests library. Create the following example.py and Dockerfile files in the same directory.

📝 example.py

import requests

r = requests.get("https://jsonplaceholder.typicode.com/todos/1")
r.raise_for_status()
print(r.json())

📝 Dockerfile

FROM python:3.11-slim-bookworm
WORKDIR /app

COPY example.py .

# Install dependencies
RUN pip install --upgrade pip \
    && pip install requests

ENTRYPOINT [ "python3", "example.py" ]

FROM
- This defines which image to inherit from, In this case we are using a Python image with the Python 3.11 version running on a slim version of the Bookwork version of Debian linux. Image definitions can be viewed from the DockerHub TAG link such as the python:3.11-slim-bookworm and official images like this one typically have pretty complicated definitions in order to get them highly optimized.
WORKDIR
- This defines which directory to use, otherwise it will do everything at the root / directory.
COPY
- This line copies our local file into the Docker container.
RUN
- This line runs any executable shell command such as for installing dependencies in this case and you can have many different RUN commands to install things as needed. You can also run multiple commands with a single RUN statement with && in between them.
ENTRYPOINT
- This defines what command to run when the container starts and allows for additional command line arguments to be passed in

Building a Custom Image

Now that we have our Dockerfile and example.py Python script we need to build the local docker image.

$ docker build . -t py-todos:1.0

[+] Building 8.1s (10/10) FINISHED                                                               docker:desktop-linux
 ...
 => [internal] load metadata for docker.io/library/python:3.11-slim-bookworm                                     1.6s
 => [auth] library/python:pull token for registry-1.docker.io                                                    0.0s
 => [1/4] FROM docker.io/library/python:3.11-slim-bookworm@sha256:edaf703dce209d774af3ff768fc92b1e3b60261e76021  3.3s
 ...
 => [2/4] WORKDIR /app                                                                                           0.1s
 => [3/4] COPY example.py .                                                                                      0.0s
 => [4/4] RUN pip install --upgrade pip     && pip install requests                                              3.0s
 => exporting to image                                                                                           0.1s
 => => exporting layers                                                                                          0.1s
 => => writing image sha256:342db88be1b9f09b3aa0e85c52590d7dc8acb59259cd02eaaea955255c5acefd                     0.0s
 => => naming to docker.io/library/py-todos:1.0                                                                  0.0s

We can verify that our image was built successfully with docker image commands.

$ docker image ls

REPOSITORY  TAG  IMAGE ID       CREATED              SIZE
py-todos    1.0  342db88be1b9   About a minute ago   171MB

Running a Custom Image

Now that we have our custom image built we can run it the same way that we have ran the NGINX or Mongo image.

$ docker run py-todos:1.0

{'userId': 1, 'id': 1, 'title': 'delectus aut autem', 'completed': False}

Pushing an image to a Repository

We have successfully containerized an application! 🎉 This is very useful but the container image currently only exists on our local laptop so in order to share the image it needs to be pushed to a container repository. The most popular container repository is DockerHub, create an account, login and then create a Personal Access Token so we can push our images to a repository.

$ docker login

Log in with your Docker ID or email address to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com/ to create one.
You can log in with your password or a Personal Access Token (PAT). Using a limited-scope PAT grants better security and is required for organizations using SSO. Learn more at https://docs.docker.com/go/access-tokens/

Username: dpills
Password:
Login Succeeded

After logging in we can update our local image tag with a tag containing the remote container repository which will have the syntax your_username/container_image_name.

🛑 The dockerhub container repositories are public by default so always be careful that you do not push any sensitive information in the container

$ docker image tag py-todos:1.0 dpills/py-todos:1.0

$ docker image push dpills/py-todos:1.0

The push refers to repository [docker.io/dpills/py-todos]
66acad84a3a9: Pushed
350eed7dde11: Pushed
755eced23209: Pushed
96c02c33d5bb: Mounted from library/python
02436e886926: Mounted from library/python
157a5fb7cdeb: Mounted from library/python
c4d9cc0a5063: Mounted from library/python
311627f8702d: Mounted from library/python
1.0: digest: sha256:7909c0c054aa0f7deacad0871dc07a98467a0d0c97458d6660ae46b40682c63b size: 1994

The image should now show up with the container repo in your local images and also be pushed up to the centralized container repo.

$ docker image ls
REPOSITORY                                     TAG                           IMAGE ID       CREATED          SIZE
dpills/py-todos                                1.0                           342db88be1b9   16 minutes ago   171MB
py-todos                                       1.0                           342db88be1b9   16 minutes ago   171MB

Going forward for any container which is intended to be pushed to a container repo you can just build it with the repository path from the start.

$ docker build . -t dpills/py-todos:1.1

[+] Building 0.5s (9/9) FINISHED                                   docker:desktop-linux
...
 => [internal] load metadata for docker.io/library/python:3.11-slim-bookworm       0.5s
 => [1/4] FROM docker.io/library/python:3.11-slim-bookworm@sha256:edaf703dce209d7  0.0s
...
 => CACHED [2/4] WORKDIR /app                                                      0.0s
 => CACHED [3/4] COPY example.py .                                                 0.0s
 => CACHED [4/4] RUN pip install --upgrade pip     && pip install requests         0.0s
 => exporting to image                                                             0.0s
 => => exporting layers                                                            0.0s
 => => writing image sha256:342db88be1b9f09b3aa0e85c52590d7dc8acb59259cd02eaaea95  0.0s
 => => naming to docker.io/dpills/py-todos:1.1                                     0.0s

Multi-Architecture Images

Docker builds are Architecture specific so if you are using an Apple Silicon Macbook for example then the images will be built for ARM64 CPUs but most servers use AMD64 CPUs. In order to create a multi-architecture build you will need to use buildx. Once we start this build we can see it go through the same steps for each architecture. You can also use the --push flag to automatically push it to the container repo after building.

$ docker buildx create --use
$ docker buildx build --push --platform linux/amd64,linux/arm64 . -t dpills/py-todos:1.1

[+] Building 79.6s (17/17) FINISHED                                                     docker-container:unruffled_shockley
 => [internal] booting buildkit                                                                                        4.6s
 => => pulling image moby/buildkit:buildx-stable-1                                                                     4.2s
 => => creating container buildx_buildkit_unruffled_shockley0                                                          0.5s
 => [internal] load build definition from Dockerfile                                                                   0.0s
 => => transferring dockerfile: 226B                                                                                   0.0s
 => [linux/arm64 internal] load metadata for docker.io/library/python:3.11-slim-bookworm                               1.5s
 => [linux/amd64 internal] load metadata for docker.io/library/python:3.11-slim-bookworm                               1.6s
...
 => [linux/arm64 1/4] FROM docker.io/library/python:3.11-slim-bookworm@sha256:edaf703dce209d774af3ff768fc92b1e3b60261  4.0s
...
 => => transferring context: 156B                                                                                      0.0s
 => [linux/amd64 1/4] FROM docker.io/library/python:3.11-slim-bookworm@sha256:edaf703dce209d774af3ff768fc92b1e3b60261  3.7s
...
 => [linux/amd64 3/4] COPY example.py .                                                                                0.0s
 => [linux/amd64 4/4] RUN pip install --upgrade pip     && pip install requests                                       17.2s
 => [linux/arm64 2/4] WORKDIR /app                                                                                     0.0s
 => [linux/arm64 3/4] COPY example.py .                                                                                0.0s
 => [linux/arm64 4/4] RUN pip install --upgrade pip     && pip install requests                                        3.0s
...
 => => pushing manifest for docker.io/dpills/py-todos:1.1@sha256:a2080925c4f090ca44720e77dfe37b28a8543b1be57c24dc3508  1.4s

How to rate limit FastAPI with Redis 📈

Deon Pillsbury — Sun, 24 Sep 2023 14:42:07 +0000

Rate limiting is crucial to protect against Distributed Denial of Service outages from malicious actors or from API consumers who may be unintentionally calling an endpoint inefficiently. The following script shows how we can add per user rate limiting to a FastAPI MiddleWare using Redis.

Note: This example is available on GitHub

Setup

Make sure you have a Redis Server running and the Python dependencies installed. We are using Docker Compose to run Redis and Poetry to manage the dependencies in this example.

$ docker-compose up redis -d
$ poetry install

Setup the imports, settings, clients and bootstrap our app. Note we are setting the rate limit setting to 3 in the settings and a .env file is used locally to make sure we do not expose our Redis password in the source code and is required so the redis_password setting gets set properly.

import hashlib
from datetime import datetime, timedelta
from typing import Annotated, Any, Callable, TypeVar

import uvicorn
from fastapi import FastAPI, Header, Request, Response
from fastapi.responses import JSONResponse
from pydantic_settings import BaseSettings, SettingsConfigDict
from redis.asyncio import Redis

F = TypeVar("F", bound=Callable[..., Any])


class Settings(BaseSettings):
    redis_password: str
    redis_host: str = "127.0.0.1"
    redis_port: int = 6379
    user_rate_limit_per_minute: int = 3
    model_config = SettingsConfigDict(env_file=".env", extra="ignore")


settings = Settings()

redis_client = Redis(
    host=settings.redis_host,
    port=settings.redis_port,
    db=0,
    decode_responses=True,
    password=settings.redis_password,
)
app = FastAPI(
    title="FastAPI Rate Limiting",
    description="Rate limiting users using Redis middleware",
    docs_url="/",
)

Main Logic

This is the main rate limiter logic, this implementation enforces a per user, per minute rate limit. The users name is hashed and appended with the datetime string for the current minute, this is then Incremented in redis which is set to 1 if it does not exist. If the value is 1 that means it did not exists so we then set a 1 minute Expiration for the key so we properly clean them up. If the current count has exceeded the rate limit we return an HTTP 429 Too Many Requests Error, with a X-Rate-Limit header to let the user know what the rate limit is set to and a Retry-After header so they know how long they need to wait until they can call it again.

async def rate_limit_user(user: str, rate_limit: int) -> JSONResponse | None:
    """
    Apply rate limiting per user, per minute
    """
    # Increment our most recent redis key
    username_hash = hashlib.sha256(bytes(user, "utf-8")).hexdigest()
    now = datetime.utcnow()
    current_minute = now.strftime("%Y-%m-%dT%H:%M")

    redis_key = f"rate_limit_{username_hash}_{current_minute}"
    current_count = await redis_client.incr(redis_key)

    # If we just created a new key (count is 1) set an expiration
    if current_count == 1:
        await redis_client.expireat(name=redis_key, when=now + timedelta(minutes=1))

    # Check rate limit
    if current_count > rate_limit:
        return JSONResponse(
            status_code=429,
            content={"detail": "User Rate Limit Exceeded"},
            headers={
                "Retry-After": f"{60 - now.second}",
                "X-Rate-Limit": f"{rate_limit}",
            },
        )

    return None

Plug this in to the API middleware and call our rate_limit_user function. If a response is returned it means the rate limit has been exceeded and we should just return the HTTP 429 response, else continue as normal.

@app.middleware("http")
async def rate_limit_middleware(request: Request, call_next: F) -> Response:
    """
    Rate limit requests per user
    """
    user = request.headers.get("x-user")
    if user:
        rate_limit_exceeded_response = await rate_limit_user(
            user=user, rate_limit=settings.user_rate_limit_per_minute
        )
        if rate_limit_exceeded_response:
            return rate_limit_exceeded_response

    return await call_next(request)

Add an endpoint to test with.

Note: I use an OpenResty NGINX Reverse Proxy in my production environments which handles the authentication and passes the X-User header to the API. For this small test script we are just allowing an X-User header to be manually passed to emulate a secure setup but this should not be used in production.

Example Endpoint

@app.get("/user", response_model=str | None)
def get_user(x_user: Annotated[str | None, Header()] = None):
    """
    **NOTE**: the`X-User` header should be passed by a reverse proxy,
    we are manually adding it to this endpoint so you can test
    this example locally
    """
    return x_user

Test It Out

$ python3 -m app.main

INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [16315] using WatchFiles
INFO:     Started server process [16317]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     127.0.0.1:52330 - "GET /user HTTP/1.1" 200 OK
INFO:     127.0.0.1:52342 - "GET /user HTTP/1.1" 200 OK
INFO:     127.0.0.1:52345 - "GET /user HTTP/1.1" 200 OK
INFO:     127.0.0.1:52346 - "GET /user HTTP/1.1" 429 Too Many Requests

Make 4 calls quickly and since our rate limit is set to 3 the 4th call should fail which is also reflected in the API logs and we can see the response headers show the rate limit is 3 and we can retry after 33 seconds.

$ curl -v http://localhost:8000/user -H 'x-user: joe'
...
< HTTP/1.1 200 OK
...
"joe"

$ curl -v http://localhost:8000/user -H 'x-user: joe'
...
< HTTP/1.1 200 OK
...
"joe"

$ curl -v http://localhost:8000/user -H 'x-user: joe'
...
< HTTP/1.1 200 OK
...
"joe"

$ curl -v http://localhost:8000/user -H 'x-user: joe'
*   Trying 127.0.0.1:8000...
* Connected to localhost (127.0.0.1) port 8000 (#0)
> GET /user HTTP/1.1
> Host: localhost:8000
> User-Agent: curl/8.1.2
> Accept: */*
> x-user: joe
> 
< HTTP/1.1 429 Too Many Requests
< date: Sat, 09 Sep 2023 20:42:27 GMT
< server: uvicorn
< retry-after: 33
< x-rate-limit: 3
< content-length: 37
< content-type: application/json

{"detail":"User Rate Limit Exceeded"}

This API is now protected from any single user overloading it and the rate limiting will be applied to all new endpoints.