Aquilon doc: add documentation on configuring cluster

Author: jouvin

_aquilon/management.md

@@ -365,6 +365,76 @@ 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
+* 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
+```
+
+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.
+
+### 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

_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.

_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