Skip to content

Aquilon doc: add documentation on configuring cluster #259

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jouvin wants to merge 1 commit into
base: main
Choose a base branch
from
+127 −3
Open

Aquilon doc: add documentation on configuring cluster #259

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions .travis-scripts/dictionary.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,7 @@ GPUs
GRN
GRNs
hacky
Hadoop
HPC
HTC
HEPiX
Expand Down Expand Up @@ -144,6 +145,7 @@ vCenter
versioned
VirtualEnv
virtualenv
virtualisation
virtualised
VLAN
VM
Expand Down
118 changes: 116 additions & 2 deletions _aquilon/management.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -202,8 +202,8 @@ the command would be:
aq bind_feature --feature demo --personality test --archetype web_servers
```

*Note: despite the command help mentions that features can also be bound to archetypes, it is
highly recommended not to do it.*
*Note: it is possible to bind a feature to an archetype if you want all the personalities in the archetype
to have this feature. To do this, just remove `--personality`.*


## Personalities
Expand Down Expand Up @@ -365,6 +365,120 @@ 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
Comment thread
ned21 marked this conversation as resolved.
the same way. It may be hypervisors in a cloud, disk servers in a distributed storage infrastructure like Hadoop
or Ceph, or hosts behind proxy.

Clusters, like hosts, have an archetype and personality attached. It allows for cluster-wide configuration
to be applied after most of the host configuration is done, just before including the host archetype `final.pan`
(the last thing done in any plenary object template). Thus the cluster personality is added to the host
personality. Depending on the cluster type, the host personality of a clustered host may be as minimal
as providing the basic OS configuration (typically the case for hypervisors in a cloud)or also
configure some features specific to the host (e.g. the hosts
behind a proxy may not all run the same services).

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
* Optionally, 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 compute` option must be added.. Depending if the
archetype is defined as compilable or not, a profile will be created for the cluster (or not).

A typical example would be:

```bash
aq add_archetype --archetype cluster_test --cluster_type compute
```

Option `--compilable` must be added to define the archetype as compilable and get a cluster profile
object created. If you want the archetype to be compilable, you must create the same templates for
the cluster archetype 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. `declaration.pan` must be similar to the one used in a host archetype
if you are using the template library. The exact content of `base.pan` and `final.pan`depend on what is required
by the personality and features bound to the archetype: you should in particular make available all the information
normally accessible to the features in the context of a host archetype.

Personality is created and managed 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
archetype instead of the 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 `mycloud`, use the following command:

```bash
aq add cluster --cluster cluster_test --archetype mycloud --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

The command `aq reconfigure --membersof` allows to rebuild the host profile for each
member of the cluster.

For example, to rebuild the cluster `cluster_test` and its hosts, use:

```bash
aq reconfigure --membersof 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.

In addition, there is a specific profile built for cluster itself if the archetype is compilable. To
build or rebuild this cluster profile, use the command:

```bash
aq make cluster --cluster cluster_test
```


### Binding virtual machines to the cluster

If the cluster is describing a virtualisation infrastructure like a cluster, hosts that are not part of the cluster
may be associated with it through the (virtual) 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. But 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.

To be able to bind a virtual machine to a cluster, it is necessary that the virtual machine has no local disk.
Use `virtual_disk` as the disk type when creating the machine model that will be used by the virtual machine.

## Initial Installation

Initial installation of a node in Quattor is managed by the AII component that generally runs on
Expand Down
9 changes: 8 additions & 1 deletion _aquilon/technical_details.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -119,11 +119,18 @@ the AII service used for the initial installation of an Aquilon host.
## Clusters

Clusters are collections of hosts that have a similar role/function. They are typically used describe
a cluster of hypervisors, like those provided by VMware ESX or clouds. Aquilon can provide some monitoring
a cluster of hypervisors, like those provided by VMware ESX or clouds, a disk servers in a distributed
storage technology like Hadoop or Ceph, hosts behind a proxy...

Aquilon can provide some monitoring
thresholds associated with the cluster, like the minimum or maximum number of hosts that must be running at
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
Copy link
Copy Markdown
Contributor

@ned21 ned21 Oct 31, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would say:

Clusters, like hosts, have an archetype and personality attached. It allows for cluster-wide configuration to be applied by including a new file after the host personality but before archetype/final. That file is $host-archetype/$cluster-archetype/$cluster-personality/config (relative to the LOADPATH).

Typically relative to the root of your template-king domain the file is:

$host-archetype/features/$host-archetype/$cluster-archetype/$cluster-personality/config

Copy link
Copy Markdown
Contributor Author

@jouvin jouvin Nov 2, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ned21 are you sure you want to give these details. These templates are plenary templates. An Aquilon user should not try (and probably will not be able) to access them directly. He/she should use aq cat. At the end it works line for any other personality... What about the new wording?

Copy link
Copy Markdown

@xaf xaf Nov 2, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I like the start of the paragraph that Nathan proposed:

Clusters, like hosts, have an archetype and personality attached. It allows for cluster-wide configuration to be applied by including a new file after the host personality

Not sure for the rest of the paragraph. If we decide to have it also, I would recommend clarifying the variable names (perhaps like in bash with ${cluster-personality} for instance, as when reading it for now I was not sure at first glance if it was ${cluster}-personality or the above)

Copy link
Copy Markdown
Contributor Author

@jouvin jouvin Nov 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@xaf I still don't understand... The last version of this PR has this sentence copy/pasted. The rest of the § proposed by @ned21 IMO is not appropriate and I phrased it differently.

Copy link
Copy Markdown

@xaf xaf Nov 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, checking from my phone and github mobile version is not that clean to navigate. I'm good with the current version of that sentence.

Copy link
Copy Markdown
Contributor

@ned21 ned21 Nov 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ned21 are you sure you want to give these details. These templates are plenary templates. An Aquilon user should not try (and probably will not be able) to access them directly. He/she should use aq cat.

These are not plenaries, they are files that must appear in template-king if you want the cluster personality to influence the host profile.

At the end it works line for any other personality...

Not really. I think this is the confusing thing about clusters: the cluster object is a separate PAN-generated object profile. The personality is the configuration of that cluster object. You can use PAN's $object:/path/ syntax to access attributes of that object from within the Host profile but the cluster object is an independent entity. The inclusion of a template file named after the cluster $archetype/$personality is what allows the cluster object to add configuration to the member hosts, but that's just a standard include hook and has no relation to the Cluster object.

(The development of this data model predates my employment at MS. :-)

What about the new wording?

The new wording is good but I am concerned that if the path I referenced isn't documented here, it's not documented anywhere.

Copy link
Copy Markdown
Contributor Author

@jouvin jouvin Nov 4, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ned21 The inclusion logic you mention for cluster personalities is not what I'm seeing... at the end of a host template you have the cluster/$cluster_name/client' included (just before final.pan`) and it includes the cluster personality template if it exists. There is no direct reference to the cluster object.

Copy link
Copy Markdown
Contributor

@ned21 ned21 Nov 4, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

hmm.. This may be LOADPATH dependent. I've just spotted that my original filename reference version is perhaps slightly incorrect. I believe what gets included is: features/$cluster-archetype/$cluster-personality/config which traditionally means that must appear under the host's archetype because the cluster archetype is not added to the host's LOADPATH. i.e. the full path to that is:

$host-archetype/features/$host-archetype/$cluster-archetype/$cluster-personality/config

This is not the same file as:

$cluster-archetype/personality/$cluster-personality/config

part of the cluster receive the same configuration. The cluster personality is added to the host, in addition
Copy link
Copy Markdown
Contributor

@ned21 ned21 Nov 2, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The cluster personality is added to the host, in addition to the host personality.

To me this wording implies the cluster personality is "merged to" the host personality which is not strictly true. I am not sure if I am just nitpicking the wording here or if the model is just so complex I haven't managed to explain it properly yet. :-(

This was the reason I thought it was good to reference the file being include ($host-archetype/$cluster-archetype/$cluster-personality/config) because if that file doesn't exist compilation will continue, and so if you don't know that's the path you have to create, it's hard to figure out how to add cluster-driven configuration to the host profile--I doubt that file path is properly documented anywhere else.

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.
Expand Down
1 change: 1 addition & 0 deletions _includes/link_definitions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down