code.grnet.gr Git - ganeti-local/blob - man/ganeti.sgml

   1 <!doctype refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [
   2
   3   <!-- Fill in your name for FIRSTNAME and SURNAME. -->
   4   <!-- Please adjust the date whenever revising the manpage. -->
   5   <!ENTITY dhdate      "<date>June 08, 2010</date>">
   6   <!-- SECTION should be 1-8, maybe w/ subsection other parameters are
   7        allowed: see man(7), man(1). -->
   8   <!ENTITY dhsection   "<manvolnum>7</manvolnum>">
   9   <!ENTITY dhucpackage "<refentrytitle>ganeti</refentrytitle>">
  10   <!ENTITY dhpackage   "ganeti">
  11
  12   <!ENTITY debian      "<productname>Debian</productname>">
  13   <!ENTITY gnu         "<acronym>GNU</acronym>">
  14   <!ENTITY gpl         "&gnu; <acronym>GPL</acronym>">
  15   <!ENTITY footer SYSTEM "footer.sgml">
  16 ]>
  17
  18 <refentry>
  19   <refentryinfo>
  20     <copyright>
  21       <year>2006</year>
  22       <year>2007</year>
  23       <year>2008</year>
  24       <year>2009</year>
  25       <year>2010</year>
  26       <holder>Google Inc.</holder>
  27     </copyright>
  28     &dhdate;
  29   </refentryinfo>
  30   <refmeta>
  31     &dhucpackage;
  32
  33     &dhsection;
  34     <refmiscinfo>Ganeti 2.2</refmiscinfo>
  35   </refmeta>
  36   <refnamediv>
  37     <refname>&dhpackage;</refname>
  38
  39     <refpurpose>cluster-based virtualization management</refpurpose>
  40
  41   </refnamediv>
  42   <refsynopsisdiv>
  43     <screen>
  44 # gnt-cluster init cluster1.example.com
  45 # gnt-node add node2.example.com
  46 # gnt-instance add -n node2.example.com \
  47 &gt; -o debootstrap --disk 0:size=30g \
  48 &gt; -t plain instance1.example.com
  49     </screen>
  50   </refsynopsisdiv>
  51   <refsect1>
  52     <title>DESCRIPTION</title>
  53
  54     <para>
  55       The Ganeti software manages physical nodes and virtual instances
  56       of a cluster based on a virtualization software. The current
  57       version (2.2) supports Xen 3.x and KVM (72 or above) as hypervisors.
  58     </para>
  59
  60   </refsect1>
  61   <refsect1>
  62     <title>Quick start</title>
  63
  64     <para>
  65       First you must install the software on all the cluster nodes,
  66       either from sources or (if available) from a package. The next
  67       step is to create the initial cluster configuration, using
  68       <userinput>gnt-cluster init</userinput>.
  69     </para>
  70
  71     <para>
  72       Then you can add other nodes, or start creating instances.
  73     </para>
  74
  75   </refsect1>
  76
  77   <refsect1>
  78     <title>Cluster architecture</title>
  79
  80     <para>
  81       In Ganeti 2.0, the architecture of the cluster is a little more
  82       complicated than in 1.2. The cluster is coordinated by a master
  83       daemon (<citerefentry>
  84       <refentrytitle>ganeti-masterd</refentrytitle>
  85       <manvolnum>8</manvolnum> </citerefentry>), running on the master
  86       node. Each node runs (as before) a node daemon, and the master
  87       has the <acronym>RAPI</acronym> daemon running too.
  88     </para>
  89
  90     <refsect2>
  91       <title>Node roles</title>
  92
  93       <para>Each node can be in one of the following states:
  94         <variablelist>
  95           <varlistentry>
  96             <term>master</term>
  97             <listitem>
  98               <para>
  99                 Only one node per cluster can be in this role, and
 100                 this node is the one holding the authoritative copy of
 101                 the cluster configuration and the one that can
 102                 actually execute commands on the cluster and modify
 103                 the cluster state. See more details under
 104                 <emphasis>Cluster configuration</emphasis>.
 105               </para>
 106             </listitem>
 107           </varlistentry>
 108           <varlistentry>
 109             <term>master_candidate</term>
 110             <listitem>
 111               <para>The node receives the full cluster configuration
 112               (configuration file and jobs) and can become a master
 113               via the <command>gnt-cluster master-failover</command>
 114               command. Nodes that are not in this state cannot
 115               transition into the master role due to missing
 116               state.</para>
 117             </listitem>
 118           </varlistentry>
 119           <varlistentry>
 120             <term>regular</term>
 121             <listitem>
 122               <para>This the normal state of a node.</para>
 123             </listitem>
 124           </varlistentry>
 125           <varlistentry>
 126             <term>drained</term>
 127             <listitem>
 128               <para>Nodes in this state are functioning normally but
 129               cannot receive new instance, because the intention is to
 130               set them to <emphasis>offline</emphasis> or remove them
 131               from the cluster.</para>
 132             </listitem>
 133           </varlistentry>
 134           <varlistentry>
 135             <term>offline</term>
 136             <listitem>
 137               <para>These nodes are still recorded in the Ganeti
 138               configuration, but except for the master daemon startup
 139               voting procedure, they are not actually contacted by the
 140               master. This state was added in order to allow broken
 141               machines (that are being repaired) to remain in the
 142               cluster but without creating problems.</para>
 143             </listitem>
 144           </varlistentry>
 145         </variablelist>
 146       </para>
 147     </refsect2>
 148
 149     <refsect2>
 150       <title>Node flags</title>
 151
 152       <para>Nodes have two flags which govern which roles they can take:
 153         <variablelist>
 154           <varlistentry>
 155             <term>master_capable</term>
 156             <listitem>
 157               <para>
 158                 The node can become a master candidate, and
 159                 furthermore the master node. When this flag is
 160                 disabled, the node cannot become a candidate; this can
 161                 be useful for special networking cases, or less
 162                 reliable hardware.
 163               </para>
 164             </listitem>
 165           </varlistentry>
 166           <varlistentry>
 167             <term>vm_capable</term>
 168             <listitem>
 169               <para>
 170                 The node can host instances. When enabled (the default
 171                 state), the node will participate in instance
 172                 allocation, capacity calculation, etc. When disabled,
 173                 the node will be skipped in many cluster checks and
 174                 operations.
 175               </para>
 176             </listitem>
 177           </varlistentry>
 178         </variablelist>
 179       </para>
 180     </refsect2>
 181
 182     <refsect2>
 183       <title>Cluster configuration</title>
 184
 185       <para>The master node keeps and is responsible for the cluster
 186       configuration. On the filesystem, this is stored under the
 187       <filename
 188       class="directory">@LOCALSTATEDIR@/ganeti/lib</filename>
 189       directory, and if the master daemon is stopped it can be backed
 190       up normally.</para>
 191
 192       <para>The master daemon will replicate the configuration
 193       database called <filename>config.data</filename> and the job
 194       files to all the nodes in the master candidate role. It will
 195       also distribute a copy of some configuration values via the
 196       <emphasis>ssconf</emphasis> files, which are stored in the same
 197       directory and start with <filename>ssconf_</filename> prefix, to
 198       all nodes.</para>
 199
 200     </refsect2>
 201
 202     <refsect2>
 203       <title>Jobs</title>
 204
 205       <para>
 206         All cluster modification are done via jobs. A job consists of
 207         one or more opcodes, and the list of opcodes is processed
 208         serially. If an opcode fails, the entire job is failed and
 209         later opcodes are no longer processed. A job can be in one of
 210         the following states:
 211         <variablelist>
 212           <varlistentry>
 213             <term>queued</term>
 214             <listitem>
 215               <simpara>The job has been submitted but not yet
 216               processed by the master daemon.</simpara>
 217             </listitem>
 218           </varlistentry>
 219           <varlistentry>
 220             <term>waiting</term>
 221             <listitem>
 222               <simpara>The job is waiting for for locks before the
 223               first of its opcodes.</simpara>
 224             </listitem>
 225           </varlistentry>
 226           <varlistentry>
 227             <term>canceling</term>
 228             <listitem>
 229               <para>The job is waiting for locks, but is has been
 230               marked for cancellation. It will not transition to
 231               <emphasis>running</emphasis>, but to
 232               <emphasis>canceled</emphasis>.
 233               </para>
 234             </listitem>
 235           </varlistentry>
 236           <varlistentry>
 237             <term>running</term>
 238             <listitem>
 239               <simpara>The job is currently being executed.</simpara>
 240             </listitem>
 241           </varlistentry>
 242           <varlistentry>
 243             <term>canceled</term>
 244             <listitem>
 245               <para>The job has been canceled before starting
 246               execution.</para>
 247             </listitem>
 248           </varlistentry>
 249           <varlistentry>
 250             <term>success</term>
 251             <listitem>
 252               <para>The job has finished successfully.</para>
 253             </listitem>
 254           </varlistentry>
 255           <varlistentry>
 256             <term>error</term>
 257             <listitem>
 258               <para>The job has failed during runtime, or the master
 259               daemon has been stopped during the job execution.</para>
 260             </listitem>
 261           </varlistentry>
 262         </variablelist>
 263       </para>
 264     </refsect2>
 265   </refsect1>
 266
 267   <refsect1>
 268     <title>Common options</title>
 269
 270     <para>
 271       Many Ganeti commands provide the following options. The availability for
 272       a certain command can be checked by calling the command using the
 273       <option>--help</option> option.
 274     </para>
 275
 276     <cmdsynopsis>
 277       <command>gnt-<replaceable>...</replaceable> <replaceable>command</replaceable></command>
 278       <arg>--dry-run</arg>
 279       <arg>--priority <group choice="req">
 280         <arg>low</arg>
 281         <arg>normal</arg>
 282         <arg>high</arg>
 283       </group></arg>
 284     </cmdsynopsis>
 285
 286     <para>
 287       The <option>--dry-run</option> option can be used to check whether an
 288       operation would succeed.
 289     </para>
 290
 291     <para>
 292       The option <option>--priority</option> sets the priority for opcodes
 293       submitted by the command.
 294     </para>
 295
 296   </refsect1>
 297
 298   &footer;
 299
 300 </refentry>
 301
 302 <!-- Keep this comment at the end of the file
 303 Local variables:
 304 mode: sgml
 305 sgml-omittag:t
 306 sgml-shorttag:t
 307 sgml-minimize-attributes:nil
 308 sgml-always-quote-attributes:t
 309 sgml-indent-step:2
 310 sgml-indent-data:t
 311 sgml-parent-document:nil
 312 sgml-default-dtd-file:nil
 313 sgml-exposed-tags:nil
 314 sgml-local-catalogs:nil
 315 sgml-local-ecat-files:nil
 316 End:
 317 -->