--------
**hspace** {backend options...} [algorithm options...] [request options...]
-[ -p [*fields*] ] [-v... | -q]
+[output options...] [-v... | -q]
**hspace** --version
**[--vcpus** *vcpus* **]**
**[--tiered-alloc** *spec* **]**
+Output options:
+
+**[--machine-readable**[=*CHOICE*] **]**
+**[-p**[*fields*]**]**
+
DESCRIPTION
-----------
allocation. It uses the exact same allocation algorithm as the hail
iallocator plugin in *allocate* mode.
-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).
+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 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
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).
+ The memory size of the instances to be placed (defaults to
+ 4GiB). Units can be used (see below for more details).
--disk *disk*
- The disk size of the instances to be placed (defaults to 100GiB).
+ The disk size of the instances to be placed (defaults to
+ 100GiB). Units can be used.
--disk-template *template*
The disk template for the instance; one of the Ganeti disk templates
The number of VCPUs of the instances to be placed (defaults to 1).
--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
+-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.
- scnt
- number of secondary instances
-
- 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.
+ 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).
--tiered-alloc *spec*
Besides the standard, fixed-size allocation, also do a tiered
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
+ - 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
+ An example description would be *100G,4g,2* describing an initial
+ starting specification of 100GB of disk space, 4GiB of memory and 2
VCPUs.
Also note that the normal allocation and the tiered allocation are
the instance count for these two modes are not related one to
another.
+--machines-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
-----------
projects / ganeti-local / blobdiff