canonical · roosterfish · Jun 30, 2025 · Jun 23, 2025 · Jun 23, 2025 · Jun 23, 2025
diff --git a/doc/.custom_wordlist.txt b/doc/.custom_wordlist.txt
@@ -5,6 +5,8 @@ AGPLv
 backend
 backporting
 balancers
+bugfix
+bugfixes
 CCLA
 Ceph
 Ceph's
@@ -29,6 +31,7 @@ intra
 IOV
 IPs
 IPv
+lifecycle
 LTS
 LXD
 LXD's
@@ -61,6 +64,7 @@ subnets
 SVG
 TinyPNG
 uplink
+upstream's
 VLAN
 vlatest
 VM

diff --git a/doc/Makefile b/doc/Makefile
@@ -82,15 +82,15 @@ html: integrate
 	cd integration/lxd/doc/ && $(MAKE) html BUILDDIR=$(current_dir)/_build/lxd
 	cd integration/microceph/docs/ && $(MAKE) html BUILDDIR=$(current_dir)/_build/microceph
 	cd integration/microovn/docs/ && $(MAKE) html BUILDDIR=$(current_dir)/_build/microovn
-	$(MAKE) -f Makefile.sp sp-html BUILDDIR=$(current_dir)/_build/microcloud
+	$(MAKE) -f Makefile.sp sp-html BUILDDIR=$(current_dir)/_build/microcloud ADDPREREQS='pyyaml'
 
 # `html-rtd` builds the integrated docs, with the correct paths for Read the Docs.
 # This target is used by the Read the Docs build.
 html-rtd:
 	PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/lxd/doc/ html-rtd BUILDDIR=$(READTHEDOCS_OUTPUT)/html/lxd
 	PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/microceph/docs/ html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microceph
 	PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -C integration/microovn/docs/ html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microovn
-	PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -f Makefile.sp sp-html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microcloud
+	ADDPREREQS='pyyaml' PATH_PREFIX=$(PATH_PREFIX) $(MAKE) -f Makefile.sp sp-html BUILDDIR=$(READTHEDOCS_OUTPUT)/html/microcloud
 
 # `spelling` checks only the MicroCloud docs.
 spelling: clean-doc microcloud
@@ -112,5 +112,8 @@ serve: html
 serve-microcloud: microcloud
 	cd $(current_dir)/_build/; python3 -m http.server --bind 127.0.0.1 8000
 
+install:
+	$(MAKE) -f Makefile.sp sp-install ADDPREREQS='pyyaml'
+
 %:
 	$(MAKE) -f Makefile.sp sp-$@
diff --git a/doc/custom_conf.py b/doc/custom_conf.py
@@ -1,5 +1,6 @@
 import datetime
 import os
+import yaml
 
 # Custom configuration for the Sphinx documentation builder.
 # All configuration specific to your project should be done in this file.
@@ -163,7 +164,9 @@
 # Links to ignore when checking links
 linkcheck_ignore = [
     'http://127.0.0.1:8000',
-    'http://localhost:8000'
+    'http://localhost:8000',
+    # These links may fail from time to time
+    'https://ceph.io',
     ]
 
 # Pages on which to ignore anchors
@@ -221,6 +224,7 @@
 # sphinxext-opengraph
 custom_required_modules = [
     'sphinx-sitemap',
+    'pyyaml',
 ]
 
 # Add files or directories that should be excluded from processing.
@@ -294,3 +298,8 @@
     custom_templates_path = ['integration/microcloud/_templates']
     redirects['../index'] = 'microcloud/'
     custom_tags.append('integrated')
+
+# Load substitutions from YAML file
+if os.path.exists('./substitutions.yaml'):
+    with open('./substitutions.yaml', 'r') as fd:
+        myst_substitutions = yaml.safe_load(fd.read())
diff --git a/doc/how-to/install.md b/doc/how-to/install.md
@@ -86,27 +86,73 @@ For detailed information, see: {ref}`reference-requirements`.
 ```{youtube} https://www.youtube.com/watch?v=M0y0hQ16YuE
 ```
 
-To install MicroCloud, install all required {ref}`snaps <reference-requirements-software-snaps>` on all machines that you want to include in your cluster.
+To install MicroCloud, install all required {ref}`snaps <reference-requirements-software-snaps>` on all machines that you want to include in your cluster. You can {ref}`optionally specify a channel <howto-install-specify-channel>` for each snap, but generally, you can leave out the channel to use the current recommended default. 
 
 To do so, enter the following commands on all machines:
 
-    sudo snap install lxd --channel=5.21/stable --cohort="+"
-    sudo snap install microceph --channel=squid/stable --cohort="+"
-    sudo snap install microovn --channel=24.03/stable --cohort="+"
-    sudo snap install microcloud --channel=2/stable --cohort="+"
+```bash
+sudo snap install lxd --cohort="+"
+sudo snap install microceph --cohort="+"
+sudo snap install microovn --cohort="+"
+sudo snap install microcloud --cohort="+"
+```
+
+The `--cohort` flag ensures that versions remain {ref}`synchronized during later updates <howto-update-sync>`.
+
+Following installation, make sure to {ref}`hold updates <howto-update-hold>`.
+
+### Previously installed snaps
+
+If a required snap is already installed on your machine, you will receive a message to that effect. In this case, check the version for the installed snap:
+
+```bash
+snap list <snap>
+```
+
+View the {ref}`matrix of compatible versions <ref-releases-matrix>` to determine whether you need to upgrade the snap to a different channel. Follow either the update or upgrade instructions below.
+
+#### Update
+
+If the installed snap is using a channel corresponding to a release that is compatible with the other snaps, update to the most recent stable version of the snap without changing the channel:
+
+```bash
+sudo snap refresh <snap> --cohort="+"
+```
 
-```{note}
-Make sure to install the same version of the snaps on all machines.
-See {ref}`howto-snap` for more information.
+#### Upgrade
 
-If you don't want to use MicroCloud's full functionality, you can install only some of the snaps.
-However, this is not recommended.
+If you need to upgrade the channel, run:
+
+```bash
+sudo snap refresh <snap> --cohort="+" --channel=<target channel>
+```
+
+Example:
+
+```bash
+sudo snap refresh microcloud --cohort="+" --channel=2/stable
+```
+
+(howto-install-specify-channel)=
+### Optionally specify a channel
+
+Channels correspond to different {ref}`releases <ref-releases-snaps>`. When unspecified, MicroCloud and its components' snaps use their respective recommended default channels.
+
+To specify a different channel, add the `--channel` flag at installation:
+
+```bash
+sudo snap install <snap> --cohort="+" --channel=<target channel>
 ```
 
-```{note}
-It's possible that a required snap is already installed on your machine. For example, it might be a version of Ubuntu that comes with LXD pre-installed.
-In this case, run `sudo snap refresh <snap> --channel=<track>/stable --cohort="+"` to refresh (update) the installed snap.
+For example, to use the `3/edge` channel for the MicroCloud snap, run:
+
+```bash
+sudo snap install microcloud --cohort="+" --channel=3/edge
 ```
 
-After installing the snaps make sure to hold any automatic updates to keep the used snap versions across MicroCloud in sync.
-See {ref}`howto-snap-hold-updates` for more information.
+For details about the MicroCloud snap channels, see: {ref}`ref-snaps-microcloud-channels`.
+
+(howto-install-hold-updates)=
+## Hold updates
+
+When a new release is published to a snap channel, installed snaps following that channel update automatically by default. This is undesired behavior for MicroCloud and its components, and you should override this default behavior by holding updates. See: {ref}`howto-update-hold`.
diff --git a/doc/how-to/snaps.md b/doc/how-to/snaps.md
@@ -1,87 +1,78 @@
 (howto-snap)=
 # How to manage the snaps
 
-MicroCloud is distributed as a [snap](https://snapcraft.io/docs).
-The benefit of packaging MicroCloud as a snap is that it makes it possible to include the required dependencies, and that it allows MicroCloud to be installed on many different Linux distributions.
-The snap ensures that MicroCloud runs in a consistent environment.
+Manage MicroCloud and its components (LXD, MicroCeph, and MicroOVN) through their snap packages.
 
-Because MicroCloud uses a set of {ref}`other snaps <reference-requirements-software-snaps>`, you must make sure to have suitable versions of these snaps installed on all machines of your MicroCloud cluster.
-The installed snap versions must be compatible with one another, and for each of the snaps, the same version must be installed on all machines.
+For the installation guide, see: {ref}`howto-install`. For details about the snaps, including {ref}`supported and compatible releases <ref-releases-matrix>`, {ref}`tracks <ref-snaps-microcloud-tracks>`, and {ref}`release processes <ref-releases-microcloud>`, see: {ref}`ref-releases-snap`.
 
-## Choose the right channel and track
+(howto-snap-info)=
+## View snap information
 
-Snaps come with different channels that define which release of a snap is installed and tracked for updates.
-See [Channels and tracks](https://snapcraft.io/docs/channels) in the snap documentation for detailed information.
+To view information about a snap, including the available channels and installed version, run:
 
-MicroCloud currently provides the `2` LTS and `3` development track. The `1` track reached {abbr}`EOL (End of Life)` at the end of April 2025.
-
-```{tip}
-In general, you should use the default channels for all snaps required to run MicroCloud.
-
-See {ref}`howto-support` for a list of supported channels that are orchestrated to work together.
+```bash
+snap info <microcloud|lxd|microceph|microovn>
 ```
 
-When installing a snap, specify the channel as follows:
-
-    sudo snap install <snap_name> --channel=<channel>
-
-For example:
-
-    sudo snap install microcloud --channel=2/stable
-
-To see all available channels of a snap, run the following command:
-
-    snap info <snap_name>
+To view information about the installed version only, run:
 
-(howto-snap-control-updates)=
-## Control updates
+```bash
+snap list <microcloud|lxd|microceph|microovn>
+```
 
-By default, snaps are updated automatically.
-In the case of MicroCloud, this can be problematic because the related snaps must always use compatible versions, and because all machines of a cluster must use the same version of each snap.
+Sample output:
 
-Therefore, you should manually apply your updates and make sure that all cluster members are in sync regarding the snap versions that they use.
+```{terminal}
+:input: snap list microcloud
+:user: root
+:host: instance
 
-(howto-snap-hold-updates)=
-### Hold updates
+Name        Version        Rev   Tracking  Publisher   Notes
+microcloud  2.1.0-3e8b183  1144  2/stable  canonical✓  in-cohort,held
+```
 
-You can hold snap updates for a specific time or forever, for all snaps or for specific snaps.
+The first part of the version string corresponds to the release (in this sample, `2.1.0`).
 
-Which strategy to choose depends on your use case.
-If you want to fully control updates to your MicroCloud setup, you should put a hold on all related snaps until you decide to update them.
+(howto-snap-daemon)=
+## Manage the MicroCloud daemon
 
-Enter the following command to indefinitely hold all updates to the snaps needed for MicroCloud:
+Installing the MicroCloud snap creates the MicroCloud daemon as a [snap service](https://snapcraft.io/docs/service-management). Use the following `snap` commands to manage this daemon.
 
-    sudo snap refresh --hold lxd microceph microovn microcloud
+To view the status of the daemon, run:
 
-See [Hold refreshes](https://snapcraft.io/docs/managing-updates#heading--hold) in the snap documentation for detailed information about holding snap updates.
+```bash
+snap services microcloud
+```
 
-(howto-snap-cluster)=
-### Keep cluster members in sync
+To stop the daemon, run:
 
-Snap updates are delivered as [progressive releases](https://snapcraft.io/docs/progressive-releases), which means that updated snap versions are made available to different machines at different times.
-This method can cause a problem for cluster updates if some cluster members are refreshed to a version that is not available to other cluster members yet.
+```bash
+sudo snap stop microcloud
+```
 
-To avoid this problem, use the `--cohort="+"` flag when refreshing your snaps:
+To start the daemon, run:
 
-    sudo snap refresh <snap> --cohort="+"
+```bash
+sudo snap start microcloud
+```
 
-This flag ensures that all machines in a cluster see the same snap revision and are therefore not affected by a progressive rollout.
+To restart the daemon, run:
 
-## Use an Enterprise Store Proxy
+```bash
+sudo snap restart microcloud
+```
 
-If you manage a large MicroCloud deployment and you need absolute control over when updates are applied, consider installing an Enterprise Store Proxy.
+For more information about managing snap services, visit [Service management](https://snapcraft.io/docs/service-management) in the Snap documentation.
 
-The Enterprise Store Proxy is a separate application that sits between the snap client command on your machines and the snap store.
-You can configure the Enterprise Store Proxy to make only specific snap revisions available for installation.
+## Related topics
 
-See the [Enterprise Store Proxy documentation](https://documentation.ubuntu.com/enterprise-store/) for information about how to install and register the Enterprise Store Proxy.
+How-to guides:
+- {ref}`howto-update-upgrade`
+- {ref}`howto-install`
 
-After setting it up, configure the snap clients on all cluster members to use the proxy.
-See [Configuring devices](https://documentation.ubuntu.com/enterprise-store/main/how-to/devices/) for instructions.
+Reference:
+- {ref}`ref-releases-snaps`
 
-You can then configure the Enterprise Store Proxy to override the revisions for the snaps that are needed for MicroCloud:
+In the LXD documentation:
 
-    sudo snap-proxy override lxd <channel>=<revision>
-    sudo snap-proxy override microceph <channel>=<revision>
-    sudo snap-proxy override microovn <channel>=<revision>
-    sudo snap-proxy override microcloud <channel>=<revision>
+- {ref}`lxd:howto-snap`
diff --git a/doc/how-to/support.md b/doc/how-to/support.md
@@ -1,38 +1,31 @@
 (howto-support)=
 # How to get support
 
-We recommend using the following channels for the snaps required to run MicroCloud:
+For information about supported and compatible releases of MicroCloud and its components, see: {ref}`ref-releases-matrix`.
 
-* For MicroCloud: `2/(stable|candidate|edge)`
-* For LXD: `5.21/(stable|candidate|edge)`
-* For MicroCeph: `squid/(stable|candidate|edge)`
-* For MicroOVN: `24.03/(stable|candidate|edge)`
+## Community support
 
-The LTS version of MicroCloud is available in the `2` track.
-It's recommended to use the `<track>/stable` channels for production deployments.
+You can seek support from the LXD developers as well as the wider community through the following channels.
 
-```{admonition} Users of the 1 track
-:class: important
-MicroCloud `1/(stable|candidate|edge)` reached {abbr}`EOL (End of Life)` at the end of April 2025.
-If you use this track, make sure to upgrade to the `2` LTS track. See the {ref}`howto-update-upgrade-upgrade` guide for more information.
-```
+### Forum
 
-## Support and community
+Ask questions or engage in discussions in our [Discourse forum](https://discourse.ubuntu.com/c/lxd/microcloud/145).
 
-The following channels are available for you to interact with the MicroCloud community:
+### Documentation
 
-- You can file bug reports and feature requests as [GitHub issues](https://github.com/canonical/microcloud/issues/new).
-- To ask questions, go to the MicroCloud section of our [discussion forum](https://discourse.ubuntu.com/c/lxd/microcloud/145).
+Access the [official documentation](https://documentation.ubuntu.com/microcloud/latest/).
 
-## Commercial support
+### Bug reports and feature requests
+
+To file a new bug or feature request, [submit an issue on GitHub](https://github.com/canonical/microcloud/issues/new).
 
-Commercial support for MicroCloud is available through [Ubuntu Pro](https://ubuntu.com/support) (Ubuntu Pro (Infra-only) or full Ubuntu Pro).
-The support will cover all LTS versions for five years starting from the day of the release.
+### Other community resources
 
-See the full [Ubuntu Pro service description](https://ubuntu.com/legal/ubuntu-pro-description) for detailed information about what support Ubuntu Pro provides.
+You can find additional resources on the [MicroCloud website](https://canonical.com/microcloud) and on [the LXD channel on YouTube](https://www.youtube.com/channel/UCuP6xPt0WTeZu32CkQPpbvA).
+
+## Commercial support
 
-## Documentation
+LTS releases of MicroCloud receive standard support for five years, which means they receive continuous updates. Commercial support for MicroCloud is provided as part of [Ubuntu Pro](https://ubuntu.com/pro) (both Infra-only and full Ubuntu Pro). See the [full service description](https://ubuntu.com/legal/ubuntu-pro-description) for details.
 
-See the [MicroCloud documentation](https://documentation.ubuntu.com/microcloud/latest/microcloud/) for official product documentation.
+Managed solutions and firefighting support are also available for MicroCloud deployments. See: [Managed services](https://ubuntu.com/managed).
 
-You can find additional resources on the [website](https://canonical.com/microcloud) and in the [discussion forum](https://discourse.ubuntu.com/c/lxd/microcloud/145).
-Original file line number
+Diff line change
@@ Expand Up / @@ -5,6 +5,8 @@ AGPLv @@
     backend
     backporting
     balancers
+    bugfix
+    bugfixes
     CCLA
     Ceph
     Ceph's
@@ Expand All / @@ -29,6 +31,7 @@ intra @@
     IOV
     IPs
     IPv
+    lifecycle
     LTS
     LXD
     LXD's
@@ Expand Down Expand Up / @@ -61,6 +64,7 @@ subnets @@
     SVG
     TinyPNG
     uplink
+    upstream's
     VLAN
     vlatest
     VM
@@ Expand Down @@