Statistics
| Branch: | Tag: | Revision:

root / man / ganeti.rst @ 23fe06c2

History | View | Annotate | Download (9.2 kB)

1 cc424a1d Iustin Pop
ganeti(7) Ganeti | Version @GANETI_VERSION@
2 cc424a1d Iustin Pop
===========================================
3 cc424a1d Iustin Pop
4 cc424a1d Iustin Pop
Name
5 cc424a1d Iustin Pop
----
6 cc424a1d Iustin Pop
7 cc424a1d Iustin Pop
ganeti - cluster-based virtualization management
8 cc424a1d Iustin Pop
9 cc424a1d Iustin Pop
Synopsis
10 cc424a1d Iustin Pop
--------
11 cc424a1d Iustin Pop
12 cc424a1d Iustin Pop
::
13 cc424a1d Iustin Pop
14 cc424a1d Iustin Pop
    # gnt-cluster init cluster1.example.com
15 cc424a1d Iustin Pop
    # gnt-node add node2.example.com
16 cc424a1d Iustin Pop
    # gnt-instance add -n node2.example.com \
17 cc424a1d Iustin Pop
    > -o debootstrap --disk 0:size=30g \
18 cc424a1d Iustin Pop
    > -t plain instance1.example.com
19 cc424a1d Iustin Pop
20 cc424a1d Iustin Pop
21 cc424a1d Iustin Pop
DESCRIPTION
22 cc424a1d Iustin Pop
-----------
23 cc424a1d Iustin Pop
24 cc424a1d Iustin Pop
The Ganeti software manages physical nodes and virtual instances of a
25 cc424a1d Iustin Pop
cluster based on a virtualization software. The current version (2.3)
26 cc424a1d Iustin Pop
supports Xen 3.x and KVM (72 or above) as hypervisors, and LXC as an
27 cc424a1d Iustin Pop
experimental hypervisor.
28 cc424a1d Iustin Pop
29 cc424a1d Iustin Pop
Quick start
30 cc424a1d Iustin Pop
-----------
31 cc424a1d Iustin Pop
32 cc424a1d Iustin Pop
First you must install the software on all the cluster nodes, either
33 cc424a1d Iustin Pop
from sources or (if available) from a package. The next step is to
34 cc424a1d Iustin Pop
create the initial cluster configuration, using **gnt-cluster init**.
35 cc424a1d Iustin Pop
36 cc424a1d Iustin Pop
Then you can add other nodes, or start creating instances.
37 cc424a1d Iustin Pop
38 cc424a1d Iustin Pop
Cluster architecture
39 cc424a1d Iustin Pop
--------------------
40 cc424a1d Iustin Pop
41 cc424a1d Iustin Pop
In Ganeti 2.0, the architecture of the cluster is a little more
42 cc424a1d Iustin Pop
complicated than in 1.2. The cluster is coordinated by a master daemon
43 cc424a1d Iustin Pop
(**ganeti-masterd**(8)), running on the master node. Each node runs
44 cc424a1d Iustin Pop
(as before) a node daemon, and the master has the RAPI daemon running
45 cc424a1d Iustin Pop
too.
46 cc424a1d Iustin Pop
47 cc424a1d Iustin Pop
Node roles
48 cc424a1d Iustin Pop
~~~~~~~~~~
49 cc424a1d Iustin Pop
50 cc424a1d Iustin Pop
Each node can be in one of the following states:
51 cc424a1d Iustin Pop
52 cc424a1d Iustin Pop
master
53 cc424a1d Iustin Pop
    Only one node per cluster can be in this role, and this node is the
54 cc424a1d Iustin Pop
    one holding the authoritative copy of the cluster configuration and
55 cc424a1d Iustin Pop
    the one that can actually execute commands on the cluster and
56 cc424a1d Iustin Pop
    modify the cluster state. See more details under
57 cc424a1d Iustin Pop
    *Cluster configuration*.
58 cc424a1d Iustin Pop
59 cc424a1d Iustin Pop
master_candidate
60 cc424a1d Iustin Pop
    The node receives the full cluster configuration (configuration
61 cc424a1d Iustin Pop
    file and jobs) and can become a master via the
62 cc424a1d Iustin Pop
    **gnt-cluster master-failover** command. Nodes that are not in this
63 cc424a1d Iustin Pop
    state cannot transition into the master role due to missing state.
64 cc424a1d Iustin Pop
65 cc424a1d Iustin Pop
regular
66 cc424a1d Iustin Pop
    This the normal state of a node.
67 cc424a1d Iustin Pop
68 cc424a1d Iustin Pop
drained
69 cc424a1d Iustin Pop
    Nodes in this state are functioning normally but cannot receive
70 cc424a1d Iustin Pop
    new instances, because the intention is to set them to *offline*
71 cc424a1d Iustin Pop
    or remove them from the cluster.
72 cc424a1d Iustin Pop
73 cc424a1d Iustin Pop
offline
74 cc424a1d Iustin Pop
    These nodes are still recorded in the Ganeti configuration, but
75 cc424a1d Iustin Pop
    except for the master daemon startup voting procedure, they are not
76 cc424a1d Iustin Pop
    actually contacted by the master. This state was added in order to
77 cc424a1d Iustin Pop
    allow broken machines (that are being repaired) to remain in the
78 cc424a1d Iustin Pop
    cluster but without creating problems.
79 cc424a1d Iustin Pop
80 cc424a1d Iustin Pop
81 cc424a1d Iustin Pop
Node flags
82 cc424a1d Iustin Pop
~~~~~~~~~~
83 cc424a1d Iustin Pop
84 cc424a1d Iustin Pop
Nodes have two flags which govern which roles they can take:
85 cc424a1d Iustin Pop
86 cc424a1d Iustin Pop
master_capable
87 cc424a1d Iustin Pop
    The node can become a master candidate, and furthermore the master
88 cc424a1d Iustin Pop
    node. When this flag is disabled, the node cannot become a
89 cc424a1d Iustin Pop
    candidate; this can be useful for special networking cases, or less
90 cc424a1d Iustin Pop
    reliable hardware.
91 cc424a1d Iustin Pop
92 cc424a1d Iustin Pop
vm_capable
93 cc424a1d Iustin Pop
    The node can host instances. When enabled (the default state), the
94 cc424a1d Iustin Pop
    node will participate in instance allocation, capacity calculation,
95 cc424a1d Iustin Pop
    etc. When disabled, the node will be skipped in many cluster checks
96 cc424a1d Iustin Pop
    and operations.
97 cc424a1d Iustin Pop
98 cc424a1d Iustin Pop
99 b74bf80c René Nussbaumer
Node Parameters
100 b74bf80c René Nussbaumer
~~~~~~~~~~~~~~~
101 b74bf80c René Nussbaumer
102 b74bf80c René Nussbaumer
These parameters are node specific and can be preseeded on node-group
103 b74bf80c René Nussbaumer
and cluster level.
104 b74bf80c René Nussbaumer
105 b74bf80c René Nussbaumer
Currently we support the following node parameters:
106 b74bf80c René Nussbaumer
107 b74bf80c René Nussbaumer
oob_program
108 b74bf80c René Nussbaumer
    Path to an executable used as the out-of-band helper as described in
109 b74bf80c René Nussbaumer
    the `Ganeti Node OOB Management Framework <design-oob.rst>`_ design
110 b74bf80c René Nussbaumer
    document.
111 b74bf80c René Nussbaumer
112 b74bf80c René Nussbaumer
113 cc424a1d Iustin Pop
Cluster configuration
114 cc424a1d Iustin Pop
~~~~~~~~~~~~~~~~~~~~~
115 cc424a1d Iustin Pop
116 cc424a1d Iustin Pop
The master node keeps and is responsible for the cluster
117 cc424a1d Iustin Pop
configuration. On the filesystem, this is stored under the
118 cc424a1d Iustin Pop
``@LOCALSTATEDIR@/ganeti/lib`` directory, and if the master daemon is
119 cc424a1d Iustin Pop
stopped it can be backed up normally.
120 cc424a1d Iustin Pop
121 cc424a1d Iustin Pop
The master daemon will replicate the configuration database called
122 cc424a1d Iustin Pop
``config.data`` and the job files to all the nodes in the master
123 cc424a1d Iustin Pop
candidate role. It will also distribute a copy of some configuration
124 cc424a1d Iustin Pop
values via the *ssconf* files, which are stored in the same directory
125 cc424a1d Iustin Pop
and start with a ``ssconf_`` prefix, to all nodes.
126 cc424a1d Iustin Pop
127 cc424a1d Iustin Pop
Jobs
128 cc424a1d Iustin Pop
~~~~
129 cc424a1d Iustin Pop
130 cc424a1d Iustin Pop
All cluster modification are done via jobs. A job consists of one
131 cc424a1d Iustin Pop
or more opcodes, and the list of opcodes is processed serially. If
132 cc424a1d Iustin Pop
an opcode fails, the entire job is failed and later opcodes are no
133 cc424a1d Iustin Pop
longer processed. A job can be in one of the following states:
134 cc424a1d Iustin Pop
135 cc424a1d Iustin Pop
queued
136 cc424a1d Iustin Pop
    The job has been submitted but not yet processed by the master
137 cc424a1d Iustin Pop
    daemon.
138 cc424a1d Iustin Pop
139 cc424a1d Iustin Pop
waiting
140 cc424a1d Iustin Pop
    The job is waiting for for locks before the first of its opcodes.
141 cc424a1d Iustin Pop
142 cc424a1d Iustin Pop
canceling
143 cc424a1d Iustin Pop
    The job is waiting for locks, but is has been marked for
144 cc424a1d Iustin Pop
    cancellation. It will not transition to *running*, but to
145 cc424a1d Iustin Pop
    *canceled*.
146 cc424a1d Iustin Pop
147 cc424a1d Iustin Pop
running
148 cc424a1d Iustin Pop
    The job is currently being executed.
149 cc424a1d Iustin Pop
150 cc424a1d Iustin Pop
canceled
151 cc424a1d Iustin Pop
    The job has been canceled before starting execution.
152 cc424a1d Iustin Pop
153 cc424a1d Iustin Pop
success
154 cc424a1d Iustin Pop
    The job has finished successfully.
155 cc424a1d Iustin Pop
156 cc424a1d Iustin Pop
error
157 cc424a1d Iustin Pop
    The job has failed during runtime, or the master daemon has been
158 cc424a1d Iustin Pop
    stopped during the job execution.
159 cc424a1d Iustin Pop
160 cc424a1d Iustin Pop
161 7ba19f39 Iustin Pop
Common command line features
162 7ba19f39 Iustin Pop
----------------------------
163 7ba19f39 Iustin Pop
164 7ba19f39 Iustin Pop
Options
165 7ba19f39 Iustin Pop
~~~~~~~
166 cc424a1d Iustin Pop
167 cc424a1d Iustin Pop
Many Ganeti commands provide the following options. The
168 cc424a1d Iustin Pop
availability for a certain command can be checked by calling the
169 cc424a1d Iustin Pop
command using the ``--help`` option.
170 cc424a1d Iustin Pop
171 cc424a1d Iustin Pop
**gnt-...** *command* [--dry-run] [--priority {low | normal | high}]
172 cc424a1d Iustin Pop
173 cc424a1d Iustin Pop
The ``--dry-run`` option can be used to check whether an operation
174 cc424a1d Iustin Pop
would succeed.
175 cc424a1d Iustin Pop
176 cc424a1d Iustin Pop
The option ``--priority`` sets the priority for opcodes submitted
177 cc424a1d Iustin Pop
by the command.
178 8cabf472 Michael Hanselmann
179 7ba19f39 Iustin Pop
Field formatting
180 7ba19f39 Iustin Pop
----------------
181 f0b1bafe Iustin Pop
182 f0b1bafe Iustin Pop
Multiple ganeti commands use the same framework for tabular listing of
183 f0b1bafe Iustin Pop
resources (e.g. **gnt-instance list**, **gnt-node list**, **gnt-group
184 f0b1bafe Iustin Pop
list**, **gnt-debug locks**, etc.). For these commands, special states
185 f0b1bafe Iustin Pop
are denoted via a special symbol (in terse mode) or a string (in
186 f0b1bafe Iustin Pop
verbose mode):
187 f0b1bafe Iustin Pop
188 3802f3cf Michael Hanselmann
\*, (offline)
189 f0b1bafe Iustin Pop
    The node in question is marked offline, and thus it cannot be
190 f0b1bafe Iustin Pop
    queried for data. This result is persistent until the node is
191 f0b1bafe Iustin Pop
    de-offlined.
192 f0b1bafe Iustin Pop
193 f0b1bafe Iustin Pop
?, (nodata)
194 f0b1bafe Iustin Pop
    Ganeti expected to receive an answer from this entity, but the
195 f0b1bafe Iustin Pop
    cluster RPC call failed and/or we didn't receive a valid answer;
196 f0b1bafe Iustin Pop
    usually more information is available in the node daemon log (if
197 f0b1bafe Iustin Pop
    the node is alive) or the master daemon log. This result is
198 f0b1bafe Iustin Pop
    transient, and re-running command might return a different result.
199 f0b1bafe Iustin Pop
200 f0b1bafe Iustin Pop
-, (unavail)
201 f0b1bafe Iustin Pop
    The respective field doesn't make sense for this entity;
202 f0b1bafe Iustin Pop
    e.g. querying a down instance for its current memory 'live' usage,
203 f0b1bafe Iustin Pop
    or querying a non-vm_capable node for disk/memory data. This
204 f0b1bafe Iustin Pop
    result is persistent, and until the entity state is changed via
205 f0b1bafe Iustin Pop
    ganeti commands, the result won't change.
206 f0b1bafe Iustin Pop
207 f0b1bafe Iustin Pop
??, (unknown)
208 f0b1bafe Iustin Pop
    This field is not known (note that this is different from entity
209 f0b1bafe Iustin Pop
    being unknown). Either you have mis-typed the field name, or you
210 f0b1bafe Iustin Pop
    are using a field that the running Ganeti master daemon doesn't
211 f0b1bafe Iustin Pop
    know. This result is persistent, re-running the command won't
212 f0b1bafe Iustin Pop
    change it.
213 7ba19f39 Iustin Pop
214 7ba19f39 Iustin Pop
Key-value parameters
215 7ba19f39 Iustin Pop
~~~~~~~~~~~~~~~~~~~~
216 7ba19f39 Iustin Pop
217 7ba19f39 Iustin Pop
Multiple options take parameters that are of the form
218 7ba19f39 Iustin Pop
``key=value,key=value,...`` or ``category:key=value,...``. Examples
219 7ba19f39 Iustin Pop
are the hypervisor parameters, backend parameters, etc. For these,
220 7ba19f39 Iustin Pop
it's possible to use values that contain commas by escaping with via a
221 7ba19f39 Iustin Pop
backslash (which needs two if not single-quoted, due to shell
222 7ba19f39 Iustin Pop
behaviour)::
223 7ba19f39 Iustin Pop
224 7ba19f39 Iustin Pop
  # gnt-instance modify -H kernel_path=an\\,example instance1
225 7ba19f39 Iustin Pop
  # gnt-instance modify -H kernel_path='an\,example' instance1
226 7ba19f39 Iustin Pop
227 3802f3cf Michael Hanselmann
Query filters
228 3802f3cf Michael Hanselmann
~~~~~~~~~~~~~
229 3802f3cf Michael Hanselmann
230 3802f3cf Michael Hanselmann
Most commands listing resources (e.g. instances or nodes) support filtering.
231 3802f3cf Michael Hanselmann
The filter language is similar to Python expressions with some elements from
232 3802f3cf Michael Hanselmann
Perl. The language is not generic. Each condition must consist of a field name
233 3802f3cf Michael Hanselmann
and a value (except for boolean checks), a field can not be compared to another
234 3802f3cf Michael Hanselmann
field. Keywords are case-sensitive.
235 3802f3cf Michael Hanselmann
236 3802f3cf Michael Hanselmann
Syntax in pseudo-BNF::
237 3802f3cf Michael Hanselmann
238 3802f3cf Michael Hanselmann
  <quoted-string> ::= /* String quoted with single or double quotes,
239 3802f3cf Michael Hanselmann
                         backslash for escaping */
240 3802f3cf Michael Hanselmann
241 3802f3cf Michael Hanselmann
  <integer> ::= /* Number in base-10 positional notation */
242 3802f3cf Michael Hanselmann
243 3802f3cf Michael Hanselmann
  <re> ::= /* Regular expression */
244 3802f3cf Michael Hanselmann
245 3802f3cf Michael Hanselmann
  /*
246 3802f3cf Michael Hanselmann
    Modifier "i": Case-insensitive matching, see
247 3802f3cf Michael Hanselmann
    http://docs.python.org/library/re#re.IGNORECASE
248 3802f3cf Michael Hanselmann
249 3802f3cf Michael Hanselmann
    Modifier "s": Make the "." special character match any character,
250 3802f3cf Michael Hanselmann
    including newline, see http://docs.python.org/library/re#re.DOTALL
251 3802f3cf Michael Hanselmann
  */
252 3802f3cf Michael Hanselmann
  <re-modifiers> ::= /* empty */ | i | s
253 3802f3cf Michael Hanselmann
254 3802f3cf Michael Hanselmann
  <value> ::= <quoted-string> | <integer>
255 3802f3cf Michael Hanselmann
256 3802f3cf Michael Hanselmann
  <condition> ::=
257 3802f3cf Michael Hanselmann
    { /* Value comparison */
258 3802f3cf Michael Hanselmann
      <field> { == | != } <value>
259 3802f3cf Michael Hanselmann
260 3802f3cf Michael Hanselmann
      /* Collection membership */
261 3802f3cf Michael Hanselmann
      | <value> [ not ] in <field>
262 3802f3cf Michael Hanselmann
263 3802f3cf Michael Hanselmann
      /* Regular expressions (recognized delimiters
264 3802f3cf Michael Hanselmann
         are "/", "#", "^", and "|"; backslash for escaping)
265 3802f3cf Michael Hanselmann
      */
266 3802f3cf Michael Hanselmann
      | <field> { =~ | !~ } m/<re>/<re-modifiers>
267 3802f3cf Michael Hanselmann
268 16629d10 Michael Hanselmann
      /* Globbing */
269 16629d10 Michael Hanselmann
      | <field> { =* | !* } <quoted-string>
270 16629d10 Michael Hanselmann
271 3802f3cf Michael Hanselmann
      /* Boolean */
272 3802f3cf Michael Hanselmann
      | <field>
273 3802f3cf Michael Hanselmann
    }
274 3802f3cf Michael Hanselmann
275 3802f3cf Michael Hanselmann
  <filter> ::=
276 3802f3cf Michael Hanselmann
    { [ not ] <condition> | ( <filter> ) }
277 3802f3cf Michael Hanselmann
    [ { and | or } <filter> ]
278 3802f3cf Michael Hanselmann
279 3802f3cf Michael Hanselmann
Operators:
280 3802f3cf Michael Hanselmann
281 3802f3cf Michael Hanselmann
*==*
282 3802f3cf Michael Hanselmann
  Equality
283 3802f3cf Michael Hanselmann
*!=*
284 3802f3cf Michael Hanselmann
  Inequality
285 3802f3cf Michael Hanselmann
*=~*
286 3802f3cf Michael Hanselmann
  Pattern match using regular expression
287 3802f3cf Michael Hanselmann
*!~*
288 3802f3cf Michael Hanselmann
  Logically negated from *=~*
289 16629d10 Michael Hanselmann
*=\**
290 16629d10 Michael Hanselmann
  Globbing, see **glob**(7), though only * and ? are supported
291 16629d10 Michael Hanselmann
*!\**
292 16629d10 Michael Hanselmann
  Logically negated from *=\**
293 3802f3cf Michael Hanselmann
*in*, *not in*
294 3802f3cf Michael Hanselmann
  Collection membership and negation
295 3802f3cf Michael Hanselmann
296 037c7b95 Michael Hanselmann
As a shortcut globbing patterns can be specified as names, e.g.
297 037c7b95 Michael Hanselmann
``gnt-instance list '*.site1' '*.site2'``.
298 037c7b95 Michael Hanselmann
299 3802f3cf Michael Hanselmann
300 7ba19f39 Iustin Pop
Common daemon functionality
301 7ba19f39 Iustin Pop
---------------------------
302 7ba19f39 Iustin Pop
303 7ba19f39 Iustin Pop
All Ganeti daemons re-open the log file(s) when sent a SIGHUP signal.
304 7ba19f39 Iustin Pop
**logrotate**(8) can be used to rotate Ganeti's log files.
305 9ff4f2c0 Michael Hanselmann
306 9ff4f2c0 Michael Hanselmann
.. vim: set textwidth=72 :
307 9ff4f2c0 Michael Hanselmann
.. Local Variables:
308 9ff4f2c0 Michael Hanselmann
.. mode: rst
309 9ff4f2c0 Michael Hanselmann
.. fill-column: 72
310 9ff4f2c0 Michael Hanselmann
.. End: