Chore(docs): Changed tutorial to how-to. Updated spread test.

canonical · Dec 9, 2024 · 5d7739e · 5d7739e
1 parent 5000827
commit 5d7739e
Show file tree

Hide file tree

Showing 9 changed files with 62 additions and 466 deletions.
diff --git a/docs/tutorial/code/flask-async/app.py → docs/howto/code/flask-async/app.py b/docs/tutorial/code/flask-async/app.py → docs/howto/code/flask-async/app.py
diff --git a/docs/howto/code/flask-async/requirements.txt b/docs/howto/code/flask-async/requirements.txt
@@ -0,0 +1,2 @@
+Flask
+gevent
diff --git a/docs/tutorial/code/flask-async/task.yaml → docs/howto/code/flask-async/task.yaml b/docs/tutorial/code/flask-async/task.yaml → docs/howto/code/flask-async/task.yaml
@@ -5,7 +5,7 @@
 # markers for including said instructions
 # as snippets in the docs.
 ###########################################
-summary: Getting started with Flask tutorial
+summary: How to create async Flask Charm
 
 kill-timeout: 90m
 
@@ -35,15 +35,10 @@ execute: |
   snapcraft pack
   snap install --dangerous --classic rockcraft_*
 
-
-  snap install lxd
-  lxd init --auto
   # snap refresh charmcraft --channel=latest/edge --amend
-  snap install microk8s --channel=1.31-strict/stable
-  snap install juju --channel=3.5/stable
+  snap install microk8s --channel=1.32-strict/stable
+  snap install juju --channel=3/stable
 
-  # Juju config setup
-  lxc network set lxdbr0 ipv6.address none
   mkdir -p ~/.local/share
 
   # MicroK8s config setup
@@ -61,7 +56,6 @@ execute: |
   python3 -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt
-  pip install Flask
   # [docs:create-venv-end]
 
   flask run -p 8000 &
@@ -84,36 +78,6 @@ execute: |
   sed -i "s/name: .*/name: flask-async-app/g" rockcraft.yaml
   sed -i "s/amd64/$(dpkg --print-architecture)/g" rockcraft.yaml
 
-  # uncomment the parts main section
-  sed -i "s/# parts:/parts:/g" rockcraft.yaml
-  # uncomment the async-dependencies part
-  awk -i inplace -v block_key="flask-framework/async-dependencies" '
-  BEGIN {
-    in_block = 0;
-    comment_pattern = "^#[[:space:]]";
-    uncommented_line = "";
-  }
-
-  /^#[[:space:]]/ {
-    # Check if the line contains the block key
-    if (in_block == 0 && $0 ~ block_key) {
-      in_block = 1;
-    }
-  }
-
-  {
-    # If in_block is active, uncomment lines
-    if (in_block == 1) {
-      uncommented_line = gensub(comment_pattern, "", 1, $0);
-      if (uncommented_line == $0) {
-        in_block = 0;
-      }
-      print uncommented_line;
-    } else {
-      print $0;
-    }
-  }' rockcraft.yaml
-
   # [docs:pack]
   rockcraft pack
   # [docs:pack-end]
@@ -181,6 +145,8 @@ execute: |
   juju config flask-async-app webserver-worker-class=gevent
   # [docs:config-async-end]
 
+  juju wait-for application flask-async-app --query='status=="active"' --timeout 10m
+
   # test the async flask service
   NUM_REQUESTS=15
   ASYNC_RESULT='TRUE'
@@ -221,8 +187,7 @@ execute: |
   deactivate
   rm -rf charm .venv __pycache__
   # delete all the files created during the tutorial
-  rm flask-async-app_0.1_$(dpkg --print-architecture).rock flask-async-app_0.2_$(dpkg --print-architecture).rock \
-    flask-async-app_0.3_$(dpkg --print-architecture).rock rockcraft.yaml app.py \
+  rm flask-async-app_0.1_$(dpkg --print-architecture).rock rockcraft.yaml app.py \
     requirements.txt migrate.py
   # Remove the juju model
   juju destroy-model flask-async-app --destroy-storage --no-prompt --force

diff --git a/docs/howto/flask-async.rst b/docs/howto/flask-async.rst
@@ -0,0 +1,48 @@
+======================================================
+How to write a Kubernetes charm for an Async Flask app
+======================================================
+
+In this how to we will configure 12 Factor Flask application
+to use asynchronous Gunicorn workers to be able to serve
+to multiple users easily.
+
+Make the rock async
+===================
+
+Before packing the rock make sure to put the following in ``requirements.txt``
+file:
+
+.. literalinclude:: code/flask-async/requirements.txt
+
+Configure the async application
+===============================
+
+Now let's enable async Gunicorn workers using a configuration option. We will
+expect this configuration option to be available in the Flask app configuration
+under the keyword ``webserver-worker-class``. Verify that the new configuration
+has been added using
+``juju config flask-async-app | grep -A 6 webserver-worker-class:`` which should
+show the configuration option.
+
+.. note::
+
+    The ``grep`` command extracts a portion of the configuration to make
+    it easier to check whether the configuration option has been added.
+
+The worker class can be changed using Juju:
+
+.. literalinclude:: code/flask-async/task.yaml
+    :language: bash
+    :start-after: [docs:config-async]
+    :end-before: [docs:config-async-end]
+    :dedent: 2
+
+Now you can run
+``curl --parallel --parallel-immediate --resolve flask-async-app:80:127.0.0.1 \
+http://flask-async-app/io http://flask-async-app/io http://flask-async-app/io \
+http://flask-async-app/io http://flask-async-app/io``
+in they will all return at the same time.
+
+.. note::
+
+    It might take a short time for the configuration to take effect.
diff --git a/docs/howto/index.rst b/docs/howto/index.rst
@@ -9,3 +9,4 @@ How-To
    charm-to-poetry
    charm-to-python
    shared-cache
+   flask-async
diff --git a/docs/tutorial/code/flask-async/requirements.txt b/docs/tutorial/code/flask-async/requirements.txt