Commit 36e23a40 authored by Iustin Pop's avatar Iustin Pop
Browse files

Update the install and admin documents

This is not a real update, just a quick pass changing the obvious parts.

Reviewed-by: imsnah
parent 4dc76b24
......@@ -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>
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment