Statistics
| Branch: | Tag: | Revision:

root / doc / virtual-cluster.rst @ b031e99d

History | View | Annotate | Download (4.2 kB)

1
Virtual cluster support
2
=======================
3

    
4
Documents Ganeti version 2.8
5

    
6
.. contents::
7

    
8
Introduction
9
------------
10

    
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>`.
14

    
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>`).
20

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

    
25

    
26
.. _limitations:
27

    
28
Limitations
29
-----------
30

    
31
Due to historical and practical design decisions virtual clusters
32
have several limitations.
33

    
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
37
  memory)
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
43

    
44

    
45
Basics
46
------
47

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

    
56
The whole content of ``GANETI_ROOTDIR`` is the node directory, its
57
parent directory (without hostname) is the cluster directory.
58

    
59
Example for environment variables::
60

    
61
  GANETI_ROOTDIR=/tmp/vcluster/node1.example.com
62
  GANETI_HOSTNAME=node1.example.com
63

    
64

    
65
With this example the node directory is
66
``/tmp/vcluster/node1.example.com`` and the cluster directory
67
``/tmp/vcluster``.
68

    
69

    
70
.. _vcluster-setup:
71

    
72
Setup
73
-----
74

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

    
82
.. TODO: Describe setup of non-root virtual cluster
83

    
84

    
85
Use
86
---
87

    
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
93
settings.
94

    
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:
99

    
100
.. highlight:: shell-example
101

    
102
::
103

    
104
  # Let's create a cluster with node1 as its master node
105
  $ cd /tmp/vcluster
106
  $ node1.example.com/cmd gnt-cluster info
107
  Cluster name: cluster.example.com
108
109
  Master node: node1.example.com
110
111
  # Configure cluster as per "vcluster-setup" script
112
  $ node1.example.com/cmd gnt-cluster modify …
113

    
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``.
118

    
119
Adding an instance (assuming node1.example.com is the master node as per
120
the example above):
121

    
122
.. highlight:: shell-example
123

    
124
::
125

    
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
129

    
130
.. vim: set textwidth=72 :
131
.. Local Variables:
132
.. mode: rst
133
.. fill-column: 72
134
.. End: