xenial (7) ganeti-extstorage-interface.7.gz

Provided by: ganeti-2.15_2.15.2-3_all bug

Name
       ganeti-extstorage-interface - Specifications for ExtStorage providers


DESCRIPTION
       The  method  for  supporting external shared storage in Ganeti is to have an ExtStorage provider for each
       external shared storage hardware type.  The ExtStorage provider is a set of files (executable scripts and
       text  files),  contained  inside  a  directory which is named after the provider.  This directory must be
       present across all nodes of a nodegroup (Ganeti doesn't replicate it), in order for the  provider  to  be
       usable  by  Ganeti  for  this  nodegroup  (valid).   The  external shared storage hardware should also be
       accessible by all nodes of this nodegroup too.


REFERENCE
       There are eight required files: create, attach, detach, remove, grow, setinfo, verify, (executables)  and
       parameters.list (text file).

       There are also three optional files: open, close, and snapshot (executables).

   Common environment
       All  commands will get their input via environment variables.  A common set of variables will be exported
       for all commands, and some commands might have extra variables.  Note that all counts are zero-based.

       Since Ganeti version 2.5, the environment will be cleaned up before being passed  to  scripts,  therefore
       they will not inherit the environment in with which the ganeti node daemon was started.  If you depend on
       any environment variables (non-Ganeti), then you will need to define or source them appropriately.

       VOL_NAME
              The name of the volume.  This is unique for Ganeti and it uses it to refer to  a  specific  volume
              inside the external storage.  Its format is UUID.ext.diskX where UUID is produced by Ganeti and is
              unique inside the Ganeti context.  X is the number of the disk count.

       VOL_SIZE
              Available only to the create and grow scripts.  The volume's size in mebibytes.

       VOL_NEW_SIZE
              Available only to the grow script.  It declares  the  new  size  of  the  volume  after  grow  (in
              mebibytes).   To  find  the  amount  of grow, the scipt should calculate the number VOL_NEW_SIZE -
              VOL_SIZE.

       EXTP_name
              Each ExtStorage parameter (see below) will be exported in its own variable, prefixed  with  EXTP_,
              and upper-cased.  For example, a fromsnap parameter will be exported as EXTP_FROMSNAP.

       VOL_METADATA
              Available  only  to  the  setinfo  script.  A string containing metadata to be associated with the
              volume.  Currently, Ganeti sets this value to originstname+X where X is the instance's name.

       VOL_CNAME
              The human-readable name of the Disk config object (optional).

       VOL_UUID
              The uuid of the Disk config object.

       VOL_SNAPSHOT_NAME
              The name of the volume's snapshot.

       VOL_SNAPSHOT_SIZE
              The size of the volume's snapshot.

       VOL_OPEN_EXCLUSIVE
              Whether the volume will be opened for exclusive access or  not.   This  will  be  False  (denoting
              shared access) during migration.


EXECUTABLE SCRIPTS
   create
       The  create  command is used for creating a new volume inside the external storage.  The VOL_NAME denotes
       the volume's name, which should be unique.  After creation, Ganeti will refer to this volume by this name
       for all other actions.

       Ganeti  produces  this name dynamically and ensures its uniqueness inside the Ganeti context.  Therefore,
       you should make sure not to provision manually additional volumes inside the external storage  with  this
       type of name, because this will lead to conflicts and possible loss of data.

       The VOL_SIZE variable denotes the size of the new volume to be created in mebibytes.

       If  the script ends successfully, a new volume of size VOL_SIZE should exist inside the external storage.
       e.g:: a lun inside a NAS appliance.

       The script returns 0 on success.

   attach
       This command is used in order to make an already created volume visible to the physical node  which  will
       host  the  instance.  This is done by mapping the already provisioned volume to a block device inside the
       host node.

       The VOL_NAME variable denotes the volume to be mapped.

       After successful attachment the script returns to its stdout a string, which is  the  full  path  of  the
       block device to which the volume is mapped.  e.g:: /dev/dummy1

       When attach returns, this path should be a valid block device on the host node.

       The  attach  script  should  be  idempotent  if the volume is already mapped.  If the requested volume is
       already mapped, then the script should just return to its stdout the path which is already mapped to.

       In case the storage technology supports userspace access to volumes as well, e.g.   the  QEMU  Hypervisor
       can  see an RBD volume using its embedded driver for the RBD protocol, then the provider can return extra
       lines denoting the available userspace access URIs per hypervisor.  The URI should be  in  the  following
       format:  <hypervisor>:<uri>.  For example, a RADOS provider should return kvm:rbd:<pool>/<volume name> in
       the second line of stdout after the local block device path (e.g.  /dev/rbd1).

       So, if the access disk parameter is userspace for the ext disk template, then the QEMU command  will  end
       up having file=<URI> in the -drive option.

       In  case  the storage technology supports only userspace access to volumes, then the first line of stdout
       should be an empty line, denoting that a local block device is not available.  If neither a block  device
       nor a URI is returned, then Ganeti will complain.

   detach
       This  command  is  used  in  order  to  unmap an already mapped volume from the host node.  Detach undoes
       everything attach did.  This is done by unmapping the requested volume from the block device it is mapped
       to.

       The VOL_NAME variable denotes the volume to be unmapped.

       detach  doesn't affect the volume itself.  It just unmaps it from the host node.  The volume continues to
       exist inside the external storage.  It's just not accessible by the node anymore.   This  script  doesn't
       return anything to its stdout.

       The  detach  script should be idempotent if the volume is already unmapped.  If the volume is not mapped,
       the script doesn't perform any action at all.

       The script returns 0 on success.

   remove
       This command is used to remove an existing volume from the external storage.  The volume  is  permanently
       removed from inside the external storage along with all its data.

       The VOL_NAME variable denotes the volume to be removed.

       The script returns 0 on success.

   grow
       This command is used to grow an existing volume of the external storage.

       The VOL_NAME variable denotes the volume to grow.

       The  VOL_SIZE  variable  denotes  the  current  volume's  size (in mebibytes).  The VOL_NEW_SIZE variable
       denotes the final size after the volume has been grown (in mebibytes).

       The amount of grow can be easily calculated by the scipt and is:

       grow_amount = VOL_NEW_SIZE - VOL_SIZE (in mebibytes)

       Ganeti ensures that: VOL_NEW_SIZE > VOL_SIZE

       If the script returns successfully, then the volume inside the external storage will have a new  size  of
       VOL_NEW_SIZE.   This  isn't immediately reflected to the instance's disk.  See gnt-instance grow for more
       details on when the running instance becomes aware of its grown disk.

       The script returns 0 on success.

   setinfo
       This script is used to add metadata to an existing volume.  It  is  helpful  when  we  need  to  keep  an
       external, Ganeti-independent mapping between instances and volumes; primarily for recovery reasons.  This
       is provider specific and the author of the provider chooses whether/how to implement this.  You can  just
       exit  with  0, if you do not want to implement this feature, without harming the overall functionality of
       the provider.

       The VOL_METADATA variable contains the metadata of the volume.

       Currently, Ganeti sets this value to originstname+X where X is the instance's name.

       The script returns 0 on success.

   verify
       The verify script is used to verify consistency of the external parameters (ext-params) (see below).  The
       command  should  take one or more arguments denoting what checks should be performed, and return a proper
       exit code depending on whether the validation failed or succeeded.

       Currently, the script is not invoked by Ganeti, but should be present for future use and consistency with
       gnt-os-interface's verify script.

       The script should return 0 on success.

   snapshot
       The snapshot script is used to take a snapshot of the given volume.

       The  VOL_SNAPSHOT_NAME  and  VOL_SNAPSHOT_SIZE variables contain the name and size of the snapshot we are
       about to create.

       Currently this operation is  used  only  during  gnt-backup  export  and  Ganeti  sets  those  values  to
       VOL_NAME.snap and VOL_SIZE respectively (see above).

       The script returns 0 on success.

       Please  note  that this script is optional and not all providers should implement it.  Of course if it is
       not present, instance backup export will not be supported for the given provider.

   open
       The open script is used to open the given volume.

       This makes the volume ready for I/O.

       The VOL_OPEN_EXCLUSIVE variable denotes whether the volume will be opened for exclusive  access  or  not.
       It is True by default and False (denoting shared access) during migration.

       The script returns 0 on success.

       Please note that this script is optional and not all providers should implement it.

   close
       The close script is used to close the given volume.

       This disables I/O on the volume.

       The script returns 0 on success.

       Please note that this script is optional and not all providers should implement it.


TEXT FILES
   parameters.list
       This file declares the parameters supported by the ExtStorage provider, one parameter per line, with name
       and description (space and/or tab separated).  For example:

              fromsnap Snapshot name to create the volume from
              nas_ip The IP of the NAS appliance

       The parameters can then be used during instance add as follows:

              # gnt-instance add --disk=0:fromsnap="file_name",nas_ip="1.2.3.4" ...


EXAMPLES
       In the following examples  we  assume  that  you  have  already  installed  successfully  two  ExtStorage
       providers: pvdr1 and pvdr2

       Add a new instance with a 10G first disk provided by pvdr1 and a 20G second disk provided by pvdr2:

              # gnt-instance add -t ext --disk=0:size=10G,provider=pvdr1
                                        --disk=1:size=20G,provider=pvdr2

       Add  a  new  instance  with  a  5G  first  disk  provided  by provider pvdr1 and also pass the prm1, prm2
       parameters to the provider, with the corresponding values val1, val2:

              # gnt-instance add -t ext
                                 --disk=0:size=5G,provider=pvdr1,prm1=val1,prm2=val2

       Modify an existing instance of disk type ext by adding a new 30G disk provided by provider pvdr2:

              # gnt-instance modify --disk 1:add,size=30G,provider=pvdr2 <instance>

       Modify an existing instance of disk type ext by adding 2 new disks, of different providers,  passing  one
       parameter for the first one:

              # gnt-instance modify --disk 2:add,size=3G,provider=pvdr1,prm1=val1
                                    --disk 3:add,size=5G,provider=pvdr2
                                    <instance>


NOTES
   Backwards compatibility
       The  ExtStorage  Interface  was  introduced  in  Ganeti  2.7.   Ganeti  2.7 and up is compatible with the
       ExtStorage Interface.

   Common behaviour
       All the scripts should display an usage message when called with a wrong number of arguments or when  the
       first argument is -h or --help.


REPORTING BUGS
       Report  bugs  to  project  website (http://code.google.com/p/ganeti/) or contact the developers using the
       Ganeti mailing list (ganeti@googlegroups.com).


SEE ALSO
       Ganeti overview and  specifications:  ganeti(7)  (general  overview),  ganeti-os-interface(7)  (guest  OS
       definitions), ganeti-extstorage-interface(7) (external storage providers).

       Ganeti  commands:  gnt-cluster(8) (cluster-wide commands), gnt-job(8) (job-related commands), gnt-node(8)
       (node-related  commands),  gnt-instance(8)  (instance   commands),   gnt-os(8)   (guest   OS   commands),
       gnt-storage(8)   (storage   commands),   gnt-group(8)  (node  group  commands),  gnt-backup(8)  (instance
       import/export commands), gnt-debug(8) (debug commands).

       Ganeti daemons: ganeti-watcher(8) (automatic instance restarter), ganeti-cleaner(8) (job queue  cleaner),
       ganeti-noded(8) (node daemon), ganeti-rapi(8) (remote API daemon).

       Ganeti  htools: htools(1) (generic binary), hbal(1) (cluster balancer), hspace(1) (capacity calculation),
       hail(1) (IAllocator plugin), hscan(1) (data gatherer from remote clusters), hinfo(1) (cluster information
       printer), mon-collector(7) (data collectors interface).


       Copyright (C) 2006-2015 Google Inc.  All rights reserved.

       Redistribution  and  use in source and binary forms, with or without modification, are permitted provided
       that the following conditions are met:

       1.  Redistributions of source code must retain the above copyright notice, this list  of  conditions  and
       the following disclaimer.

       2.  Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
       the following disclaimer in the documentation and/or other materials provided with the distribution.

       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY  EXPRESS  OR  IMPLIED
       WARRANTIES,  INCLUDING,  BUT  NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
       PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE  FOR
       ANY  DIRECT,  INDIRECT,  INCIDENTAL,  SPECIAL,  EXEMPLARY,  OR  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
       LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF  USE,  DATA,  OR  PROFITS;  OR  BUSINESS
       INTERRUPTION)  HOWEVER  CAUSED  AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
       TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE  OF  THIS  SOFTWARE,  EVEN  IF
       ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.