Commit ab171697 authored by Michael Hanselmann's avatar Michael Hanselmann
Browse files

Add first version of virtual cluster documentation

- Add document describing virtual clusters
  - Non-root clusters are not yet described, will be done in another
- Change title of design document to avoid confusion
Signed-off-by: default avatarMichael Hanselmann <>
Reviewed-by: default avatarBernardo Dal Seno <>
parent d04d998b
......@@ -378,6 +378,7 @@ docrst = \
doc/rapi.rst \
doc/security.rst \
doc/upgrade.rst \
doc/virtual-cluster.rst \
HS_PROGS = htools/htools
......@@ -1426,7 +1427,7 @@ check-local: check-dirs $(GENERATED_FILES)
echo "Incorrect version in README, expected $$expver"; \
exit 1; \
fi; \
for file in doc/iallocator.rst doc/hooks.rst; do \
for file in doc/iallocator.rst doc/hooks.rst doc/virtual-cluster.rst; do \
if test "`sed -ne '4 p' $(top_srcdir)/$$file`" != \
"Documents Ganeti version $$expver"; then \
echo "Incorrect version in $$file, expected $$expver"; \
Virtual clusters support
Design for virtual clusters support
......@@ -29,6 +29,7 @@ Contents:
Virtual cluster support
Documents Ganeti version 2.6
.. contents::
This is a description of Ganeti's support for virtual clusters
introduced in version 2.7. The original design is described
in a separate :doc:`design document <design-virtual-clusters>`.
A virtual cluster consists of multiple virtual nodes (instances of
Ganeti daemons) running on the same physical machine within one
operating system. This way multiple (virtual) nodes can be simulated
using a single machine. Virtual clusters can be run as a user without
root privileges (see :ref:`limitations <limitations>`).
While not implemented in the helper setup script at the time of this
writing, virtual clusters can also be split over multiple physical
machines, allowing for even more virtual nodes.
.. _limitations:
Due to historical and practical design decisions virtual clusters
have several limitations.
- "fake" hypervisor only
- Instances must be diskless or file-backed
- Node information is the same over multiple virtual nodes (e.g. free
- If running as a user without root privileges, certain operations are
not available; some operations are not useful even when running as
root (e.g. powercycle)
- OS definitions must be prepared for this setup
- Setup is partially manual, especially when not running as root
Ganeti programs act as running on a virtual node if the environment
variables ``GANETI_ROOTDIR`` and ``GANETI_HOSTNAME`` are set. The former
must be an absolute path to a directory with the last component being
equal to the value of ``GANETI_HOSTNAME``, which contains the name of
the virtual node. The reason for this requirement is that one virtual
node must be able to compute an absolute path on another node for
copying files via SSH.
The whole content of ``GANETI_ROOTDIR`` is the node directory, its
parent directory (without hostname) is the cluster directory.
Example for environment variables::
With this example the node directory is
``/tmp/vcluster/`` and the cluster directory
.. _vcluster-setup:
A script to configure virtual clusters is included with Ganeti as
``tools/vcluster-setup`` (usually installed as
``/usr/lib/ganeti/tools/vcluster-setup``). Running it with the ``-h``
option prints a usage description. The script creates all necessary
directories, configures network interfaces, adds or updates entries in
``/etc/hosts`` and generates a small number of helper scripts.
.. TODO: Describe setup of non-root virtual cluster
Once the virtual cluster has been :ref:`set up <vcluster-setup>`, the
cluster can be initialized. The instructions for doing so have been
printed by the ``vcluster-setup`` script together with other useful
information, such as the list of virtual nodes. The commands printed
should be used to configure the list of enabled hypervisors and other
To run commands for a specific virtual node, the script named ``cmd``
located in the node directory can be used. It takes a command as its
argument(s), sets the environment variables ``GANETI_ROOTDIR`` and
``GANETI_HOSTNAME`` and then runs the command. Example:
.. highlight:: shell-example
# Let's create a cluster with node1 as its master node
$ cd /tmp/vcluster
$ gnt-cluster info
Cluster name:
Master node:
# Configure cluster as per "vcluster-setup" script
$ gnt-cluster modify …
Scripts are provided in the cluster root directory to start, stop or
restart all daemons for all virtual nodes. These are named
``start-all``, ``stop-all`` and ``restart-all``. ``ganeti-watcher`` can
be run for all virtual nodes using ``watcher-all``.
Adding an instance (assuming is the master node as per
the example above):
.. highlight:: shell-example
$ gnt-instance add --os-size 1G \
--disk-template=file --os-type dummy -B memory=192 -I hail \
.. vim: set textwidth=72 :
.. Local Variables:
.. mode: rst
.. fill-column: 72
.. End:
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment