Synnefo » snf-ganeti » ganeti-local

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [

]>

  <article class="specification">

  <articleinfo>

    <title>Ganeti installation tutorial</title>

  </articleinfo>

  <para>Documents Ganeti version 1.2</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

      semi-automatic procedure if you plan to deploy Ganeti on a

      medium/large scale.

    </para>

    <para>

      A basic Ganeti terminology glossary is provided in the

      introductory section of the <emphasis>Ganeti administrator's

      guide</emphasis>. Please refer to that document if you are

      uncertain about the terms we are using.

    </para>

    <para>

      Ganeti has been developed for Linux and is

      distribution-agnostic.  This documentation will use Debian Etch

      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.

    </para>

    <para>This document is divided into two main sections:

      <itemizedlist>

        <listitem>

          <simpara>Installation of the base system and base

          components</simpara>

        </listitem>

        <listitem>

          <simpara>Configuration of the environment for

          Ganeti</simpara>

        </listitem>

      </itemizedlist>

    Each of these is divided into sub-sections. While a full Ganeti

    system will need all of the steps specified, some are not strictly

    required for every environment. Which ones they are, and why, is

    specified in the corresponding sections.

    </para>

  </sect1>

  <sect1>

    <title>Installing the base system and base components</title>

    <sect2>

      <title>Hardware requirements</title>

      <para>

         Any system supported by your Linux distribution is fine.

         64-bit systems are better as they can support more memory.

      </para>

      <para>

         Any disk drive recognized by Linux

         (<literal>IDE</literal>/<literal>SCSI</literal>/<literal>SATA</literal>/etc.)

         is supported in Ganeti. Note that no shared storage

         (e.g. <literal>SAN</literal>) is needed to get high-availability features. It is

         highly recommended to use more than one disk drive to improve

         speed. But Ganeti also works with one disk per machine.

      </para>

    <sect2>

      <title>Installing the base system</title>

      <para>

        <emphasis role="strong">Mandatory</emphasis> on all nodes.

      </para>

      <para>

        It is advised to start with a clean, minimal install of the

        operating system. The only requirement you need to be aware of

        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>.

      </para>

      <para>

        While you can use an existing system, please note that the

        Ganeti installation is intrusive in terms of changes to the

        system configuration, and it's best to use a newly-installed

        system without important data on it.

      </para>

      <para>

        Also, for best results, it's advised that the nodes have as

        much as possible the same hardware and software

        configuration. This will make administration much easier.

      </para>

      <sect3>

        <title>Hostname issues</title>

        <para>

          Note that Ganeti requires the hostnames of the systems

          (i.e. what the <computeroutput>hostname</computeroutput>

          command outputs to be a fully-qualified name, not a short

          name. In other words, you should use

          <literal>node1.example.com</literal> as a hostname and not

          just <literal>node1</literal>.

        </para>

        <formalpara>

          <title>Debian</title>

          <para>

            Note that Debian Etch 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:

<screen>

127.0.0.1       localhost

127.0.1.1       node1.example.com node1

</screen>

          but for Ganeti you need to have:

<screen>

127.0.0.1       localhost

192.168.1.1     node1.example.com node1

</screen>

            replacing <literal>192.168.1.1</literal> with your node's

            address. Also, the file <filename>/etc/hostname</filename>

            which configures the hostname of the system should contain

            <literal>node1.example.com</literal> and not just

            <literal>node1</literal> (you need to run the command

            <computeroutput>/etc/init.d/hostname.sh

            start</computeroutput> after changing the file).

          </para>

        </formalpara>

      </sect3>

    </sect2>

    <sect2>

      <title>Installing Xen</title>

      <para>

        <emphasis role="strong">Mandatory</emphasis> on all nodes.

      </para>

      <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

        versions are: <simplelist type="inline">

        <member><literal>3.0.3</literal></member>

        <member><literal>3.0.4</literal></member>

        <member><literal>3.1</literal></member> </simplelist>.

      </para>

      <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.

      </para>

      <para>

        After installing Xen you need to reboot into your xenified

        dom0 system. On some distributions this might involve

        configuring GRUB appropriately, whereas others will configure

        it automatically when you install Xen from a package.

      </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>lib6-xen</computeroutput> package

        (run <computeroutput>apt-get install

        libc6-xen</computeroutput>).

      </para>

      </formalpara>

      <sect3>

        <title>Selecting the instance kernel</title>

        <para>

          After you have installed xen, you need to tell Ganeti

          exactly what kernel to use for the instances it will

          create. This is done by creating a

          <emphasis>symlink</emphasis> from your actual kernel to

          <filename>/boot/vmlinuz-2.6-xenU</filename>, and one from

          your initrd to

          <filename>/boot/initrd-2.6-xenU</filename>. Note that if you

          don't use an initrd for the <literal>domU</literal> kernel,

          you don't need to create the initrd symlink.

        </para>

        <formalpara>

          <title>Debian</title>

          <para>

            After installation of the

            <literal>xen-linux-system</literal> package, you need to

            run (replace the exact version number with the one you

            have):

            <screen>

cd /boot

ln -s vmlinuz-2.6.18-5-xen-686 vmlinuz-2.6-xenU

ln -s initrd.img-2.6.18-5-xen-686 initrd-2.6-xenU

            </screen>

          </para>

        </formalpara>

      </sect3>

    </sect2>

    <sect2>

      <title>Installing DRBD</title>

      <para>

        Recommended on all nodes: <ulink

        url="http://www.drbd.org/">DRBD</ulink> is required if you

        want to use the high availability (HA) features of Ganeti, but

        optional if you don't require HA or only run Ganeti on

        single-node clusters. You can upgrade a non-HA cluster to an

        HA one later, but you might need to export and re-import all

        your instances to take advantage of the new features.

      </para>

      <para>

        Supported DRBD version: the <literal>0.7</literal>

        series. It's recommended to have at least version

        <literal>0.7.24</literal> if you use <command>udev</command>

        since older versions have a bug related to device discovery

        which can be triggered in cases of hard drive failure.

      </para>

      <para>

        Now the bad news: unless your distribution already provides it

        installing DRBD might involve recompiling your kernel or

        anyway fiddling with it. Hopefully at least the xenified

        kernel source to start from will be provided.

      </para>

      <para>

        The good news is that you don't need to configure DRBD at all.

        Ganeti will do it for you for every instance you set up.  If

        you have the DRBD utils installed and the module in your

        kernel you're fine. Please check that your system is

        configured to load the module at every boot, and that it

        passes the following option to the module:

        <computeroutput>minor_count=64</computeroutput> (this will

        allow you to use up to 32 instances per node).

      </para>

      <formalpara><title>Debian</title>

        <para>

         You can just install (build) the DRBD 0.7 module with the

         following commands (make sure you are running the Xen

         kernel):

        </para>

      </formalpara>

      <screen>

apt-get install drbd0.7-module-source drbd0.7-utils

m-a update

m-a a-i drbd0.7

echo drbd minor_count=64 >> /etc/modules

modprobe drbd minor_count=64

      </screen>

    </sect2>

    <sect2>

      <title>Other required software</title>

      <para>Besides Xen and DRBD, you will need to install the

      following (on all nodes):</para>

      <itemizedlist>

        <listitem>

          <simpara><ulink url="http://sourceware.org/lvm2/">LVM

          version 2</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="http://www.openssl.org/">OpenSSL</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="http://www.openssh.com/portable.html">OpenSSH</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink url="http://bridge.sourceforge.net/">Bridge

          utilities</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="http://fping.sourceforge.net/">fping</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="http://developer.osdl.org/dev/iproute2">iproute2</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="ftp://ftp.inr.ac.ru/ip-routing/iputils-current.tar.gz">arping</ulink>

          (part of iputils package)</simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="http://www.kernel.org/pub/linux/utils/raid/mdadm/">mdadm</ulink>

          (Linux Software Raid tools)</simpara>

        </listitem>

        <listitem>

          <simpara><ulink url="http://www.python.org">Python 2.4</ulink></simpara>

        </listitem>

        <listitem>

          <simpara><ulink url="http://twistedmatrix.com/">Python

          Twisted library</ulink> - the core library is

          enough</simpara>

        </listitem>

        <listitem>

          <simpara><ulink

          url="http://pyopenssl.sourceforge.net/">Python OpenSSL

          bindings</ulink></simpara>

        </listitem>

      </itemizedlist>

      <para>

        These programs are supplied as part of most Linux

        distributions, so usually they can be installed via apt or

        similar methods. Also many of them will already be installed

        on a standard machine.

      </para>

      <formalpara><title>Debian</title>

      <para>You can use this command line to install all of them:</para>

      </formalpara>

      <screen>

# apt-get install lvm2 ssh bridge-utils iproute iputils-arping \

  fping python2.4 python-twisted-core python-pyopenssl openssl \

  mdadm

      </screen>

    </sect2>

  </sect1>

  <sect1>

    <title>Setting up the environment for Ganeti</title>

    <sect2>

      <title>Configuring the network</title>

      <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>

      <para>

        Ganeti relies on Xen running in "bridge mode", which means the

        instances network interfaces will be attached to a software bridge

        running in dom0. Xen by default creates such a bridge at startup, but

        your distribution might have a different way to do things.

      </para>

      <para>

        Beware that the default name Ganeti uses is

        <hardware>xen-br0</hardware> (which was used in Xen 2.0)

        while Xen 3.0 uses <hardware>xenbr0</hardware> by

        default. The default bridge your Ganeti cluster will use for new

        instances can be specified at cluster initialization time.

      </para>

      <formalpara><title>Debian</title>

        <para>

          The recommended Debian way to configure the xen bridge is to

          edit your <filename>/etc/network/interfaces</filename> file

          and substitute your normal Ethernet stanza with the

          following snippet:

        <screen>

auto xen-br0

iface xen-br0 inet static

        address <replaceable>YOUR_IP_ADDRESS</replaceable>

        netmask <replaceable>YOUR_NETMASK</replaceable>

        network <replaceable>YOUR_NETWORK</replaceable>

        broadcast <replaceable>YOUR_BROADCAST_ADDRESS</replaceable>

        gateway <replaceable>YOUR_GATEWAY</replaceable>

        bridge_ports eth0

        bridge_stp off

        bridge_fd 0

        </screen>

        </para>

      </formalpara>

     <para>

The following commands need to be executed on the local console

     </para>

      <screen>

ifdown eth0

ifup xen-br0

      </screen>

      <para>

        To check if the bridge is setup, use <command>ip</command>

        and <command>brctl show</command>:

      <para>

      <screen>

# ip a show xen-br0

9: xen-br0: <BROADCAST,MULTICAST,UP,10000> mtu 1500 qdisc noqueue

    link/ether 00:20:fc:1e:d5:5d brd ff:ff:ff:ff:ff:ff

    inet 10.1.1.200/24 brd 10.1.1.255 scope global xen-br0

    inet6 fe80::220:fcff:fe1e:d55d/64 scope link

       valid_lft forever preferred_lft forever

# brctl show xen-br0

bridge name     bridge id               STP enabled     interfaces

xen-br0         8000.0020fc1ed55d       no              eth0

      </screen>

    </sect2>

    <sect2>

      <title>Configuring LVM</title>

      <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>

      <note>

        <simpara>The volume group is required to be at least

        <constant>20GiB</constant>.</simpara>

      </note>

      <para>

        If you haven't configured your LVM volume group at install

        time you need to do it before trying to initialize the Ganeti

        cluster. This is done by formatting the devices/partitions you

        want to use for it and then adding them to the relevant volume

        group:

       <screen>

pvcreate /dev/sda3

vgcreate xenvg /dev/sda3

       </screen>

or

       <screen>

pvcreate /dev/sdb1

pvcreate /dev/sdc1

vgcreate xenvg /dev/sdb1 /dev/sdc1

       </screen>

      </para>

      <para>

	If you want to add a device later you can do so with the

	<citerefentry><refentrytitle>vgextend</refentrytitle>

	<manvolnum>8</manvolnum></citerefentry> command:

      </para>

      <screen>

pvcreate /dev/sdd1

vgextend xenvg /dev/sdd1

      </screen>

    </sect2>

    <sect2>

      <title>Installing Ganeti</title>

      <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>

      <para>

        It's now time to install the Ganeti software itself.  Download

        the source from <ulink

        url="http://code.google.com/p/ganeti/"></ulink>.

      </para>

        <screen>

tar xvzf ganeti-1.2b1.tar.gz

cd ganeti-1.2b1

./configure --localstatedir=/var

make

make install

mkdir /srv/ganeti/ /srv/ganeti/os /srv/ganeti/export

        </screen>

      <para>

        You also need to copy the file

        <filename>docs/examples/ganeti.initd</filename>

        from the source archive to

        <filename>/etc/init.d/ganeti</filename> and register it with

        your distribution's startup scripts, for example in Debian:

      </para>

      <screen>update-rc.d ganeti defaults 20 80</screen>

      <para>

        In order to automatically restart failed instances, you need

        to setup a cron job run the

        <computeroutput>ganeti-watcher</computeroutput> program. A

        sample cron file is provided in the source at

        <filename>docs/examples/ganeti.cron</filename> and you can

        copy that (eventually altering the path) to

        <filename>/etc/cron.d/ganeti</filename>

      </para>

    </sect2>

    <sect2>

      <title>Installing the Operating System support packages</title>

      <para><emphasis role="strong">Mandatory</emphasis> on all nodes.</para>

      <para>

        To be able to install instances you need to have an Operating

        System installation script. An example for Debian Etch 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:

      </para>

      <screen>

cd /srv/ganeti/os

tar xvf instance-debian-etch-0.1.tar

mv instance-debian-etch-0.1 debian-etch

      </screen>

      <para>

        In order to use this OS definition, you need to have internet

        access from your nodes and have <citerefentry>

        <refentrytitle>debootstrap</refentrytitle>

        <manvolnum>8</manvolnum> </citerefentry> installed on all the

        nodes.

      </para>

      <formalpara>

        <title>Debian</title>

        <para>

          Use this command on all nodes to install

          <computeroutput>debootstrap</computeroutput>:

          <screen>apt-get install debootstrap</screen>

        </para>

      </formalpara>

      <para>

        Alternatively, you can create your own OS definitions. See the

        manpage

        <citerefentry>

        <refentrytitle>ganeti-os-interface</refentrytitle>

        <manvolnum>8</manvolnum>

        </citerefentry>.

      </para>

    </sect2>

    <sect2>

      <title>Initializing the cluster</title>

      <para><emphasis role="strong">Mandatory:</emphasis> only on one

      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>

      <screen>

gnt-cluster init <replaceable>CLUSTERNAME</replaceable>

      </screen>

      <para>

        The <replaceable>CLUSTERNAME</replaceable> is a hostname,

        which must be resolvable (e.g. it must exist in DNS or in

        <filename>/etc/hosts</filename>) by all the nodes in the

        cluster. You must choose a name different from any of the

        nodes names for a multi-node cluster. In general the best

        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.

      </para>

      <para>

        If the bridge name you are using is not

        <literal>xen-br0</literal>, use the <option>-b

        <replaceable>BRIDGENAME</replaceable></option> option to

        specify the bridge name. In this case, you should also use the

        <option>--master-netdev

        <replaceable>BRIDGENAME</replaceable></option> option with the

        same <replaceable>BRIDGENAME</replaceable> argument.

      </para>

      <para>

        You can use a different name than <literal>xenvg</literal> for

        the volume group (but note that the name must be identical on

        all nodes). In this case you need to specify it by passing the

        <option>-g <replaceable>VGNAME</replaceable></option> option

        to <computeroutput>gnt-cluster init</computeroutput>.

      </para>

      <para>

        You can also invoke the command with the

        <option>--help</option> option in order to see all the

        possibilities.

      </para>

    </sect2>

    <sect2>

      <title>Joining the nodes to the cluster</title>

      <para>

        <emphasis role="strong">Mandatory:</emphasis> for all the

        other nodes.

      </para>

      <para>

        After you have initialized your cluster you need to join the

        other nodes to it. You can do so by executing the following

        command on the master node:

      </para>

        <screen>

gnt-node add <replaceable>NODENAME</replaceable>

        </screen>

    </sect2>

    <sect2>

      <title>Separate replication network</title>

      <para><emphasis role="strong">Optional</emphasis></para>

      <para>

        Ganeti uses DRBD to mirror the disk of the virtual instances

        between nodes. To use a dedicated network interface for this

        (in order to improve performance or to enhance security) you

        need to configure an additional interface for each node.  Use

        the <option>-s</option> option with

        <computeroutput>gnt-cluster init</computeroutput> and

        <computeroutput>gnt-node add</computeroutput> to specify the

        IP address of this secondary inteface to use for each

        node. Note that if you specified this option at cluster setup

        time, you must afterwards use it for every node add operation.

      </para>

    </sect2>

    <sect2>

      <title>Testing the setup</title>

      <para>

        Execute the <computeroutput>gnt-node list</computeroutput>

        command to see all nodes in the cluster:

      <screen>

# gnt-node list

Node              DTotal  DFree MTotal MNode MFree Pinst Sinst

node1.example.com 197404 197404   2047  1896   125     0     0

      </screen>

    </para>

  </sect2>

  <sect1>

    <title>Setting up and managing virtual instances</title>

    <sect2>

      <title>Setting up virtual instances</title>

      <para>

        This step shows how to setup a virtual instance with either

        non-mirrored disks (<computeroutput>plain</computeroutput>) or

        with network mirrored disks

        (<computeroutput>remote_raid1</computeroutput>).  All commands

        need to be executed on the Ganeti master node (the one on

        which <computeroutput>gnt-cluster init</computeroutput> was

        run).  Verify that the OS scripts are present on all cluster

        nodes with <computeroutput>gnt-os list</computeroutput>.

      </para>

      <para>

        To create a virtual instance, you need a hostname which is

        resolvable (DNS or <filename>/etc/hosts</filename> on all

        nodes). The following command will create a non-mirrored

        instance for you:

      </para>

      <screen>

gnt-instance add --node=node1 -o debian-etch -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.

Instance inst1.example.com's disks are in sync.

creating os for instance inst1.example.com on node node1.example.com

* running the instance OS create scripts...

      </screen>

      <para>

        The above instance will have no network interface enabled.

        You can access it over the virtual console with

        <computeroutput>gnt-instance console

        <literal>inst1</literal></computeroutput>. There is no

        password for root.  As this is a Debian instance, you can

        modifiy the <filename>/etc/network/interfaces</filename> file

        to setup the network interface (<literal>eth0</literal> is the

        name of the interface provided to the instance).

      </para>

      <para>

        To create a network mirrored instance, change the argument to

        the <option>-t</option> option from <literal>plain</literal>

        to <literal>remote_raid1</literal> and specify the node on

        which the mirror should reside with the

        <option>--secondary-node</option> option, like this:

      </para>

      <screen>

# gnt-instance add -t remote_raid1 --secondary-node node1 \

  -n node2 -o debian-etch instance2

* creating instance disks...

adding instance instance2 to cluster config

Waiting for instance instance1 to sync disks.

- device sdb:  3.50% done, 304 estimated seconds remaining

- device sdb: 21.70% done, 270 estimated seconds remaining

- device sdb: 39.80% done, 247 estimated seconds remaining

- device sdb: 58.10% done, 121 estimated seconds remaining

- device sdb: 76.30% done, 72 estimated seconds remaining

- device sdb: 94.80% done, 18 estimated seconds remaining

Instance instance2's disks are in sync.

creating os for instance instance2 on node node2.example.com

* running the instance OS create scripts...

* starting instance...

      </screen>

    </sect2>

    <sect2>

      <title>Managing virtual instances</title>

      <para>

        All commands need to be executed on the Ganeti master node

      </para>

      <para>

        To access the console of an instance, use

        <computeroutput>gnt-instance console

        <replaceable>INSTANCENAME</replaceable></computeroutput>.

      </para>

      <para>

        To shutdown an instance, use <computeroutput>gnt-instance

        shutdown

        <replaceable>INSTANCENAME</replaceable></computeroutput>. To

        startup an instance, use <computeroutput>gnt-instance startup

        <replaceable>INSTANCENAME</replaceable></computeroutput>.

      </para>

      <para>

        To failover an instance to its secondary node (only possible

        in <literal>remote_raid1</literal> setup), use

        <computeroutput>gnt-instance failover

        <replaceable>INSTANCENAME</replaceable></computeroutput>.

      </para>

      <para>

        For more instance and cluster administration details, see the

        <emphasis>Ganeti administrator's guide</emphasis>.

      </para>

    </sect2>

  </sect1>

  </article>