Statistics
| Branch: | Tag: | Revision:

root / man / ganeti.rst @ 7ba19f39

History | View | Annotate | Download (7.3 kB)

1
ganeti(7) Ganeti | Version @GANETI_VERSION@
2
===========================================
3

    
4
Name
5
----
6

    
7
ganeti - cluster-based virtualization management
8

    
9
Synopsis
10
--------
11

    
12
::
13

    
14
    # gnt-cluster init cluster1.example.com
15
    # gnt-node add node2.example.com
16
    # gnt-instance add -n node2.example.com \
17
    > -o debootstrap --disk 0:size=30g \
18
    > -t plain instance1.example.com
19

    
20

    
21
DESCRIPTION
22
-----------
23

    
24
The Ganeti software manages physical nodes and virtual instances of a
25
cluster based on a virtualization software. The current version (2.3)
26
supports Xen 3.x and KVM (72 or above) as hypervisors, and LXC as an
27
experimental hypervisor.
28

    
29
Quick start
30
-----------
31

    
32
First you must install the software on all the cluster nodes, either
33
from sources or (if available) from a package. The next step is to
34
create the initial cluster configuration, using **gnt-cluster init**.
35

    
36
Then you can add other nodes, or start creating instances.
37

    
38
Cluster architecture
39
--------------------
40

    
41
In Ganeti 2.0, the architecture of the cluster is a little more
42
complicated than in 1.2. The cluster is coordinated by a master daemon
43
(**ganeti-masterd**(8)), running on the master node. Each node runs
44
(as before) a node daemon, and the master has the RAPI daemon running
45
too.
46

    
47
Node roles
48
~~~~~~~~~~
49

    
50
Each node can be in one of the following states:
51

    
52
master
53
    Only one node per cluster can be in this role, and this node is the
54
    one holding the authoritative copy of the cluster configuration and
55
    the one that can actually execute commands on the cluster and
56
    modify the cluster state. See more details under
57
    *Cluster configuration*.
58

    
59
master_candidate
60
    The node receives the full cluster configuration (configuration
61
    file and jobs) and can become a master via the
62
    **gnt-cluster master-failover** command. Nodes that are not in this
63
    state cannot transition into the master role due to missing state.
64

    
65
regular
66
    This the normal state of a node.
67

    
68
drained
69
    Nodes in this state are functioning normally but cannot receive
70
    new instances, because the intention is to set them to *offline*
71
    or remove them from the cluster.
72

    
73
offline
74
    These nodes are still recorded in the Ganeti configuration, but
75
    except for the master daemon startup voting procedure, they are not
76
    actually contacted by the master. This state was added in order to
77
    allow broken machines (that are being repaired) to remain in the
78
    cluster but without creating problems.
79

    
80

    
81
Node flags
82
~~~~~~~~~~
83

    
84
Nodes have two flags which govern which roles they can take:
85

    
86
master_capable
87
    The node can become a master candidate, and furthermore the master
88
    node. When this flag is disabled, the node cannot become a
89
    candidate; this can be useful for special networking cases, or less
90
    reliable hardware.
91

    
92
vm_capable
93
    The node can host instances. When enabled (the default state), the
94
    node will participate in instance allocation, capacity calculation,
95
    etc. When disabled, the node will be skipped in many cluster checks
96
    and operations.
97

    
98

    
99
Node Parameters
100
~~~~~~~~~~~~~~~
101

    
102
These parameters are node specific and can be preseeded on node-group
103
and cluster level.
104

    
105
Currently we support the following node parameters:
106

    
107
oob_program
108
    Path to an executable used as the out-of-band helper as described in
109
    the `Ganeti Node OOB Management Framework <design-oob.rst>`_ design
110
    document.
111

    
112

    
113
Cluster configuration
114
~~~~~~~~~~~~~~~~~~~~~
115

    
116
The master node keeps and is responsible for the cluster
117
configuration. On the filesystem, this is stored under the
118
``@LOCALSTATEDIR@/ganeti/lib`` directory, and if the master daemon is
119
stopped it can be backed up normally.
120

    
121
The master daemon will replicate the configuration database called
122
``config.data`` and the job files to all the nodes in the master
123
candidate role. It will also distribute a copy of some configuration
124
values via the *ssconf* files, which are stored in the same directory
125
and start with a ``ssconf_`` prefix, to all nodes.
126

    
127
Jobs
128
~~~~
129

    
130
All cluster modification are done via jobs. A job consists of one
131
or more opcodes, and the list of opcodes is processed serially. If
132
an opcode fails, the entire job is failed and later opcodes are no
133
longer processed. A job can be in one of the following states:
134

    
135
queued
136
    The job has been submitted but not yet processed by the master
137
    daemon.
138

    
139
waiting
140
    The job is waiting for for locks before the first of its opcodes.
141

    
142
canceling
143
    The job is waiting for locks, but is has been marked for
144
    cancellation. It will not transition to *running*, but to
145
    *canceled*.
146

    
147
running
148
    The job is currently being executed.
149

    
150
canceled
151
    The job has been canceled before starting execution.
152

    
153
success
154
    The job has finished successfully.
155

    
156
error
157
    The job has failed during runtime, or the master daemon has been
158
    stopped during the job execution.
159

    
160

    
161
Common command line features
162
----------------------------
163

    
164
Options
165
~~~~~~~
166

    
167
Many Ganeti commands provide the following options. The
168
availability for a certain command can be checked by calling the
169
command using the ``--help`` option.
170

    
171
**gnt-...** *command* [--dry-run] [--priority {low | normal | high}]
172

    
173
The ``--dry-run`` option can be used to check whether an operation
174
would succeed.
175

    
176
The option ``--priority`` sets the priority for opcodes submitted
177
by the command.
178

    
179
Field formatting
180
----------------
181

    
182
Multiple ganeti commands use the same framework for tabular listing of
183
resources (e.g. **gnt-instance list**, **gnt-node list**, **gnt-group
184
list**, **gnt-debug locks**, etc.). For these commands, special states
185
are denoted via a special symbol (in terse mode) or a string (in
186
verbose mode):
187

    
188
*, (offline)
189
    The node in question is marked offline, and thus it cannot be
190
    queried for data. This result is persistent until the node is
191
    de-offlined.
192

    
193
?, (nodata)
194
    Ganeti expected to receive an answer from this entity, but the
195
    cluster RPC call failed and/or we didn't receive a valid answer;
196
    usually more information is available in the node daemon log (if
197
    the node is alive) or the master daemon log. This result is
198
    transient, and re-running command might return a different result.
199

    
200
-, (unavail)
201
    The respective field doesn't make sense for this entity;
202
    e.g. querying a down instance for its current memory 'live' usage,
203
    or querying a non-vm_capable node for disk/memory data. This
204
    result is persistent, and until the entity state is changed via
205
    ganeti commands, the result won't change.
206

    
207
??, (unknown)
208
    This field is not known (note that this is different from entity
209
    being unknown). Either you have mis-typed the field name, or you
210
    are using a field that the running Ganeti master daemon doesn't
211
    know. This result is persistent, re-running the command won't
212
    change it.
213

    
214
Key-value parameters
215
~~~~~~~~~~~~~~~~~~~~
216

    
217
Multiple options take parameters that are of the form
218
``key=value,key=value,...`` or ``category:key=value,...``. Examples
219
are the hypervisor parameters, backend parameters, etc. For these,
220
it's possible to use values that contain commas by escaping with via a
221
backslash (which needs two if not single-quoted, due to shell
222
behaviour)::
223

    
224
  # gnt-instance modify -H kernel_path=an\\,example instance1
225
  # gnt-instance modify -H kernel_path='an\,example' instance1
226

    
227
Common daemon functionality
228
---------------------------
229

    
230
All Ganeti daemons re-open the log file(s) when sent a SIGHUP signal.
231
**logrotate**(8) can be used to rotate Ganeti's log files.