Statistics
| Branch: | Tag: | Revision:

root / doc / admin.sgml @ 04daec5d

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
187
                one, which must be specified with the --secondary-node
188
                option. Use this option to obtain a highly available
189
                instance that can be failed over to a remote node
190
                should the primary one fail.
191
	      </simpara>
192
            </listitem>
193
        </varlistentry>
194

    
195
      </variablelist>
196

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

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

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

    
208
      </para>
209

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

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

    
217
      </para>
218
    </sect2>
219

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

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

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

    
230
        While the command to stop one is:
231

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

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

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

    
239
      </para>
240

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

    
249
    </sect2>
250

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

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

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

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

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

    
276
      <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>
277

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

    
281
      </para>
282
    </sect2>
283

    
284
  </sect1>
285

    
286

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
352
        and maybe add a new one:
353

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    
412
      </para>
413

    
414
    </sect2>
415

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

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

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

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

    
438
  </sect1>
439

    
440
  </article>