Commit 95b92c34 authored by Constantinos Venetsanopoulos's avatar Constantinos Venetsanopoulos Committed by Iustin Pop
Browse files

Add ExtStorage related man pages



 * ganeti-extstorage-interface man page
 * gnt-storage man page
Signed-off-by: default avatarConstantinos Venetsanopoulos <cven@grnet.gr>
Signed-off-by: default avatarIustin Pop <iustin@google.com>
Reviewed-by: default avatarIustin Pop <iustin@google.com>
parent b954f097
......@@ -110,6 +110,7 @@
/scripts/gnt-node
/scripts/gnt-os
/scripts/gnt-network
/scripts/gnt-storage
# htools-specific rules
/htools/apidoc
......
......@@ -838,6 +838,7 @@ man_MANS = \
man/ganeti-masterd.8 \
man/ganeti-noded.8 \
man/ganeti-os-interface.7 \
man/ganeti-extstorage-interface.7 \
man/ganeti-rapi.8 \
man/ganeti-watcher.8 \
man/ganeti.7 \
......@@ -850,6 +851,7 @@ man_MANS = \
man/gnt-job.8 \
man/gnt-node.8 \
man/gnt-os.8 \
man/gnt-storage.8 \
man/hail.1 \
man/hbal.1 \
man/hcheck.1 \
......
......@@ -9,14 +9,15 @@ SEE ALSO
--------
Ganeti overview and specifications: **ganeti**(7) (general overview),
**ganeti-os-interface**(7) (guest OS definitions).
**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-group**(8) (node group commands),
**gnt-backup**(8) (instance import/export commands), **gnt-debug**(8)
(debug commands).
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
......
ganeti-extstorage-interface(7) Ganeti | Version @GANETI_VERSION@
================================================================
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 seven required files: *create*, *attach*, *detach*, *remove*,
*grow*, *verify* (executables) and *parameters.list* (text file).
Common environment
~~~~~~~~~~~~~~~~~~
All commands will get their input via environment variables. A common
set of variables will be exported for all commands, and some of them
might have extra ones. 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
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``.
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.
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.
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.
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" ...
NOTES
-----
Backwards compatibility
~~~~~~~~~~~~~~~~~~~~~~~
The ExtStorage Interface was introduced in Ganeti 2.6.
Ganeti 2.6 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``.
.. vim: set textwidth=72 :
.. Local Variables:
.. mode: rst
.. fill-column: 72
.. End:
gnt-storage(8) Ganeti | Version @GANETI_VERSION@
================================================
Name
----
gnt-storage - Ganeti storage administration
Synopsis
--------
**gnt-storage** {command} [arguments...]
DESCRIPTION
-----------
The **gnt-storage** is used for managing the available storage inside
the Ganeti cluster. At the moment, it manages only external storage
(ExtStorage).
COMMANDS
--------
**diagnose**
This command provides detailed information about the state of all
ExtStorage providers available in the Ganeti cluster. The state of each
provider is calculated per nodegroup. This means that a provider may be
valid (meaning usable) for some nodegroups, and invalid (not usable) for
some others. This command will help you see why an installed ExtStorage
provider is not valid for a specific nodegroup. It could be that it is
missing from a node, or is only partially installed. This command will
show the details of all ExtStorage providers and the reasons they are or
aren't valid for every nodegroup in the cluster.
**info**
This command will list detailed information about each ExtStorage
provider found in the cluster, including its nodegroup validity, the
supported parameters (if any) and their documentations, etc.
For each ExtStorage provider only the valid nodegroups will be listed.
If run with no arguments, it will display info for all ExtStorage
providers found in the cluster. If given ExtStorage provider's names as
arguments it will list info only for providers given.
NOTES
-----
In the future **gnt-storage** can be extended to also handle internal
storage (such as lvm, drbd, etc) and also provide diagnostics for them
too.
It can also be extended to handle internal and external storage pools,
if/when this kind of abstraction is implemented to Ganeti.
.. vim: set textwidth=72 :
.. Local Variables:
.. mode: rst
.. fill-column: 72
.. End:
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