Statistics
| Branch: | Tag: | Revision:

root / doc / admin.sgml @ 4677a909

History | View | Annotate | Download (14 kB)

1
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
2
]>
3
  <article class="specification">
4
  <articleinfo>
5
    <title>Ganeti administrator's guide</title>
6
  </articleinfo>
7
  <para>Documents Ganeti version 1.2</para>
8
  <sect1>
9
    <title>Introduction</title>
10

    
11
    <para>Ganeti is a virtualization cluster management software. You are
12
    expected to be a system administrator familiar with your Linux distribution
13
    and the Xen virtualization environment before using it.
14
    </para>
15

    
16
    <para>The various components of Ganeti all have man pages and interactive
17
    help. This manual though will help you getting familiar with the system by
18
    explaining the most common operations, grouped by related use.
19
    </para>
20

    
21
    <para>After a terminology glossary and a section on the prerequisites
22
    needed to use this manual, the rest of this document is divided in three
23
    main sections, which group different features of Ganeti:
24
      <itemizedlist>
25
        <listitem>
26
          <simpara>Instance Management</simpara>
27
        </listitem>
28
        <listitem>
29
          <simpara>High Availability Features</simpara>
30
        </listitem>
31
        <listitem>
32
          <simpara>Debugging Features</simpara>
33
        </listitem>
34
      </itemizedlist>
35
    </para>
36

    
37
    <sect2>
38

    
39
      <title>Ganeti terminology</title>
40

    
41
      <para>This section provides a small introduction to Ganeti terminology,
42
      which might be useful to read the rest of the document.
43

    
44
      <glosslist>
45
          <glossentry>
46
            <glossterm>Cluster</glossterm>
47
            <glossdef>
48
              <simpara>
49
                A set of machines (nodes) that cooperate to offer a
50
                coherent highly available virtualization service.
51
              </simpara>
52
            </glossdef>
53
          </glossentry>
54
          <glossentry>
55
            <glossterm>Node</glossterm>
56
            <glossdef>
57
              <simpara>
58
                A physical machine which is member of a cluster.
59
                Nodes are the basic cluster infrastructure, and are
60
                not fault tolerant.
61
              </simpara>
62
            </glossdef>
63
          </glossentry>
64
          <glossentry>
65
            <glossterm>Master node</glossterm>
66
            <glossdef>
67
              <simpara>
68
                The node which controls the Cluster, from which all
69
                Ganeti commands must be given.
70
              </simpara>
71
            </glossdef>
72
          </glossentry>
73
          <glossentry>
74
            <glossterm>Instance</glossterm>
75
            <glossdef>
76
              <simpara>
77
                A virtual machine which runs on a cluster. It can be a
78
                fault tolerant highly available entity.
79
              </simpara>
80
            </glossdef>
81
          </glossentry>
82
          <glossentry>
83
            <glossterm>Pool</glossterm>
84
            <glossdef>
85
              <simpara>
86
                A pool is a set of clusters sharing the same network.
87
              </simpara>
88
            </glossdef>
89
          </glossentry>
90
          <glossentry>
91
            <glossterm>Meta-Cluster</glossterm>
92
            <glossdef>
93
              <simpara>
94
                Anything that concerns more than one cluster.
95
              </simpara>
96
            </glossdef>
97
          </glossentry>
98
      </glosslist>
99

    
100
      </para>
101
    </sect2>
102

    
103
    <sect2>
104
      <title>Prerequisites</title>
105

    
106
      <para>
107
        You need to have your Ganeti cluster installed and configured
108
        before you try any of the commands in this document. Please
109
        follow the <emphasis>Ganeti installation tutorial</emphasis>
110
        for instructions on how to do that.
111
      </para>
112
    </sect2>
113

    
114
  </sect1>
115

    
116
  <sect1>
117
    <title>Managing Instances</title>
118

    
119
    <sect2>
120
      <title>Adding/Removing an instance</title>
121

    
122
      <para>
123
        Adding a new virtual instance to your Ganeti cluster is really
124
        easy. The command is:
125

    
126
      <synopsis>gnt-instance add -n <replaceable>TARGET_NODE</replaceable> -o <replaceable>OS_TYPE</replaceable> -t <replaceable>DISK_TEMPLATE</replaceable> <replaceable>INSTANCE_NAME</replaceable></synopsis>
127

    
128
        The instance name must be resolvable (e.g. exist in DNS) and
129
        of course map to an address in the same subnet as the cluster
130
        itself. Options you can give to this command include:
131

    
132
      <itemizedlist>
133
        <listitem>
134
          <simpara>The disk size (<option>-s</option>)</simpara>
135
        </listitem>
136
        <listitem>
137
          <simpara>The swap size (<option>--swap-size</option>)</simpara>
138
        </listitem>
139
        <listitem>
140
          <simpara>The memory size (<option>-m</option>)</simpara>
141
        </listitem>
142
        <listitem>
143
          <simpara>The number of virtual CPUs (<option>-p</option>)</simpara>
144
        </listitem>
145
        <listitem>
146
	  <simpara>The instance ip address (<option>-i</option>) (use
147
	  the value <literal>auto</literal> to make Ganeti record the
148
	  address from dns)</simpara>
149
        </listitem>
150
        <listitem>
151
	  <simpara>The bridge to connect the instance to
152
	  (<option>-b</option>), if you don't want to use the default
153
	  one</simpara>
154
        </listitem>
155
      </itemizedlist>
156
      </para>
157

    
158
      <para>There are four types of disk template you can choose from:</para>
159

    
160
      <variablelist>
161
        <varlistentry>
162
          <term>diskless</term>
163
	  <listitem><para>The instance has no disks. Only used for special
164
	  purpouse operating systems or for testing.</para></listitem>
165
        </varlistentry>
166

    
167
        <varlistentry>
168
          <term>plain</term>
169
	  <listitem><para>The instance will use LVM devices as backend for its
170
	  disks. No redundancy is provided.</para></listitem>
171
        </varlistentry>
172

    
173
        <varlistentry>
174
          <term>local_raid1</term>
175
	  <listitem><para>A local mirror is set between LVM devices to back the
176
	  instance. This provides some redundancy for the instance's
177
	  data.</para></listitem>
178
        </varlistentry>
179

    
180
        <varlistentry>
181
          <term>remote_raid1</term>
182
	  <listitem>
183
            <simpara><emphasis role="strong">Note:</emphasis> This is
184
            only valid for multi-node clusters.</simpara>
185
            <simpara>
186
              A mirror is set between the local node and a remote one, which
187
              must be specified with the second value of the --node option. Use
188
              this option to obtain a highly available instance that can be
189
              failed over to a remote node should the primary one fail.
190
	      </simpara>
191
            </listitem>
192
        </varlistentry>
193

    
194
      </variablelist>
195

    
196
      <para>
197
        For example if you want to create an highly available instance
198
        use the remote_raid1 disk template:
199
        <synopsis>gnt-instance add -n <replaceable>TARGET_NODE</replaceable><optional>:<replaceable>SECONDARY_NODE</replaceable></optional> -o <replaceable>OS_TYPE</replaceable> -t remote_raid1 \
200
  <replaceable>INSTANCE_NAME</replaceable></synopsis>
201

    
202
      <para>
203
        To know which operating systems your cluster supports you can use:
204

    
205
        <synopsis>gnt-os list</synopsis>
206

    
207
      </para>
208

    
209
      <para>
210
        Removing an instance is even easier than creating one. This
211
        operation is non-reversible and destroys all the contents of
212
        your instance. Use with care:
213

    
214
      <synopsis>gnt-instance remove <replaceable>INSTANCE_NAME</replaceable></synopsis>
215

    
216
      </para>
217
    </sect2>
218

    
219
    <sect2>
220
      <title>Starting/Stopping an instance</title>
221

    
222
      <para>
223
        Instances are automatically started at instance creation
224
        time. To manually start one which is currently stopped you can
225
        run:
226

    
227
      <synopsis>gnt-instance startup <replaceable>INSTANCE_NAME</replaceable></synopsis>
228

    
229
        While the command to stop one is:
230

    
231
      <synopsis>gnt-instance shutdown <replaceable>INSTANCE_NAME</replaceable></synopsis>
232

    
233
        The command to see all the instances configured and their
234
        status is:
235

    
236
      <synopsis>gnt-instance list</synopsis>
237

    
238
      </para>
239

    
240
      <para>
241
        Do not use the xen commands to stop instances. If you run for
242
        example xm shutdown or xm destroy on an instance Ganeti will
243
        automatically restart it (via the
244
        <citerefentry><refentrytitle>ganeti-watcher</refentrytitle>
245
        <manvolnum>8</manvolnum></citerefentry>)
246
      </para>
247

    
248
    </sect2>
249

    
250
    <sect2>
251
      <title>Exporting/Importing an instance</title>
252

    
253
      <para>
254
        You can create a snapshot of an instance disk and Ganeti
255
        configuration, which then you can backup, or import into
256
        another cluster.  The way to export an instance is:
257

    
258
      <synopsis>gnt-backup export -n <replaceable>TARGET_NODE</replaceable> <replaceable>INSTANCE_NAME</replaceable></synopsis>
259

    
260
        The target node can be any node in the cluster with enough
261
        space under <filename class="directory">/srv/ganeti</filename>
262
        to hold the instance image. Use the
263
        <option>--noshutdown</option> option to snapshot an instance
264
        without rebooting it. Any previous snapshot of the same
265
        instance existing cluster-wide under <filename
266
        class="directory">/srv/ganeti</filename> will be removed by
267
        this operation: if you want to keep them move them out of the
268
        Ganeti exports directory.
269
      </para>
270

    
271
      <para>
272
        Importing an instance is similar to creating a new one. The
273
        command is:
274

    
275
      <synopsis>gnt-backup import -n <replaceable>TARGET_NODE</replaceable> -t <replaceable>DISK_TEMPLATE</replaceable> --src-node=<replaceable>NODE</replaceable> --src-dir=DIR INSTANCE_NAME</synopsis>
276

    
277
        Most of the options available for the command
278
        <emphasis>gnt-instance add</emphasis> are supported here too.
279

    
280
      </para>
281
    </sect2>
282

    
283
  </sect1>
284

    
285

    
286
  <sect1>
287
    <title>High availability features</title>
288

    
289
    <note>
290
      <simpara>This section only applies to multi-node clusters.</simpara>
291
    </note>
292

    
293
    <sect2>
294
      <title>Failing over an instance</title>
295

    
296
      <para>
297
        If an instance is built in highly available mode you can at
298
        any time fail it over to its secondary node, even if the
299
        primary has somehow failed and it's not up anymore. Doing it
300
        is really easy, on the master node you can just run:
301

    
302
      <synopsis>gnt-instance failover <replaceable>INSTANCE_NAME</replaceable></synopsis>
303

    
304
        That's it. After the command completes the secondary node is
305
        now the primary, and vice versa.
306
      </para>
307
    </sect2>
308

    
309
    <sect2>
310
      <title>Replacing an instance disks</title>
311

    
312
      <para>
313
        So what if instead the secondary node for an instance has
314
        failed, or you plan to remove a node from your cluster, and
315
        you failed over all its instances, but it's still secondary
316
        for some? The solution here is to replace the instance disks,
317
        changing the secondary node:
318

    
319
      <synopsis>gnt-instance replace-disks -n <replaceable>NEW_SECONDARY</replaceable> <replaceable>INSTANCE_NAME</replaceable></synopsis>
320

    
321
        This process is a bit longer, but involves no instance
322
        downtime, and at the end of it the instance has changed its
323
        secondary node, to which it can if necessary be failed over.
324
      </para>
325
    </sect2>
326
    <sect2>
327
      <title>Failing over the master node</title>
328

    
329
      <para>
330
        This is all good as long as the Ganeti Master Node is
331
        up. Should it go down, or should you wish to decommission it,
332
        just run on any other node the command:
333

    
334
      <synopsis>gnt-cluster masterfailover</synopsis>
335

    
336
        and the node you ran it on is now the new master.
337
      </para>
338
    </sect2>
339
    <sect2>
340
      <title>Adding/Removing nodes</title>
341

    
342
      <para>
343
        And of course, now that you know how to move instances around,
344
        it's easy to free up a node, and then you can remove it from
345
        the cluster:
346

    
347
      <synopsis>
348
gnt-node remove <replaceable>NODE_NAME</replaceable>
349
      </synopsis>
350

    
351
        and maybe add a new one:
352

    
353
      <synopsis>
354
gnt-node add <optional><option>--secondary-ip=<replaceable>ADDRESS</replaceable></option></optional> <replaceable>NODE_NAME</replaceable>
355

    
356
      </synopsis>
357
      </para>
358
    </sect2>
359
  </sect1>
360

    
361
  <sect1>
362
    <title>Debugging Features</title>
363

    
364
    <para>
365
      At some point you might need to do some debugging operations on
366
      your cluster or on your instances. This section will help you
367
      with the most used debugging functionalities.
368
    </para>
369

    
370
    <sect2>
371
      <title>Accessing an instance's disks</title>
372

    
373
      <para>
374
        From an instance's primary node you have access to its
375
        disks. Never ever mount the underlying logical volume manually
376
        on a fault tolerant instance, or you risk breaking
377
        replication. The correct way to access them is to run the
378
        command:
379

    
380
      <synopsis> gnt-instance activate-disks <replaceable>INSTANCE_NAME</replaceable></synopsis>
381

    
382
        And then access the device that gets created.  After you've
383
        finished you can deactivate them with the deactivate-disks
384
        command, which works in the same way.
385
      </para>
386
    </sect2>
387

    
388
    <sect2>
389
      <title>Accessing an instance's console</title>
390

    
391
      <para>
392
        The command to access a running instance's console is:
393

    
394
      <synopsis>gnt-instance console <replaceable>INSTANCE_NAME</replaceable></synopsis>
395

    
396
        Use the console normally and then type
397
        <userinput>^]</userinput> when done, to exit.
398
      </para>
399
    </sect2>
400

    
401
    <sect2>
402
      <title>Instance Operating System Debugging</title>
403

    
404
      <para>
405
        Should you have any problems with operating systems support
406
        the command to ran to see a complete status for all your nodes
407
        is:
408

    
409
      <synopsis>gnt-os diagnose</synopsis>
410

    
411
      </para>
412

    
413
    </sect2>
414

    
415
    <sect2>
416
      <title>Cluster-wide debugging</title>
417

    
418
      <para>
419
        The gnt-cluster command offers several options to run tests or
420
        execute cluster-wide operations. For example:
421

    
422
      <screen>
423
gnt-cluster command
424
gnt-cluster copyfile
425
gnt-cluster verify
426
gnt-cluster getmaster
427
gnt-cluster version
428
      </screen>
429

    
430
        See the man page <citerefentry>
431
        <refentrytitle>gnt-cluster</refentrytitle>
432
        <manvolnum>8</manvolnum> </citerefentry> to know more about
433
        their usage.
434
      </para>
435
    </sect2>
436

    
437
  </sect1>
438

    
439
  </article>