---
name: "hspace"
section: "1"
platform: "linux"
package: "ganeti-htools"
version: "2.5.2-1+deb7u2"
release: "Debian 7 (Wheezy)"
platforms: ["linux"]
url: "https://new.carta.tech/hspace"
---

# hspace(1)

Cluster space analyzer for Ganeti

## NAME

hspace - Cluster space analyzer for Ganeti

## SYNOPSIS

**hspace** {backend options...} \[algorithm options...\] \[request options...\] \[output options...\] \[-v... \| -q\]

**hspace** --version

Backend options:

{ **-m** *cluster* \| **-L\[** *path* **\] \[-X\]** \| **-t** *data-file* \| **--simulate** *spec* }

Algorithm options:

**\[ --max-cpu** *cpu-ratio* **\]** **\[ --min-disk** *disk-ratio* **\]** **\[ -O** *name...* **\]**

*Request options:*

**\[--memory** *mem* **\]** **\[--disk** *disk* **\]** **\[--disk-template** *template* **\]** **\[--vcpus** *vcpus* **\]** **\[--tiered-alloc** *spec* **\]**

*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 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 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\_DISK\_TEMPLATE**

  *These represent the specifications of the instance model used for* *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 the cluster.*

- **INI\_SCORE, FIN\_SCORE**

  *These are the initial (current) and final cluster score (see the* *hbal man page for details about the scoring algorithm).*

- **INI\_INST\_CNT, FIN\_INST\_CNT**

  *The initial and final instance count.*

- **INI\_MEM\_FREE, FIN\_MEM\_FREE**

  *The initial and final total free memory in the cluster (but this* *doesn't necessarily mean available for use).*

- **INI\_MEM\_AVAIL, FIN\_MEM\_AVAIL**

  *The initial and final total available memory for allocation in the* *cluster. If allocating redundant instances, new instances could* *increase the reserved memory so it doesn't necessarily mean the* *entirety of this memory can be used for new instance allocations.*

- **INI\_MEM\_RESVD, FIN\_MEM\_RESVD**

  *The initial and final reserved memory (for redundancy/N+1* *purposes).*

- **INI\_MEM\_INST, FIN\_MEM\_INST**

  *The initial and final memory used for instances (actual runtime* *used RAM).*

- **INI\_MEM\_OVERHEAD, FIN\_MEM\_OVERHEAD**

  *The initial and final memory overhead--memory used for the node* *itself and unacounted memory (e.g. due to hypervisor overhead).*

- **INI\_MEM\_EFF, HTS\_INI\_MEM\_EFF**

  *The initial and final memory efficiency, represented as instance* *memory divided by total memory.*

- **INI\_DSK\_FREE, INI\_DSK\_AVAIL, INI\_DSK\_RESVD, INI\_DSK\_INST, INI\_DSK\_EFF**

  *Initial disk stats, similar to the memory ones.*

- **FIN\_DSK\_FREE, FIN\_DSK\_AVAIL, FIN\_DSK\_RESVD, FIN\_DSK\_INST, FIN\_DSK\_EFF**

  *Final disk stats, similar to the memory ones.*

- **INI\_CPU\_INST, FIN\_CPU\_INST**

  *Initial and final number of virtual CPUs used by instances.*

- **INI\_CPU\_EFF, FIN\_CPU\_EFF**

  *The initial and final CPU efficiency, represented as the count of* *virtual instance CPUs divided by the total physical CPU count.*

- **INI\_MNODE\_MEM\_AVAIL, FIN\_MNODE\_MEM\_AVAIL**

  *The initial and final maximum per-node available memory. This is* *not very useful as a metric but can give an impression of the* *status of the nodes; as an example, this value restricts the* *maximum instance size that can be still created on the cluster.*

- **INI\_MNODE\_DSK\_AVAIL, FIN\_MNODE\_DSK\_AVAIL**

  *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***.*

- **KM\_USED\_CPU, KM\_USED\_NPU, KM\_USED\_MEM, KM\_USED\_DSK**

  *These represents the metrics of used resources at the start of the* *computation (only for tiered allocation mode). The NPU value is* *"normalized" CPU count, i.e. the number of virtual CPUs divided by* *the maximum ratio of the virtual to physical CPUs.*

- **KM\_POOL\_CPU, KM\_POOL\_NPU, KM\_POOL\_MEM, KM\_POOL\_DSK**

  *These represents the total resources allocated during the tiered* *allocation process. In effect, they represent how much is readily* *available for allocation.*

- **KM\_UNAV\_CPU, KM\_POOL\_NPU, KM\_UNAV\_MEM, KM\_UNAV\_DSK**

  *These represents the resources left over (either free as in* *unallocable or allocable on their own) after the tiered allocation* *has been completed. They represent better the actual unallocable* *resources, because some other resource has been exhausted. For* *example, the cluster might still have 100GiB disk free, but with no* *memory left for instances, we cannot allocate another instance, so* *in effect the disk space is unallocable. Note that the CPUs here* *represent instance virtual CPUs, and in case the --max-cpu* *option hasn't been specified this will be -1.*

- **ALLOC\_USAGE**

  *The current usage represented as initial number of instances* *divided per final number of instances.*

- **ALLOC\_COUNT**

  *The number of instances allocated (delta between FIN\_INST\_CNT and* *INI\_INST\_CNT).*

- **ALLOC\_FAIL\*\_CNT**

  *For the last attemp at allocations (which would have increased* *FIN\_INST\_CNT with one, if it had succeeded), this is the count of* *the failure reasons per failure type; currently defined are* *FAILMEM, FAILDISK and FAILCPU which represent errors due to not* *enough memory, disk and CPUs, and FAILN1 which represents a non N+1* *compliant cluster on which we can't allocate instances at all.*

- **ALLOC\_FAIL\_REASON**

  *The reason for most of the failures, being one of the above FAIL\** *strings.*

- **OK**

  *A marker representing the successful end of the computation, and* *having value "1". If this key is not present in the output it means* *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.*

*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).* *Units can be used (see below for more details).*

- **--disk *disk***

  *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 (e.g. plain, drbd, so on) should be passed in.*

- **--vcpus *vcpus***

  *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 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. 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* *being offline.* *This means a couple of things:*

  - •

    *instances won't be placed on these nodes, not even temporarily;*

    *e.g. the replace primary move is not available if the* *secondary node is offline, since this move requires a failover.*

  - •

    *these nodes will not be included in the score calculation (except* *for the percentage of instances on offline nodes)*

  *Note that the algorithm will also mark as offline any nodes which* *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.*

- **-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.*

- **-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.*

- **--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 (default in mebibytes, units can be* *used)*

  - •

    *the memory size of the nodes (default in mebibytes, units can be* *used)*

  - •

    *the cpu core count for the nodes*

  *An example description would be* **preferred,B20,100G,16g,4** *describing a 20-node cluster where each node has 100GB 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 (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 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* *independent, and both start from the initial cluster state; as* *such, 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) from the default of one.*

- **-q, --quiet**

  *Decrease the output verbosity. Each usage of this option will* *decrease the verbosity (less than zero doesn't make sense) from* *the default of one.*

- **-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)](/units/7.md) man page.*

## EXIT STATUS

*The exist status of the command will be zero, unless for some* *reason the algorithm fatally failed (e.g. wrong node or instance* *data).*

## BUGS

*The algorithm is highly dependent on the number of nodes; its* *runtime grows exponentially with this number, and as such is* *impractical for really big clusters.*

*The algorithm doesn't rebalance the cluster or try to get the* *optimal fit; it just allocates in the best place for the current* *step, without taking into consideration the impact on future* *placements.*

## 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 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).*

*Ganeti daemons:* **ganeti-watcher***(8) (automatic instance* *restarter),* **ganeti-cleaner***(8) (job queue cleaner),* **ganeti-noded***(8) (node daemon),* **ganeti-masterd***(8)* *(master 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).*

## COPYRIGHT

*Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 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.*