1 Virtual cluster support
2 =======================
4 Documents Ganeti version 2.9
11 This is a description of Ganeti's support for virtual clusters
12 introduced in version 2.7. The original design is described
13 in a separate :doc:`design document <design-virtual-clusters>`.
15 A virtual cluster consists of multiple virtual nodes (instances of
16 Ganeti daemons) running on the same physical machine within one
17 operating system. This way multiple (virtual) nodes can be simulated
18 using a single machine. Virtual clusters can be run as a user without
19 root privileges (see :ref:`limitations <limitations>`).
21 While not implemented in the helper setup script at the time of this
22 writing, virtual clusters can also be split over multiple physical
23 machines, allowing for even more virtual nodes.
31 Due to historical and practical design decisions virtual clusters
32 have several limitations.
34 - "fake" hypervisor only
35 - Instances must be diskless or file-backed
36 - Node information is the same over multiple virtual nodes (e.g. free
38 - If running as a user without root privileges, certain operations are
39 not available; some operations are not useful even when running as
40 root (e.g. powercycle)
41 - OS definitions must be prepared for this setup
42 - Setup is partially manual, especially when not running as root
48 Ganeti programs act as running on a virtual node if the environment
49 variables ``GANETI_ROOTDIR`` and ``GANETI_HOSTNAME`` are set. The former
50 must be an absolute path to a directory with the last component being
51 equal to the value of ``GANETI_HOSTNAME``, which contains the name of
52 the virtual node. The reason for this requirement is that one virtual
53 node must be able to compute an absolute path on another node for
54 copying files via SSH.
56 The whole content of ``GANETI_ROOTDIR`` is the node directory, its
57 parent directory (without hostname) is the cluster directory.
59 Example for environment variables::
61 GANETI_ROOTDIR=/tmp/vcluster/node1.example.com
62 GANETI_HOSTNAME=node1.example.com
65 With this example the node directory is
66 ``/tmp/vcluster/node1.example.com`` and the cluster directory
75 A script to configure virtual clusters is included with Ganeti as
76 ``tools/vcluster-setup`` (usually installed as
77 ``/usr/lib/ganeti/tools/vcluster-setup``). Running it with the ``-h``
78 option prints a usage description. The script creates all necessary
79 directories, configures network interfaces, adds or updates entries in
80 ``/etc/hosts`` and generates a small number of helper scripts.
82 .. TODO: Describe setup of non-root virtual cluster
88 Once the virtual cluster has been :ref:`set up <vcluster-setup>`, the
89 cluster can be initialized. The instructions for doing so have been
90 printed by the ``vcluster-setup`` script together with other useful
91 information, such as the list of virtual nodes. The commands printed
92 should be used to configure the list of enabled hypervisors and other
95 To run commands for a specific virtual node, the script named ``cmd``
96 located in the node directory can be used. It takes a command as its
97 argument(s), sets the environment variables ``GANETI_ROOTDIR`` and
98 ``GANETI_HOSTNAME`` and then runs the command. Example:
100 .. highlight:: shell-example
104 # Let's create a cluster with node1 as its master node
106 $ node1.example.com/cmd gnt-cluster info
107 Cluster name: cluster.example.com
109 Master node: node1.example.com
111 # Configure cluster as per "vcluster-setup" script
112 $ node1.example.com/cmd gnt-cluster modify …
114 Scripts are provided in the cluster root directory to start, stop or
115 restart all daemons for all virtual nodes. These are named
116 ``start-all``, ``stop-all`` and ``restart-all``. ``ganeti-watcher`` can
117 be run for all virtual nodes using ``watcher-all``.
119 Adding an instance (assuming node1.example.com is the master node as per
122 .. highlight:: shell-example
126 $ node1.example.com/cmd gnt-instance add --os-size 1G \
127 --disk-template=file --os-type dummy -B memory=192 -I hail \
128 instance1.example.com
130 .. vim: set textwidth=72 :