/usr/share/doc/ganeti/html/design-query2.html is in ganeti-doc 2.16.0~rc2-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Query version 2 design — Ganeti 2.16.0~rc2 documentation</title>
<link rel="stylesheet" href="_static/style.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '2.16.0~rc2',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Splitting the query and job execution paths" href="design-query-splitting.html" />
<link rel="prev" title="Redundancy for the plain disk template" href="design-plain-redundancy.html" />
</head>
<body>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="design-query-splitting.html" title="Splitting the query and job execution paths"
accesskey="N">next</a></li>
<li class="right" >
<a href="design-plain-redundancy.html" title="Redundancy for the plain disk template"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Ganeti 2.16.0~rc2 documentation</a> »</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="query-version-2-design">
<h1><a class="toc-backref" href="#id8">Query version 2 design</a><a class="headerlink" href="#query-version-2-design" title="Permalink to this headline">¶</a></h1>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field-odd field"><th class="field-name">Created:</th><td class="field-body">2010-Nov-12</td>
</tr>
<tr class="field-even field"><th class="field-name">Status:</th><td class="field-body">Implemented</td>
</tr>
<tr class="field-odd field"><th class="field-name">Ganeti-Version:</th><td class="field-body">2.4.0</td>
</tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#query-version-2-design" id="id8">Query version 2 design</a><ul>
<li><a class="reference internal" href="#current-state-and-shortcomings" id="id9">Current state and shortcomings</a><ul>
<li><a class="reference internal" href="#proposed-changes" id="id10">Proposed changes</a><ul>
<li><a class="reference internal" href="#regular-expressions" id="id11">Regular expressions</a></li>
<li><a class="reference internal" href="#item-types" id="id12">Item types</a></li>
<li><a class="reference internal" href="#data-query" id="id13">Data query</a></li>
<li><a class="reference internal" href="#fields-query" id="id14">Fields query</a></li>
<li><a class="reference internal" href="#field-definition" id="id15">Field definition</a></li>
<li><a class="reference internal" href="#old-result-format" id="id16">Old result format</a></li>
<li><a class="reference internal" href="#luxi" id="id17">LUXI</a></li>
<li><a class="reference internal" href="#python" id="id18">Python</a></li>
<li><a class="reference internal" href="#rapi" id="id19">RAPI</a></li>
<li><a class="reference internal" href="#cli-programs" id="id20">CLI programs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-discussed-solutions" id="id21">Other discussed solutions</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<div class="section" id="current-state-and-shortcomings">
<h2><a class="toc-backref" href="#id9">Current state and shortcomings</a><a class="headerlink" href="#current-state-and-shortcomings" title="Permalink to this headline">¶</a></h2>
<p>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.</p>
<p>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.</p>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cli</span><span class="o">.</span><span class="n">GetClient</span><span class="p">()</span><span class="o">.</span><span class="n">QueryNodes</span><span class="p">([],</span> <span class="p">[</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"pip"</span><span class="p">,</span> <span class="s2">"mfree"</span><span class="p">],</span> <span class="bp">False</span><span class="p">)</span>
<span class="go">[</span>
<span class="go"> ['node1.example.com', '192.0.2.18', 14800],</span>
<span class="go"> ['node2.example.com', '192.0.2.19', 31280]</span>
<span class="go">]</span>
</pre></div>
</div>
<p>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:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">cli</span><span class="o">.</span><span class="n">GetClient</span><span class="p">()</span><span class="o">.</span><span class="n">QueryNodes</span><span class="p">([],</span> <span class="p">[</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"UnknownField"</span><span class="p">],</span> <span class="bp">False</span><span class="p">)</span>
<span class="go">ganeti.errors.OpPrereqError: (u'Unknown output fields selected: UnknownField', u'wrong_input')</span>
</pre></div>
</div>
<p>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.</p>
<div class="section" id="proposed-changes">
<h3><a class="toc-backref" href="#id10">Proposed changes</a><a class="headerlink" href="#proposed-changes" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
<p>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.</p>
<p>In Python code, the objects described below will be implemented using
subclasses of <code class="docutils literal"><span class="pre">objects.ConfigObject</span></code>, providing existing facilities
for de-/serializing.</p>
<div class="section" id="regular-expressions">
<h4><a class="toc-backref" href="#id11">Regular expressions</a><a class="headerlink" href="#regular-expressions" title="Permalink to this headline">¶</a></h4>
<p>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:</p>
<ul class="simple">
<li>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 <code class="docutils literal"><span class="pre">utils.FindMatch</span></code>).</li>
<li>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.</li>
<li>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
(<code class="docutils literal"><span class="pre">re.MatchObject.expand</span></code> can be used). With just strings, the field
definitions can be passed directly to the client. They’re static.</li>
<li>Only a side note: In the memory consumed for 1‘000
<code class="docutils literal"><span class="pre">_sre.SRE_Pattern</span></code> objects (as returned by <code class="docutils literal"><span class="pre">re.compile</span></code> 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).</li>
</ul>
</div>
<div class="section" id="item-types">
<span id="id1"></span><h4><a class="toc-backref" href="#id12">Item types</a><a class="headerlink" href="#item-types" title="Permalink to this headline">¶</a></h4>
<p>The proposal is to implement this new interface for the following
items:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">instance</span></code></dt>
<dd>Instances</dd>
<dt><code class="docutils literal"><span class="pre">node</span></code></dt>
<dd>Nodes</dd>
<dt><code class="docutils literal"><span class="pre">job</span></code></dt>
<dd>Jobs</dd>
<dt><code class="docutils literal"><span class="pre">lock</span></code></dt>
<dd>Locks</dd>
<dt><code class="docutils literal"><span class="pre">os</span></code></dt>
<dd>Operating systems</dd>
</dl>
</div>
<div class="section" id="data-query">
<span id="id2"></span><h4><a class="toc-backref" href="#id13">Data query</a><a class="headerlink" href="#data-query" title="Permalink to this headline">¶</a></h4>
<div class="section" id="request">
<span id="data-query-request"></span><h5>Request<a class="headerlink" href="#request" title="Permalink to this headline">¶</a></h5>
<p>The request is a dictionary with the following entries:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">what</span></code> (string, required)</dt>
<dd>An <a class="reference internal" href="#item-types"><span class="std std-ref">item type</span></a>.</dd>
<dt><code class="docutils literal"><span class="pre">fields</span></code> (list of strings, required)</dt>
<dd><p class="first">List of names of fields to return. Example:</p>
<div class="last highlight-python"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"mem"</span><span class="p">,</span> <span class="s2">"nic0.ip"</span><span class="p">,</span> <span class="s2">"disk0.size"</span><span class="p">,</span> <span class="s2">"disk1.size"</span><span class="p">]</span>
</pre></div>
</div>
</dd>
<dt><code class="docutils literal"><span class="pre">filter</span></code> (optional)</dt>
<dd><p class="first">This will be used to filter queries. In this implementation only names
can be filtered to replace the previous <code class="docutils literal"><span class="pre">names</span></code> parameter to
queries. An empty filter (<code class="docutils literal"><span class="pre">None</span></code>) will return all items. To retrieve
specific names, the filter must be specified as follows, with the
inner part repeated for each name:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">"|"</span><span class="p">,</span> <span class="p">[</span><span class="s2">"="</span><span class="p">,</span> <span class="s2">"name"</span><span class="p">,</span> <span class="s2">"node1"</span><span class="p">],</span> <span class="p">[</span><span class="s2">"="</span><span class="p">,</span> <span class="s2">"name"</span><span class="p">,</span> <span class="s2">"node2"</span><span class="p">],</span> <span class="o">...</span><span class="p">]</span>
</pre></div>
</div>
<p>Filters consist of S-expressions (<code class="docutils literal"><span class="pre">["operator",</span> <span class="pre"><operands...>]</span></code>) 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.</p>
<p class="last">To reiterate: Filters for this implementation must consist of exactly
one OR expression (<code class="docutils literal"><span class="pre">["|",</span> <span class="pre">...]</span></code>) and one or more name equality filters
(<code class="docutils literal"><span class="pre">["=",</span> <span class="pre">"name",</span> <span class="pre">"..."]</span></code>).</p>
</dd>
</dl>
<p>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.</p>
</div>
<div class="section" id="response">
<span id="data-query-response"></span><h5>Response<a class="headerlink" href="#response" title="Permalink to this headline">¶</a></h5>
<p>The result is a dictionary with the following entries:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">fields</span></code> (list of <a class="reference internal" href="#field-def"><span class="std std-ref">field definitions</span></a>)</dt>
<dd>In-order list of a <a class="reference internal" href="#field-def"><span class="std std-ref">field definition</span></a> for each
requested field, unknown fields are returned with the kind
<code class="docutils literal"><span class="pre">unknown</span></code>. Length must be equal to number of requested fields.</dd>
<dt><code class="docutils literal"><span class="pre">data</span></code> (list of lists of tuples)</dt>
<dd><p class="first">List of lists, one list for each item found. Each item’s list must
have one entry for each field listed in <code class="docutils literal"><span class="pre">fields</span></code> (meaning their
length is equal). Each field entry is a tuple of <code class="docutils literal"><span class="pre">(status,</span> <span class="pre">value)</span></code>.
<code class="docutils literal"><span class="pre">status</span></code> must be one of the following values:</p>
<dl class="last docutils">
<dt>Normal (numeric 0)</dt>
<dd>Value is available and matches the kind in the <a class="reference internal" href="#field-def"><span class="std std-ref">field
definition</span></a>.</dd>
<dt>Unknown field (numeric 1)</dt>
<dd>Field for this column is not known. Value must be <code class="docutils literal"><span class="pre">None</span></code>.</dd>
<dt>No data (numeric 2)</dt>
<dd>Exact meaning depends on query, e.g. node is unreachable or marked
offline. Value must be <code class="docutils literal"><span class="pre">None</span></code>.</dd>
<dt>Value unavailable for item (numeric 3)</dt>
<dd>Used if, for example, NIC 3 is requested for an instance with only
one network interface. Value must be <code class="docutils literal"><span class="pre">None</span></code>.</dd>
<dt>Resource offline (numeric 4)</dt>
<dd>Used if resource is marked offline. Value must be <code class="docutils literal"><span class="pre">None</span></code>.</dd>
</dl>
</dd>
</dl>
<p>Example response after requesting the fields <code class="docutils literal"><span class="pre">name</span></code>, <code class="docutils literal"><span class="pre">mfree</span></code>,
<code class="docutils literal"><span class="pre">xyz</span></code>, <code class="docutils literal"><span class="pre">mtotal</span></code>, <code class="docutils literal"><span class="pre">nic0.ip</span></code>, <code class="docutils literal"><span class="pre">nic1.ip</span></code> and <code class="docutils literal"><span class="pre">nic2.ip</span></code>:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"fields"</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"name"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Name"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"mfree"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"MemFree"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="c1"># Unknown field</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"xyz"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="bp">None</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unknown"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"mtotal"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"MemTotal"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic0.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/0"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic1.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/1"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic2.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/2"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">],</span>
<span class="s2">"data"</span><span class="p">:</span> <span class="p">[</span>
<span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"node1"</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">128</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="bp">None</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">4096</span><span class="p">),</span>
<span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"192.0.2.1"</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"192.0.2.2"</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="bp">None</span><span class="p">)],</span>
<span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"node2"</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">96</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="bp">None</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">5000</span><span class="p">),</span>
<span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"192.0.2.21"</span><span class="p">),</span> <span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"192.0.2.39"</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="s2">"192.0.2.90"</span><span class="p">)],</span>
<span class="c1"># Node not available, can't get "mfree" or "mtotal"</span>
<span class="p">[(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"node3"</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="bp">None</span><span class="p">),</span> <span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="bp">None</span><span class="p">),</span> <span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="bp">None</span><span class="p">),</span>
<span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="s2">"192.0.2.30"</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="bp">None</span><span class="p">),</span> <span class="p">(</span><span class="mi">3</span><span class="p">,</span> <span class="bp">None</span><span class="p">)],</span>
<span class="p">],</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="fields-query">
<span id="id3"></span><h4><a class="toc-backref" href="#id14">Fields query</a><a class="headerlink" href="#fields-query" title="Permalink to this headline">¶</a></h4>
<div class="section" id="fields-query-request">
<span id="id4"></span><h5>Request<a class="headerlink" href="#fields-query-request" title="Permalink to this headline">¶</a></h5>
<p>The request is a dictionary with the following entries:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">what</span></code> (string, required)</dt>
<dd>An <a class="reference internal" href="#item-types"><span class="std std-ref">item type</span></a>.</dd>
<dt><code class="docutils literal"><span class="pre">fields</span></code> (list of strings, optional)</dt>
<dd><p class="first">List of names of fields to return. If not set, all fields are
returned. Example:</p>
<div class="last highlight-python"><div class="highlight"><pre><span></span><span class="p">[</span><span class="s2">"name"</span><span class="p">,</span> <span class="s2">"mem"</span><span class="p">,</span> <span class="s2">"nic0.ip"</span><span class="p">,</span> <span class="s2">"disk0.size"</span><span class="p">,</span> <span class="s2">"disk1.size"</span><span class="p">]</span>
</pre></div>
</div>
</dd>
</dl>
</div>
<div class="section" id="fields-query-response">
<span id="id5"></span><h5>Response<a class="headerlink" href="#fields-query-response" title="Permalink to this headline">¶</a></h5>
<p>The result is a dictionary with the following entries:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">fields</span></code> (list of <a class="reference internal" href="#field-def"><span class="std std-ref">field definitions</span></a>)</dt>
<dd>List of a <a class="reference internal" href="#field-def"><span class="std std-ref">field definition</span></a> for each field. If
<code class="docutils literal"><span class="pre">fields</span></code> was set in the request and contained an unknown field, it
is returned as type <code class="docutils literal"><span class="pre">unknown</span></code>.</dd>
</dl>
<p>Example:</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"fields"</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"name"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Name"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"mfree"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"MemFree"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"mtotal"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"MemTotal"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic0.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/0"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic1.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/1"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic2.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/2"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"nic3.ip"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Nic.IP/3"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span> <span class="p">},</span>
<span class="c1"># …</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"disk0.size"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Disk.Size/0"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"disk1.size"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Disk.Size/1"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"disk2.size"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Disk.Size/2"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="p">{</span> <span class="s2">"name"</span><span class="p">:</span> <span class="s2">"disk3.size"</span><span class="p">,</span> <span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Disk.Size/3"</span><span class="p">,</span> <span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span> <span class="p">},</span>
<span class="c1"># …</span>
<span class="p">]</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="field-definition">
<span id="field-def"></span><h4><a class="toc-backref" href="#id15">Field definition</a><a class="headerlink" href="#field-definition" title="Permalink to this headline">¶</a></h4>
<p>A field definition is a dictionary with the following entries:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">name</span></code> (string)</dt>
<dd>Field name. Must only contain characters matching <code class="docutils literal"><span class="pre">[a-z0-9/._]</span></code>.</dd>
<dt><code class="docutils literal"><span class="pre">title</span></code> (string)</dt>
<dd>Human-readable title to use in output. Must not contain whitespace.</dd>
<dt><code class="docutils literal"><span class="pre">kind</span></code> (string)</dt>
<dd><p class="first">Field type, one of the following:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">unknown</span></code></dt>
<dd>Unknown field</dd>
<dt><code class="docutils literal"><span class="pre">text</span></code></dt>
<dd>String</dd>
<dt><code class="docutils literal"><span class="pre">bool</span></code></dt>
<dd>Boolean, true/false</dd>
<dt><code class="docutils literal"><span class="pre">number</span></code></dt>
<dd>Numeric</dd>
<dt><code class="docutils literal"><span class="pre">unit</span></code></dt>
<dd>Numeric, in megabytes</dd>
<dt><code class="docutils literal"><span class="pre">timestamp</span></code></dt>
<dd>Unix timestamp in seconds since the epoch</dd>
<dt><code class="docutils literal"><span class="pre">other</span></code></dt>
<dd>Free-form type, depending on query</dd>
</dl>
<p class="last">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.</p>
</dd>
<dt><code class="docutils literal"><span class="pre">doc</span></code> (string)</dt>
<dd>Human-readable description. Must start with uppercase character and
must not end with punctuation or contain newlines.</dd>
</dl>
<p>Example 1 (item name):</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">"name"</span><span class="p">,</span>
<span class="s2">"title"</span><span class="p">:</span> <span class="s2">"Name"</span><span class="p">,</span>
<span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"text"</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Example 2 (free memory):</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">"mfree"</span><span class="p">,</span>
<span class="s2">"title"</span><span class="p">:</span> <span class="s2">"MemFree"</span><span class="p">,</span>
<span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"unit"</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
<p>Example 3 (list of primary instances):</p>
<div class="highlight-python"><div class="highlight"><pre><span></span><span class="p">{</span>
<span class="s2">"name"</span><span class="p">:</span> <span class="s2">"pinst"</span><span class="p">,</span>
<span class="s2">"title"</span><span class="p">:</span> <span class="s2">"PrimaryInstances"</span><span class="p">,</span>
<span class="s2">"kind"</span><span class="p">:</span> <span class="s2">"other"</span><span class="p">,</span>
<span class="p">}</span>
</pre></div>
</div>
</div>
<div class="section" id="old-result-format">
<span id="id6"></span><h4><a class="toc-backref" href="#id16">Old result format</a><a class="headerlink" href="#old-result-format" title="Permalink to this headline">¶</a></h4>
<p>To limit the amount of code necessary, the <a class="reference internal" href="#data-query-response"><span class="std std-ref">new result format</span></a> will be converted for clients calling the old
methods. Unavailable values are set to <code class="docutils literal"><span class="pre">None</span></code>. If unknown fields were
requested, the whole query fails as the client expects exactly the
fields it requested.</p>
</div>
<div class="section" id="luxi">
<span id="query2-luxi"></span><h4><a class="toc-backref" href="#id17">LUXI</a><a class="headerlink" href="#luxi" title="Permalink to this headline">¶</a></h4>
<p>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
<a class="reference internal" href="#old-result-format"><span class="std std-ref">old result format</span></a>. 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:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">Query</span></code></dt>
<dd>Execute a query on items, optionally filtered. Takes a single
parameter, a <a class="reference internal" href="#data-query-request"><span class="std std-ref">query object</span></a> encoded as a
dictionary and returns a <a class="reference internal" href="#data-query-response"><span class="std std-ref">data query response</span></a>.</dd>
<dt><code class="docutils literal"><span class="pre">QueryFields</span></code></dt>
<dd>Return list of supported fields as <a class="reference internal" href="#field-def"><span class="std std-ref">field definitions</span></a>. Takes a single parameter, a <a class="reference internal" href="#fields-query-request"><span class="std std-ref">fields query object</span></a> encoded as a dictionary and returns a
<a class="reference internal" href="#fields-query-response"><span class="std std-ref">fields query response</span></a>.</dd>
</dl>
</div>
<div class="section" id="python">
<h4><a class="toc-backref" href="#id18">Python</a><a class="headerlink" href="#python" title="Permalink to this headline">¶</a></h4>
<p>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.</p>
</div>
<div class="section" id="rapi">
<h4><a class="toc-backref" href="#id19">RAPI</a><a class="headerlink" href="#rapi" title="Permalink to this headline">¶</a></h4>
<p>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.</p>
</div>
<div class="section" id="cli-programs">
<span id="id7"></span><h4><a class="toc-backref" href="#id20">CLI programs</a><a class="headerlink" href="#cli-programs" title="Permalink to this headline">¶</a></h4>
<p>Command line programs might have difficulties to display the verbose
status data to the user. There are several options:</p>
<ul class="simple">
<li>Use colours to indicate missing values</li>
<li>Display status as value in parentheses, e.g. “(unavailable)”</li>
<li>Hide unknown columns from the result table and print a warning</li>
<li>Exit with non-zero code to indicate failures and/or missing data</li>
</ul>
<p>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 (<code class="docutils literal"><span class="pre">--separator=…</span></code>) can be used to differentiate between
interactive and programmatic usage.</p>
</div>
</div>
<div class="section" id="other-discussed-solutions">
<h3><a class="toc-backref" href="#id21">Other discussed solutions</a><a class="headerlink" href="#other-discussed-solutions" title="Permalink to this headline">¶</a></h3>
<p>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.</p>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="index.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Query version 2 design</a><ul>
<li><a class="reference internal" href="#current-state-and-shortcomings">Current state and shortcomings</a><ul>
<li><a class="reference internal" href="#proposed-changes">Proposed changes</a><ul>
<li><a class="reference internal" href="#regular-expressions">Regular expressions</a></li>
<li><a class="reference internal" href="#item-types">Item types</a></li>
<li><a class="reference internal" href="#data-query">Data query</a><ul>
<li><a class="reference internal" href="#request">Request</a></li>
<li><a class="reference internal" href="#response">Response</a></li>
</ul>
</li>
<li><a class="reference internal" href="#fields-query">Fields query</a><ul>
<li><a class="reference internal" href="#fields-query-request">Request</a></li>
<li><a class="reference internal" href="#fields-query-response">Response</a></li>
</ul>
</li>
<li><a class="reference internal" href="#field-definition">Field definition</a></li>
<li><a class="reference internal" href="#old-result-format">Old result format</a></li>
<li><a class="reference internal" href="#luxi">LUXI</a></li>
<li><a class="reference internal" href="#python">Python</a></li>
<li><a class="reference internal" href="#rapi">RAPI</a></li>
<li><a class="reference internal" href="#cli-programs">CLI programs</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-discussed-solutions">Other discussed solutions</a></li>
</ul>
</li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="design-plain-redundancy.html"
title="previous chapter">Redundancy for the plain disk template</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="design-query-splitting.html"
title="next chapter">Splitting the query and job execution paths</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/design-query2.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="design-query-splitting.html" title="Splitting the query and job execution paths"
>next</a></li>
<li class="right" >
<a href="design-plain-redundancy.html" title="Redundancy for the plain disk template"
>previous</a> |</li>
<li class="nav-item nav-item-0"><a href="index.html">Ganeti 2.16.0~rc2 documentation</a> »</li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2018, 2007, 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015 Google Inc..
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.6.7.
</div>
</body>
</html>
|