From d8ebc7de1f782127f3e19ba28b72fbc182fb5061 Mon Sep 17 00:00:00 2001 From: "Joshua M. Boniface" Date: Sat, 16 Sep 2023 23:59:55 -0400 Subject: [PATCH] Reorganize documentation --- docs/about-pvc.md | 2 +- .../cluster-architecture.md | 6 +++--- docs/{deployment => architecture}/fencing.md | 4 ++-- .../hardware-requirements.md | 6 +++--- .../images/pvc-3-node-cluster.png | Bin .../images/pvc-8-node-cluster.png | Bin .../images/pvc-software.png | Bin docs/index.md | 4 ++-- mkdocs.yml | 9 +++++---- 9 files changed, 16 insertions(+), 15 deletions(-) rename docs/{deployment => architecture}/cluster-architecture.md (97%) rename docs/{deployment => architecture}/fencing.md (95%) rename docs/{deployment => architecture}/hardware-requirements.md (95%) rename docs/{deployment => architecture}/images/pvc-3-node-cluster.png (100%) rename docs/{deployment => architecture}/images/pvc-8-node-cluster.png (100%) rename docs/{deployment => architecture}/images/pvc-software.png (100%) diff --git a/docs/about-pvc.md b/docs/about-pvc.md index 810324c..00c9188 100644 --- a/docs/about-pvc.md +++ b/docs/about-pvc.md @@ -65,7 +65,7 @@ If all you want is a simple home server solution, or you demand scalability beyo For a redundant cluster, yes. PVC requires a majority quorum for proper operation at various levels, and the smallest possible majority quorum is 2-of-3; thus 3 nodes is the smallest safe minimum. That said, you can run PVC on a single node for testing/lab purposes without host-level redundancy, should you wish to do so, and it might also be possible to run 2 "main" systems with a 3rd "quorum observer" hosting only the management tools but no VMs; however these options are not officially supported, as PVC is designed primarily for 3+ node operation. -For more details, see the [Cluster Architecture page](/deployment/cluster-architecture). +For more details, see the [Cluster Architecture page](/architecture/cluster-architecture). #### Does PVC support containers (Docker/Kubernetes/LXC/etc.)? diff --git a/docs/deployment/cluster-architecture.md b/docs/architecture/cluster-architecture.md similarity index 97% rename from docs/deployment/cluster-architecture.md rename to docs/architecture/cluster-architecture.md index 9ec00c5..d18c8b0 100644 --- a/docs/deployment/cluster-architecture.md +++ b/docs/architecture/cluster-architecture.md @@ -78,7 +78,7 @@ Many PVC daemons, as discussed below, leverage a majority quorum to function. A This is an important consideration when deciding the number of coordinators to allocate: a 3-coordinator system can tolerate the loss of a single coordinator without impacting the cluster, but losing 2 would render the cluster inoperable; similarly, a 5-coordinator system can tolerate the loss of 2 coordinators, but losing 3 would render the cluster inoperable. In addition, these coordinators must be located in such a way that a majority can communicate in outage events, in order for the cluster to remain operational. This affects the network and physical design of a cluster and must be carefully considered during deployment; for instance, network switches and links, and power, should be redundant. -For more details on this, see the [Fencing](/deployment/fencing) and [Georedundancy](/deployment/georedundancy) documentation. The first also covers the node fencing process, which allows automatic recovery from a node failure in certain outage events. +For more details on this, see the [Fencing](/architecture/fencing) and [Georedundancy](/architecture/georedundancy) documentation. The first also covers the node fencing process, which allows automatic recovery from a node failure in certain outage events. Hypervisors are not affected by the coordinator quorum: a cluster can lose any number of non-coordinator hypervisors without impacting core services, though compute resources (CPU and memory) must be available on the remaining nodes for VMs to function properly, and any OSDs on these hypervisors, if applicable, would become unavailable, potentially impacting storage availability. @@ -120,7 +120,7 @@ Within each core network, each node is assigned a static IP address; DHCP is not In addition to the main static IP of each node, there is also a "floating" IP in each network which is bound to the primary coordinator. This IP can be used as a single point of access into the cluster for the API or other services that need to see the "cluster as a whole" rather than individual nodes. -Some or all of these networks can be collapsed, though for optimal performance and security, it is recommended that, at a minimum, the "upstream" and "cluster"/"storage" networks be separated. The physical aspect is discussed further in the [Hardware Requirements](/deployment/hardware-requirements) documentation, however larger clusters should generally lean towards splitting these networks into separate physical, as well as logical, links. +Some or all of these networks can be collapsed, though for optimal performance and security, it is recommended that, at a minimum, the "upstream" and "cluster"/"storage" networks be separated. The physical aspect is discussed further in the [Hardware Requirements](/architecture/hardware-requirements) documentation, however larger clusters should generally lean towards splitting these networks into separate physical, as well as logical, links. #### Upstream @@ -130,7 +130,7 @@ The "upstream" network requires outbound Internet access, as it will be used to This network, though it requires Internet access, should not be exposed directly to the Internet or to other untrusted local networks for security reasons. PVC itself makes no attempt to hinder access to nodes from within this network. At a minimum, an upstream firewall should prevent external access to this network, and only trusted hosts or on-cluster VMs should be added to it. -In addition to all other functions, server IPMI interfaces should reside either directly in this network, or in a network directly reachable from this network, to provide fencing and auto-recovery functionality. For more details, see the [Fencing](/deployment/fencing) documentation. +In addition to all other functions, server IPMI interfaces should reside either directly in this network, or in a network directly reachable from this network, to provide fencing and auto-recovery functionality. For more details, see the [Fencing](/architecture/fencing) documentation. #### Cluster diff --git a/docs/deployment/fencing.md b/docs/architecture/fencing.md similarity index 95% rename from docs/deployment/fencing.md rename to docs/architecture/fencing.md index 5199703..c93290d 100644 --- a/docs/deployment/fencing.md +++ b/docs/architecture/fencing.md @@ -20,8 +20,8 @@ Fencing can be temporarily disabled by setting the cluster maintenance mode to ` For fencing to be enabled, several configurations must be correctly set. -* The node must have a proper IPMI interface, as detailed in the [Hardware Requirements](/deployment/hardware-requirements/#ipmilights-out-management) documentation. -* The IPMI interface must be either in the [cluster "upstream" network](/deployment/cluster-architecture/#upstream), or in another network reachable by it. The former is strongly recommended, because the latter is potentially susceptable to network faults in the routing between the networks which might cause fencing to fail in otherwise valid scenarios. +* The node must have a proper IPMI interface, as detailed in the [Hardware Requirements](/architecture/hardware-requirements/#ipmilights-out-management) documentation. +* The IPMI interface must be either in the [cluster "upstream" network](/architecture/cluster-architecture/#upstream), or in another network reachable by it. The former is strongly recommended, because the latter is potentially susceptable to network faults in the routing between the networks which might cause fencing to fail in otherwise valid scenarios. * The IPMI BMC must be configured with an `Administrator`-level user with IPMI-over-LAN privilieges enabled. * The IPMI interface (IP or hostname) and aforementioned user of each node must be configured in the `fencing` -> `ipmi` section of the `pvcnoded.yaml` file of that node. diff --git a/docs/deployment/hardware-requirements.md b/docs/architecture/hardware-requirements.md similarity index 95% rename from docs/deployment/hardware-requirements.md rename to docs/architecture/hardware-requirements.md index a97dabd..b5809ef 100644 --- a/docs/deployment/hardware-requirements.md +++ b/docs/architecture/hardware-requirements.md @@ -16,7 +16,7 @@ PVC is designed to operate in "N-1" mode, that is, all sizing of the cluster sho For example, consider 3 nodes each with 16 CPU cores and 128GB of RAM. This totals 48 CPU cores and 384GB of RAM, however we should consider the N-1 number, that is 32 CPU cores and 256GB of RAM, to be the maximum usable quantity of each available across the entire cluster. -Disks are even more limited. As outlined in the [Cluster Storage section of the Cluster Architecture](/deployment/cluster-architecture/#cluster-storage) documentation, a normal pool replication level for reliable redundant operation is 3 copies with 2 minimum copies. Thus, to continue the above 3 node example, if each node features a 2TB data SSD, the total available N-1 storage is 2TB (as 3 x 2TB / 3 = 2TB). +Disks are even more limited. As outlined in the [Cluster Storage section of the Cluster Architecture](/architecture/cluster-architecture/#cluster-storage) documentation, a normal pool replication level for reliable redundant operation is 3 copies with 2 minimum copies. Thus, to continue the above 3 node example, if each node features a 2TB data SSD, the total available N-1 storage is 2TB (as 3 x 2TB / 3 = 2TB). ## Hardware Vendors @@ -28,9 +28,9 @@ Some common recommended vendors, with whom the author has had good experiences, All aforementioned server vendors support some form of IPMI Lights-out Management, e.g. Dell iDRAC, Cisco CIMC, HP iLO, etc. with IPMI-over-LAN functionality. Consumer and low-end Workstation hardware does not normally support IPMI Lights-out Management and is thus unsuitable for a production node. -* It is **recommended** for a redundant, production PVC node to feature IPMI Lights-out Management, on a dedicated Ethernet port, with support for IPMI-over-LAN functionality, reachable from or in the [cluster "upstream" network](/deployment/cluster-architecture/#upstream). +* It is **recommended** for a redundant, production PVC node to feature IPMI Lights-out Management, on a dedicated Ethernet port, with support for IPMI-over-LAN functionality, reachable from or in the [cluster "upstream" network](/architecture/cluster-architecture/#upstream). -This feature is not strictly required, however it is required for the [PVC fencing system](/deployment/fencing) to function properly, which is required for auto-recovery from node failures. PVC will detect the lack of a reachable IPMI interface at startup and disable fencing and auto-recovery in such a case. +This feature is not strictly required, however it is required for the [PVC fencing system](/architecture/fencing) to function properly, which is required for auto-recovery from node failures. PVC will detect the lack of a reachable IPMI interface at startup and disable fencing and auto-recovery in such a case. ## CPU diff --git a/docs/deployment/images/pvc-3-node-cluster.png b/docs/architecture/images/pvc-3-node-cluster.png similarity index 100% rename from docs/deployment/images/pvc-3-node-cluster.png rename to docs/architecture/images/pvc-3-node-cluster.png diff --git a/docs/deployment/images/pvc-8-node-cluster.png b/docs/architecture/images/pvc-8-node-cluster.png similarity index 100% rename from docs/deployment/images/pvc-8-node-cluster.png rename to docs/architecture/images/pvc-8-node-cluster.png diff --git a/docs/deployment/images/pvc-software.png b/docs/architecture/images/pvc-software.png similarity index 100% rename from docs/deployment/images/pvc-software.png rename to docs/architecture/images/pvc-software.png diff --git a/docs/index.md b/docs/index.md index f042ea7..3b95bde 100644 --- a/docs/index.md +++ b/docs/index.md @@ -22,7 +22,7 @@ Installation of PVC is accomplished by two main components: a [Node installer IS Just give it physical servers, and it will run your VMs without you having to think about it, all in just an hour or two of setup time. -For more details on the project motivation, please see the [About](https://parallelvirtualcluster.readthedocs.io/en/latest/about/) page. +For more details on the project motivation, please see the [About](/about/) page. ## What is it based on? @@ -38,7 +38,7 @@ The core node and API daemons, as well as the CLI API client, are written in Pyt ## Getting Started -To get started with PVC, read over the [Cluster Architecture](https://parallelvirtualcluster.readthedocs.io/en/latest/cluster-architecture/) page then see the [Getting Started](https://parallelvirtualcluster.readthedocs.io/en/latest/getting-started/) guide for details on configuring your first cluster. +To get started with PVC, read over the [Cluster Architecture](/architecture/cluster-architecture/) pages then see the [Getting Started](/deployment/getting-started/) guide for details on configuring your first cluster. ## Changelog diff --git a/mkdocs.yml b/mkdocs.yml index 295c101..9e4181b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -12,11 +12,12 @@ markdown_extensions: nav: - 'Home': 'index.md' - 'About PVC': 'about-pvc.md' + - 'Architecture': + - 'Cluster Architecture': 'architecture/cluster-architecture.md' + - 'Hardware Requirements': 'architecture/hardware-requirements.md' + - 'Fencing': 'architecture/fencing.md' + - 'Georedundancy': 'architecture/georedundancy.md' - 'Deployment': - - 'Cluster Architecture': 'deployment/cluster-architecture.md' - - 'Hardware Requirements': 'deployment/hardware-requirements.md' - - 'Fencing': 'deployment/fencing.md' - - 'Georedundancy': 'deployment/georedundancy.md' - 'Getting Started Guide': 'deployment/getting-started.md' - 'Manuals': - 'PVC CLI': 'manuals/cli.md'