Statistics
| Branch: | Tag: | Revision:

root / lib / rapi / client.py @ 1f350e0f

History | View | Annotate | Download (63 kB)

1
#
2
#
3

    
4
# Copyright (C) 2010, 2011, 2012 Google Inc.
5
#
6
# This program is free software; you can redistribute it and/or modify
7
# it under the terms of the GNU General Public License as published by
8
# the Free Software Foundation; either version 2 of the License, or
9
# (at your option) any later version.
10
#
11
# This program is distributed in the hope that it will be useful, but
12
# WITHOUT ANY WARRANTY; without even the implied warranty of
13
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14
# General Public License for more details.
15
#
16
# You should have received a copy of the GNU General Public License
17
# along with this program; if not, write to the Free Software
18
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
19
# 02110-1301, USA.
20

    
21

    
22
"""Ganeti RAPI client.
23

24
@attention: To use the RAPI client, the application B{must} call
25
            C{pycurl.global_init} during initialization and
26
            C{pycurl.global_cleanup} before exiting the process. This is very
27
            important in multi-threaded programs. See curl_global_init(3) and
28
            curl_global_cleanup(3) for details. The decorator L{UsesRapiClient}
29
            can be used.
30

31
"""
32

    
33
# No Ganeti-specific modules should be imported. The RAPI client is supposed to
34
# be standalone.
35

    
36
import logging
37
import simplejson
38
import socket
39
import urllib
40
import threading
41
import pycurl
42
import time
43

    
44
try:
45
  from cStringIO import StringIO
46
except ImportError:
47
  from StringIO import StringIO
48

    
49

    
50
GANETI_RAPI_PORT = 5080
51
GANETI_RAPI_VERSION = 2
52

    
53
HTTP_DELETE = "DELETE"
54
HTTP_GET = "GET"
55
HTTP_PUT = "PUT"
56
HTTP_POST = "POST"
57
HTTP_OK = 200
58
HTTP_NOT_FOUND = 404
59
HTTP_APP_JSON = "application/json"
60

    
61
REPLACE_DISK_PRI = "replace_on_primary"
62
REPLACE_DISK_SECONDARY = "replace_on_secondary"
63
REPLACE_DISK_CHG = "replace_new_secondary"
64
REPLACE_DISK_AUTO = "replace_auto"
65

    
66
NODE_EVAC_PRI = "primary-only"
67
NODE_EVAC_SEC = "secondary-only"
68
NODE_EVAC_ALL = "all"
69

    
70
NODE_ROLE_DRAINED = "drained"
71
NODE_ROLE_MASTER_CANDIATE = "master-candidate"
72
NODE_ROLE_MASTER = "master"
73
NODE_ROLE_OFFLINE = "offline"
74
NODE_ROLE_REGULAR = "regular"
75

    
76
JOB_STATUS_QUEUED = "queued"
77
JOB_STATUS_WAITING = "waiting"
78
JOB_STATUS_CANCELING = "canceling"
79
JOB_STATUS_RUNNING = "running"
80
JOB_STATUS_CANCELED = "canceled"
81
JOB_STATUS_SUCCESS = "success"
82
JOB_STATUS_ERROR = "error"
83
JOB_STATUS_PENDING = frozenset([
84
  JOB_STATUS_QUEUED,
85
  JOB_STATUS_WAITING,
86
  JOB_STATUS_CANCELING,
87
  ])
88
JOB_STATUS_FINALIZED = frozenset([
89
  JOB_STATUS_CANCELED,
90
  JOB_STATUS_SUCCESS,
91
  JOB_STATUS_ERROR,
92
  ])
93
JOB_STATUS_ALL = frozenset([
94
  JOB_STATUS_RUNNING,
95
  ]) | JOB_STATUS_PENDING | JOB_STATUS_FINALIZED
96

    
97
# Legacy name
98
JOB_STATUS_WAITLOCK = JOB_STATUS_WAITING
99

    
100
# Internal constants
101
_REQ_DATA_VERSION_FIELD = "__version__"
102
_QPARAM_DRY_RUN = "dry-run"
103
_QPARAM_FORCE = "force"
104

    
105
# Feature strings
106
INST_CREATE_REQV1 = "instance-create-reqv1"
107
INST_REINSTALL_REQV1 = "instance-reinstall-reqv1"
108
NODE_MIGRATE_REQV1 = "node-migrate-reqv1"
109
NODE_EVAC_RES1 = "node-evac-res1"
110

    
111
# Old feature constant names in case they're references by users of this module
112
_INST_CREATE_REQV1 = INST_CREATE_REQV1
113
_INST_REINSTALL_REQV1 = INST_REINSTALL_REQV1
114
_NODE_MIGRATE_REQV1 = NODE_MIGRATE_REQV1
115
_NODE_EVAC_RES1 = NODE_EVAC_RES1
116

    
117
#: Resolver errors
118
ECODE_RESOLVER = "resolver_error"
119

    
120
#: Not enough resources (iallocator failure, disk space, memory, etc.)
121
ECODE_NORES = "insufficient_resources"
122

    
123
#: Temporarily out of resources; operation can be tried again
124
ECODE_TEMP_NORES = "temp_insufficient_resources"
125

    
126
#: Wrong arguments (at syntax level)
127
ECODE_INVAL = "wrong_input"
128

    
129
#: Wrong entity state
130
ECODE_STATE = "wrong_state"
131

    
132
#: Entity not found
133
ECODE_NOENT = "unknown_entity"
134

    
135
#: Entity already exists
136
ECODE_EXISTS = "already_exists"
137

    
138
#: Resource not unique (e.g. MAC or IP duplication)
139
ECODE_NOTUNIQUE = "resource_not_unique"
140

    
141
#: Internal cluster error
142
ECODE_FAULT = "internal_error"
143

    
144
#: Environment error (e.g. node disk error)
145
ECODE_ENVIRON = "environment_error"
146

    
147
#: List of all failure types
148
ECODE_ALL = frozenset([
149
  ECODE_RESOLVER,
150
  ECODE_NORES,
151
  ECODE_TEMP_NORES,
152
  ECODE_INVAL,
153
  ECODE_STATE,
154
  ECODE_NOENT,
155
  ECODE_EXISTS,
156
  ECODE_NOTUNIQUE,
157
  ECODE_FAULT,
158
  ECODE_ENVIRON,
159
  ])
160

    
161
# Older pycURL versions don't have all error constants
162
try:
163
  _CURLE_SSL_CACERT = pycurl.E_SSL_CACERT
164
  _CURLE_SSL_CACERT_BADFILE = pycurl.E_SSL_CACERT_BADFILE
165
except AttributeError:
166
  _CURLE_SSL_CACERT = 60
167
  _CURLE_SSL_CACERT_BADFILE = 77
168

    
169
_CURL_SSL_CERT_ERRORS = frozenset([
170
  _CURLE_SSL_CACERT,
171
  _CURLE_SSL_CACERT_BADFILE,
172
  ])
173

    
174

    
175
class Error(Exception):
176
  """Base error class for this module.
177

178
  """
179
  pass
180

    
181

    
182
class GanetiApiError(Error):
183
  """Generic error raised from Ganeti API.
184

185
  """
186
  def __init__(self, msg, code=None):
187
    Error.__init__(self, msg)
188
    self.code = code
189

    
190

    
191
class CertificateError(GanetiApiError):
192
  """Raised when a problem is found with the SSL certificate.
193

194
  """
195
  pass
196

    
197

    
198
def _AppendIf(container, condition, value):
199
  """Appends to a list if a condition evaluates to truth.
200

201
  """
202
  if condition:
203
    container.append(value)
204

    
205
  return condition
206

    
207

    
208
def _AppendDryRunIf(container, condition):
209
  """Appends a "dry-run" parameter if a condition evaluates to truth.
210

211
  """
212
  return _AppendIf(container, condition, (_QPARAM_DRY_RUN, 1))
213

    
214

    
215
def _AppendForceIf(container, condition):
216
  """Appends a "force" parameter if a condition evaluates to truth.
217

218
  """
219
  return _AppendIf(container, condition, (_QPARAM_FORCE, 1))
220

    
221

    
222
def _SetItemIf(container, condition, item, value):
223
  """Sets an item if a condition evaluates to truth.
224

225
  """
226
  if condition:
227
    container[item] = value
228

    
229
  return condition
230

    
231

    
232
def UsesRapiClient(fn):
233
  """Decorator for code using RAPI client to initialize pycURL.
234

235
  """
236
  def wrapper(*args, **kwargs):
237
    # curl_global_init(3) and curl_global_cleanup(3) must be called with only
238
    # one thread running. This check is just a safety measure -- it doesn't
239
    # cover all cases.
240
    assert threading.activeCount() == 1, \
241
           "Found active threads when initializing pycURL"
242

    
243
    pycurl.global_init(pycurl.GLOBAL_ALL)
244
    try:
245
      return fn(*args, **kwargs)
246
    finally:
247
      pycurl.global_cleanup()
248

    
249
  return wrapper
250

    
251

    
252
def GenericCurlConfig(verbose=False, use_signal=False,
253
                      use_curl_cabundle=False, cafile=None, capath=None,
254
                      proxy=None, verify_hostname=False,
255
                      connect_timeout=None, timeout=None,
256
                      _pycurl_version_fn=pycurl.version_info):
257
  """Curl configuration function generator.
258

259
  @type verbose: bool
260
  @param verbose: Whether to set cURL to verbose mode
261
  @type use_signal: bool
262
  @param use_signal: Whether to allow cURL to use signals
263
  @type use_curl_cabundle: bool
264
  @param use_curl_cabundle: Whether to use cURL's default CA bundle
265
  @type cafile: string
266
  @param cafile: In which file we can find the certificates
267
  @type capath: string
268
  @param capath: In which directory we can find the certificates
269
  @type proxy: string
270
  @param proxy: Proxy to use, None for default behaviour and empty string for
271
                disabling proxies (see curl_easy_setopt(3))
272
  @type verify_hostname: bool
273
  @param verify_hostname: Whether to verify the remote peer certificate's
274
                          commonName
275
  @type connect_timeout: number
276
  @param connect_timeout: Timeout for establishing connection in seconds
277
  @type timeout: number
278
  @param timeout: Timeout for complete transfer in seconds (see
279
                  curl_easy_setopt(3)).
280

281
  """
282
  if use_curl_cabundle and (cafile or capath):
283
    raise Error("Can not use default CA bundle when CA file or path is set")
284

    
285
  def _ConfigCurl(curl, logger):
286
    """Configures a cURL object
287

288
    @type curl: pycurl.Curl
289
    @param curl: cURL object
290

291
    """
292
    logger.debug("Using cURL version %s", pycurl.version)
293

    
294
    # pycurl.version_info returns a tuple with information about the used
295
    # version of libcurl. Item 5 is the SSL library linked to it.
296
    # e.g.: (3, '7.18.0', 463360, 'x86_64-pc-linux-gnu', 1581, 'GnuTLS/2.0.4',
297
    # 0, '1.2.3.3', ...)
298
    sslver = _pycurl_version_fn()[5]
299
    if not sslver:
300
      raise Error("No SSL support in cURL")
301

    
302
    lcsslver = sslver.lower()
303
    if lcsslver.startswith("openssl/"):
304
      pass
305
    elif lcsslver.startswith("nss/"):
306
      # TODO: investigate compatibility beyond a simple test
307
      pass
308
    elif lcsslver.startswith("gnutls/"):
309
      if capath:
310
        raise Error("cURL linked against GnuTLS has no support for a"
311
                    " CA path (%s)" % (pycurl.version, ))
312
    else:
313
      raise NotImplementedError("cURL uses unsupported SSL version '%s'" %
314
                                sslver)
315

    
316
    curl.setopt(pycurl.VERBOSE, verbose)
317
    curl.setopt(pycurl.NOSIGNAL, not use_signal)
318

    
319
    # Whether to verify remote peer's CN
320
    if verify_hostname:
321
      # curl_easy_setopt(3): "When CURLOPT_SSL_VERIFYHOST is 2, that
322
      # certificate must indicate that the server is the server to which you
323
      # meant to connect, or the connection fails. [...] When the value is 1,
324
      # the certificate must contain a Common Name field, but it doesn't matter
325
      # what name it says. [...]"
326
      curl.setopt(pycurl.SSL_VERIFYHOST, 2)
327
    else:
328
      curl.setopt(pycurl.SSL_VERIFYHOST, 0)
329

    
330
    if cafile or capath or use_curl_cabundle:
331
      # Require certificates to be checked
332
      curl.setopt(pycurl.SSL_VERIFYPEER, True)
333
      if cafile:
334
        curl.setopt(pycurl.CAINFO, str(cafile))
335
      if capath:
336
        curl.setopt(pycurl.CAPATH, str(capath))
337
      # Not changing anything for using default CA bundle
338
    else:
339
      # Disable SSL certificate verification
340
      curl.setopt(pycurl.SSL_VERIFYPEER, False)
341

    
342
    if proxy is not None:
343
      curl.setopt(pycurl.PROXY, str(proxy))
344

    
345
    # Timeouts
346
    if connect_timeout is not None:
347
      curl.setopt(pycurl.CONNECTTIMEOUT, connect_timeout)
348
    if timeout is not None:
349
      curl.setopt(pycurl.TIMEOUT, timeout)
350

    
351
  return _ConfigCurl
352

    
353

    
354
class GanetiRapiClient(object): # pylint: disable=R0904
355
  """Ganeti RAPI client.
356

357
  """
358
  USER_AGENT = "Ganeti RAPI Client"
359
  _json_encoder = simplejson.JSONEncoder(sort_keys=True)
360

    
361
  def __init__(self, host, port=GANETI_RAPI_PORT,
362
               username=None, password=None, logger=logging,
363
               curl_config_fn=None, curl_factory=None):
364
    """Initializes this class.
365

366
    @type host: string
367
    @param host: the ganeti cluster master to interact with
368
    @type port: int
369
    @param port: the port on which the RAPI is running (default is 5080)
370
    @type username: string
371
    @param username: the username to connect with
372
    @type password: string
373
    @param password: the password to connect with
374
    @type curl_config_fn: callable
375
    @param curl_config_fn: Function to configure C{pycurl.Curl} object
376
    @param logger: Logging object
377

378
    """
379
    self._username = username
380
    self._password = password
381
    self._logger = logger
382
    self._curl_config_fn = curl_config_fn
383
    self._curl_factory = curl_factory
384

    
385
    try:
386
      socket.inet_pton(socket.AF_INET6, host)
387
      address = "[%s]:%s" % (host, port)
388
    except socket.error:
389
      address = "%s:%s" % (host, port)
390

    
391
    self._base_url = "https://%s" % address
392

    
393
    if username is not None:
394
      if password is None:
395
        raise Error("Password not specified")
396
    elif password:
397
      raise Error("Specified password without username")
398

    
399
  def _CreateCurl(self):
400
    """Creates a cURL object.
401

402
    """
403
    # Create pycURL object if no factory is provided
404
    if self._curl_factory:
405
      curl = self._curl_factory()
406
    else:
407
      curl = pycurl.Curl()
408

    
409
    # Default cURL settings
410
    curl.setopt(pycurl.VERBOSE, False)
411
    curl.setopt(pycurl.FOLLOWLOCATION, False)
412
    curl.setopt(pycurl.MAXREDIRS, 5)
413
    curl.setopt(pycurl.NOSIGNAL, True)
414
    curl.setopt(pycurl.USERAGENT, self.USER_AGENT)
415
    curl.setopt(pycurl.SSL_VERIFYHOST, 0)
416
    curl.setopt(pycurl.SSL_VERIFYPEER, False)
417
    curl.setopt(pycurl.HTTPHEADER, [
418
      "Accept: %s" % HTTP_APP_JSON,
419
      "Content-type: %s" % HTTP_APP_JSON,
420
      ])
421

    
422
    assert ((self._username is None and self._password is None) ^
423
            (self._username is not None and self._password is not None))
424

    
425
    if self._username:
426
      # Setup authentication
427
      curl.setopt(pycurl.HTTPAUTH, pycurl.HTTPAUTH_BASIC)
428
      curl.setopt(pycurl.USERPWD,
429
                  str("%s:%s" % (self._username, self._password)))
430

    
431
    # Call external configuration function
432
    if self._curl_config_fn:
433
      self._curl_config_fn(curl, self._logger)
434

    
435
    return curl
436

    
437
  @staticmethod
438
  def _EncodeQuery(query):
439
    """Encode query values for RAPI URL.
440

441
    @type query: list of two-tuples
442
    @param query: Query arguments
443
    @rtype: list
444
    @return: Query list with encoded values
445

446
    """
447
    result = []
448

    
449
    for name, value in query:
450
      if value is None:
451
        result.append((name, ""))
452

    
453
      elif isinstance(value, bool):
454
        # Boolean values must be encoded as 0 or 1
455
        result.append((name, int(value)))
456

    
457
      elif isinstance(value, (list, tuple, dict)):
458
        raise ValueError("Invalid query data type %r" % type(value).__name__)
459

    
460
      else:
461
        result.append((name, value))
462

    
463
    return result
464

    
465
  def _SendRequest(self, method, path, query, content):
466
    """Sends an HTTP request.
467

468
    This constructs a full URL, encodes and decodes HTTP bodies, and
469
    handles invalid responses in a pythonic way.
470

471
    @type method: string
472
    @param method: HTTP method to use
473
    @type path: string
474
    @param path: HTTP URL path
475
    @type query: list of two-tuples
476
    @param query: query arguments to pass to urllib.urlencode
477
    @type content: str or None
478
    @param content: HTTP body content
479

480
    @rtype: str
481
    @return: JSON-Decoded response
482

483
    @raises CertificateError: If an invalid SSL certificate is found
484
    @raises GanetiApiError: If an invalid response is returned
485

486
    """
487
    assert path.startswith("/")
488

    
489
    curl = self._CreateCurl()
490

    
491
    if content is not None:
492
      encoded_content = self._json_encoder.encode(content)
493
    else:
494
      encoded_content = ""
495

    
496
    # Build URL
497
    urlparts = [self._base_url, path]
498
    if query:
499
      urlparts.append("?")
500
      urlparts.append(urllib.urlencode(self._EncodeQuery(query)))
501

    
502
    url = "".join(urlparts)
503

    
504
    self._logger.debug("Sending request %s %s (content=%r)",
505
                       method, url, encoded_content)
506

    
507
    # Buffer for response
508
    encoded_resp_body = StringIO()
509

    
510
    # Configure cURL
511
    curl.setopt(pycurl.CUSTOMREQUEST, str(method))
512
    curl.setopt(pycurl.URL, str(url))
513
    curl.setopt(pycurl.POSTFIELDS, str(encoded_content))
514
    curl.setopt(pycurl.WRITEFUNCTION, encoded_resp_body.write)
515

    
516
    try:
517
      # Send request and wait for response
518
      try:
519
        curl.perform()
520
      except pycurl.error, err:
521
        if err.args[0] in _CURL_SSL_CERT_ERRORS:
522
          raise CertificateError("SSL certificate error %s" % err,
523
                                 code=err.args[0])
524

    
525
        raise GanetiApiError(str(err), code=err.args[0])
526
    finally:
527
      # Reset settings to not keep references to large objects in memory
528
      # between requests
529
      curl.setopt(pycurl.POSTFIELDS, "")
530
      curl.setopt(pycurl.WRITEFUNCTION, lambda _: None)
531

    
532
    # Get HTTP response code
533
    http_code = curl.getinfo(pycurl.RESPONSE_CODE)
534

    
535
    # Was anything written to the response buffer?
536
    if encoded_resp_body.tell():
537
      response_content = simplejson.loads(encoded_resp_body.getvalue())
538
    else:
539
      response_content = None
540

    
541
    if http_code != HTTP_OK:
542
      if isinstance(response_content, dict):
543
        msg = ("%s %s: %s" %
544
               (response_content["code"],
545
                response_content["message"],
546
                response_content["explain"]))
547
      else:
548
        msg = str(response_content)
549

    
550
      raise GanetiApiError(msg, code=http_code)
551

    
552
    return response_content
553

    
554
  def GetVersion(self):
555
    """Gets the Remote API version running on the cluster.
556

557
    @rtype: int
558
    @return: Ganeti Remote API version
559

560
    """
561
    return self._SendRequest(HTTP_GET, "/version", None, None)
562

    
563
  def GetFeatures(self):
564
    """Gets the list of optional features supported by RAPI server.
565

566
    @rtype: list
567
    @return: List of optional features
568

569
    """
570
    try:
571
      return self._SendRequest(HTTP_GET, "/%s/features" % GANETI_RAPI_VERSION,
572
                               None, None)
573
    except GanetiApiError, err:
574
      # Older RAPI servers don't support this resource
575
      if err.code == HTTP_NOT_FOUND:
576
        return []
577

    
578
      raise
579

    
580
  def GetOperatingSystems(self):
581
    """Gets the Operating Systems running in the Ganeti cluster.
582

583
    @rtype: list of str
584
    @return: operating systems
585

586
    """
587
    return self._SendRequest(HTTP_GET, "/%s/os" % GANETI_RAPI_VERSION,
588
                             None, None)
589

    
590
  def GetInfo(self):
591
    """Gets info about the cluster.
592

593
    @rtype: dict
594
    @return: information about the cluster
595

596
    """
597
    return self._SendRequest(HTTP_GET, "/%s/info" % GANETI_RAPI_VERSION,
598
                             None, None)
599

    
600
  def RedistributeConfig(self):
601
    """Tells the cluster to redistribute its configuration files.
602

603
    @rtype: string
604
    @return: job id
605

606
    """
607
    return self._SendRequest(HTTP_PUT,
608
                             "/%s/redistribute-config" % GANETI_RAPI_VERSION,
609
                             None, None)
610

    
611
  def ModifyCluster(self, **kwargs):
612
    """Modifies cluster parameters.
613

614
    More details for parameters can be found in the RAPI documentation.
615

616
    @rtype: string
617
    @return: job id
618

619
    """
620
    body = kwargs
621

    
622
    return self._SendRequest(HTTP_PUT,
623
                             "/%s/modify" % GANETI_RAPI_VERSION, None, body)
624

    
625
  def GetClusterTags(self):
626
    """Gets the cluster tags.
627

628
    @rtype: list of str
629
    @return: cluster tags
630

631
    """
632
    return self._SendRequest(HTTP_GET, "/%s/tags" % GANETI_RAPI_VERSION,
633
                             None, None)
634

    
635
  def AddClusterTags(self, tags, dry_run=False):
636
    """Adds tags to the cluster.
637

638
    @type tags: list of str
639
    @param tags: tags to add to the cluster
640
    @type dry_run: bool
641
    @param dry_run: whether to perform a dry run
642

643
    @rtype: string
644
    @return: job id
645

646
    """
647
    query = [("tag", t) for t in tags]
648
    _AppendDryRunIf(query, dry_run)
649

    
650
    return self._SendRequest(HTTP_PUT, "/%s/tags" % GANETI_RAPI_VERSION,
651
                             query, None)
652

    
653
  def DeleteClusterTags(self, tags, dry_run=False):
654
    """Deletes tags from the cluster.
655

656
    @type tags: list of str
657
    @param tags: tags to delete
658
    @type dry_run: bool
659
    @param dry_run: whether to perform a dry run
660
    @rtype: string
661
    @return: job id
662

663
    """
664
    query = [("tag", t) for t in tags]
665
    _AppendDryRunIf(query, dry_run)
666

    
667
    return self._SendRequest(HTTP_DELETE, "/%s/tags" % GANETI_RAPI_VERSION,
668
                             query, None)
669

    
670
  def GetInstances(self, bulk=False):
671
    """Gets information about instances on the cluster.
672

673
    @type bulk: bool
674
    @param bulk: whether to return all information about all instances
675

676
    @rtype: list of dict or list of str
677
    @return: if bulk is True, info about the instances, else a list of instances
678

679
    """
680
    query = []
681
    _AppendIf(query, bulk, ("bulk", 1))
682

    
683
    instances = self._SendRequest(HTTP_GET,
684
                                  "/%s/instances" % GANETI_RAPI_VERSION,
685
                                  query, None)
686
    if bulk:
687
      return instances
688
    else:
689
      return [i["id"] for i in instances]
690

    
691
  def GetInstance(self, instance):
692
    """Gets information about an instance.
693

694
    @type instance: str
695
    @param instance: instance whose info to return
696

697
    @rtype: dict
698
    @return: info about the instance
699

700
    """
701
    return self._SendRequest(HTTP_GET,
702
                             ("/%s/instances/%s" %
703
                              (GANETI_RAPI_VERSION, instance)), None, None)
704

    
705
  def GetInstanceInfo(self, instance, static=None):
706
    """Gets information about an instance.
707

708
    @type instance: string
709
    @param instance: Instance name
710
    @rtype: string
711
    @return: Job ID
712

713
    """
714
    if static is not None:
715
      query = [("static", static)]
716
    else:
717
      query = None
718

    
719
    return self._SendRequest(HTTP_GET,
720
                             ("/%s/instances/%s/info" %
721
                              (GANETI_RAPI_VERSION, instance)), query, None)
722

    
723
  @staticmethod
724
  def _UpdateWithKwargs(base, **kwargs):
725
    """Updates the base with params from kwargs.
726

727
    @param base: The base dict, filled with required fields
728

729
    @note: This is an inplace update of base
730

731
    """
732
    conflicts = set(kwargs.iterkeys()) & set(base.iterkeys())
733
    if conflicts:
734
      raise GanetiApiError("Required fields can not be specified as"
735
                           " keywords: %s" % ", ".join(conflicts))
736

    
737
    base.update((key, value) for key, value in kwargs.iteritems()
738
                if key != "dry_run")
739

    
740
  def InstanceAllocation(self, mode, name, disk_template, disks, nics,
741
                         **kwargs):
742
    """Generates an instance allocation as used by multiallocate.
743

744
    More details for parameters can be found in the RAPI documentation.
745
    It is the same as used by CreateInstance.
746

747
    @type mode: string
748
    @param mode: Instance creation mode
749
    @type name: string
750
    @param name: Hostname of the instance to create
751
    @type disk_template: string
752
    @param disk_template: Disk template for instance (e.g. plain, diskless,
753
                          file, or drbd)
754
    @type disks: list of dicts
755
    @param disks: List of disk definitions
756
    @type nics: list of dicts
757
    @param nics: List of NIC definitions
758

759
    @return: A dict with the generated entry
760

761
    """
762
    # All required fields for request data version 1
763
    alloc = {
764
      "mode": mode,
765
      "name": name,
766
      "disk_template": disk_template,
767
      "disks": disks,
768
      "nics": nics,
769
      }
770

    
771
    self._UpdateWithKwargs(alloc, **kwargs)
772

    
773
    return alloc
774

    
775
  def InstancesMultiAlloc(self, instances, **kwargs):
776
    """Tries to allocate multiple instances.
777

778
    More details for parameters can be found in the RAPI documentation.
779

780
    @param instances: A list of L{InstanceAllocation} results
781

782
    """
783
    query = []
784
    body = {
785
      "instances": instances,
786
      }
787
    self._UpdateWithKwargs(body, **kwargs)
788

    
789
    _AppendDryRunIf(query, kwargs.get("dry_run"))
790

    
791
    return self._SendRequest(HTTP_POST,
792
                             "/%s/instances-multi-alloc" % GANETI_RAPI_VERSION,
793
                             query, body)
794

    
795
  def CreateInstance(self, mode, name, disk_template, disks, nics,
796
                     **kwargs):
797
    """Creates a new instance.
798

799
    More details for parameters can be found in the RAPI documentation.
800

801
    @type mode: string
802
    @param mode: Instance creation mode
803
    @type name: string
804
    @param name: Hostname of the instance to create
805
    @type disk_template: string
806
    @param disk_template: Disk template for instance (e.g. plain, diskless,
807
                          file, or drbd)
808
    @type disks: list of dicts
809
    @param disks: List of disk definitions
810
    @type nics: list of dicts
811
    @param nics: List of NIC definitions
812
    @type dry_run: bool
813
    @keyword dry_run: whether to perform a dry run
814

815
    @rtype: string
816
    @return: job id
817

818
    """
819
    query = []
820

    
821
    _AppendDryRunIf(query, kwargs.get("dry_run"))
822

    
823
    if _INST_CREATE_REQV1 in self.GetFeatures():
824
      body = self.InstanceAllocation(mode, name, disk_template, disks, nics,
825
                                     **kwargs)
826
      body[_REQ_DATA_VERSION_FIELD] = 1
827
    else:
828
      raise GanetiApiError("Server does not support new-style (version 1)"
829
                           " instance creation requests")
830

    
831
    return self._SendRequest(HTTP_POST, "/%s/instances" % GANETI_RAPI_VERSION,
832
                             query, body)
833

    
834
  def DeleteInstance(self, instance, dry_run=False):
835
    """Deletes an instance.
836

837
    @type instance: str
838
    @param instance: the instance to delete
839

840
    @rtype: string
841
    @return: job id
842

843
    """
844
    query = []
845
    _AppendDryRunIf(query, dry_run)
846

    
847
    return self._SendRequest(HTTP_DELETE,
848
                             ("/%s/instances/%s" %
849
                              (GANETI_RAPI_VERSION, instance)), query, None)
850

    
851
  def ModifyInstance(self, instance, **kwargs):
852
    """Modifies an instance.
853

854
    More details for parameters can be found in the RAPI documentation.
855

856
    @type instance: string
857
    @param instance: Instance name
858
    @rtype: string
859
    @return: job id
860

861
    """
862
    body = kwargs
863

    
864
    return self._SendRequest(HTTP_PUT,
865
                             ("/%s/instances/%s/modify" %
866
                              (GANETI_RAPI_VERSION, instance)), None, body)
867

    
868
  def ActivateInstanceDisks(self, instance, ignore_size=None):
869
    """Activates an instance's disks.
870

871
    @type instance: string
872
    @param instance: Instance name
873
    @type ignore_size: bool
874
    @param ignore_size: Whether to ignore recorded size
875
    @rtype: string
876
    @return: job id
877

878
    """
879
    query = []
880
    _AppendIf(query, ignore_size, ("ignore_size", 1))
881

    
882
    return self._SendRequest(HTTP_PUT,
883
                             ("/%s/instances/%s/activate-disks" %
884
                              (GANETI_RAPI_VERSION, instance)), query, None)
885

    
886
  def DeactivateInstanceDisks(self, instance):
887
    """Deactivates an instance's disks.
888

889
    @type instance: string
890
    @param instance: Instance name
891
    @rtype: string
892
    @return: job id
893

894
    """
895
    return self._SendRequest(HTTP_PUT,
896
                             ("/%s/instances/%s/deactivate-disks" %
897
                              (GANETI_RAPI_VERSION, instance)), None, None)
898

    
899
  def RecreateInstanceDisks(self, instance, disks=None, nodes=None):
900
    """Recreate an instance's disks.
901

902
    @type instance: string
903
    @param instance: Instance name
904
    @type disks: list of int
905
    @param disks: List of disk indexes
906
    @type nodes: list of string
907
    @param nodes: New instance nodes, if relocation is desired
908
    @rtype: string
909
    @return: job id
910

911
    """
912
    body = {}
913
    _SetItemIf(body, disks is not None, "disks", disks)
914
    _SetItemIf(body, nodes is not None, "nodes", nodes)
915

    
916
    return self._SendRequest(HTTP_POST,
917
                             ("/%s/instances/%s/recreate-disks" %
918
                              (GANETI_RAPI_VERSION, instance)), None, body)
919

    
920
  def GrowInstanceDisk(self, instance, disk, amount, wait_for_sync=None):
921
    """Grows a disk of an instance.
922

923
    More details for parameters can be found in the RAPI documentation.
924

925
    @type instance: string
926
    @param instance: Instance name
927
    @type disk: integer
928
    @param disk: Disk index
929
    @type amount: integer
930
    @param amount: Grow disk by this amount (MiB)
931
    @type wait_for_sync: bool
932
    @param wait_for_sync: Wait for disk to synchronize
933
    @rtype: string
934
    @return: job id
935

936
    """
937
    body = {
938
      "amount": amount,
939
      }
940

    
941
    _SetItemIf(body, wait_for_sync is not None, "wait_for_sync", wait_for_sync)
942

    
943
    return self._SendRequest(HTTP_POST,
944
                             ("/%s/instances/%s/disk/%s/grow" %
945
                              (GANETI_RAPI_VERSION, instance, disk)),
946
                             None, body)
947

    
948
  def GetInstanceTags(self, instance):
949
    """Gets tags for an instance.
950

951
    @type instance: str
952
    @param instance: instance whose tags to return
953

954
    @rtype: list of str
955
    @return: tags for the instance
956

957
    """
958
    return self._SendRequest(HTTP_GET,
959
                             ("/%s/instances/%s/tags" %
960
                              (GANETI_RAPI_VERSION, instance)), None, None)
961

    
962
  def AddInstanceTags(self, instance, tags, dry_run=False):
963
    """Adds tags to an instance.
964

965
    @type instance: str
966
    @param instance: instance to add tags to
967
    @type tags: list of str
968
    @param tags: tags to add to the instance
969
    @type dry_run: bool
970
    @param dry_run: whether to perform a dry run
971

972
    @rtype: string
973
    @return: job id
974

975
    """
976
    query = [("tag", t) for t in tags]
977
    _AppendDryRunIf(query, dry_run)
978

    
979
    return self._SendRequest(HTTP_PUT,
980
                             ("/%s/instances/%s/tags" %
981
                              (GANETI_RAPI_VERSION, instance)), query, None)
982

    
983
  def DeleteInstanceTags(self, instance, tags, dry_run=False):
984
    """Deletes tags from an instance.
985

986
    @type instance: str
987
    @param instance: instance to delete tags from
988
    @type tags: list of str
989
    @param tags: tags to delete
990
    @type dry_run: bool
991
    @param dry_run: whether to perform a dry run
992
    @rtype: string
993
    @return: job id
994

995
    """
996
    query = [("tag", t) for t in tags]
997
    _AppendDryRunIf(query, dry_run)
998

    
999
    return self._SendRequest(HTTP_DELETE,
1000
                             ("/%s/instances/%s/tags" %
1001
                              (GANETI_RAPI_VERSION, instance)), query, None)
1002

    
1003
  def RebootInstance(self, instance, reboot_type=None, ignore_secondaries=None,
1004
                     dry_run=False, reason=None):
1005
    """Reboots an instance.
1006

1007
    @type instance: str
1008
    @param instance: instance to reboot
1009
    @type reboot_type: str
1010
    @param reboot_type: one of: hard, soft, full
1011
    @type ignore_secondaries: bool
1012
    @param ignore_secondaries: if True, ignores errors for the secondary node
1013
        while re-assembling disks (in hard-reboot mode only)
1014
    @type dry_run: bool
1015
    @param dry_run: whether to perform a dry run
1016
    @type reason: string
1017
    @param reason: the reason for the reboot
1018
    @rtype: string
1019
    @return: job id
1020

1021
    """
1022
    query = []
1023
    _AppendDryRunIf(query, dry_run)
1024
    _AppendIf(query, reboot_type, ("type", reboot_type))
1025
    _AppendIf(query, ignore_secondaries is not None,
1026
              ("ignore_secondaries", ignore_secondaries))
1027
    _AppendIf(query, reason, ("reason", reason))
1028

    
1029
    return self._SendRequest(HTTP_POST,
1030
                             ("/%s/instances/%s/reboot" %
1031
                              (GANETI_RAPI_VERSION, instance)), query, None)
1032

    
1033
  def ShutdownInstance(self, instance, dry_run=False, no_remember=False,
1034
                       reason=None, **kwargs):
1035
    """Shuts down an instance.
1036

1037
    @type instance: str
1038
    @param instance: the instance to shut down
1039
    @type dry_run: bool
1040
    @param dry_run: whether to perform a dry run
1041
    @type no_remember: bool
1042
    @param no_remember: if true, will not record the state change
1043
    @type reason: string
1044
    @param reason: the reason for the shutdown
1045
    @rtype: string
1046
    @return: job id
1047

1048
    """
1049
    query = []
1050
    body = kwargs
1051

    
1052
    _AppendDryRunIf(query, dry_run)
1053
    _AppendIf(query, no_remember, ("no_remember", 1))
1054
    _AppendIf(query, reason, ("reason", reason))
1055

    
1056
    return self._SendRequest(HTTP_PUT,
1057
                             ("/%s/instances/%s/shutdown" %
1058
                              (GANETI_RAPI_VERSION, instance)), query, body)
1059

    
1060
  def StartupInstance(self, instance, dry_run=False, no_remember=False):
1061
    """Starts up an instance.
1062

1063
    @type instance: str
1064
    @param instance: the instance to start up
1065
    @type dry_run: bool
1066
    @param dry_run: whether to perform a dry run
1067
    @type no_remember: bool
1068
    @param no_remember: if true, will not record the state change
1069
    @rtype: string
1070
    @return: job id
1071

1072
    """
1073
    query = []
1074
    _AppendDryRunIf(query, dry_run)
1075
    _AppendIf(query, no_remember, ("no_remember", 1))
1076

    
1077
    return self._SendRequest(HTTP_PUT,
1078
                             ("/%s/instances/%s/startup" %
1079
                              (GANETI_RAPI_VERSION, instance)), query, None)
1080

    
1081
  def ReinstallInstance(self, instance, os=None, no_startup=False,
1082
                        osparams=None):
1083
    """Reinstalls an instance.
1084

1085
    @type instance: str
1086
    @param instance: The instance to reinstall
1087
    @type os: str or None
1088
    @param os: The operating system to reinstall. If None, the instance's
1089
        current operating system will be installed again
1090
    @type no_startup: bool
1091
    @param no_startup: Whether to start the instance automatically
1092
    @rtype: string
1093
    @return: job id
1094

1095
    """
1096
    if _INST_REINSTALL_REQV1 in self.GetFeatures():
1097
      body = {
1098
        "start": not no_startup,
1099
        }
1100
      _SetItemIf(body, os is not None, "os", os)
1101
      _SetItemIf(body, osparams is not None, "osparams", osparams)
1102
      return self._SendRequest(HTTP_POST,
1103
                               ("/%s/instances/%s/reinstall" %
1104
                                (GANETI_RAPI_VERSION, instance)), None, body)
1105

    
1106
    # Use old request format
1107
    if osparams:
1108
      raise GanetiApiError("Server does not support specifying OS parameters"
1109
                           " for instance reinstallation")
1110

    
1111
    query = []
1112
    _AppendIf(query, os, ("os", os))
1113
    _AppendIf(query, no_startup, ("nostartup", 1))
1114

    
1115
    return self._SendRequest(HTTP_POST,
1116
                             ("/%s/instances/%s/reinstall" %
1117
                              (GANETI_RAPI_VERSION, instance)), query, None)
1118

    
1119
  def ReplaceInstanceDisks(self, instance, disks=None, mode=REPLACE_DISK_AUTO,
1120
                           remote_node=None, iallocator=None):
1121
    """Replaces disks on an instance.
1122

1123
    @type instance: str
1124
    @param instance: instance whose disks to replace
1125
    @type disks: list of ints
1126
    @param disks: Indexes of disks to replace
1127
    @type mode: str
1128
    @param mode: replacement mode to use (defaults to replace_auto)
1129
    @type remote_node: str or None
1130
    @param remote_node: new secondary node to use (for use with
1131
        replace_new_secondary mode)
1132
    @type iallocator: str or None
1133
    @param iallocator: instance allocator plugin to use (for use with
1134
                       replace_auto mode)
1135

1136
    @rtype: string
1137
    @return: job id
1138

1139
    """
1140
    query = [
1141
      ("mode", mode),
1142
      ]
1143

    
1144
    # TODO: Convert to body parameters
1145

    
1146
    if disks is not None:
1147
      _AppendIf(query, True,
1148
                ("disks", ",".join(str(idx) for idx in disks)))
1149

    
1150
    _AppendIf(query, remote_node is not None, ("remote_node", remote_node))
1151
    _AppendIf(query, iallocator is not None, ("iallocator", iallocator))
1152

    
1153
    return self._SendRequest(HTTP_POST,
1154
                             ("/%s/instances/%s/replace-disks" %
1155
                              (GANETI_RAPI_VERSION, instance)), query, None)
1156

    
1157
  def PrepareExport(self, instance, mode):
1158
    """Prepares an instance for an export.
1159

1160
    @type instance: string
1161
    @param instance: Instance name
1162
    @type mode: string
1163
    @param mode: Export mode
1164
    @rtype: string
1165
    @return: Job ID
1166

1167
    """
1168
    query = [("mode", mode)]
1169
    return self._SendRequest(HTTP_PUT,
1170
                             ("/%s/instances/%s/prepare-export" %
1171
                              (GANETI_RAPI_VERSION, instance)), query, None)
1172

    
1173
  def ExportInstance(self, instance, mode, destination, shutdown=None,
1174
                     remove_instance=None,
1175
                     x509_key_name=None, destination_x509_ca=None):
1176
    """Exports an instance.
1177

1178
    @type instance: string
1179
    @param instance: Instance name
1180
    @type mode: string
1181
    @param mode: Export mode
1182
    @rtype: string
1183
    @return: Job ID
1184

1185
    """
1186
    body = {
1187
      "destination": destination,
1188
      "mode": mode,
1189
      }
1190

    
1191
    _SetItemIf(body, shutdown is not None, "shutdown", shutdown)
1192
    _SetItemIf(body, remove_instance is not None,
1193
               "remove_instance", remove_instance)
1194
    _SetItemIf(body, x509_key_name is not None, "x509_key_name", x509_key_name)
1195
    _SetItemIf(body, destination_x509_ca is not None,
1196
               "destination_x509_ca", destination_x509_ca)
1197

    
1198
    return self._SendRequest(HTTP_PUT,
1199
                             ("/%s/instances/%s/export" %
1200
                              (GANETI_RAPI_VERSION, instance)), None, body)
1201

    
1202
  def MigrateInstance(self, instance, mode=None, cleanup=None,
1203
                      target_node=None):
1204
    """Migrates an instance.
1205

1206
    @type instance: string
1207
    @param instance: Instance name
1208
    @type mode: string
1209
    @param mode: Migration mode
1210
    @type cleanup: bool
1211
    @param cleanup: Whether to clean up a previously failed migration
1212
    @type target_node: string
1213
    @param target_node: Target Node for externally mirrored instances
1214
    @rtype: string
1215
    @return: job id
1216

1217
    """
1218
    body = {}
1219
    _SetItemIf(body, mode is not None, "mode", mode)
1220
    _SetItemIf(body, cleanup is not None, "cleanup", cleanup)
1221
    _SetItemIf(body, target_node is not None, "target_node", target_node)
1222

    
1223
    return self._SendRequest(HTTP_PUT,
1224
                             ("/%s/instances/%s/migrate" %
1225
                              (GANETI_RAPI_VERSION, instance)), None, body)
1226

    
1227
  def FailoverInstance(self, instance, iallocator=None,
1228
                       ignore_consistency=None, target_node=None):
1229
    """Does a failover of an instance.
1230

1231
    @type instance: string
1232
    @param instance: Instance name
1233
    @type iallocator: string
1234
    @param iallocator: Iallocator for deciding the target node for
1235
      shared-storage instances
1236
    @type ignore_consistency: bool
1237
    @param ignore_consistency: Whether to ignore disk consistency
1238
    @type target_node: string
1239
    @param target_node: Target node for shared-storage instances
1240
    @rtype: string
1241
    @return: job id
1242

1243
    """
1244
    body = {}
1245
    _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1246
    _SetItemIf(body, ignore_consistency is not None,
1247
               "ignore_consistency", ignore_consistency)
1248
    _SetItemIf(body, target_node is not None, "target_node", target_node)
1249

    
1250
    return self._SendRequest(HTTP_PUT,
1251
                             ("/%s/instances/%s/failover" %
1252
                              (GANETI_RAPI_VERSION, instance)), None, body)
1253

    
1254
  def RenameInstance(self, instance, new_name, ip_check=None, name_check=None):
1255
    """Changes the name of an instance.
1256

1257
    @type instance: string
1258
    @param instance: Instance name
1259
    @type new_name: string
1260
    @param new_name: New instance name
1261
    @type ip_check: bool
1262
    @param ip_check: Whether to ensure instance's IP address is inactive
1263
    @type name_check: bool
1264
    @param name_check: Whether to ensure instance's name is resolvable
1265
    @rtype: string
1266
    @return: job id
1267

1268
    """
1269
    body = {
1270
      "new_name": new_name,
1271
      }
1272

    
1273
    _SetItemIf(body, ip_check is not None, "ip_check", ip_check)
1274
    _SetItemIf(body, name_check is not None, "name_check", name_check)
1275

    
1276
    return self._SendRequest(HTTP_PUT,
1277
                             ("/%s/instances/%s/rename" %
1278
                              (GANETI_RAPI_VERSION, instance)), None, body)
1279

    
1280
  def GetInstanceConsole(self, instance):
1281
    """Request information for connecting to instance's console.
1282

1283
    @type instance: string
1284
    @param instance: Instance name
1285
    @rtype: dict
1286
    @return: dictionary containing information about instance's console
1287

1288
    """
1289
    return self._SendRequest(HTTP_GET,
1290
                             ("/%s/instances/%s/console" %
1291
                              (GANETI_RAPI_VERSION, instance)), None, None)
1292

    
1293
  def GetJobs(self):
1294
    """Gets all jobs for the cluster.
1295

1296
    @rtype: list of int
1297
    @return: job ids for the cluster
1298

1299
    """
1300
    return [int(j["id"])
1301
            for j in self._SendRequest(HTTP_GET,
1302
                                       "/%s/jobs" % GANETI_RAPI_VERSION,
1303
                                       None, None)]
1304

    
1305
  def GetJobStatus(self, job_id):
1306
    """Gets the status of a job.
1307

1308
    @type job_id: string
1309
    @param job_id: job id whose status to query
1310

1311
    @rtype: dict
1312
    @return: job status
1313

1314
    """
1315
    return self._SendRequest(HTTP_GET,
1316
                             "/%s/jobs/%s" % (GANETI_RAPI_VERSION, job_id),
1317
                             None, None)
1318

    
1319
  def WaitForJobCompletion(self, job_id, period=5, retries=-1):
1320
    """Polls cluster for job status until completion.
1321

1322
    Completion is defined as any of the following states listed in
1323
    L{JOB_STATUS_FINALIZED}.
1324

1325
    @type job_id: string
1326
    @param job_id: job id to watch
1327
    @type period: int
1328
    @param period: how often to poll for status (optional, default 5s)
1329
    @type retries: int
1330
    @param retries: how many time to poll before giving up
1331
                    (optional, default -1 means unlimited)
1332

1333
    @rtype: bool
1334
    @return: C{True} if job succeeded or C{False} if failed/status timeout
1335
    @deprecated: It is recommended to use L{WaitForJobChange} wherever
1336
      possible; L{WaitForJobChange} returns immediately after a job changed and
1337
      does not use polling
1338

1339
    """
1340
    while retries != 0:
1341
      job_result = self.GetJobStatus(job_id)
1342

    
1343
      if job_result and job_result["status"] == JOB_STATUS_SUCCESS:
1344
        return True
1345
      elif not job_result or job_result["status"] in JOB_STATUS_FINALIZED:
1346
        return False
1347

    
1348
      if period:
1349
        time.sleep(period)
1350

    
1351
      if retries > 0:
1352
        retries -= 1
1353

    
1354
    return False
1355

    
1356
  def WaitForJobChange(self, job_id, fields, prev_job_info, prev_log_serial):
1357
    """Waits for job changes.
1358

1359
    @type job_id: string
1360
    @param job_id: Job ID for which to wait
1361
    @return: C{None} if no changes have been detected and a dict with two keys,
1362
      C{job_info} and C{log_entries} otherwise.
1363
    @rtype: dict
1364

1365
    """
1366
    body = {
1367
      "fields": fields,
1368
      "previous_job_info": prev_job_info,
1369
      "previous_log_serial": prev_log_serial,
1370
      }
1371

    
1372
    return self._SendRequest(HTTP_GET,
1373
                             "/%s/jobs/%s/wait" % (GANETI_RAPI_VERSION, job_id),
1374
                             None, body)
1375

    
1376
  def CancelJob(self, job_id, dry_run=False):
1377
    """Cancels a job.
1378

1379
    @type job_id: string
1380
    @param job_id: id of the job to delete
1381
    @type dry_run: bool
1382
    @param dry_run: whether to perform a dry run
1383
    @rtype: tuple
1384
    @return: tuple containing the result, and a message (bool, string)
1385

1386
    """
1387
    query = []
1388
    _AppendDryRunIf(query, dry_run)
1389

    
1390
    return self._SendRequest(HTTP_DELETE,
1391
                             "/%s/jobs/%s" % (GANETI_RAPI_VERSION, job_id),
1392
                             query, None)
1393

    
1394
  def GetNodes(self, bulk=False):
1395
    """Gets all nodes in the cluster.
1396

1397
    @type bulk: bool
1398
    @param bulk: whether to return all information about all instances
1399

1400
    @rtype: list of dict or str
1401
    @return: if bulk is true, info about nodes in the cluster,
1402
        else list of nodes in the cluster
1403

1404
    """
1405
    query = []
1406
    _AppendIf(query, bulk, ("bulk", 1))
1407

    
1408
    nodes = self._SendRequest(HTTP_GET, "/%s/nodes" % GANETI_RAPI_VERSION,
1409
                              query, None)
1410
    if bulk:
1411
      return nodes
1412
    else:
1413
      return [n["id"] for n in nodes]
1414

    
1415
  def GetNode(self, node):
1416
    """Gets information about a node.
1417

1418
    @type node: str
1419
    @param node: node whose info to return
1420

1421
    @rtype: dict
1422
    @return: info about the node
1423

1424
    """
1425
    return self._SendRequest(HTTP_GET,
1426
                             "/%s/nodes/%s" % (GANETI_RAPI_VERSION, node),
1427
                             None, None)
1428

    
1429
  def EvacuateNode(self, node, iallocator=None, remote_node=None,
1430
                   dry_run=False, early_release=None,
1431
                   mode=None, accept_old=False):
1432
    """Evacuates instances from a Ganeti node.
1433

1434
    @type node: str
1435
    @param node: node to evacuate
1436
    @type iallocator: str or None
1437
    @param iallocator: instance allocator to use
1438
    @type remote_node: str
1439
    @param remote_node: node to evaucate to
1440
    @type dry_run: bool
1441
    @param dry_run: whether to perform a dry run
1442
    @type early_release: bool
1443
    @param early_release: whether to enable parallelization
1444
    @type mode: string
1445
    @param mode: Node evacuation mode
1446
    @type accept_old: bool
1447
    @param accept_old: Whether caller is ready to accept old-style (pre-2.5)
1448
        results
1449

1450
    @rtype: string, or a list for pre-2.5 results
1451
    @return: Job ID or, if C{accept_old} is set and server is pre-2.5,
1452
      list of (job ID, instance name, new secondary node); if dry_run was
1453
      specified, then the actual move jobs were not submitted and the job IDs
1454
      will be C{None}
1455

1456
    @raises GanetiApiError: if an iallocator and remote_node are both
1457
        specified
1458

1459
    """
1460
    if iallocator and remote_node:
1461
      raise GanetiApiError("Only one of iallocator or remote_node can be used")
1462

    
1463
    query = []
1464
    _AppendDryRunIf(query, dry_run)
1465

    
1466
    if _NODE_EVAC_RES1 in self.GetFeatures():
1467
      # Server supports body parameters
1468
      body = {}
1469

    
1470
      _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1471
      _SetItemIf(body, remote_node is not None, "remote_node", remote_node)
1472
      _SetItemIf(body, early_release is not None,
1473
                 "early_release", early_release)
1474
      _SetItemIf(body, mode is not None, "mode", mode)
1475
    else:
1476
      # Pre-2.5 request format
1477
      body = None
1478

    
1479
      if not accept_old:
1480
        raise GanetiApiError("Server is version 2.4 or earlier and caller does"
1481
                             " not accept old-style results (parameter"
1482
                             " accept_old)")
1483

    
1484
      # Pre-2.5 servers can only evacuate secondaries
1485
      if mode is not None and mode != NODE_EVAC_SEC:
1486
        raise GanetiApiError("Server can only evacuate secondary instances")
1487

    
1488
      _AppendIf(query, iallocator, ("iallocator", iallocator))
1489
      _AppendIf(query, remote_node, ("remote_node", remote_node))
1490
      _AppendIf(query, early_release, ("early_release", 1))
1491

    
1492
    return self._SendRequest(HTTP_POST,
1493
                             ("/%s/nodes/%s/evacuate" %
1494
                              (GANETI_RAPI_VERSION, node)), query, body)
1495

    
1496
  def MigrateNode(self, node, mode=None, dry_run=False, iallocator=None,
1497
                  target_node=None):
1498
    """Migrates all primary instances from a node.
1499

1500
    @type node: str
1501
    @param node: node to migrate
1502
    @type mode: string
1503
    @param mode: if passed, it will overwrite the live migration type,
1504
        otherwise the hypervisor default will be used
1505
    @type dry_run: bool
1506
    @param dry_run: whether to perform a dry run
1507
    @type iallocator: string
1508
    @param iallocator: instance allocator to use
1509
    @type target_node: string
1510
    @param target_node: Target node for shared-storage instances
1511

1512
    @rtype: string
1513
    @return: job id
1514

1515
    """
1516
    query = []
1517
    _AppendDryRunIf(query, dry_run)
1518

    
1519
    if _NODE_MIGRATE_REQV1 in self.GetFeatures():
1520
      body = {}
1521

    
1522
      _SetItemIf(body, mode is not None, "mode", mode)
1523
      _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1524
      _SetItemIf(body, target_node is not None, "target_node", target_node)
1525

    
1526
      assert len(query) <= 1
1527

    
1528
      return self._SendRequest(HTTP_POST,
1529
                               ("/%s/nodes/%s/migrate" %
1530
                                (GANETI_RAPI_VERSION, node)), query, body)
1531
    else:
1532
      # Use old request format
1533
      if target_node is not None:
1534
        raise GanetiApiError("Server does not support specifying target node"
1535
                             " for node migration")
1536

    
1537
      _AppendIf(query, mode is not None, ("mode", mode))
1538

    
1539
      return self._SendRequest(HTTP_POST,
1540
                               ("/%s/nodes/%s/migrate" %
1541
                                (GANETI_RAPI_VERSION, node)), query, None)
1542

    
1543
  def GetNodeRole(self, node):
1544
    """Gets the current role for a node.
1545

1546
    @type node: str
1547
    @param node: node whose role to return
1548

1549
    @rtype: str
1550
    @return: the current role for a node
1551

1552
    """
1553
    return self._SendRequest(HTTP_GET,
1554
                             ("/%s/nodes/%s/role" %
1555
                              (GANETI_RAPI_VERSION, node)), None, None)
1556

    
1557
  def SetNodeRole(self, node, role, force=False, auto_promote=None):
1558
    """Sets the role for a node.
1559

1560
    @type node: str
1561
    @param node: the node whose role to set
1562
    @type role: str
1563
    @param role: the role to set for the node
1564
    @type force: bool
1565
    @param force: whether to force the role change
1566
    @type auto_promote: bool
1567
    @param auto_promote: Whether node(s) should be promoted to master candidate
1568
                         if necessary
1569

1570
    @rtype: string
1571
    @return: job id
1572

1573
    """
1574
    query = []
1575
    _AppendForceIf(query, force)
1576
    _AppendIf(query, auto_promote is not None, ("auto-promote", auto_promote))
1577

    
1578
    return self._SendRequest(HTTP_PUT,
1579
                             ("/%s/nodes/%s/role" %
1580
                              (GANETI_RAPI_VERSION, node)), query, role)
1581

    
1582
  def PowercycleNode(self, node, force=False):
1583
    """Powercycles a node.
1584

1585
    @type node: string
1586
    @param node: Node name
1587
    @type force: bool
1588
    @param force: Whether to force the operation
1589
    @rtype: string
1590
    @return: job id
1591

1592
    """
1593
    query = []
1594
    _AppendForceIf(query, force)
1595

    
1596
    return self._SendRequest(HTTP_POST,
1597
                             ("/%s/nodes/%s/powercycle" %
1598
                              (GANETI_RAPI_VERSION, node)), query, None)
1599

    
1600
  def ModifyNode(self, node, **kwargs):
1601
    """Modifies a node.
1602

1603
    More details for parameters can be found in the RAPI documentation.
1604

1605
    @type node: string
1606
    @param node: Node name
1607
    @rtype: string
1608
    @return: job id
1609

1610
    """
1611
    return self._SendRequest(HTTP_POST,
1612
                             ("/%s/nodes/%s/modify" %
1613
                              (GANETI_RAPI_VERSION, node)), None, kwargs)
1614

    
1615
  def GetNodeStorageUnits(self, node, storage_type, output_fields):
1616
    """Gets the storage units for a node.
1617

1618
    @type node: str
1619
    @param node: the node whose storage units to return
1620
    @type storage_type: str
1621
    @param storage_type: storage type whose units to return
1622
    @type output_fields: str
1623
    @param output_fields: storage type fields to return
1624

1625
    @rtype: string
1626
    @return: job id where results can be retrieved
1627

1628
    """
1629
    query = [
1630
      ("storage_type", storage_type),
1631
      ("output_fields", output_fields),
1632
      ]
1633

    
1634
    return self._SendRequest(HTTP_GET,
1635
                             ("/%s/nodes/%s/storage" %
1636
                              (GANETI_RAPI_VERSION, node)), query, None)
1637

    
1638
  def ModifyNodeStorageUnits(self, node, storage_type, name, allocatable=None):
1639
    """Modifies parameters of storage units on the node.
1640

1641
    @type node: str
1642
    @param node: node whose storage units to modify
1643
    @type storage_type: str
1644
    @param storage_type: storage type whose units to modify
1645
    @type name: str
1646
    @param name: name of the storage unit
1647
    @type allocatable: bool or None
1648
    @param allocatable: Whether to set the "allocatable" flag on the storage
1649
                        unit (None=no modification, True=set, False=unset)
1650

1651
    @rtype: string
1652
    @return: job id
1653

1654
    """
1655
    query = [
1656
      ("storage_type", storage_type),
1657
      ("name", name),
1658
      ]
1659

    
1660
    _AppendIf(query, allocatable is not None, ("allocatable", allocatable))
1661

    
1662
    return self._SendRequest(HTTP_PUT,
1663
                             ("/%s/nodes/%s/storage/modify" %
1664
                              (GANETI_RAPI_VERSION, node)), query, None)
1665

    
1666
  def RepairNodeStorageUnits(self, node, storage_type, name):
1667
    """Repairs a storage unit on the node.
1668

1669
    @type node: str
1670
    @param node: node whose storage units to repair
1671
    @type storage_type: str
1672
    @param storage_type: storage type to repair
1673
    @type name: str
1674
    @param name: name of the storage unit to repair
1675

1676
    @rtype: string
1677
    @return: job id
1678

1679
    """
1680
    query = [
1681
      ("storage_type", storage_type),
1682
      ("name", name),
1683
      ]
1684

    
1685
    return self._SendRequest(HTTP_PUT,
1686
                             ("/%s/nodes/%s/storage/repair" %
1687
                              (GANETI_RAPI_VERSION, node)), query, None)
1688

    
1689
  def GetNodeTags(self, node):
1690
    """Gets the tags for a node.
1691

1692
    @type node: str
1693
    @param node: node whose tags to return
1694

1695
    @rtype: list of str
1696
    @return: tags for the node
1697

1698
    """
1699
    return self._SendRequest(HTTP_GET,
1700
                             ("/%s/nodes/%s/tags" %
1701
                              (GANETI_RAPI_VERSION, node)), None, None)
1702

    
1703
  def AddNodeTags(self, node, tags, dry_run=False):
1704
    """Adds tags to a node.
1705

1706
    @type node: str
1707
    @param node: node to add tags to
1708
    @type tags: list of str
1709
    @param tags: tags to add to the node
1710
    @type dry_run: bool
1711
    @param dry_run: whether to perform a dry run
1712

1713
    @rtype: string
1714
    @return: job id
1715

1716
    """
1717
    query = [("tag", t) for t in tags]
1718
    _AppendDryRunIf(query, dry_run)
1719

    
1720
    return self._SendRequest(HTTP_PUT,
1721
                             ("/%s/nodes/%s/tags" %
1722
                              (GANETI_RAPI_VERSION, node)), query, tags)
1723

    
1724
  def DeleteNodeTags(self, node, tags, dry_run=False):
1725
    """Delete tags from a node.
1726

1727
    @type node: str
1728
    @param node: node to remove tags from
1729
    @type tags: list of str
1730
    @param tags: tags to remove from the node
1731
    @type dry_run: bool
1732
    @param dry_run: whether to perform a dry run
1733

1734
    @rtype: string
1735
    @return: job id
1736

1737
    """
1738
    query = [("tag", t) for t in tags]
1739
    _AppendDryRunIf(query, dry_run)
1740

    
1741
    return self._SendRequest(HTTP_DELETE,
1742
                             ("/%s/nodes/%s/tags" %
1743
                              (GANETI_RAPI_VERSION, node)), query, None)
1744

    
1745
  def GetNetworks(self, bulk=False):
1746
    """Gets all networks in the cluster.
1747

1748
    @type bulk: bool
1749
    @param bulk: whether to return all information about the networks
1750

1751
    @rtype: list of dict or str
1752
    @return: if bulk is true, a list of dictionaries with info about all
1753
        networks in the cluster, else a list of names of those networks
1754

1755
    """
1756
    query = []
1757
    _AppendIf(query, bulk, ("bulk", 1))
1758

    
1759
    networks = self._SendRequest(HTTP_GET, "/%s/networks" % GANETI_RAPI_VERSION,
1760
                                 query, None)
1761
    if bulk:
1762
      return networks
1763
    else:
1764
      return [n["name"] for n in networks]
1765

    
1766
  def GetNetwork(self, network):
1767
    """Gets information about a network.
1768

1769
    @type network: str
1770
    @param network: name of the network whose info to return
1771

1772
    @rtype: dict
1773
    @return: info about the network
1774

1775
    """
1776
    return self._SendRequest(HTTP_GET,
1777
                             "/%s/networks/%s" % (GANETI_RAPI_VERSION, network),
1778
                             None, None)
1779

    
1780
  def CreateNetwork(self, network_name, network, gateway=None, network6=None,
1781
                    gateway6=None, mac_prefix=None,
1782
                    add_reserved_ips=None, tags=None, dry_run=False):
1783
    """Creates a new network.
1784

1785
    @type network_name: str
1786
    @param network_name: the name of network to create
1787
    @type dry_run: bool
1788
    @param dry_run: whether to peform a dry run
1789

1790
    @rtype: string
1791
    @return: job id
1792

1793
    """
1794
    query = []
1795
    _AppendDryRunIf(query, dry_run)
1796

    
1797
    if add_reserved_ips:
1798
      add_reserved_ips = add_reserved_ips.split(",")
1799

    
1800
    if tags:
1801
      tags = tags.split(",")
1802

    
1803
    body = {
1804
      "network_name": network_name,
1805
      "gateway": gateway,
1806
      "network": network,
1807
      "gateway6": gateway6,
1808
      "network6": network6,
1809
      "mac_prefix": mac_prefix,
1810
      "add_reserved_ips": add_reserved_ips,
1811
      "tags": tags,
1812
      }
1813

    
1814
    return self._SendRequest(HTTP_POST, "/%s/networks" % GANETI_RAPI_VERSION,
1815
                             query, body)
1816

    
1817
  def ConnectNetwork(self, network_name, group_name, mode, link, dry_run=False):
1818
    """Connects a Network to a NodeGroup with the given netparams
1819

1820
    """
1821
    body = {
1822
      "group_name": group_name,
1823
      "network_mode": mode,
1824
      "network_link": link,
1825
      }
1826

    
1827
    query = []
1828
    _AppendDryRunIf(query, dry_run)
1829

    
1830
    return self._SendRequest(HTTP_PUT,
1831
                             ("/%s/networks/%s/connect" %
1832
                             (GANETI_RAPI_VERSION, network_name)), query, body)
1833

    
1834
  def DisconnectNetwork(self, network_name, group_name, dry_run=False):
1835
    """Connects a Network to a NodeGroup with the given netparams
1836

1837
    """
1838
    body = {
1839
      "group_name": group_name,
1840
      }
1841

    
1842
    query = []
1843
    _AppendDryRunIf(query, dry_run)
1844

    
1845
    return self._SendRequest(HTTP_PUT,
1846
                             ("/%s/networks/%s/disconnect" %
1847
                             (GANETI_RAPI_VERSION, network_name)), query, body)
1848

    
1849
  def ModifyNetwork(self, network, **kwargs):
1850
    """Modifies a network.
1851

1852
    More details for parameters can be found in the RAPI documentation.
1853

1854
    @type network: string
1855
    @param network: Network name
1856
    @rtype: string
1857
    @return: job id
1858

1859
    """
1860
    return self._SendRequest(HTTP_PUT,
1861
                             ("/%s/networks/%s/modify" %
1862
                              (GANETI_RAPI_VERSION, network)), None, kwargs)
1863

    
1864
  def DeleteNetwork(self, network, dry_run=False):
1865
    """Deletes a network.
1866

1867
    @type network: str
1868
    @param network: the network to delete
1869
    @type dry_run: bool
1870
    @param dry_run: whether to peform a dry run
1871

1872
    @rtype: string
1873
    @return: job id
1874

1875
    """
1876
    query = []
1877
    _AppendDryRunIf(query, dry_run)
1878

    
1879
    return self._SendRequest(HTTP_DELETE,
1880
                             ("/%s/networks/%s" %
1881
                              (GANETI_RAPI_VERSION, network)), query, None)
1882

    
1883
  def GetNetworkTags(self, network):
1884
    """Gets tags for a network.
1885

1886
    @type network: string
1887
    @param network: Node group whose tags to return
1888

1889
    @rtype: list of strings
1890
    @return: tags for the network
1891

1892
    """
1893
    return self._SendRequest(HTTP_GET,
1894
                             ("/%s/networks/%s/tags" %
1895
                              (GANETI_RAPI_VERSION, network)), None, None)
1896

    
1897
  def AddNetworkTags(self, network, tags, dry_run=False):
1898
    """Adds tags to a network.
1899

1900
    @type network: str
1901
    @param network: network to add tags to
1902
    @type tags: list of string
1903
    @param tags: tags to add to the network
1904
    @type dry_run: bool
1905
    @param dry_run: whether to perform a dry run
1906

1907
    @rtype: string
1908
    @return: job id
1909

1910
    """
1911
    query = [("tag", t) for t in tags]
1912
    _AppendDryRunIf(query, dry_run)
1913

    
1914
    return self._SendRequest(HTTP_PUT,
1915
                             ("/%s/networks/%s/tags" %
1916
                              (GANETI_RAPI_VERSION, network)), query, None)
1917

    
1918
  def DeleteNetworkTags(self, network, tags, dry_run=False):
1919
    """Deletes tags from a network.
1920

1921
    @type network: str
1922
    @param network: network to delete tags from
1923
    @type tags: list of string
1924
    @param tags: tags to delete
1925
    @type dry_run: bool
1926
    @param dry_run: whether to perform a dry run
1927
    @rtype: string
1928
    @return: job id
1929

1930
    """
1931
    query = [("tag", t) for t in tags]
1932
    _AppendDryRunIf(query, dry_run)
1933

    
1934
    return self._SendRequest(HTTP_DELETE,
1935
                             ("/%s/networks/%s/tags" %
1936
                              (GANETI_RAPI_VERSION, network)), query, None)
1937

    
1938
  def GetGroups(self, bulk=False):
1939
    """Gets all node groups in the cluster.
1940

1941
    @type bulk: bool
1942
    @param bulk: whether to return all information about the groups
1943

1944
    @rtype: list of dict or str
1945
    @return: if bulk is true, a list of dictionaries with info about all node
1946
        groups in the cluster, else a list of names of those node groups
1947

1948
    """
1949
    query = []
1950
    _AppendIf(query, bulk, ("bulk", 1))
1951

    
1952
    groups = self._SendRequest(HTTP_GET, "/%s/groups" % GANETI_RAPI_VERSION,
1953
                               query, None)
1954
    if bulk:
1955
      return groups
1956
    else:
1957
      return [g["name"] for g in groups]
1958

    
1959
  def GetGroup(self, group):
1960
    """Gets information about a node group.
1961

1962
    @type group: str
1963
    @param group: name of the node group whose info to return
1964

1965
    @rtype: dict
1966
    @return: info about the node group
1967

1968
    """
1969
    return self._SendRequest(HTTP_GET,
1970
                             "/%s/groups/%s" % (GANETI_RAPI_VERSION, group),
1971
                             None, None)
1972

    
1973
  def CreateGroup(self, name, alloc_policy=None, dry_run=False):
1974
    """Creates a new node group.
1975

1976
    @type name: str
1977
    @param name: the name of node group to create
1978
    @type alloc_policy: str
1979
    @param alloc_policy: the desired allocation policy for the group, if any
1980
    @type dry_run: bool
1981
    @param dry_run: whether to peform a dry run
1982

1983
    @rtype: string
1984
    @return: job id
1985

1986
    """
1987
    query = []
1988
    _AppendDryRunIf(query, dry_run)
1989

    
1990
    body = {
1991
      "name": name,
1992
      "alloc_policy": alloc_policy,
1993
      }
1994

    
1995
    return self._SendRequest(HTTP_POST, "/%s/groups" % GANETI_RAPI_VERSION,
1996
                             query, body)
1997

    
1998
  def ModifyGroup(self, group, **kwargs):
1999
    """Modifies a node group.
2000

2001
    More details for parameters can be found in the RAPI documentation.
2002

2003
    @type group: string
2004
    @param group: Node group name
2005
    @rtype: string
2006
    @return: job id
2007

2008
    """
2009
    return self._SendRequest(HTTP_PUT,
2010
                             ("/%s/groups/%s/modify" %
2011
                              (GANETI_RAPI_VERSION, group)), None, kwargs)
2012

    
2013
  def DeleteGroup(self, group, dry_run=False):
2014
    """Deletes a node group.
2015

2016
    @type group: str
2017
    @param group: the node group to delete
2018
    @type dry_run: bool
2019
    @param dry_run: whether to peform a dry run
2020

2021
    @rtype: string
2022
    @return: job id
2023

2024
    """
2025
    query = []
2026
    _AppendDryRunIf(query, dry_run)
2027

    
2028
    return self._SendRequest(HTTP_DELETE,
2029
                             ("/%s/groups/%s" %
2030
                              (GANETI_RAPI_VERSION, group)), query, None)
2031

    
2032
  def RenameGroup(self, group, new_name):
2033
    """Changes the name of a node group.
2034

2035
    @type group: string
2036
    @param group: Node group name
2037
    @type new_name: string
2038
    @param new_name: New node group name
2039

2040
    @rtype: string
2041
    @return: job id
2042

2043
    """
2044
    body = {
2045
      "new_name": new_name,
2046
      }
2047

    
2048
    return self._SendRequest(HTTP_PUT,
2049
                             ("/%s/groups/%s/rename" %
2050
                              (GANETI_RAPI_VERSION, group)), None, body)
2051

    
2052
  def AssignGroupNodes(self, group, nodes, force=False, dry_run=False):
2053
    """Assigns nodes to a group.
2054

2055
    @type group: string
2056
    @param group: Node group name
2057
    @type nodes: list of strings
2058
    @param nodes: List of nodes to assign to the group
2059

2060
    @rtype: string
2061
    @return: job id
2062

2063
    """
2064
    query = []
2065
    _AppendForceIf(query, force)
2066
    _AppendDryRunIf(query, dry_run)
2067

    
2068
    body = {
2069
      "nodes": nodes,
2070
      }
2071

    
2072
    return self._SendRequest(HTTP_PUT,
2073
                             ("/%s/groups/%s/assign-nodes" %
2074
                             (GANETI_RAPI_VERSION, group)), query, body)
2075

    
2076
  def GetGroupTags(self, group):
2077
    """Gets tags for a node group.
2078

2079
    @type group: string
2080
    @param group: Node group whose tags to return
2081

2082
    @rtype: list of strings
2083
    @return: tags for the group
2084

2085
    """
2086
    return self._SendRequest(HTTP_GET,
2087
                             ("/%s/groups/%s/tags" %
2088
                              (GANETI_RAPI_VERSION, group)), None, None)
2089

    
2090
  def AddGroupTags(self, group, tags, dry_run=False):
2091
    """Adds tags to a node group.
2092

2093
    @type group: str
2094
    @param group: group to add tags to
2095
    @type tags: list of string
2096
    @param tags: tags to add to the group
2097
    @type dry_run: bool
2098
    @param dry_run: whether to perform a dry run
2099

2100
    @rtype: string
2101
    @return: job id
2102

2103
    """
2104
    query = [("tag", t) for t in tags]
2105
    _AppendDryRunIf(query, dry_run)
2106

    
2107
    return self._SendRequest(HTTP_PUT,
2108
                             ("/%s/groups/%s/tags" %
2109
                              (GANETI_RAPI_VERSION, group)), query, None)
2110

    
2111
  def DeleteGroupTags(self, group, tags, dry_run=False):
2112
    """Deletes tags from a node group.
2113

2114
    @type group: str
2115
    @param group: group to delete tags from
2116
    @type tags: list of string
2117
    @param tags: tags to delete
2118
    @type dry_run: bool
2119
    @param dry_run: whether to perform a dry run
2120
    @rtype: string
2121
    @return: job id
2122

2123
    """
2124
    query = [("tag", t) for t in tags]
2125
    _AppendDryRunIf(query, dry_run)
2126

    
2127
    return self._SendRequest(HTTP_DELETE,
2128
                             ("/%s/groups/%s/tags" %
2129
                              (GANETI_RAPI_VERSION, group)), query, None)
2130

    
2131
  def Query(self, what, fields, qfilter=None):
2132
    """Retrieves information about resources.
2133

2134
    @type what: string
2135
    @param what: Resource name, one of L{constants.QR_VIA_RAPI}
2136
    @type fields: list of string
2137
    @param fields: Requested fields
2138
    @type qfilter: None or list
2139
    @param qfilter: Query filter
2140

2141
    @rtype: string
2142
    @return: job id
2143

2144
    """
2145
    body = {
2146
      "fields": fields,
2147
      }
2148

    
2149
    _SetItemIf(body, qfilter is not None, "qfilter", qfilter)
2150
    # TODO: remove "filter" after 2.7
2151
    _SetItemIf(body, qfilter is not None, "filter", qfilter)
2152

    
2153
    return self._SendRequest(HTTP_PUT,
2154
                             ("/%s/query/%s" %
2155
                              (GANETI_RAPI_VERSION, what)), None, body)
2156

    
2157
  def QueryFields(self, what, fields=None):
2158
    """Retrieves available fields for a resource.
2159

2160
    @type what: string
2161
    @param what: Resource name, one of L{constants.QR_VIA_RAPI}
2162
    @type fields: list of string
2163
    @param fields: Requested fields
2164

2165
    @rtype: string
2166
    @return: job id
2167

2168
    """
2169
    query = []
2170

    
2171
    if fields is not None:
2172
      _AppendIf(query, True, ("fields", ",".join(fields)))
2173

    
2174
    return self._SendRequest(HTTP_GET,
2175
                             ("/%s/query/%s/fields" %
2176
                              (GANETI_RAPI_VERSION, what)), query, None)