-HSPACE(1) htools | Ganeti H-tools
-=================================
+HSPACE(1) Ganeti | Version @GANETI_VERSION@
+===========================================
NAME
----
--------
**hspace** {backend options...} [algorithm options...] [request options...]
-[ -p [*fields*] ] [-v... | -q]
+[output options...] [-v... | -q]
**hspace** --version
Request options:
-**[--memory** *mem* **]**
-**[--disk** *disk* **]**
-**[--req-nodes** *req-nodes* **]**
-**[--vcpus** *vcpus* **]**
-**[--tiered-alloc** *spec* **]**
+**[--disk-template** *template* **]**
+
+**[--standard-alloc** *disk,ram,cpu* **]**
+
+**[--tiered-alloc** *disk,ram,cpu* **]**
+
+Output options:
+
+**[--machine-readable**[=*CHOICE*] **]**
+**[-p**[*fields*]**]**
DESCRIPTION
-----------
-
hspace computes how many additional instances can be fit on a cluster,
while maintaining N+1 status.
The program will try to place instances, all of the same size, on the
cluster, until the point where we don't have any N+1 possible
allocation. It uses the exact same allocation algorithm as the hail
-iallocator plugin.
+iallocator plugin in *allocate* mode.
+
+The output of the program is designed either for human consumption (the
+default) or, when enabled with the ``--machine-readable`` option
+(described further below), for machine consumption. In the latter case,
+it is intended to interpreted as a shell fragment (or parsed as a
+*key=value* file). Options which extend the output (e.g. -p, -v) will
+output the additional information on stderr (such that the stdout is
+still parseable).
-The output of the program is designed to interpreted as a shell
-fragment (or parsed as a *key=value* file). Options which extend the
-output (e.g. -p, -v) will output the additional information on stderr
-(such that the stdout is still parseable).
+By default, the instance specifications will be read from the cluster;
+the options ``--standard-alloc`` and ``--tiered-alloc`` can be used to
+override them.
-The following keys are available in the output of the script (all
-prefixed with *HTS_*):
+The following keys are available in the machine-readable output of the
+script (all prefixed with *HTS_*):
-SPEC_MEM, SPEC_DSK, SPEC_CPU, SPEC_RQN
+SPEC_MEM, SPEC_DSK, SPEC_CPU, SPEC_RQN, SPEC_DISK_TEMPLATE
These represent the specifications of the instance model used for
- allocation (the memory, disk, cpu, requested nodes).
+ allocation (the memory, disk, cpu, requested nodes, disk template).
+
+TSPEC_INI_MEM, TSPEC_INI_DSK, TSPEC_INI_CPU, ...
+ Only defined when the tiered mode allocation is enabled, these are
+ similar to the above specifications but show the initial starting spec
+ for tiered allocation.
CLUSTER_MEM, CLUSTER_DSK, CLUSTER_CPU, CLUSTER_NODES
These represent the total memory, disk, CPU count and total nodes in
Like the above but for disk.
TSPEC
- If the tiered allocation mode has been enabled, this parameter holds
- the pairs of specifications and counts of instances that can be
- created in this mode. The value of the key is a space-separated list
- of values; each value is of the form *memory,disk,vcpu=count* where
- the memory, disk and vcpu are the values for the current spec, and
- count is how many instances of this spec can be created. A complete
- value for this variable could be: **4096,102400,2=225
- 2560,102400,2=20 512,102400,2=21**.
+ This parameter holds the pairs of specifications and counts of
+ instances that can be created in the *tiered allocation* mode. The
+ value of the key is a space-separated list of values; each value is of
+ the form *memory,disk,vcpu=count* where the memory, disk and vcpu are
+ the values for the current spec, and count is how many instances of
+ this spec can be created. A complete value for this variable could be:
+ **4096,102400,2=225 2560,102400,2=20 512,102400,2=21**.
KM_USED_CPU, KM_USED_NPU, KM_USED_MEM, KM_USED_DSK
These represents the metrics of used resources at the start of the
that the computation failed and any values present should not be
relied upon.
-If the tiered allocation mode is enabled, then many of the INI_/FIN_
-metrics will be also displayed with a TRL_ prefix, and denote the
-cluster status at the end of the tiered allocation run.
+Many of the INI_/FIN_ metrics will be also displayed with a TRL_ prefix,
+and denote the cluster status at the end of the tiered allocation run.
+
+The human output format should be self-explanatory, so it is not
+described further.
OPTIONS
-------
The options that can be passed to the program are as follows:
---memory *mem*
- The memory size of the instances to be placed (defaults to 4GiB).
-
---disk *disk*
- The disk size of the instances to be placed (defaults to 100GiB).
-
---req-nodes *num-nodes*
- The number of nodes for the instances; the default of two means
- mirrored instances, while passing one means plain type instances.
-
---vcpus *vcpus*
- The number of VCPUs of the instances to be placed (defaults to 1).
+--disk-template *template*
+ Overrides the disk template for the instance read from the cluster;
+ one of the Ganeti disk templates (e.g. plain, drbd, so on) should be
+ passed in.
--max-cpu=*cpu-ratio*
- The maximum virtual to physical cpu ratio, as a floating point
- number between zero and one. For example, specifying *cpu-ratio* as
- **2.5** means that, for a 4-cpu machine, a maximum of 10 virtual
- cpus should be allowed to be in use for primary instances. A value
- of one doesn't make sense though, as that means no disk space can be
- used on it.
+ The maximum virtual to physical cpu ratio, as a floating point number
+ greater than or equal to one. For example, specifying *cpu-ratio* as
+ **2.5** means that, for a 4-cpu machine, a maximum of 10 virtual cpus
+ should be allowed to be in use for primary instances. A value of
+ exactly one means there will be no over-subscription of CPU (except
+ for the CPU time used by the node itself), and values below one do not
+ make sense, as that means other resources (e.g. disk) won't be fully
+ utilised due to CPU restrictions.
--min-disk=*disk-ratio*
The minimum amount of free disk space remaining, as a floating point
number. For example, specifying *disk-ratio* as **0.25** means that
at least one quarter of disk space should be left free on nodes.
--p, --print-nodes
- Prints the before and after node status, in a format designed to
- allow the user to understand the node's most important parameters.
-
- It is possible to customise the listed information by passing a
- comma-separated list of field names to this option (the field list
- is currently undocumented), or to extend the default field list by
- prefixing the additional field list with a plus sign. By default,
- the node list will contain the following information:
-
- F
- a character denoting the status of the node, with '-' meaning an
- offline node, '*' meaning N+1 failure and blank meaning a good
- node
-
- Name
- the node name
-
- t_mem
- the total node memory
-
- n_mem
- the memory used by the node itself
-
- i_mem
- the memory used by instances
-
- x_mem
- amount memory which seems to be in use but cannot be determined
- why or by which instance; usually this means that the hypervisor
- has some overhead or that there are other reporting errors
-
- f_mem
- the free node memory
-
- r_mem
- the reserved node memory, which is the amount of free memory
- needed for N+1 compliance
-
- t_dsk
- total disk
-
- f_dsk
- free disk
-
- pcpu
- the number of physical cpus on the node
-
- vcpu
- the number of virtual cpus allocated to primary instances
-
- pcnt
- number of primary instances
-
- scnt
- number of secondary instances
+-l *rounds*, --max-length=*rounds*
+ Restrict the number of instance allocations to this length. This is
+ not very useful in practice, but can be used for testing hspace
+ itself, or to limit the runtime for very big clusters.
- p_fmem
- percent of free memory
-
- p_fdsk
- percent of free disk
-
- r_cpu
- ratio of virtual to physical cpus
-
- lCpu
- the dynamic CPU load (if the information is available)
-
- lMem
- the dynamic memory load (if the information is available)
-
- lDsk
- the dynamic disk load (if the information is available)
-
- lNet
- the dynamic net load (if the information is available)
+-p, --print-nodes
+ Prints the before and after node status, in a format designed to allow
+ the user to understand the node's most important parameters. See the
+ man page **htools**(1) for more details about this option.
-O *name*
This option (which can be given multiple times) will mark nodes as
are reported by RAPI as such, or that have "?" in file-based input
in any numeric fields.
--t *datafile*, --text-data=*datafile*
- The name of the file holding node and instance information (if not
- collecting via RAPI or LUXI). This or one of the other backends must
- be selected.
-
-S *filename*, --save-cluster=*filename*
If given, the state of the cluster at the end of the allocation is
saved to a file named *filename.alloc*, and if tiered allocation is
enabled, the state after tiered allocation will be saved to
*filename.tiered*. This allows re-feeding the cluster state to
either hspace itself (with different parameters) or for example
- hbal.
+ hbal, via the ``-t`` option.
+
+-t *datafile*, --text-data=*datafile*
+ Backend specification: the name of the file holding node and instance
+ information (if not collecting via RAPI or LUXI). This or one of the
+ other backends must be selected. The option is described in the man
+ page **htools**(1).
-m *cluster*
- Collect data directly from the *cluster* given as an argument via
- RAPI. If the argument doesn't contain a colon (:), then it is
- converted into a fully-built URL via prepending ``https://`` and
- appending the default RAPI port, otherwise it's considered a
- fully-specified URL and is used as-is.
+ Backend specification: collect data directly from the *cluster* given
+ as an argument via RAPI. The option is described in the man page
+ **htools**(1).
-L [*path*]
- Collect data directly from the master daemon, which is to be
- contacted via the luxi (an internal Ganeti protocol). An optional
- *path* argument is interpreted as the path to the unix socket on
- which the master daemon listens; otherwise, the default path used by
- ganeti when installed with *--localstatedir=/var* is used.
+ Backend specification: collect data directly from the master daemon,
+ which is to be contacted via LUXI (an internal Ganeti protocol). The
+ option is described in the man page **htools**(1).
--simulate *description*
- Instead of using actual data, build an empty cluster given a node
- description. The *description* parameter must be a comma-separated
- list of five elements, describing in order:
-
- - the allocation policy for this node group
- - the number of nodes in the cluster
- - the disk size of the nodes, in mebibytes
- - the memory size of the nodes, in mebibytes
- - the cpu core count for the nodes
-
- An example description would be **preferred,B20,102400,16384,4**
- describing a 20-node cluster where each node has 100GiB of disk
- space, 16GiB of memory and 4 CPU cores. Note that all nodes must
- have the same specs currently.
-
- This option can be given multiple times, and each new use defines a
- new node group. Hence different node groups can have different
- allocation policies and node count/specifications.
-
---tiered-alloc *spec*
- Besides the standard, fixed-size allocation, also do a tiered
- allocation scheme where the algorithm starts from the given
- specification and allocates until there is no more space; then it
- decreases the specification and tries the allocation again. The
- decrease is done on the matric that last failed during
- allocation. The specification given is similar to the *--simulate*
- option and it holds:
-
- - the disk size of the instance
- - the memory size of the instance
+ Backend specification: similar to the **-t** option, this allows
+ overriding the cluster data with a simulated cluster. For details
+ about the description, see the man page **htools**(1).
+
+--standard-alloc *disk,ram,cpu*
+ This option overrides the instance size read from the cluster for the
+ *standard* allocation mode, where we simply allocate instances of the
+ same, fixed size until the cluster runs out of space.
+
+ The specification given is similar to the *--simulate* option and it
+ holds:
+
+ - the disk size of the instance (units can be used)
+ - the memory size of the instance (units can be used)
- the vcpu count for the insance
- An example description would be *10240,8192,2* describing an initial
- starting specification of 10GiB of disk space, 4GiB of memory and 2
- VCPUs.
+ An example description would be *100G,4g,2* describing an instance
+ specification of 100GB of disk space, 4GiB of memory and 2 VCPUs.
+
+--tiered-alloc *disk,ram,cpu*
+ This option overrides the instance size for the *tiered* allocation
+ mode. In this mode, the algorithm starts from the given specification
+ and allocates until there is no more space; then it decreases the
+ specification and tries the allocation again. The decrease is done on
+ the metric that last failed during allocation. The argument should
+ have the same format as for ``--standard-alloc``.
Also note that the normal allocation and the tiered allocation are
independent, and both start from the initial cluster state; as such,
the instance count for these two modes are not related one to
another.
+--machine-readable[=*choice*]
+ By default, the output of the program is in "human-readable" format,
+ i.e. text descriptions. By passing this flag you can either enable
+ (``--machine-readable`` or ``--machine-readable=yes``) or explicitly
+ disable (``--machine-readable=no``) the machine readable format
+ described above.
+
-v, --verbose
Increase the output verbosity. Each usage of this option will
increase the verbosity (currently more than 2 doesn't make sense)
-V, --version
Just show the program version and exit.
+UNITS
+~~~~~
+
+By default, all unit-accepting options use mebibytes. Using the
+lower-case letters of *m*, *g* and *t* (or their longer equivalents of
+*mib*, *gib*, *tib*, for which case doesn't matter) explicit binary
+units can be selected. Units in the SI system can be selected using the
+upper-case letters of *M*, *G* and *T* (or their longer equivalents of
+*MB*, *GB*, *TB*, for which case doesn't matter).
+
+More details about the difference between the SI and binary systems can
+be read in the *units(7)* man page.
+
EXIT STATUS
-----------
fit; it just allocates in the best place for the current step, without
taking into consideration the impact on future placements.
-ENVIRONMENT
------------
-
-If the variables **HTOOLS_NODES** and **HTOOLS_INSTANCES** are present
-in the environment, they will override the default names for the nodes
-and instances files. These will have of course no effect when the RAPI
-or Luxi backends are used.
-
-SEE ALSO
---------
-
-**hbal**(1), **hscan**(1), **hail**(1), **ganeti**(7),
-**gnt-instance**(8), **gnt-node**(8)
-
-COPYRIGHT
----------
-
-Copyright (C) 2009, 2010 Google Inc. Permission is granted to copy,
-distribute and/or modify under the terms of the GNU General Public
-License as published by the Free Software Foundation; either version 2
-of the License, or (at your option) any later version.
-
-On Debian systems, the complete text of the GNU General Public License
-can be found in /usr/share/common-licenses/GPL.
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End:
projects / ganeti-local / blobdiff