From 48cb4f0b0cf19acce4bb1cd672ea020d060d9451 Mon Sep 17 00:00:00 2001 From: Michel Jouvin Date: Tue, 30 Oct 2018 16:28:33 +0100 Subject: [PATCH] Aquilon doc: add documentation on configuring cluster --- _aquilon/management.md | 92 +++++++++++++++++++++++++++++++++++ _aquilon/technical_details.md | 4 ++ _includes/link_definitions.md | 1 + 3 files changed, 97 insertions(+) diff --git a/_aquilon/management.md b/_aquilon/management.md index aa329d78..baf39466 100644 --- a/_aquilon/management.md +++ b/_aquilon/management.md @@ -365,6 +365,98 @@ remove the service requirement matching the host with the command The mapping is actually removed at the next `aq reconfigure` for the host after modifying the service requirements. +## Using Aquilon clusters + +[Clusters][aquilon_details] are intended to represent in Aquilon a group of hosts that must be configured in +the same way and will host other Aquilon machines, typically hypervisors in a cloud. Like hosts, they have +an archetype and personality attached. It allows to ensure that all hosts that are +part of the cluster receive the same configuration. The cluster personality is added to the host, in addition +to the host personality (each cluster has a plenary template describing the cluster configuration and +personality that is included in the configuration of all hosts belonging to the cluster). Except for specific +requirements, the host personality of a clustered host is generally kept minimal, just providing the basic +OS configuration. + +Configuring a cluster involves: +* Creating the cluster archetype and personality +* Creating the cluster +* Adding hosts (hypervisors) to the cluster +* Building the cluster and its hosts +* Using the cluster as the "machine location" for virtual machines + +### Creating the cluster archetype and personality + +A cluster archetype is created the same way as as [host archetype](#adding-archetypes), +with the exception that `--cluster_type compilable` option must be added. A typical example would be: + +```bash +aq add_archetype --archetype cluster_test --compilable --cluster_type compute +``` + +Cluster archetype creation involves the creation of the same templates as for a +[host archetype](/aquilon/configuration.html#creating-the-archetypebase-and-archetypefinal-templates), as well +as a [archetype/declaration.pan](/aquilon/configuration.html#enabling-the-template-library) +if it is enabled for host archetypes. + +Personality is created the same way as for a [host personality](#personalities)). The same personality +(and archetype) can be used with several clusters. + +Like for host archetypes, it is possible to [bind](#binding-features-to-personalities) a feature to a cluster personality. + + +### Creating the cluster + +A cluster is created with `aq add_cluster`. For example, to create a cluster `cluster_test` that will +use the personality `os_hv_test` from archetype `cluster_test`, use the following command: + +```bash +aq add cluster --cluster cluster_test --archetype cluster_test --personality os_hv_test + --down_hosts 0 --building hq --sandbox your/sandbox +``` + +In the previous command, `--down_hosts` is set to 0 as Aquilon doesn't make a direct use of this value +(an external monitoring tool would be required). For `--building` and `--sandbox`, use values appropriate +to your site (sandbox name must be in the form `user/sandbox_name`). + +### Adding hosts to the cluster + +After creating the cluster, it is necessary to add or more hosts as the cluster members (e.g. hypervisors in a +cluster representing a cloud). The host must have been created with the [standard procedure](/aquilon/configuration.html#declaring-hosts) +before adding it to the cluster. This is done with the command `aq cluster`. + +For example, to add a node `hv1.example.com` in the cluster `cluster_test`: + +```bash +aq cluster --cluster cluster_test --hostname hv1.example.com +``` + +Note that if the host was previously part of another cluster, it will be removed from the original cluster. + + +### Building the cluster and its hosts + +In addition to the configuration added to each cluster host, there is a specific profile built for cluster +itself. The command `aq make cluster` allows to rebuild both the cluster profile and the host profile for each +member. + +For example, to rebuild the cluster `cluster_test` and its hosts, use: + +```bash +aq make cluster --cluster cluster_test +``` + +This command must be used after every change affecting the cluster configuration (in particular the cluster +personality) to ensure that all the configuration (profile) of each cluster member is updated. + +### Binding virtual machines to the cluster + +Hosts are associated with the cluster through the machine they use. When creating the machine, use the +option `--cluster` instead of `--rack`, `--desk` or `--chassis`. One the machine is configured, +[add the hosts][aquilon_hosts] to Aquilon using the same procedure as for hosts using bare metal machines. + +It is not possible to update a machine that was initially configured to use a bare metal machine to become +a virtual machine. It is possible to change the cluster hosting a machine (or change a virtual machine hosted +by a host to a VM hosted by a cluster) with `aq update_machine` command with the `--cluster` option. + ## Initial Installation Initial installation of a node in Quattor is managed by the AII component that generally runs on diff --git a/_aquilon/technical_details.md b/_aquilon/technical_details.md index b1678c26..c844987e 100644 --- a/_aquilon/technical_details.md +++ b/_aquilon/technical_details.md @@ -124,6 +124,10 @@ thresholds associated with the cluster, like the minimum or maximum number of ho any time. Clusters can also be used to describe a HA cluster. Note that Aquilon is not a replacement for the cluster middleware: it just allows to represent a group of machines managed by such a middleware. +Clusters, like hosts, have an archetype and personality attached. It allows to ensure that all hosts that are +part of the cluster receive the same configuration. The cluster personality is added to the host, in addition +to the host personality. + Once a cluster is defined, it can be used as an alternative to a machine object to describe where is running a host. In this case, Aquilon doesn't track on which cluster node the host is running: it lets the middleware do the scheduling, assuming that all hosts in the cluster are equivalent. diff --git a/_includes/link_definitions.md b/_includes/link_definitions.md index 15cab108..ad8c3f97 100644 --- a/_includes/link_definitions.md +++ b/_includes/link_definitions.md @@ -7,6 +7,7 @@ This file contains link definitions that can be used in reference links. [aquilon_configuration]: /aquilon/configuration.html [aquilon_details]: /aquilon/technical_details.html [aquilon_domains]: /aquilon/technical_details.html#domains +[aquilon_hosts]: /aquilon/configuration.html#declaring-hosts [aquilon_install]: /aquilon/00-install.html [aquilon_management]: /aquilon/management.html [aquilon_plenary]: /aquilon/technical_details.html#plenary-templates