Query version 2 design

Created:2010-Nov-12
Status:Implemented
Ganeti-Version:2.4.0

Current state and shortcomings

Queries are used to retrieve information about the cluster, e.g. a list of instances or nodes. For historical reasons they use a simple data structure for their result. The client submits the fields it would like to receive and the query returns a list for each item (instance, node, etc.) available. Each item consists of another list representing the fields’ values.

This data structure has a few drawbacks. It can’t associate a status (e.g. “node offline”) with fields as using special values can lead to ambiguities. Additionally it can’t mark fields as “not found” as the list of returned columns must match the fields requested.

Example:

>>> cli.GetClient().QueryNodes([], ["name", "pip", "mfree"], False)
[
  ['node1.example.com', '192.0.2.18', 14800],
  ['node2.example.com', '192.0.2.19', 31280]
]

There is no way for clients to determine the list of possible fields, meaning they have to be hardcoded. Selecting unknown fields raises an exception:

>>> cli.GetClient().QueryNodes([], ["name", "UnknownField"], False)
ganeti.errors.OpPrereqError: (u'Unknown output fields selected: UnknownField', u'wrong_input')

The client must also know each fields’ kind, that is whether a field is numeric, boolean, describes a storage size, etc. Centralizing this information in one place, the master daemon, is desirable.

Proposed changes

The current query result format can not be changed as it’s being used in various places. Changing the format from one Ganeti version to another would cause too much disruption. For this reason the ability to explicitly request a new result format must be added while the old format stays the default.

The implementation of query filters is planned for the future. To avoid having to change the calls again, a (hopefully) future-compatible interface will be implemented now.

In Python code, the objects described below will be implemented using subclasses of objects.ConfigObject, providing existing facilities for de-/serializing.

Regular expressions

As it turned out, only very few fields for instances used regular expressions, all of which can easily be turned into static field names. Therefore their use in field names is dropped. Reasons:

  • When regexps are used and a field name is not listed as a simple string in the field dictionary, all keys in the field dictionary have to be checked whether they’re a regular expression object and if so, matched (see utils.FindMatch).
  • Code becomes simpler. There would be no need anymore to care about regular expressions as field names—they’d all be simple strings, even if there are many more. The list of field names would be static once built at module-load time.
  • There’s the issue of formatting titles for the clients. Should it be done in the server? In the client? The field definition’s title would contain backreferences to the regexp groups in the field name (re.MatchObject.expand can be used). With just strings, the field definitions can be passed directly to the client. They’re static.
  • Only a side note: In the memory consumed for 1‘000 _sre.SRE_Pattern objects (as returned by re.compile for an expression with one group) one can easily store 10‘000 strings of the same length (the regexp objects keep the expression string around, so compiling the expression always uses more memory).

Item types

The proposal is to implement this new interface for the following items:

instance
Instances
node
Nodes
job
Jobs
lock
Locks
os
Operating systems

Data query

Request

The request is a dictionary with the following entries:

what (string, required)
An item type.
fields (list of strings, required)

List of names of fields to return. Example:

["name", "mem", "nic0.ip", "disk0.size", "disk1.size"]
filter (optional)

This will be used to filter queries. In this implementation only names can be filtered to replace the previous names parameter to queries. An empty filter (None) will return all items. To retrieve specific names, the filter must be specified as follows, with the inner part repeated for each name:

["|", ["=", "name", "node1"], ["=", "name", "node2"], ...]

Filters consist of S-expressions (["operator", <operands...>]) and extensions will be made in the future to allow for more operators and fields. Such extensions might include a Python-style “in” operator, but for simplicity only “=” is supported in this implementation.

To reiterate: Filters for this implementation must consist of exactly one OR expression (["|", ...]) and one or more name equality filters (["=", "name", "..."]).

Support for synchronous queries, currently available in the interface but disabled in the master daemon, will be dropped. Direct calls to opcodes have to be used instead.

Response

The result is a dictionary with the following entries:

fields (list of field definitions)
In-order list of a field definition for each requested field, unknown fields are returned with the kind unknown. Length must be equal to number of requested fields.
data (list of lists of tuples)

List of lists, one list for each item found. Each item’s list must have one entry for each field listed in fields (meaning their length is equal). Each field entry is a tuple of (status, value). status must be one of the following values:

Normal (numeric 0)
Value is available and matches the kind in the field definition.
Unknown field (numeric 1)
Field for this column is not known. Value must be None.
No data (numeric 2)
Exact meaning depends on query, e.g. node is unreachable or marked offline. Value must be None.
Value unavailable for item (numeric 3)
Used if, for example, NIC 3 is requested for an instance with only one network interface. Value must be None.
Resource offline (numeric 4)
Used if resource is marked offline. Value must be None.

Example response after requesting the fields name, mfree, xyz, mtotal, nic0.ip, nic1.ip and nic2.ip:

{
  "fields": [
    { "name": "name", "title": "Name", "kind": "text", },
    { "name": "mfree", "title": "MemFree", "kind": "unit", },
    # Unknown field
    { "name": "xyz", "title": None, "kind": "unknown", },
    { "name": "mtotal", "title": "MemTotal", "kind": "unit", },
    { "name": "nic0.ip", "title": "Nic.IP/0", "kind": "text", },
    { "name": "nic1.ip", "title": "Nic.IP/1", "kind": "text", },
    { "name": "nic2.ip", "title": "Nic.IP/2", "kind": "text", },
    ],

  "data": [
    [(0, "node1"), (0, 128), (1, None), (0, 4096),
     (0, "192.0.2.1"), (0, "192.0.2.2"), (3, None)],
    [(0, "node2"), (0, 96), (1, None), (0, 5000),
     (0, "192.0.2.21"), (0, "192.0.2.39"), (3, "192.0.2.90")],
    # Node not available, can't get "mfree" or "mtotal"
    [(0, "node3"), (2, None), (1, None), (2, None),
     (0, "192.0.2.30"), (3, None), (3, None)],
    ],
}

Fields query

Request

The request is a dictionary with the following entries:

what (string, required)
An item type.
fields (list of strings, optional)

List of names of fields to return. If not set, all fields are returned. Example:

["name", "mem", "nic0.ip", "disk0.size", "disk1.size"]
Response

The result is a dictionary with the following entries:

fields (list of field definitions)
List of a field definition for each field. If fields was set in the request and contained an unknown field, it is returned as type unknown.

Example:

{
  "fields": [
    { "name": "name", "title": "Name", "kind": "text", },
    { "name": "mfree", "title": "MemFree", "kind": "unit", },
    { "name": "mtotal", "title": "MemTotal", "kind": "unit", },
    { "name": "nic0.ip", "title": "Nic.IP/0", "kind": "text", },
    { "name": "nic1.ip", "title": "Nic.IP/1", "kind": "text", },
    { "name": "nic2.ip", "title": "Nic.IP/2", "kind": "text", },
    { "name": "nic3.ip", "title": "Nic.IP/3", "kind": "text", },
    # …
    { "name": "disk0.size", "title": "Disk.Size/0", "kind": "unit", },
    { "name": "disk1.size", "title": "Disk.Size/1", "kind": "unit", },
    { "name": "disk2.size", "title": "Disk.Size/2", "kind": "unit", },
    { "name": "disk3.size", "title": "Disk.Size/3", "kind": "unit", },
    # …
    ]
}

Field definition

A field definition is a dictionary with the following entries:

name (string)
Field name. Must only contain characters matching [a-z0-9/._].
title (string)
Human-readable title to use in output. Must not contain whitespace.
kind (string)

Field type, one of the following:

unknown
Unknown field
text
String
bool
Boolean, true/false
number
Numeric
unit
Numeric, in megabytes
timestamp
Unix timestamp in seconds since the epoch
other
Free-form type, depending on query

More types can be added in the future, so clients should default to formatting any unknown types the same way as “other”, which should be a string representation in most cases.

doc (string)
Human-readable description. Must start with uppercase character and must not end with punctuation or contain newlines.

Example 1 (item name):

{
  "name": "name",
  "title": "Name",
  "kind": "text",
}

Example 2 (free memory):

{
  "name": "mfree",
  "title": "MemFree",
  "kind": "unit",
}

Example 3 (list of primary instances):

{
  "name": "pinst",
  "title": "PrimaryInstances",
  "kind": "other",
}

Old result format

To limit the amount of code necessary, the new result format will be converted for clients calling the old methods. Unavailable values are set to None. If unknown fields were requested, the whole query fails as the client expects exactly the fields it requested.

LUXI

Currently query calls take a number of parameters, e.g. names, fields and whether to use locking. These will continue to work and return the old result format. Only clients using the new calls described below will be able to make use of new features such as filters. Two new calls are introduced:

Query
Execute a query on items, optionally filtered. Takes a single parameter, a query object encoded as a dictionary and returns a data query response.
QueryFields
Return list of supported fields as field definitions. Takes a single parameter, a fields query object encoded as a dictionary and returns a fields query response.

Python

The LUXI API is more or less mapped directly into Python. In addition to the existing stub functions new ones will be added for the new query requests.

RAPI

The RAPI interface already returns dictionaries for each item, but to not break compatibility no changes should be made to the structure (e.g. to include field definitions). The proposal here is to add a new parameter to allow clients to execute the requests described in this proposal directly and to receive the unmodified result. The new formats are a lot more verbose, flexible and extensible.

CLI programs

Command line programs might have difficulties to display the verbose status data to the user. There are several options:

  • Use colours to indicate missing values
  • Display status as value in parentheses, e.g. “(unavailable)”
  • Hide unknown columns from the result table and print a warning
  • Exit with non-zero code to indicate failures and/or missing data

Some are better for interactive usage, some better for use by other programs. It is expected that a combination will be used. The column separator (--separator=…) can be used to differentiate between interactive and programmatic usage.

Other discussed solutions

Another solution discussed was to add an additional column for each non-static field containing the status. Clients interested in the status could explicitly query for it.