docs: add spread testing for tutorial

.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

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.
-

docs/tutorial.md

@@ -48,6 +48,8 @@ juju deploy ubuntu
 
 Wait until the deployment is complete:
 
+<!-- SPREAD SKIP -->
+
 ```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
 ```
 
+<!-- SPREAD SKIP END -->
+
 ## 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:
 
+<!-- SPREAD SKIP -->
+
 ```
 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
 ```
 
+<!-- SPREAD SKIP END -->
+
 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:
 
+<!-- SPREAD SKIP -->
+
 ```
 application: aproxy
 application-config:
@@ -165,12 +175,18 @@ settings:
 
 ```
 
+<!-- SPREAD SKIP END -->
+
 ## 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:
 
+<!-- SPREAD juju ssh ubuntu/0 -- curl -v cloud-images.ubuntu.com | grep -q "HTTP/1.1 200 OK" -->
+
+<!-- SPREAD SKIP -->
+
 ```bash
 juju ssh ubuntu/0
 curl -v cloud-images.ubuntu.com
@@ -221,7 +237,7 @@ 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 +249,8 @@ If you used a Multipass VM for this tutorial and no longer need it, you can remo
 multipass delete --purge my-juju-vm
 ```
 
+<!-- SPREAD SKIP END -->
+
 ## Next steps
 
 Visit the [aproxy charm documentation](https://charmhub.io/aproxy/docs) for advanced usage and configuration options.

spread.yaml

@@ -0,0 +1,102 @@
+# 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
+
+  # Ensure LXD is installed and initialized for machine-based Juju models
+  sudo snap install lxd --channel=stable
+  sudo lxd waitready
+  sudo lxd init --auto
+
+suites:
+  tests/spread/:
+    summary: tutorial test
+    systems:
+      - ubuntu-24.04-64