Az webservers tutorial - #5133
Conversation
There was a problem hiding this comment.
Pull request overview
This PR restructures the documentation tutorials by moving the existing “Getting started” walkthrough into its own page, adding a new Availability Zones tutorial, and updating tutorial navigation/indexing so readers can discover both tutorials more easily.
Changes:
- Replaces the long tutorial landing page with a short tutorial index that links to individual tutorials.
- Adds two tutorial pages: Getting started (moved content) and Availability zones (new content).
- Updates the main docs landing page to link directly to the new getting-started tutorial anchor.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/tutorial/index.md | Converts the tutorial landing page into a short index + toctree for multiple tutorials. |
| docs/tutorial/getting-started.md | Adds the standalone “Getting started” tutorial content (previously embedded in the index). |
| docs/tutorial/availability-zones.md | Adds a new hands-on Availability Zones tutorial (zones, web backends, HAProxy LB, failover). |
| docs/index.md | Updates the “Basics” tutorial link target to point at the new getting-started tutorial page. |
Suppressed comments (1)
docs/tutorial/availability-zones.md:160
- Same as above:
multipass disable-zonesprompts for confirmation unless--forceis provided, which can interrupt the tutorial flow.
multipass disable-zones zone2
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Suppressed comments (6)
docs/index.md:29
- The link text says "Getting stated" (typo). This should be "Getting started" so the tutorial entry reads correctly.
- Tutorial: [Getting stated with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos)
docs/tutorial/getting-started.md:319
- This inline command uses an en dash ("–name") instead of the CLI flag "--name", which will fail if a reader copies/pastes it.
When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first).
docs/tutorial/availability-zones.md:22
- The default
multipass zonestable output includes a third "Subnet" column (seeTableFormatter::format(const ZonesReply&)), but the sample output here only shows Name/State. Updating the sample prevents confusion when readers compare outputs.
Name State Subnet
zone1 Available 192.168.252.0/24
zone2 Available 192.168.253.0/24
zone3 Available 192.168.254.0/24
docs/tutorial/availability-zones.md:136
multipass disable-zonesprompts for confirmation unless--forceis provided. In a tutorial, adding--forcemakes the command reliably copy/paste-able and matches the command's own guidance for non-interactive use.
multipass disable-zones zone1
docs/tutorial/availability-zones.md:160
- Same as above:
multipass disable-zoneswill prompt unless--forceis specified, which can interrupt a copy/paste run-through.
multipass disable-zones zone2
docs/tutorial/index.md:2
- This page introduces multiple tutorials (and the body text uses "These tutorials"), but the heading is singular. Renaming to "Tutorials" keeps the page consistent with its content.
# Tutorial
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Suppressed comments (2)
docs/index.md:29
- Typo in the link text: "Getting stated" should be "Getting started".
- Tutorial: [Getting stated with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos)
docs/tutorial/index.md:2
- The page title is singular ("Tutorial") but the introductory sentence and structure describe multiple tutorials. This is inconsistent within the page and can be confusing in navigation/search results.
# Tutorial
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.
Suppressed comments (2)
docs/tutorial/getting-started.md:319
- The command example uses an en dash in
–nameinstead of the ASCII--name. This will fail if users copy/paste the command from the docs.
When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first).
docs/tutorial/availability-zones.md:22
- The
multipass zonessample output hard-codes subnets (192.168.252.0/24, etc.), but the subnet range is platform/driver-dependent (e.g., Linux defaults to 10.97.0.0/16) and can vary if the preferred subnet is already in use. Using placeholders (or noting variability) will avoid confusing users when their output differs.
Name State Subnet
zone1 Available 192.168.252.0/24
zone2 Available 192.168.253.0/24
zone3 Available 192.168.254.0/24
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.
Suppressed comments (2)
docs/tutorial/getting-started.md:319
- The example command uses an en dash (–) in
multipass launch –name primary, which will fail if users copy/paste it. Use the normal double-hyphen option--nameinstead.
When you select Open Shell, what happens in the background is the equivalent of the CLI commands `multipass launch –name primary` followed by `multipass shell`. Open a terminal and try `multipass shell` (if you didn't follow the steps above, you will have to run the `launch` command first).
docs/index.md:29
- Link text says “Setup the driver”, but the linked page title is “How to set up the driver”. Using the verb form “Set up” reads better here and matches the target page wording.
- Tutorial: [Getting started with Multipass](tutorial-getting-started) • [Install Multipass](how-to-guides-install-multipass) • [Setup the driver](how-to-guides-customise-multipass-set-up-the-driver) • [Migrate from Hyperkit to QEMU](how-to-guides-customise-multipass-migrate-from-hyperkit-to-qemu-on-macos)
jimporter
left a comment
jimporter
left a comment
There was a problem hiding this comment.
Thanks for all the time you've spent on various versions of this tutorial. It's looking really good. Just a few minor comments below.
| (tutorial-availability-zones)= | ||
| # Multipass availability zones with a load-balanced web service | ||
|
|
||
| In this tutorial, we will use Multipass availability zones to build a simple, highly available web service. We will deploy three Nginx web servers, one in each availability zone, and a fourth instance acting as a load balancer to distribute traffic between them. |
There was a problem hiding this comment.
It might be useful to add a short description of what availability zones are, since not everyone using Multipass would know (though it's easy enough to Google). Maybe something like, "In the real world, availability zones are clusters of data centers in a particular region. Multipass provides a local simulation of availability zones for development purposes."
| zone2 Available 192.168.253.0/24 | ||
| zone3 Available 192.168.254.0/24 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
Maybe add something about why the subnets are relevant here? It probably needs some editing, but something like this: "You can see how each zone has its own subnet to simulate the different networks belonging to each real-world zone."
Or is that getting too detailed for this tutorial?
| ```bash | ||
| WEB_A_IP=$(multipass info web-a --format csv | awk -F, 'NR>1 {print $5}') | ||
| WEB_B_IP=$(multipass info web-b --format csv | awk -F, 'NR>1 {print $5}') | ||
| WEB_C_IP=$(multipass info web-c --format csv | awk -F, 'NR>1 {print $5}') | ||
| ``` |
There was a problem hiding this comment.
Should we include a Windows variant of these commands?
| ```bash | ||
| cat << EOF > haproxy.cfg | ||
|
|
||
| frontend http_front | ||
| bind *:80 | ||
| default_backend http_back | ||
|
|
||
| backend http_back | ||
| balance roundrobin | ||
| server web-a $WEB_A_IP:80 check | ||
| server web-b $WEB_B_IP:80 check | ||
| server web-c $WEB_C_IP:80 check | ||
| EOF |
| Find the IP address of your load balancer: | ||
|
|
||
| ```bash | ||
| LB_IP=$(multipass info load-balancer --format csv | awk -F, 'NR>1 {print $5}') |
| <h1>Welcome to web-c in zone3</h1> | ||
| ``` | ||
|
|
||
| Notice that neither response comes from `web-a` in `zone1`. |
There was a problem hiding this comment.
| Notice that neither response comes from `web-a` in `zone1`. | |
| Notice that none of the responses comes from `web-a` in `zone1`. |
| multipass disable-zones zone2 | ||
| ``` | ||
|
|
||
| Query the load balancer once more. With two zones down, every request can only come from `web-c` in `zone3`: |
There was a problem hiding this comment.
| Query the load balancer once more. With two zones down, every request can only come from `web-c` in `zone3`: | |
| Query the load balancer again. With two zones down, every request can only come from `web-c` in `zone3`: |
| Query the load balancer once more. With two zones down, every request can only come from `web-c` in `zone3`: | ||
|
|
||
| ```bash | ||
| curl http://$LB_IP |
There was a problem hiding this comment.
| curl http://$LB_IP | |
| curl http://$LB_IP | |
| curl http://$LB_IP |
| *Expected output:* | ||
|
|
||
| ```text | ||
| <h1>Welcome to web-c in zone3</h1> |
There was a problem hiding this comment.
| <h1>Welcome to web-c in zone3</h1> | |
| <h1>Welcome to web-c in zone3</h1> | |
| <h1>Welcome to web-c in zone3</h1> |
| multipass enable-zones zone1 zone2 | ||
| ``` | ||
|
|
||
| After a few moments, `web-a` and `web-b` rejoin the rotation and the load balancer serves all three zones once more. |
There was a problem hiding this comment.
Should we show this with an example?
Description
This PR introduces the Availability Zones tutorial and relevant index file updates.
Testing
Unit tests
Manual testing steps:
make clean && make runScreenshots (if applicable)
Checklist
MULTI-2794