code.grnet.gr Git - ganeti-local/blob - doc/move-instance.rst

   1 =================================
   2 Moving instances between clusters
   3 =================================
   4
   5 Starting with Ganeti 2.2, instances can be moved between separate Ganeti
   6 clusters using a new tool, ``move-instance``. The tool has a number of
   7 features:
   8
   9 - Moving a single or multiple instances
  10 - Moving instances in parallel (``--parallel`` option)
  11 - Renaming instance (only when moving a single instance)
  12 - SSL certificate verification for RAPI connections
  13
  14 The design of the inter-cluster instances moves is described in detail
  15 in the :doc:`Ganeti 2.2 design document <design-2.2>`. The instance move
  16 tool talks to the Ganeti clusters via RAPI and can run on any machine
  17 which can connect to the cluster's RAPI. Despite their similar name, the
  18 instance move tool should not be confused with the ``gnt-instance move``
  19 command, which is used to move without changes (instead of export/import
  20 plus rename) an instance within the cluster.
  21
  22
  23 Configuring clusters for instance moves
  24 ---------------------------------------
  25
  26 To prevent third parties from accessing the instance data, all data
  27 exchanged between the clusters is signed using a secret key, the
  28 "cluster domain secret". It is recommended to assign the same domain
  29 secret to all clusters of the same security domain, so that instances
  30 can be easily moved between them. By checking the signatures, the
  31 destination cluster can be sure the third party (e.g. this tool) didn't
  32 modify the received crypto keys and connection information.
  33
  34 .. highlight:: shell-example
  35
  36 To create a new, random cluster domain secret, run the following command
  37 on the master node::
  38
  39   $ gnt-cluster renew-crypto --new-cluster-domain-secret
  40
  41
  42 To read and set the cluster domain secret from the contents of a file,
  43 run the following command on the master node::
  44
  45   $ gnt-cluster renew-crypto --cluster-domain-secret=%/.../ganeti.cds%
  46
  47 More information about the ``renew-crypto`` command can be found in
  48 :manpage:`gnt-cluster(8)`.
  49
  50
  51 Moving instances
  52 ----------------
  53
  54 As soon as the clusters share a cluster domain secret, instances can be
  55 moved. The tool usage is as follows::
  56
  57   $ move-instance %[options]% %source-cluster% %destination-cluster% %instance-name...%
  58
  59 Multiple instances can be moved with one invocation of the instance move
  60 tool, though a few options are only available when moving a single
  61 instance.
  62
  63 The most important options are listed below. Unless specified otherwise,
  64 destination-related options default to the source value (e.g. setting
  65 ``--src-rapi-port=1234`` will make ``--dest-rapi-port``'s default 1234).
  66
  67 ``--src-rapi-port``/``--dest-rapi-port``
  68   RAPI server TCP port, defaults to 5080.
  69 ``--src-ca-file``/``--dest-ca-file``
  70   Path to file containing source cluster Certificate Authority (CA) in
  71   PEM format. For self-signed certificates, this is the certificate
  72   itself (see more details below in
  73   :ref:`instance-move-certificates`). For certificates signed by a third
  74   party CA, the complete chain must be in the file (see documentation
  75   for :manpage:`SSL_CTX_load_verify_locations(3)`).
  76 ``--src-username``/``--dest-username``
  77   RAPI username, must have write access to cluster.
  78 ``--src-password-file``/``--dest-password-file``
  79   Path to file containing RAPI password (make sure to restrict access to
  80   this file).
  81 ``--dest-instance-name``
  82   When moving a single instance: Change name of instance on destination
  83   cluster.
  84 ``--dest-primary-node``
  85   When moving a single instance: Primary node on destination cluster.
  86 ``--dest-secondary-node``
  87   When moving a single instance: Secondary node on destination cluster.
  88 ``--iallocator``
  89   Iallocator for creating instance on destination cluster.
  90 ``--hypervisor-parameters``/``--backend-parameters``/``--os-parameters``/``--net``
  91   When moving a single instance: Override instances' parameters.
  92 ``--parallel``
  93   Number of instance moves to run in parallel.
  94 ``--verbose``/``--debug``
  95   Increase output verbosity.
  96
  97 The exit value of the tool is zero if and only if all instance moves
  98 were successful.
  99
 100 .. _instance-move-certificates:
 101
 102 Certificates
 103 ------------
 104
 105 If using certificates signed by a CA, then you need to pass the same CA
 106 certificate via both ``--src-ca-file`` and ``dest-ca-file``.
 107
 108 However, if you're using self-signed certificates, this has a few
 109 (security) implications:
 110
 111 - the certificates of both the source and destinations clusters
 112   (``rapi.pem`` from the Ganeti configuration directory, usually
 113   ``/var/lib/ganeti/rapi.pem``) must be available to the tool
 114 - by default, the certificates include the private key as well, so
 115   simply copying them to a third machine means that machine can now
 116   impersonate both the source and destination clusters RAPI endpoint
 117
 118 It is therefore recommended to copy only the certificate from the
 119 ``rapi.pem`` files, and pass these to ``--src-ca-file`` and
 120 ``--dest-ca-file`` appropriately.
 121
 122 .. vim: set textwidth=72 :
 123 .. Local Variables:
 124 .. mode: rst
 125 .. fill-column: 72
 126 .. End: