From 7a22d34c9a967139f50a22914cc58a8374cc0d6a Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Thu, 19 Feb 2026 20:06:39 +0700 Subject: [PATCH 01/12] docs: add spread testing for tutorial --- .github/workflows/docs_spread.yaml | 16 +++++ docs/changelog.md | 5 +- docs/tutorial.md | 10 ++- spread.yaml | 100 +++++++++++++++++++++++++++++ 4 files changed, 129 insertions(+), 2 deletions(-) create mode 100644 .github/workflows/docs_spread.yaml create mode 100644 spread.yaml diff --git a/.github/workflows/docs_spread.yaml b/.github/workflows/docs_spread.yaml new file mode 100644 index 0000000..8bfeb25 --- /dev/null +++ b/.github/workflows/docs_spread.yaml @@ -0,0 +1,16 @@ +name: "Test tutorial documentation with Spread" + +on: + workflow_dispatch: + pull_request: + paths: + - "docs/tutorial.md" + +jobs: + tutorial-spread-test: + uses: canonical/operator-workflows/.github/workflows/docs_spread.yaml@main + secrets: inherit + with: + input-file: docs/tutorial.md + output-dir: tests/spread/tutorial/ + spread-job: github-ci:ubuntu-24.04-64:tests/spread/tutorial diff --git a/docs/changelog.md b/docs/changelog.md index 15195f5..80b8d9e 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -10,6 +10,10 @@ Each revision is versioned by the date of the revision. Place any unreleased changes here, that are subject to release in coming versions :). +## 2026-02-19 + +- Update tutorial and add workflow to test the tutorial using Spread. + ## 2025-01-11 - Fixed the model config variable names for HTTP and HTTPS proxy. @@ -25,4 +29,3 @@ Place any unreleased changes here, that are subject to release in coming version ## 2025-10-9 - Added core functionality and tests to the charm. - diff --git a/docs/tutorial.md b/docs/tutorial.md index bda54c6..a1957c2 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -171,6 +171,10 @@ To confirm that aproxy is forwarding properly, make an outbound TCP connection o For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: + + ```bash juju ssh ubuntu/0 curl -v cloud-images.ubuntu.com @@ -215,13 +219,15 @@ Expected output: 2025-10-14T08:43:00Z aproxy.aproxy[16156]: 2025/10/14 08:43:00 INFO relay HTTP connection to proxy src=10.142.134.228:41826 original_dst=185.125.190.40:80 host=cloud-images.ubuntu.com:80 ``` + + ## Tear down the environment Congratulations! ๐ŸŽ‰ You have successfully deployed the aproxy subordinate charm, related it to a primary application, and verified that it works as expected. -When youโ€™re done with the tutorial, clean up your environment to free resources: +When you're done with the tutorial, clean up your environment to free resources: ```bash juju destroy-model aproxy-tutorial --destroy-storage --force --no-prompt @@ -233,6 +239,8 @@ If you used a Multipass VM for this tutorial and no longer need it, you can remo multipass delete --purge my-juju-vm ``` + + ## Next steps Visit the [aproxy charm documentation](https://charmhub.io/aproxy/docs) for advanced usage and configuration options. diff --git a/spread.yaml b/spread.yaml new file mode 100644 index 0000000..1b6716e --- /dev/null +++ b/spread.yaml @@ -0,0 +1,100 @@ +# Copyright 2026 Canonical Ltd. +# See LICENSE file for licensing details. + +project: aproxy-operator + +path: /aproxy-operator +environment: + PROJECT_PATH: /aproxy-operator + + # important to ensure adhoc and linode/qemu behave the same + SUDO_USER: "" + SUDO_UID: "" + + LANG: "C.UTF-8" + LANGUAGE: "en" + +exclude: + - .git + - .github + - .tox + - .venv + - .*_cache + - charmcraft + - libexec + - schema + - snap + +backends: + multipass: + type: adhoc + allocate: | + # Mitigate issues found when launching multiple mutipass instances + # concurrently. See https://github.com/canonical/multipass/issues/3336 + sleep 0.$RANDOM + sleep 0.$RANDOM + sleep 0.$RANDOM + + mkdir -p "$HOME/.spread" + export counter_file="$HOME/.spread/multipass-count" + + # Sequential variable for unique instance names + instance_num=$(flock -x $counter_file bash -c ' + [ -s $counter_file ] || echo 0 > $counter_file + num=$(< $counter_file) + echo $num + echo $(( $num + 1 )) > $counter_file') + + multipass_image=$(echo "${SPREAD_SYSTEM}" | sed -e s/ubuntu-// -e s/-64//) + + system=$(echo "${SPREAD_SYSTEM}" | tr . -) + instance_name="spread-${SPREAD_BACKEND}-${instance_num}-${system}" + + multipass launch -vv --cpus 4 --disk 50G --memory 8G --name "${instance_name}" \ + --cloud-init charm/tests/spread/lib/cloud-config.yaml "${multipass_image}" + + # Get the IP from the instance + ip=$(multipass info --format csv "$instance_name" | tail -1 | cut -d\, -f3) + ADDRESS "$ip" + discard: | + instance_name=$(multipass list --format csv | grep $SPREAD_SYSTEM_ADDRESS | cut -f1 -d\,) + multipass delete --purge "${instance_name}" + systems: + - ubuntu-24.04-64: + username: spread + password: spread + workers: 1 + github-ci: + type: adhoc + allocate: | + echo "Allocating ad-hoc $SPREAD_SYSTEM" + if [ -z "${GITHUB_RUN_ID:-}" ]; then + FATAL "this back-end only works inside GitHub CI" + exit 1 + fi + echo 'ubuntu ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/99-spread-users + ADDRESS localhost:22 + discard: | + echo "Discarding ad-hoc $SPREAD_SYSTEM" + systems: + - ubuntu-24.04-64: + username: ubuntu + password: ubuntu + workers: 1 + +prepare: | + snap refresh --hold + + if systemctl is-enabled unattended-upgrades.service; then + systemctl stop unattended-upgrades.service + systemctl mask unattended-upgrades.service + fi + + sudo snap install --classic concierge + sudo concierge prepare -p microk8s + +suites: + tests/spread/: + summary: tutorial test + systems: + - ubuntu-24.04-64 From aca1b99d30459e920f9ecf1bfe258f9dc55cdf66 Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Thu, 19 Feb 2026 20:29:23 +0700 Subject: [PATCH 02/12] add spread skips --- docs/tutorial.md | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index a1957c2..272e369 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -48,6 +48,8 @@ juju deploy ubuntu Wait until the deployment is complete: + + ```bash juju status --watch 1s ``` @@ -59,6 +61,8 @@ App Version Status Scale Charm Channel Rev Exposed Message ubuntu 24.04 active 1 ubuntu latest/stable 26 no ``` + + ## Deploy the aproxy subordinate charm Now deploy the aproxy charm with the target proxy address and proxy port. In this tutorial, we will use `127.0.0.1:80`. @@ -89,6 +93,8 @@ juju status The output should be similar to the following: + + ``` Model Controller Cloud/Region Version aproxy-tutorial lxd localhost 3.4.1 @@ -102,6 +108,8 @@ ubuntu/0* active idle 0 10.152.184.228 aproxy/0* active idle 10.152.184.228 Service ready on target proxy 127.0.0.1:80 ``` + + You should see both applications in an **active** state, with aproxy listed as a subordinate unit to the Ubuntu charm. ## Run a configuration test @@ -122,6 +130,8 @@ juju config aproxy The output should be similar to the following: + + ``` application: aproxy application-config: @@ -165,21 +175,21 @@ settings: ``` + + ## Run a connection test To confirm that aproxy is forwarding properly, make an outbound TCP connection on the principal charm. For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: - - ```bash juju ssh ubuntu/0 curl -v cloud-images.ubuntu.com ``` + + If successful, the output should be similar to the following: ``` @@ -219,8 +229,6 @@ Expected output: 2025-10-14T08:43:00Z aproxy.aproxy[16156]: 2025/10/14 08:43:00 INFO relay HTTP connection to proxy src=10.142.134.228:41826 original_dst=185.125.190.40:80 host=cloud-images.ubuntu.com:80 ``` - - ## Tear down the environment Congratulations! ๐ŸŽ‰ From cf6c521e0c526233e4b4ec0a18a7f1d2e3b310c7 Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Thu, 19 Feb 2026 20:52:55 +0700 Subject: [PATCH 03/12] switch to lxd for machine charm --- spread.yaml | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/spread.yaml b/spread.yaml index 1b6716e..3e97d99 100644 --- a/spread.yaml +++ b/spread.yaml @@ -90,8 +90,11 @@ prepare: | systemctl mask unattended-upgrades.service fi - sudo snap install --classic concierge - sudo concierge prepare -p microk8s + # Ensure LXD is installed and initialized for machine-based Juju models + sudo snap install lxd --channel=stable + sudo lxd waitready + sudo lxd init --auto + juju bootstrap lxd lxd-controller suites: tests/spread/: From d2208dd2d0fd7437959662bcbc1497d35c259e9f Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Thu, 19 Feb 2026 20:53:17 +0700 Subject: [PATCH 04/12] add output check --- docs/tutorial.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 272e369..b634c1e 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -183,13 +183,15 @@ To confirm that aproxy is forwarding properly, make an outbound TCP connection o For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: + + + + ```bash juju ssh ubuntu/0 curl -v cloud-images.ubuntu.com ``` - - If successful, the output should be similar to the following: ``` From 828be18aa989094611a0d4b08e99d880addd6c25 Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Thu, 19 Feb 2026 21:16:10 +0700 Subject: [PATCH 05/12] remove juju command --- spread.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/spread.yaml b/spread.yaml index 3e97d99..17fdcdb 100644 --- a/spread.yaml +++ b/spread.yaml @@ -94,7 +94,6 @@ prepare: | sudo snap install lxd --channel=stable sudo lxd waitready sudo lxd init --auto - juju bootstrap lxd lxd-controller suites: tests/spread/: From 9e370ae92138e614cce9b4d181dd6e71bb312c47 Mon Sep 17 00:00:00 2001 From: florentianayuwono <76247368+florentianayuwono@users.noreply.github.com> Date: Fri, 20 Feb 2026 10:05:33 +0700 Subject: [PATCH 06/12] Apply suggestions from code review Co-authored-by: Erin Conley --- docs/tutorial.md | 4 +++- spread.yaml | 2 +- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index b634c1e..6fa4150 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -183,7 +183,9 @@ To confirm that aproxy is forwarding properly, make an outbound TCP connection o For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: - + diff --git a/spread.yaml b/spread.yaml index 17fdcdb..f82ac76 100644 --- a/spread.yaml +++ b/spread.yaml @@ -29,7 +29,7 @@ backends: multipass: type: adhoc allocate: | - # Mitigate issues found when launching multiple mutipass instances + # Mitigate issues found when launching multiple Multipass instances # concurrently. See https://github.com/canonical/multipass/issues/3336 sleep 0.$RANDOM sleep 0.$RANDOM From 5ae87878bd60ef809e2683331ccd0f6478ca49ca Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Fri, 20 Feb 2026 10:06:22 +0700 Subject: [PATCH 07/12] add concierge --- spread.yaml | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/spread.yaml b/spread.yaml index f82ac76..a662609 100644 --- a/spread.yaml +++ b/spread.yaml @@ -90,10 +90,8 @@ prepare: | systemctl mask unattended-upgrades.service fi - # Ensure LXD is installed and initialized for machine-based Juju models - sudo snap install lxd --channel=stable - sudo lxd waitready - sudo lxd init --auto + sudo snap install --classic concierge + sudo concierge prepare -p machine suites: tests/spread/: From 695d0ac2d083cd05d5e4584b05e4838e878bdc75 Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Fri, 20 Feb 2026 11:13:51 +0700 Subject: [PATCH 08/12] modify grep --- docs/tutorial.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 6fa4150..2f66d4f 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -183,8 +183,8 @@ To confirm that aproxy is forwarding properly, make an outbound TCP connection o For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: - From af6a39b83c59ceba360e291b0565a5f354d755cc Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Fri, 20 Feb 2026 11:26:18 +0700 Subject: [PATCH 09/12] change grep --- docs/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 2f66d4f..57041dd 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -184,7 +184,7 @@ To confirm that aproxy is forwarding properly, make an outbound TCP connection o For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: From 217dd724f87c209f9c10c2aa9f55476f9fec95c8 Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Fri, 20 Feb 2026 11:46:17 +0700 Subject: [PATCH 10/12] remove sign --- docs/tutorial.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 57041dd..9a81a1a 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -184,7 +184,7 @@ To confirm that aproxy is forwarding properly, make an outbound TCP connection o For example, let's curl `cloud-images.ubuntu.com` from inside `ubuntu/0` unit: From 2bc358c5881d656a16d0c0471e33ba5ea4abe1d0 Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Fri, 20 Feb 2026 16:39:02 +0700 Subject: [PATCH 11/12] remove file --- docs/tutorial.md | 4 ++++ spread.yaml | 3 +-- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/tutorial.md b/docs/tutorial.md index 9a81a1a..526ccd2 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -46,6 +46,10 @@ Deploy the Ubuntu charm: juju deploy ubuntu ``` + + Wait until the deployment is complete: diff --git a/spread.yaml b/spread.yaml index a662609..212f64b 100644 --- a/spread.yaml +++ b/spread.yaml @@ -50,8 +50,7 @@ backends: system=$(echo "${SPREAD_SYSTEM}" | tr . -) instance_name="spread-${SPREAD_BACKEND}-${instance_num}-${system}" - multipass launch -vv --cpus 4 --disk 50G --memory 8G --name "${instance_name}" \ - --cloud-init charm/tests/spread/lib/cloud-config.yaml "${multipass_image}" + multipass launch -vv --cpus 4 --disk 50G --memory 8G --name "${instance_name}" "${multipass_image}" # Get the IP from the instance ip=$(multipass info --format csv "$instance_name" | tail -1 | cut -d\, -f3) From b48ddcfa332d2fba4d20a8b6f5246f8d2b591cce Mon Sep 17 00:00:00 2001 From: florentianayuwono Date: Sun, 22 Feb 2026 18:58:35 +0700 Subject: [PATCH 12/12] remove backend --- spread.yaml | 56 ----------------------------------------------------- 1 file changed, 56 deletions(-) diff --git a/spread.yaml b/spread.yaml index 212f64b..d0fc682 100644 --- a/spread.yaml +++ b/spread.yaml @@ -25,62 +25,6 @@ exclude: - schema - snap -backends: - multipass: - type: adhoc - allocate: | - # Mitigate issues found when launching multiple Multipass instances - # concurrently. See https://github.com/canonical/multipass/issues/3336 - sleep 0.$RANDOM - sleep 0.$RANDOM - sleep 0.$RANDOM - - mkdir -p "$HOME/.spread" - export counter_file="$HOME/.spread/multipass-count" - - # Sequential variable for unique instance names - instance_num=$(flock -x $counter_file bash -c ' - [ -s $counter_file ] || echo 0 > $counter_file - num=$(< $counter_file) - echo $num - echo $(( $num + 1 )) > $counter_file') - - multipass_image=$(echo "${SPREAD_SYSTEM}" | sed -e s/ubuntu-// -e s/-64//) - - system=$(echo "${SPREAD_SYSTEM}" | tr . -) - instance_name="spread-${SPREAD_BACKEND}-${instance_num}-${system}" - - multipass launch -vv --cpus 4 --disk 50G --memory 8G --name "${instance_name}" "${multipass_image}" - - # Get the IP from the instance - ip=$(multipass info --format csv "$instance_name" | tail -1 | cut -d\, -f3) - ADDRESS "$ip" - discard: | - instance_name=$(multipass list --format csv | grep $SPREAD_SYSTEM_ADDRESS | cut -f1 -d\,) - multipass delete --purge "${instance_name}" - systems: - - ubuntu-24.04-64: - username: spread - password: spread - workers: 1 - github-ci: - type: adhoc - allocate: | - echo "Allocating ad-hoc $SPREAD_SYSTEM" - if [ -z "${GITHUB_RUN_ID:-}" ]; then - FATAL "this back-end only works inside GitHub CI" - exit 1 - fi - echo 'ubuntu ALL=(ALL) NOPASSWD:ALL' | sudo tee /etc/sudoers.d/99-spread-users - ADDRESS localhost:22 - discard: | - echo "Discarding ad-hoc $SPREAD_SYSTEM" - systems: - - ubuntu-24.04-64: - username: ubuntu - password: ubuntu - workers: 1 - prepare: | snap refresh --hold