diff --git a/doc/explanation/microcloud.md b/doc/explanation/microcloud.md index 3a6f58f58..637183d9d 100644 --- a/doc/explanation/microcloud.md +++ b/doc/explanation/microcloud.md @@ -64,7 +64,7 @@ You can also manage MicroCloud through the {ref}`command line ` or MicroCloud is designed to be replicable at scale, enabling you to create consistent environments across multiple sites or clusters. All configuration performed during initialization can be captured in a {ref}`preseed file ` to reproduce the deployment. This allows you to deploy identical MicroCloud clusters with minimal manual input. -Once deployed, each MicroCloud component (LXD, MicroCeph, MicroOVN) is designed to scale horizontally, meaning you can add more machines to increase capacity, performance, and redundancy. When new cluster members are added, these components automatically integrate them as control plane, storage, and networking peers without requiring manual reconfiguration. This includes {doc}`automatic failure domain adjustment ` for MicroCeph. +Once deployed, each MicroCloud component (LXD, MicroCeph, MicroOVN) is designed to scale horizontally, meaning you can add more machines to increase capacity, performance, and redundancy. When new cluster members are added, these components automatically integrate them as control plane, storage, and networking peers without requiring manual reconfiguration. This includes {ref}`automatic failure domain adjustment ` for MicroCeph. Furthermore, MicroCloud's snap-based updates help keep deployments consistent at scale. By updating cluster members to the latest version available on the LTS snap channel, you can ensure that all machines are using the same version with the latest security updates and bugfixes. Refer to {ref}`ref-releases-snaps` to learn more. @@ -75,7 +75,7 @@ MicroCloud achieves high availability (HA) through its distributed architecture: LXD provides control plane HA by allowing each cluster member to manage the cluster. If one member goes down, another can serve requests in its place. For data plane HA, LXD also provides automatic {ref}`cluster healing `. For more information, refer to the LXD documentation on {ref}`lxd:clusters-high-availability`. -Using distributed storage with MicroCeph means that data is replicated across the cluster, so even if one member goes offline, its data remains available on others. Ceph's {doc}`Controlled Replication Under Scalable Hashing (CRUSH) algorithm ` automatically redistributes data when parts of the system fail, maintaining availability. For more information, refer to the {ref}`MicroCloud storage requirements for high availability ` and the {doc}`MicroCeph documentation on its failure domain management `. +Using distributed storage with MicroCeph means that data is replicated across the cluster, so even if one member goes offline, its data remains available on others. Ceph's {doc}`Controlled Replication Under Scalable Hashing (CRUSH) algorithm ` automatically redistributes data when parts of the system fail, maintaining availability. For more information, refer to the {ref}`MicroCloud storage requirements for high availability ` and the {ref}`MicroCeph documentation on its failure domain management `. MicroOVN brings a distributed overlay network, meaning that switching and routing functions are not centralized on any single cluster member. Each member hosts its own virtual switch, avoiding a single point of failure for internal, intra-cluster traffic: every member can continue forwarding packets even if others are offline. External connectivity relies on a virtual router that is active on one member at a time; if that member fails, another takes over to keep uplink connectivity available. For more information, refer to {ref}`exp-networking-ovn`. diff --git a/doc/how-to/initialize.md b/doc/how-to/initialize.md index b4e2c0256..07436492f 100644 --- a/doc/how-to/initialize.md +++ b/doc/how-to/initialize.md @@ -13,7 +13,7 @@ You run the initialization on one of the machines, and it configures the require ## Pre-initialization requirements - Complete the steps in {ref}`howto-install` before initialization. -- If you intend to use full disk encryption (FDE) on any cluster member, that member must meet the prerequisites listed on this page: {doc}`microceph:snap/explanation/security/about-fde`. +- If you intend to use full disk encryption (FDE) on any cluster member, that member must meet the prerequisites listed on this page: {ref}`microceph:about-fde`. - Follow only the instructions in the Prerequisites section on that page. Skip its Usage section; the MicroCloud initialization process handles the disk encryption. (howto-initialize-interactive)= @@ -97,7 +97,7 @@ Complete the following steps to initialize MicroCloud: Encrypting a disk will store the encryption keys in the Ceph key ring inside the Ceph configuration folder. ```{warning} - Cluster members with disks to be encrypted require a kernel with `dm-crypt` enabled. The snap `dm-crypt` plug must also be connected. See the Prerequisites section of this page for more information: {doc}`microceph:snap/explanation/security/about-fde`. + Cluster members with disks to be encrypted require a kernel with `dm-crypt` enabled. The snap `dm-crypt` plug must also be connected. See the Prerequisites section of this page for more information: {ref}`microceph:about-fde`. If you have not enabled and connected `dm-crypt` on any cluster member that you want to encrypt, do so now before you continue. diff --git a/doc/how-to/member_remove.md b/doc/how-to/member_remove.md index dbea119b3..e72071744 100644 --- a/doc/how-to/member_remove.md +++ b/doc/how-to/member_remove.md @@ -10,7 +10,7 @@ sudo microcloud remove Before removing the cluster member, ensure that there are no LXD instances, storage volumes, or MicroCeph OSDs located on it. See {ref}`how to remove instances ` in the LXD documentation. -See {doc}`how to remove OSDs ` in the MicroCeph documentation. +See {ref}`how to remove OSDs ` in the MicroCeph documentation. ````{note} If local storage was created, MicroCloud will have also added some default storage volumes that will need to be cleaned up: diff --git a/doc/how-to/update_upgrade.md b/doc/how-to/update_upgrade.md index a184f10cb..3f9f8283d 100644 --- a/doc/how-to/update_upgrade.md +++ b/doc/how-to/update_upgrade.md @@ -12,7 +12,7 @@ Performing an update or upgrade requires going through the list of snaps one aft Before performing an update or upgrade, make sure to back up your data to prevent any data loss in case of failure. Consult the following backup guides for each of the snaps: -* {doc}`How to back up MicroCeph ` +* {ref}`How to back up MicroCeph ` * {ref}`How to back up LXD ` In case of error, refer to {ref}`howto-recover` for troubleshooting details. @@ -199,9 +199,9 @@ As MicroCloud consumes the services offered by its component snaps, the upgrade Make sure to consult the dedicated upgrade guides of each component before you perform the actual upgrade: -* {doc}`How to upgrade MicroCeph ` +* {ref}`How to upgrade MicroCeph ` * {doc}`How to upgrade MicroOVN ` -* {doc}`How to upgrade LXD ` +* {ref}`How to upgrade LXD ` To start the upgrade procedure, enter the following command on the first machine: diff --git a/doc/reference/release-notes/index.md b/doc/reference/release-notes/index.md index 8260303e3..dc36cc7f2 100644 --- a/doc/reference/release-notes/index.md +++ b/doc/reference/release-notes/index.md @@ -37,7 +37,7 @@ MicroCloud 2.1.0 LTS ` -- {doc}`MicroCeph release notes ` +- {ref}`MicroCeph release notes ` MicroOVN does not yet publish release notes. diff --git a/doc/reference/requirements.md b/doc/reference/requirements.md index 4b08b6b0b..b429bd97c 100644 --- a/doc/reference/requirements.md +++ b/doc/reference/requirements.md @@ -69,7 +69,7 @@ For production environments, we recommend at least 3 NVMe disks per cluster memb If you intend to use full disk encryption on any cluster member, the `dm-crypt` kernel module must be available, and the snap `dm-crypt` plug must be connected to MicroCeph. The `dm-crypt` module is available by default in Ubuntu 24.04 and higher. -For further information, see the Prerequisites section of this page: {doc}`microceph:snap/explanation/security/about-fde`. Note that the command shown on that page to connect the snap `dm-crypt` plug can only be performed once MicroCeph is installed. The MicroCloud installation steps include installing MicroCeph; thus, {ref}`install MicroCloud first`, then connect the plug. +For further information, see the Prerequisites section of this page: {ref}`microceph:about-fde`. Note that the command shown on that page to connect the snap `dm-crypt` plug can only be performed once MicroCeph is installed. The MicroCloud installation steps include installing MicroCeph; thus, {ref}`install MicroCloud first`, then connect the plug. (reference-requirements-network)= ## Networking requirements