From 36e23a401079d564720580f26bde566a3d63f0da Mon Sep 17 00:00:00 2001
From: Iustin Pop <iustin@google.com>
Date: Tue, 17 Feb 2009 12:43:51 +0000
Subject: [PATCH] Update the install and admin documents
This is not a real update, just a quick pass changing the obvious parts.
Reviewed-by: imsnah
---
doc/admin.sgml | 89 +++++++++++++++++++++----------
doc/install.sgml | 135 +++++++++++++++++++++++++++--------------------
2 files changed, 137 insertions(+), 87 deletions(-)
diff --git a/doc/admin.sgml b/doc/admin.sgml
index dd43da38f..239ba5612 100644
--- a/doc/admin.sgml
+++ b/doc/admin.sgml
@@ -4,23 +4,29 @@
<articleinfo>
<title>Ganeti administrator's guide</title>
</articleinfo>
- <para>Documents Ganeti version 1.3</para>
+ <para>Documents Ganeti version 2.0</para>
<sect1>
<title>Introduction</title>
- <para>Ganeti is a virtualization cluster management software. You are
- expected to be a system administrator familiar with your Linux distribution
- and the Xen virtualization environment before using it.
+ <para>
+ Ganeti is a virtualization cluster management software. You are
+ expected to be a system administrator familiar with your Linux
+ distribution and the Xen or KVM virtualization environments
+ before using it.
</para>
- <para>The various components of Ganeti all have man pages and interactive
- help. This manual though will help you getting familiar with the system by
- explaining the most common operations, grouped by related use.
+ <para>
+ The various components of Ganeti all have man pages and
+ interactive help. This manual though will help you getting
+ familiar with the system by explaining the most common
+ operations, grouped by related use.
</para>
- <para>After a terminology glossary and a section on the prerequisites
- needed to use this manual, the rest of this document is divided in three
- main sections, which group different features of Ganeti:
+ <para>
+ After a terminology glossary and a section on the prerequisites
+ needed to use this manual, the rest of this document is divided
+ in three main sections, which group different features of
+ Ganeti:
<itemizedlist>
<listitem>
<simpara>Instance Management</simpara>
@@ -122,33 +128,32 @@
Adding a new virtual instance to your Ganeti cluster is really easy.
The command is:
- <synopsis>gnt-instance add -n <replaceable>TARGET_NODE</replaceable> -o <replaceable>OS_TYPE</replaceable> -t <replaceable>DISK_TEMPLATE</replaceable> <replaceable>INSTANCE_NAME</replaceable></synopsis>
+ <synopsis>gnt-instance add -n <replaceable>TARGET_NODE<optional>:SECONDARY_NODE</optional></replaceable> -o <replaceable>OS_TYPE</replaceable> -t <replaceable>DISK_TEMPLATE</replaceable> <replaceable>INSTANCE_NAME</replaceable></synopsis>
The instance name must be resolvable (e.g. exist in DNS) and
- of course map to an address in the same subnet as the cluster
+ usually to an address in the same subnet as the cluster
itself. Options you can give to this command include:
<itemizedlist>
<listitem>
- <simpara>The disk size (<option>-s</option>)</simpara>
+ <simpara>The disk size (<option>-s</option>) for a
+ single-disk instance, or multiple <option>--disk
+ <replaceable>N</replaceable>:size=<replaceable>SIZE</replaceable></option>
+ options for multi-instance disks</simpara>
</listitem>
<listitem>
- <simpara>The swap size (<option>--swap-size</option>)</simpara>
+ <simpara>The memory size (<option>-B memory</option>)</simpara>
</listitem>
<listitem>
- <simpara>The memory size (<option>-m</option>)</simpara>
+ <simpara>The number of virtual CPUs (<option>-B vcpus</option>)</simpara>
</listitem>
<listitem>
- <simpara>The number of virtual CPUs (<option>-p</option>)</simpara>
- </listitem>
- <listitem>
- <simpara>The instance ip address (<option>-i</option>) (use the value
- <literal>auto</literal> to make Ganeti record the address from
- dns)</simpara>
- </listitem>
- <listitem>
- <simpara>The bridge to connect the instance to (<option>-b</option>),
- if you don't want to use the default one</simpara>
+ <para>
+ Arguments for the NICs of the instance; by default, a
+ single-NIC instance is created. The IP and/or bridge of
+ the NIC can be changed via <option>--nic
+ 0:ip=<replaceable>IP</replaceable>,bridge=<replaceable>BRIDGE</replaceable></option>
+ </para>
</listitem>
</itemizedlist>
</para>
@@ -164,6 +169,15 @@
</listitem>
</varlistentry>
+ <varlistentry>
+ <term>file</term>
+ <listitem>
+ <para>The instance will use plain files as backend for its
+ disks. No redundancy is provided, and this is somewhat
+ more difficult to configure for high performance.</para>
+ </listitem>
+ </varlistentry>
+
<varlistentry>
<term>plain</term>
<listitem>
@@ -200,9 +214,9 @@
</para>
<para>
- Removing an instance is even easier than creating one. This operation
- is non-reversible and destroys all the contents of your instance. Use
- with care:
+ Removing an instance is even easier than creating one. This
+ operation is irrereversible and destroys all the contents of
+ your instance. Use with care:
<synopsis>gnt-instance remove <replaceable>INSTANCE_NAME</replaceable></synopsis>
</para>
@@ -295,6 +309,21 @@
</para>
</sect2>
+ <sect2>
+ <title>Live migrating an instance</title>
+
+ <para>
+ If an instance is built in highly available mode, it currently
+ runs and both its nodes are running fine, you can at migrate
+ it over to its secondary node, without dowtime. On the master
+ node you need to run:
+
+ <synopsis>gnt-instance migrate <replaceable>INSTANCE_NAME</replaceable></synopsis>
+
+ </para>
+ </sect2>
+
+
<sect2>
<title>Replacing an instance disks</title>
@@ -304,13 +333,14 @@
you failed over all its instances, but it's still secondary
for some? The solution here is to replace the instance disks,
changing the secondary node:
- <synopsis>gnt-instance replace-disks <option>-s</option> <option>--new-secondary <replaceable>NODE</replaceable></option> <replaceable>INSTANCE_NAME</replaceable></synopsis>
+ <synopsis>gnt-instance replace-disks <option>-n <replaceable>NODE</replaceable></option> <replaceable>INSTANCE_NAME</replaceable></synopsis>
This process is a bit long, but involves no instance
downtime, and at the end of it the instance has changed its
secondary node, to which it can if necessary be failed over.
</para>
</sect2>
+
<sect2>
<title>Failing over the master node</title>
@@ -408,6 +438,7 @@
gnt-cluster command
gnt-cluster copyfile
gnt-cluster verify
+gnt-cluster verify-disks
gnt-cluster getmaster
gnt-cluster version
</screen>
diff --git a/doc/install.sgml b/doc/install.sgml
index cb5cb1f96..d1aaf1bc9 100644
--- a/doc/install.sgml
+++ b/doc/install.sgml
@@ -4,18 +4,18 @@
<articleinfo>
<title>Ganeti installation tutorial</title>
</articleinfo>
- <para>Documents Ganeti version 1.2</para>
+ <para>Documents Ganeti version 2.0</para>
<sect1>
<title>Introduction</title>
<para>
Ganeti is a cluster virtualization management system based on
- Xen. This document explains how to bootstrap a Ganeti node (Xen
- <literal>dom0</literal>), create a running cluster and install
- virtual instance (Xen <literal>domU</literal>). You need to
- repeat most of the steps in this document for every node you
- want to install, but of course we recommend creating some
+ Xen or KVM. This document explains how to bootstrap a Ganeti
+ node (Xen <literal>dom0</literal>), create a running cluster and
+ install virtual instance (Xen <literal>domU</literal>). You
+ need to repeat most of the steps in this document for every node
+ you want to install, but of course we recommend creating some
semi-automatic procedure if you plan to deploy Ganeti on a
medium/large scale.
</para>
@@ -29,11 +29,11 @@
<para>
Ganeti has been developed for Linux and is
- distribution-agnostic. This documentation will use Debian Etch
+ distribution-agnostic. This documentation will use Debian Lenny
as an example system but the examples can easily be translated
to any other distribution. You are expected to be familiar with
- your distribution, its package management system, and Xen before
- trying to use Ganeti.
+ your distribution, its package management system, and Xen or KVM
+ before trying to use Ganeti.
</para>
<para>This document is divided into two main sections:
@@ -90,9 +90,14 @@
at this stage is to partition leaving enough space for a big
(<emphasis role="strong">minimum
<constant>20GiB</constant></emphasis>) LVM volume group which
- will then host your instance filesystems. The volume group
- name Ganeti 1.2 uses (by default) is
- <emphasis>xenvg</emphasis>.
+ will then host your instance filesystems, if you want to use
+ all Ganeti features. The volume group name Ganeti 2.0 uses (by
+ default) is <emphasis>xenvg</emphasis>.
+ </para>
+
+ <para>
+ You can also use file-based storage only, without LVM, but
+ this is not detailed in this document.
</para>
<para>
@@ -122,7 +127,7 @@
<formalpara>
<title>Debian</title>
<para>
- Note that Debian Etch configures the hostname differently
+ Note that Debian Lenny configures the hostname differently
than you need it for Ganeti. For example, this is what
Etch puts in <filename>/etc/hosts</filename> in certain
situations:
@@ -158,9 +163,9 @@
<para>
While Ganeti is developed with the ability to modularly run on
- different virtualization environments in mind the only one
- currently useable on a live system is <ulink
- url="http://xen.xensource.com/">Xen</ulink>. Supported
+ different virtualization environments in mind the only two
+ currently useable on a live system are <ulink
+ url="http://xen.xensource.com/">Xen</ulink> and KVM. Supported
versions are: <simplelist type="inline">
<member><literal>3.0.3</literal></member>
<member><literal>3.0.4</literal></member>
@@ -170,25 +175,25 @@
<para>
Please follow your distribution's recommended way to install
and set up Xen, or install Xen from the upstream source, if
- you wish, following their manual.
+ you wish, following their manual. For KVM, make sure you have
+ a KVM-enabled kernel and the KVM tools.
</para>
<para>
- After installing Xen you need to reboot into your Xen-ified
- dom0 system. On some distributions this might involve
+ After installing either hypervisor, you need to reboot into
+ your new system. On some distributions this might involve
configuring GRUB appropriately, whereas others will configure
- it automatically when you install Xen from a package.
+ it automatically when you install the respective kernels.
</para>
<formalpara><title>Debian</title>
<para>
- Under Debian Etch or Sarge+backports you can install the
- relevant <literal>xen-linux-system</literal> package, which
- will pull in both the hypervisor and the relevant
- kernel. Also, if you are installing a 32-bit Etch, you should
- install the <computeroutput>libc6-xen</computeroutput> package
- (run <computeroutput>apt-get install
- libc6-xen</computeroutput>).
+ Under Debian Lenny or Etch you can install the relevant
+ <literal>xen-linux-system</literal> package, which will pull
+ in both the hypervisor and the relevant kernel. Also, if you
+ are installing a 32-bit Lenny/Etch, you should install the
+ <computeroutput>libc6-xen</computeroutput> package (run
+ <computeroutput>apt-get install libc6-xen</computeroutput>).
</para>
</formalpara>
@@ -197,8 +202,9 @@
<para>
It's recommended that dom0 is restricted to a low amount of
- memory (<constant>512MiB</constant> is reasonable) and that
- memory ballooning is disabled in the file
+ memory (<constant>512MiB</constant> or
+ <constant>1GiB</constant> is reasonable) and that memory
+ ballooning is disabled in the file
<filename>/etc/xen/xend-config.sxp</filename> by setting the
value <literal>dom0-min-mem</literal> to
<constant>0</constant>, like this:
@@ -228,10 +234,10 @@
set the memory and nosmp parameters in the file
<filename>/boot/grub/menu.lst</filename>. You need to
modify the variable <literal>xenhopt</literal> to add
- <userinput>dom0_mem=512M</userinput> like this:
+ <userinput>dom0_mem=1024M</userinput> like this:
<screen>
## Xen hypervisor options to use with the default Xen boot option
-# xenhopt=dom0_mem=512M
+# xenhopt=dom0_mem=1024M
</screen>
and the <literal>xenkopt</literal> needs to include the
<userinput>nosmp</userinput> option like this:
@@ -250,9 +256,9 @@
</para>
</formalpara>
<para>
- If you want to test the HVM support
- with Ganeti and want VNC access to the console of your
- instances, set the following two entries in
+ If you want to run HVM instances too with Ganeti and want
+ VNC access to the console of your instances, set the
+ following two entries in
<filename>/etc/xen/xend-config.sxp</filename>:
<screen>
(vnc-listen '0.0.0.0')
@@ -315,7 +321,7 @@ ln -s initrd.img-2.6.18-5-xen-686 initrd-2.6-xenU
<para>
Supported DRBD versions: <literal>8.0.x</literal>.
- It's recommended to have at least version <literal>8.0.7</literal>.
+ It's recommended to have at least version <literal>8.0.12</literal>.
</para>
<para>
@@ -346,7 +352,7 @@ ln -s initrd.img-2.6.18-5-xen-686 initrd-2.6-xenU
</formalpara>
<screen>
-apt-get install -t etch-backports drbd8-source drbd8-utils
+apt-get install drbd8-source drbd8-utils
m-a update
m-a a-i drbd8
echo drbd minor_count=128 >> /etc/modules
@@ -442,7 +448,7 @@ skip resource "r1" {
</formalpara>
<screen>
# apt-get install lvm2 ssh bridge-utils iproute iputils-arping \
- python2.4 python-pyopenssl openssl python-pyparsing python-simplejson
+ python python-pyopenssl openssl python-pyparsing python-simplejson
</screen>
</sect2>
@@ -628,19 +634,24 @@ mkdir /srv/ganeti/ /srv/ganeti/os /srv/ganeti/export
<para>
To be able to install instances you need to have an Operating
- System installation script. An example for Debian Etch is
+ System installation script. An example OS that works under
+ Debian and can install Debian and Ubuntu instace OSes is
provided on the project web site. Download it from <ulink
url="http://code.google.com/p/ganeti/"></ulink> and follow the
instructions in the <filename>README</filename> file. Here is
- the installation procedure (replace <constant>0.2</constant>
+ the installation procedure (replace <constant>0.7</constant>
with the latest version that is compatible with your ganeti
version):
</para>
<screen>
-cd /srv/ganeti/os
-tar xvf ganeti-instance-debian-etch-0.4.tar
-mv ganeti-instance-debian-etch-0.4 debian-etch
+cd /usr/local/src/
+wget http://ganeti.googlecode.com/files/ganeti-instance-debootstrap-0.7.tar.gz
+tar xzf ganeti-instance-debootstrap-0.7.tar.gz
+cd ganeti-instance-debootstrap-0.7
+./configure
+make
+make install
</screen>
<para>
@@ -652,7 +663,10 @@ mv ganeti-instance-debian-etch-0.4 debian-etch
</citerefentry> and <citerefentry>
<refentrytitle>restore</refentrytitle>
<manvolnum>8</manvolnum> </citerefentry> commands installed on
- all nodes.
+ all nodes. Also, if the OS is configured to partition the
+ instance's disk in
+ <filename>/etc/default/ganeti-instance-debootstrap</filename>,
+ you will need <command>kpartx</command> installed.
</para>
<formalpara>
<title>Debian</title>
@@ -660,7 +674,7 @@ mv ganeti-instance-debian-etch-0.4 debian-etch
Use this command on all nodes to install the required
packages:
- <screen>apt-get install debootstrap dump</screen>
+ <screen>apt-get install debootstrap dump kpartx</screen>
</para>
</formalpara>
@@ -682,8 +696,10 @@ mv ganeti-instance-debian-etch-0.4 debian-etch
node per cluster.</para>
- <para>The last step is to initialize the cluster. After you've repeated
- the above process on all of your nodes, choose one as the master, and execute:
+ <para>
+ The last step is to initialize the cluster. After you've
+ repeated the above process on all of your nodes, choose one as
+ the master, and execute:
</para>
<screen>
@@ -699,8 +715,8 @@ gnt-cluster init <replaceable>CLUSTERNAME</replaceable>
choice is to have a unique name for a cluster, even if it
consists of only one machine, as you will be able to expand it
later without any problems. Please note that the hostname used
- for this must resolve to an IP address reserved exclusively
- for this purpose.
+ for this must resolve to an IP address reserved <emphasis
+ role="strong">exclusively</emphasis> for this purpose.
</para>
<para>
@@ -723,18 +739,21 @@ gnt-cluster init <replaceable>CLUSTERNAME</replaceable>
<para>
To set up the cluster as an HVM cluster, use the
- <option>--hypervisor=xen-hvm3.1</option> option to use
- the Xen 3.1 HVM hypervisor. Note that with the
- HVM support, you will only be able to create
- HVM instances in a cluster set to this hypervisor type. Mixed
- PVM/HVM clusters are not supported by the Ganeti 1.2
- HVM support. You will also need to create the VNC
- cluster password file
- <filename>/etc/ganeti/vnc-cluster-password</filename>
+ <option>--enabled-hypervisors=xen-hvm</option> option to
+ enable the HVM hypervisor (you can also add
+ <userinput>,xen-pvm</userinput> to enable the PVM one
+ too). You will also need to create the VNC cluster password
+ file <filename>/etc/ganeti/vnc-cluster-password</filename>
which contains one line with the default VNC password for the
cluster.
</para>
+ <para>
+ To setup the cluster for KVM-only usage (KVM and Xen cannot be
+ mixed), pass <option>--enabled-hypervisors=kvm</option> to the
+ init command.
+ </para>
+
<para>
You can also invoke the command with the
<option>--help</option> option in order to see all the
@@ -815,7 +834,7 @@ node1.example.com 197404 197404 2047 1896 125 0 0
instance for you:
</para>
<screen>
-gnt-instance add --node=node1 -o debian-etch -t plain inst1.example.com
+gnt-instance add --node=node1 -o debootstrap -t plain inst1.example.com
* creating instance disks...
adding instance inst1.example.com to cluster config
Waiting for instance inst1.example.com to sync disks.
@@ -844,7 +863,7 @@ creating os for instance inst1.example.com on node node1.example.com
</para>
<screen>
-# gnt-instance add -t drbd -n node1:node2 -o debian-etch instance2
+# gnt-instance add -t drbd -n node1:node2 -o debootstrap instance2
* creating instance disks...
adding instance instance2 to cluster config
Waiting for instance instance1 to sync disks.
--
GitLab