Statistics
| Branch: | Tag: | Revision:

root / lib / rapi / client.py @ 22001b78

History | View | Annotate | Download (63.6 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, **kwargs):
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
    body = kwargs
846

    
847
    _AppendDryRunIf(query, dry_run)
848

    
849
    return self._SendRequest(HTTP_DELETE,
850
                             ("/%s/instances/%s" %
851
                              (GANETI_RAPI_VERSION, instance)), query, body)
852

    
853
  def ModifyInstance(self, instance, **kwargs):
854
    """Modifies an instance.
855

856
    More details for parameters can be found in the RAPI documentation.
857

858
    @type instance: string
859
    @param instance: Instance name
860
    @rtype: string
861
    @return: job id
862

863
    """
864
    body = kwargs
865

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

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

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

880
    """
881
    query = []
882
    _AppendIf(query, ignore_size, ("ignore_size", 1))
883

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

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

891
    @type instance: string
892
    @param instance: Instance name
893
    @rtype: string
894
    @return: job id
895

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

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

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

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

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

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

925
    More details for parameters can be found in the RAPI documentation.
926

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

938
    """
939
    body = {
940
      "amount": amount,
941
      }
942

    
943
    _SetItemIf(body, wait_for_sync is not None, "wait_for_sync", wait_for_sync)
944

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

    
950
  def GetInstanceTags(self, instance):
951
    """Gets tags for an instance.
952

953
    @type instance: str
954
    @param instance: instance whose tags to return
955

956
    @rtype: list of str
957
    @return: tags for the instance
958

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

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

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

974
    @rtype: string
975
    @return: job id
976

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

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

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

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

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

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

    
1005
  def RebootInstance(self, instance, reboot_type=None, ignore_secondaries=None,
1006
                     dry_run=False, reason=None, **kwargs):
1007
    """Reboots an instance.
1008

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

1023
    """
1024
    query = []
1025
    body = kwargs
1026

    
1027
    _AppendDryRunIf(query, dry_run)
1028
    _AppendIf(query, reboot_type, ("type", reboot_type))
1029
    _AppendIf(query, ignore_secondaries is not None,
1030
              ("ignore_secondaries", ignore_secondaries))
1031
    _AppendIf(query, reason, ("reason", reason))
1032

    
1033
    return self._SendRequest(HTTP_POST,
1034
                             ("/%s/instances/%s/reboot" %
1035
                              (GANETI_RAPI_VERSION, instance)), query, body)
1036

    
1037
  def ShutdownInstance(self, instance, dry_run=False, no_remember=False,
1038
                       reason=None, **kwargs):
1039
    """Shuts down an instance.
1040

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

1052
    """
1053
    query = []
1054
    body = kwargs
1055

    
1056
    _AppendDryRunIf(query, dry_run)
1057
    _AppendIf(query, no_remember, ("no_remember", 1))
1058
    _AppendIf(query, reason, ("reason", reason))
1059

    
1060
    return self._SendRequest(HTTP_PUT,
1061
                             ("/%s/instances/%s/shutdown" %
1062
                              (GANETI_RAPI_VERSION, instance)), query, body)
1063

    
1064
  def StartupInstance(self, instance, dry_run=False, no_remember=False,
1065
                      reason=None):
1066
    """Starts up an instance.
1067

1068
    @type instance: str
1069
    @param instance: the instance to start up
1070
    @type dry_run: bool
1071
    @param dry_run: whether to perform a dry run
1072
    @type no_remember: bool
1073
    @param no_remember: if true, will not record the state change
1074
    @type reason: string
1075
    @param reason: the reason for the startup
1076
    @rtype: string
1077
    @return: job id
1078

1079
    """
1080
    query = []
1081
    _AppendDryRunIf(query, dry_run)
1082
    _AppendIf(query, no_remember, ("no_remember", 1))
1083
    _AppendIf(query, reason, ("reason", reason))
1084

    
1085
    return self._SendRequest(HTTP_PUT,
1086
                             ("/%s/instances/%s/startup" %
1087
                              (GANETI_RAPI_VERSION, instance)), query, None)
1088

    
1089
  def ReinstallInstance(self, instance, os=None, no_startup=False,
1090
                        osparams=None):
1091
    """Reinstalls an instance.
1092

1093
    @type instance: str
1094
    @param instance: The instance to reinstall
1095
    @type os: str or None
1096
    @param os: The operating system to reinstall. If None, the instance's
1097
        current operating system will be installed again
1098
    @type no_startup: bool
1099
    @param no_startup: Whether to start the instance automatically
1100
    @rtype: string
1101
    @return: job id
1102

1103
    """
1104
    if _INST_REINSTALL_REQV1 in self.GetFeatures():
1105
      body = {
1106
        "start": not no_startup,
1107
        }
1108
      _SetItemIf(body, os is not None, "os", os)
1109
      _SetItemIf(body, osparams is not None, "osparams", osparams)
1110
      return self._SendRequest(HTTP_POST,
1111
                               ("/%s/instances/%s/reinstall" %
1112
                                (GANETI_RAPI_VERSION, instance)), None, body)
1113

    
1114
    # Use old request format
1115
    if osparams:
1116
      raise GanetiApiError("Server does not support specifying OS parameters"
1117
                           " for instance reinstallation")
1118

    
1119
    query = []
1120
    _AppendIf(query, os, ("os", os))
1121
    _AppendIf(query, no_startup, ("nostartup", 1))
1122

    
1123
    return self._SendRequest(HTTP_POST,
1124
                             ("/%s/instances/%s/reinstall" %
1125
                              (GANETI_RAPI_VERSION, instance)), query, None)
1126

    
1127
  def ReplaceInstanceDisks(self, instance, disks=None, mode=REPLACE_DISK_AUTO,
1128
                           remote_node=None, iallocator=None):
1129
    """Replaces disks on an instance.
1130

1131
    @type instance: str
1132
    @param instance: instance whose disks to replace
1133
    @type disks: list of ints
1134
    @param disks: Indexes of disks to replace
1135
    @type mode: str
1136
    @param mode: replacement mode to use (defaults to replace_auto)
1137
    @type remote_node: str or None
1138
    @param remote_node: new secondary node to use (for use with
1139
        replace_new_secondary mode)
1140
    @type iallocator: str or None
1141
    @param iallocator: instance allocator plugin to use (for use with
1142
                       replace_auto mode)
1143

1144
    @rtype: string
1145
    @return: job id
1146

1147
    """
1148
    query = [
1149
      ("mode", mode),
1150
      ]
1151

    
1152
    # TODO: Convert to body parameters
1153

    
1154
    if disks is not None:
1155
      _AppendIf(query, True,
1156
                ("disks", ",".join(str(idx) for idx in disks)))
1157

    
1158
    _AppendIf(query, remote_node is not None, ("remote_node", remote_node))
1159
    _AppendIf(query, iallocator is not None, ("iallocator", iallocator))
1160

    
1161
    return self._SendRequest(HTTP_POST,
1162
                             ("/%s/instances/%s/replace-disks" %
1163
                              (GANETI_RAPI_VERSION, instance)), query, None)
1164

    
1165
  def PrepareExport(self, instance, mode):
1166
    """Prepares an instance for an export.
1167

1168
    @type instance: string
1169
    @param instance: Instance name
1170
    @type mode: string
1171
    @param mode: Export mode
1172
    @rtype: string
1173
    @return: Job ID
1174

1175
    """
1176
    query = [("mode", mode)]
1177
    return self._SendRequest(HTTP_PUT,
1178
                             ("/%s/instances/%s/prepare-export" %
1179
                              (GANETI_RAPI_VERSION, instance)), query, None)
1180

    
1181
  def ExportInstance(self, instance, mode, destination, shutdown=None,
1182
                     remove_instance=None,
1183
                     x509_key_name=None, destination_x509_ca=None):
1184
    """Exports an instance.
1185

1186
    @type instance: string
1187
    @param instance: Instance name
1188
    @type mode: string
1189
    @param mode: Export mode
1190
    @rtype: string
1191
    @return: Job ID
1192

1193
    """
1194
    body = {
1195
      "destination": destination,
1196
      "mode": mode,
1197
      }
1198

    
1199
    _SetItemIf(body, shutdown is not None, "shutdown", shutdown)
1200
    _SetItemIf(body, remove_instance is not None,
1201
               "remove_instance", remove_instance)
1202
    _SetItemIf(body, x509_key_name is not None, "x509_key_name", x509_key_name)
1203
    _SetItemIf(body, destination_x509_ca is not None,
1204
               "destination_x509_ca", destination_x509_ca)
1205

    
1206
    return self._SendRequest(HTTP_PUT,
1207
                             ("/%s/instances/%s/export" %
1208
                              (GANETI_RAPI_VERSION, instance)), None, body)
1209

    
1210
  def MigrateInstance(self, instance, mode=None, cleanup=None,
1211
                      target_node=None):
1212
    """Migrates an instance.
1213

1214
    @type instance: string
1215
    @param instance: Instance name
1216
    @type mode: string
1217
    @param mode: Migration mode
1218
    @type cleanup: bool
1219
    @param cleanup: Whether to clean up a previously failed migration
1220
    @type target_node: string
1221
    @param target_node: Target Node for externally mirrored instances
1222
    @rtype: string
1223
    @return: job id
1224

1225
    """
1226
    body = {}
1227
    _SetItemIf(body, mode is not None, "mode", mode)
1228
    _SetItemIf(body, cleanup is not None, "cleanup", cleanup)
1229
    _SetItemIf(body, target_node is not None, "target_node", target_node)
1230

    
1231
    return self._SendRequest(HTTP_PUT,
1232
                             ("/%s/instances/%s/migrate" %
1233
                              (GANETI_RAPI_VERSION, instance)), None, body)
1234

    
1235
  def FailoverInstance(self, instance, iallocator=None,
1236
                       ignore_consistency=None, target_node=None):
1237
    """Does a failover of an instance.
1238

1239
    @type instance: string
1240
    @param instance: Instance name
1241
    @type iallocator: string
1242
    @param iallocator: Iallocator for deciding the target node for
1243
      shared-storage instances
1244
    @type ignore_consistency: bool
1245
    @param ignore_consistency: Whether to ignore disk consistency
1246
    @type target_node: string
1247
    @param target_node: Target node for shared-storage instances
1248
    @rtype: string
1249
    @return: job id
1250

1251
    """
1252
    body = {}
1253
    _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1254
    _SetItemIf(body, ignore_consistency is not None,
1255
               "ignore_consistency", ignore_consistency)
1256
    _SetItemIf(body, target_node is not None, "target_node", target_node)
1257

    
1258
    return self._SendRequest(HTTP_PUT,
1259
                             ("/%s/instances/%s/failover" %
1260
                              (GANETI_RAPI_VERSION, instance)), None, body)
1261

    
1262
  def RenameInstance(self, instance, new_name, ip_check=None, name_check=None):
1263
    """Changes the name of an instance.
1264

1265
    @type instance: string
1266
    @param instance: Instance name
1267
    @type new_name: string
1268
    @param new_name: New instance name
1269
    @type ip_check: bool
1270
    @param ip_check: Whether to ensure instance's IP address is inactive
1271
    @type name_check: bool
1272
    @param name_check: Whether to ensure instance's name is resolvable
1273
    @rtype: string
1274
    @return: job id
1275

1276
    """
1277
    body = {
1278
      "new_name": new_name,
1279
      }
1280

    
1281
    _SetItemIf(body, ip_check is not None, "ip_check", ip_check)
1282
    _SetItemIf(body, name_check is not None, "name_check", name_check)
1283

    
1284
    return self._SendRequest(HTTP_PUT,
1285
                             ("/%s/instances/%s/rename" %
1286
                              (GANETI_RAPI_VERSION, instance)), None, body)
1287

    
1288
  def GetInstanceConsole(self, instance):
1289
    """Request information for connecting to instance's console.
1290

1291
    @type instance: string
1292
    @param instance: Instance name
1293
    @rtype: dict
1294
    @return: dictionary containing information about instance's console
1295

1296
    """
1297
    return self._SendRequest(HTTP_GET,
1298
                             ("/%s/instances/%s/console" %
1299
                              (GANETI_RAPI_VERSION, instance)), None, None)
1300

    
1301
  def GetJobs(self, bulk=False):
1302
    """Gets all jobs for the cluster.
1303

1304
    @type bulk: bool
1305
    @param bulk: Whether to return detailed information about jobs.
1306
    @rtype: list of int
1307
    @return: List of job ids for the cluster or list of dicts with detailed
1308
             information about the jobs if bulk parameter was true.
1309

1310
    """
1311
    query = []
1312
    _AppendIf(query, bulk, ("bulk", 1))
1313

    
1314
    if bulk:
1315
      return self._SendRequest(HTTP_GET,
1316
                               "/%s/jobs" % GANETI_RAPI_VERSION,
1317
                               query, None)
1318
    else:
1319
      return [int(j["id"])
1320
              for j in self._SendRequest(HTTP_GET,
1321
                                         "/%s/jobs" % GANETI_RAPI_VERSION,
1322
                                         None, None)]
1323

    
1324
  def GetJobStatus(self, job_id):
1325
    """Gets the status of a job.
1326

1327
    @type job_id: string
1328
    @param job_id: job id whose status to query
1329

1330
    @rtype: dict
1331
    @return: job status
1332

1333
    """
1334
    return self._SendRequest(HTTP_GET,
1335
                             "/%s/jobs/%s" % (GANETI_RAPI_VERSION, job_id),
1336
                             None, None)
1337

    
1338
  def WaitForJobCompletion(self, job_id, period=5, retries=-1):
1339
    """Polls cluster for job status until completion.
1340

1341
    Completion is defined as any of the following states listed in
1342
    L{JOB_STATUS_FINALIZED}.
1343

1344
    @type job_id: string
1345
    @param job_id: job id to watch
1346
    @type period: int
1347
    @param period: how often to poll for status (optional, default 5s)
1348
    @type retries: int
1349
    @param retries: how many time to poll before giving up
1350
                    (optional, default -1 means unlimited)
1351

1352
    @rtype: bool
1353
    @return: C{True} if job succeeded or C{False} if failed/status timeout
1354
    @deprecated: It is recommended to use L{WaitForJobChange} wherever
1355
      possible; L{WaitForJobChange} returns immediately after a job changed and
1356
      does not use polling
1357

1358
    """
1359
    while retries != 0:
1360
      job_result = self.GetJobStatus(job_id)
1361

    
1362
      if job_result and job_result["status"] == JOB_STATUS_SUCCESS:
1363
        return True
1364
      elif not job_result or job_result["status"] in JOB_STATUS_FINALIZED:
1365
        return False
1366

    
1367
      if period:
1368
        time.sleep(period)
1369

    
1370
      if retries > 0:
1371
        retries -= 1
1372

    
1373
    return False
1374

    
1375
  def WaitForJobChange(self, job_id, fields, prev_job_info, prev_log_serial):
1376
    """Waits for job changes.
1377

1378
    @type job_id: string
1379
    @param job_id: Job ID for which to wait
1380
    @return: C{None} if no changes have been detected and a dict with two keys,
1381
      C{job_info} and C{log_entries} otherwise.
1382
    @rtype: dict
1383

1384
    """
1385
    body = {
1386
      "fields": fields,
1387
      "previous_job_info": prev_job_info,
1388
      "previous_log_serial": prev_log_serial,
1389
      }
1390

    
1391
    return self._SendRequest(HTTP_GET,
1392
                             "/%s/jobs/%s/wait" % (GANETI_RAPI_VERSION, job_id),
1393
                             None, body)
1394

    
1395
  def CancelJob(self, job_id, dry_run=False):
1396
    """Cancels a job.
1397

1398
    @type job_id: string
1399
    @param job_id: id of the job to delete
1400
    @type dry_run: bool
1401
    @param dry_run: whether to perform a dry run
1402
    @rtype: tuple
1403
    @return: tuple containing the result, and a message (bool, string)
1404

1405
    """
1406
    query = []
1407
    _AppendDryRunIf(query, dry_run)
1408

    
1409
    return self._SendRequest(HTTP_DELETE,
1410
                             "/%s/jobs/%s" % (GANETI_RAPI_VERSION, job_id),
1411
                             query, None)
1412

    
1413
  def GetNodes(self, bulk=False):
1414
    """Gets all nodes in the cluster.
1415

1416
    @type bulk: bool
1417
    @param bulk: whether to return all information about all instances
1418

1419
    @rtype: list of dict or str
1420
    @return: if bulk is true, info about nodes in the cluster,
1421
        else list of nodes in the cluster
1422

1423
    """
1424
    query = []
1425
    _AppendIf(query, bulk, ("bulk", 1))
1426

    
1427
    nodes = self._SendRequest(HTTP_GET, "/%s/nodes" % GANETI_RAPI_VERSION,
1428
                              query, None)
1429
    if bulk:
1430
      return nodes
1431
    else:
1432
      return [n["id"] for n in nodes]
1433

    
1434
  def GetNode(self, node):
1435
    """Gets information about a node.
1436

1437
    @type node: str
1438
    @param node: node whose info to return
1439

1440
    @rtype: dict
1441
    @return: info about the node
1442

1443
    """
1444
    return self._SendRequest(HTTP_GET,
1445
                             "/%s/nodes/%s" % (GANETI_RAPI_VERSION, node),
1446
                             None, None)
1447

    
1448
  def EvacuateNode(self, node, iallocator=None, remote_node=None,
1449
                   dry_run=False, early_release=None,
1450
                   mode=None, accept_old=False):
1451
    """Evacuates instances from a Ganeti node.
1452

1453
    @type node: str
1454
    @param node: node to evacuate
1455
    @type iallocator: str or None
1456
    @param iallocator: instance allocator to use
1457
    @type remote_node: str
1458
    @param remote_node: node to evaucate to
1459
    @type dry_run: bool
1460
    @param dry_run: whether to perform a dry run
1461
    @type early_release: bool
1462
    @param early_release: whether to enable parallelization
1463
    @type mode: string
1464
    @param mode: Node evacuation mode
1465
    @type accept_old: bool
1466
    @param accept_old: Whether caller is ready to accept old-style (pre-2.5)
1467
        results
1468

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

1475
    @raises GanetiApiError: if an iallocator and remote_node are both
1476
        specified
1477

1478
    """
1479
    if iallocator and remote_node:
1480
      raise GanetiApiError("Only one of iallocator or remote_node can be used")
1481

    
1482
    query = []
1483
    _AppendDryRunIf(query, dry_run)
1484

    
1485
    if _NODE_EVAC_RES1 in self.GetFeatures():
1486
      # Server supports body parameters
1487
      body = {}
1488

    
1489
      _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1490
      _SetItemIf(body, remote_node is not None, "remote_node", remote_node)
1491
      _SetItemIf(body, early_release is not None,
1492
                 "early_release", early_release)
1493
      _SetItemIf(body, mode is not None, "mode", mode)
1494
    else:
1495
      # Pre-2.5 request format
1496
      body = None
1497

    
1498
      if not accept_old:
1499
        raise GanetiApiError("Server is version 2.4 or earlier and caller does"
1500
                             " not accept old-style results (parameter"
1501
                             " accept_old)")
1502

    
1503
      # Pre-2.5 servers can only evacuate secondaries
1504
      if mode is not None and mode != NODE_EVAC_SEC:
1505
        raise GanetiApiError("Server can only evacuate secondary instances")
1506

    
1507
      _AppendIf(query, iallocator, ("iallocator", iallocator))
1508
      _AppendIf(query, remote_node, ("remote_node", remote_node))
1509
      _AppendIf(query, early_release, ("early_release", 1))
1510

    
1511
    return self._SendRequest(HTTP_POST,
1512
                             ("/%s/nodes/%s/evacuate" %
1513
                              (GANETI_RAPI_VERSION, node)), query, body)
1514

    
1515
  def MigrateNode(self, node, mode=None, dry_run=False, iallocator=None,
1516
                  target_node=None):
1517
    """Migrates all primary instances from a node.
1518

1519
    @type node: str
1520
    @param node: node to migrate
1521
    @type mode: string
1522
    @param mode: if passed, it will overwrite the live migration type,
1523
        otherwise the hypervisor default will be used
1524
    @type dry_run: bool
1525
    @param dry_run: whether to perform a dry run
1526
    @type iallocator: string
1527
    @param iallocator: instance allocator to use
1528
    @type target_node: string
1529
    @param target_node: Target node for shared-storage instances
1530

1531
    @rtype: string
1532
    @return: job id
1533

1534
    """
1535
    query = []
1536
    _AppendDryRunIf(query, dry_run)
1537

    
1538
    if _NODE_MIGRATE_REQV1 in self.GetFeatures():
1539
      body = {}
1540

    
1541
      _SetItemIf(body, mode is not None, "mode", mode)
1542
      _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1543
      _SetItemIf(body, target_node is not None, "target_node", target_node)
1544

    
1545
      assert len(query) <= 1
1546

    
1547
      return self._SendRequest(HTTP_POST,
1548
                               ("/%s/nodes/%s/migrate" %
1549
                                (GANETI_RAPI_VERSION, node)), query, body)
1550
    else:
1551
      # Use old request format
1552
      if target_node is not None:
1553
        raise GanetiApiError("Server does not support specifying target node"
1554
                             " for node migration")
1555

    
1556
      _AppendIf(query, mode is not None, ("mode", mode))
1557

    
1558
      return self._SendRequest(HTTP_POST,
1559
                               ("/%s/nodes/%s/migrate" %
1560
                                (GANETI_RAPI_VERSION, node)), query, None)
1561

    
1562
  def GetNodeRole(self, node):
1563
    """Gets the current role for a node.
1564

1565
    @type node: str
1566
    @param node: node whose role to return
1567

1568
    @rtype: str
1569
    @return: the current role for a node
1570

1571
    """
1572
    return self._SendRequest(HTTP_GET,
1573
                             ("/%s/nodes/%s/role" %
1574
                              (GANETI_RAPI_VERSION, node)), None, None)
1575

    
1576
  def SetNodeRole(self, node, role, force=False, auto_promote=None):
1577
    """Sets the role for a node.
1578

1579
    @type node: str
1580
    @param node: the node whose role to set
1581
    @type role: str
1582
    @param role: the role to set for the node
1583
    @type force: bool
1584
    @param force: whether to force the role change
1585
    @type auto_promote: bool
1586
    @param auto_promote: Whether node(s) should be promoted to master candidate
1587
                         if necessary
1588

1589
    @rtype: string
1590
    @return: job id
1591

1592
    """
1593
    query = []
1594
    _AppendForceIf(query, force)
1595
    _AppendIf(query, auto_promote is not None, ("auto-promote", auto_promote))
1596

    
1597
    return self._SendRequest(HTTP_PUT,
1598
                             ("/%s/nodes/%s/role" %
1599
                              (GANETI_RAPI_VERSION, node)), query, role)
1600

    
1601
  def PowercycleNode(self, node, force=False):
1602
    """Powercycles a node.
1603

1604
    @type node: string
1605
    @param node: Node name
1606
    @type force: bool
1607
    @param force: Whether to force the operation
1608
    @rtype: string
1609
    @return: job id
1610

1611
    """
1612
    query = []
1613
    _AppendForceIf(query, force)
1614

    
1615
    return self._SendRequest(HTTP_POST,
1616
                             ("/%s/nodes/%s/powercycle" %
1617
                              (GANETI_RAPI_VERSION, node)), query, None)
1618

    
1619
  def ModifyNode(self, node, **kwargs):
1620
    """Modifies a node.
1621

1622
    More details for parameters can be found in the RAPI documentation.
1623

1624
    @type node: string
1625
    @param node: Node name
1626
    @rtype: string
1627
    @return: job id
1628

1629
    """
1630
    return self._SendRequest(HTTP_POST,
1631
                             ("/%s/nodes/%s/modify" %
1632
                              (GANETI_RAPI_VERSION, node)), None, kwargs)
1633

    
1634
  def GetNodeStorageUnits(self, node, storage_type, output_fields):
1635
    """Gets the storage units for a node.
1636

1637
    @type node: str
1638
    @param node: the node whose storage units to return
1639
    @type storage_type: str
1640
    @param storage_type: storage type whose units to return
1641
    @type output_fields: str
1642
    @param output_fields: storage type fields to return
1643

1644
    @rtype: string
1645
    @return: job id where results can be retrieved
1646

1647
    """
1648
    query = [
1649
      ("storage_type", storage_type),
1650
      ("output_fields", output_fields),
1651
      ]
1652

    
1653
    return self._SendRequest(HTTP_GET,
1654
                             ("/%s/nodes/%s/storage" %
1655
                              (GANETI_RAPI_VERSION, node)), query, None)
1656

    
1657
  def ModifyNodeStorageUnits(self, node, storage_type, name, allocatable=None):
1658
    """Modifies parameters of storage units on the node.
1659

1660
    @type node: str
1661
    @param node: node whose storage units to modify
1662
    @type storage_type: str
1663
    @param storage_type: storage type whose units to modify
1664
    @type name: str
1665
    @param name: name of the storage unit
1666
    @type allocatable: bool or None
1667
    @param allocatable: Whether to set the "allocatable" flag on the storage
1668
                        unit (None=no modification, True=set, False=unset)
1669

1670
    @rtype: string
1671
    @return: job id
1672

1673
    """
1674
    query = [
1675
      ("storage_type", storage_type),
1676
      ("name", name),
1677
      ]
1678

    
1679
    _AppendIf(query, allocatable is not None, ("allocatable", allocatable))
1680

    
1681
    return self._SendRequest(HTTP_PUT,
1682
                             ("/%s/nodes/%s/storage/modify" %
1683
                              (GANETI_RAPI_VERSION, node)), query, None)
1684

    
1685
  def RepairNodeStorageUnits(self, node, storage_type, name):
1686
    """Repairs a storage unit on the node.
1687

1688
    @type node: str
1689
    @param node: node whose storage units to repair
1690
    @type storage_type: str
1691
    @param storage_type: storage type to repair
1692
    @type name: str
1693
    @param name: name of the storage unit to repair
1694

1695
    @rtype: string
1696
    @return: job id
1697

1698
    """
1699
    query = [
1700
      ("storage_type", storage_type),
1701
      ("name", name),
1702
      ]
1703

    
1704
    return self._SendRequest(HTTP_PUT,
1705
                             ("/%s/nodes/%s/storage/repair" %
1706
                              (GANETI_RAPI_VERSION, node)), query, None)
1707

    
1708
  def GetNodeTags(self, node):
1709
    """Gets the tags for a node.
1710

1711
    @type node: str
1712
    @param node: node whose tags to return
1713

1714
    @rtype: list of str
1715
    @return: tags for the node
1716

1717
    """
1718
    return self._SendRequest(HTTP_GET,
1719
                             ("/%s/nodes/%s/tags" %
1720
                              (GANETI_RAPI_VERSION, node)), None, None)
1721

    
1722
  def AddNodeTags(self, node, tags, dry_run=False):
1723
    """Adds tags to a node.
1724

1725
    @type node: str
1726
    @param node: node to add tags to
1727
    @type tags: list of str
1728
    @param tags: tags to add to the node
1729
    @type dry_run: bool
1730
    @param dry_run: whether to perform a dry run
1731

1732
    @rtype: string
1733
    @return: job id
1734

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

    
1739
    return self._SendRequest(HTTP_PUT,
1740
                             ("/%s/nodes/%s/tags" %
1741
                              (GANETI_RAPI_VERSION, node)), query, tags)
1742

    
1743
  def DeleteNodeTags(self, node, tags, dry_run=False):
1744
    """Delete tags from a node.
1745

1746
    @type node: str
1747
    @param node: node to remove tags from
1748
    @type tags: list of str
1749
    @param tags: tags to remove from the node
1750
    @type dry_run: bool
1751
    @param dry_run: whether to perform a dry run
1752

1753
    @rtype: string
1754
    @return: job id
1755

1756
    """
1757
    query = [("tag", t) for t in tags]
1758
    _AppendDryRunIf(query, dry_run)
1759

    
1760
    return self._SendRequest(HTTP_DELETE,
1761
                             ("/%s/nodes/%s/tags" %
1762
                              (GANETI_RAPI_VERSION, node)), query, None)
1763

    
1764
  def GetNetworks(self, bulk=False):
1765
    """Gets all networks in the cluster.
1766

1767
    @type bulk: bool
1768
    @param bulk: whether to return all information about the networks
1769

1770
    @rtype: list of dict or str
1771
    @return: if bulk is true, a list of dictionaries with info about all
1772
        networks in the cluster, else a list of names of those networks
1773

1774
    """
1775
    query = []
1776
    _AppendIf(query, bulk, ("bulk", 1))
1777

    
1778
    networks = self._SendRequest(HTTP_GET, "/%s/networks" % GANETI_RAPI_VERSION,
1779
                                 query, None)
1780
    if bulk:
1781
      return networks
1782
    else:
1783
      return [n["name"] for n in networks]
1784

    
1785
  def GetNetwork(self, network):
1786
    """Gets information about a network.
1787

1788
    @type network: str
1789
    @param network: name of the network whose info to return
1790

1791
    @rtype: dict
1792
    @return: info about the network
1793

1794
    """
1795
    return self._SendRequest(HTTP_GET,
1796
                             "/%s/networks/%s" % (GANETI_RAPI_VERSION, network),
1797
                             None, None)
1798

    
1799
  def CreateNetwork(self, network_name, network, gateway=None, network6=None,
1800
                    gateway6=None, mac_prefix=None,
1801
                    add_reserved_ips=None, tags=None, dry_run=False):
1802
    """Creates a new network.
1803

1804
    @type network_name: str
1805
    @param network_name: the name of network to create
1806
    @type dry_run: bool
1807
    @param dry_run: whether to peform a dry run
1808

1809
    @rtype: string
1810
    @return: job id
1811

1812
    """
1813
    query = []
1814
    _AppendDryRunIf(query, dry_run)
1815

    
1816
    if add_reserved_ips:
1817
      add_reserved_ips = add_reserved_ips.split(",")
1818

    
1819
    if tags:
1820
      tags = tags.split(",")
1821

    
1822
    body = {
1823
      "network_name": network_name,
1824
      "gateway": gateway,
1825
      "network": network,
1826
      "gateway6": gateway6,
1827
      "network6": network6,
1828
      "mac_prefix": mac_prefix,
1829
      "add_reserved_ips": add_reserved_ips,
1830
      "tags": tags,
1831
      }
1832

    
1833
    return self._SendRequest(HTTP_POST, "/%s/networks" % GANETI_RAPI_VERSION,
1834
                             query, body)
1835

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

1839
    """
1840
    body = {
1841
      "group_name": group_name,
1842
      "network_mode": mode,
1843
      "network_link": link,
1844
      }
1845

    
1846
    query = []
1847
    _AppendDryRunIf(query, dry_run)
1848

    
1849
    return self._SendRequest(HTTP_PUT,
1850
                             ("/%s/networks/%s/connect" %
1851
                             (GANETI_RAPI_VERSION, network_name)), query, body)
1852

    
1853
  def DisconnectNetwork(self, network_name, group_name, dry_run=False):
1854
    """Connects a Network to a NodeGroup with the given netparams
1855

1856
    """
1857
    body = {
1858
      "group_name": group_name,
1859
      }
1860

    
1861
    query = []
1862
    _AppendDryRunIf(query, dry_run)
1863

    
1864
    return self._SendRequest(HTTP_PUT,
1865
                             ("/%s/networks/%s/disconnect" %
1866
                             (GANETI_RAPI_VERSION, network_name)), query, body)
1867

    
1868
  def ModifyNetwork(self, network, **kwargs):
1869
    """Modifies a network.
1870

1871
    More details for parameters can be found in the RAPI documentation.
1872

1873
    @type network: string
1874
    @param network: Network name
1875
    @rtype: string
1876
    @return: job id
1877

1878
    """
1879
    return self._SendRequest(HTTP_PUT,
1880
                             ("/%s/networks/%s/modify" %
1881
                              (GANETI_RAPI_VERSION, network)), None, kwargs)
1882

    
1883
  def DeleteNetwork(self, network, dry_run=False):
1884
    """Deletes a network.
1885

1886
    @type network: str
1887
    @param network: the network to delete
1888
    @type dry_run: bool
1889
    @param dry_run: whether to peform a dry run
1890

1891
    @rtype: string
1892
    @return: job id
1893

1894
    """
1895
    query = []
1896
    _AppendDryRunIf(query, dry_run)
1897

    
1898
    return self._SendRequest(HTTP_DELETE,
1899
                             ("/%s/networks/%s" %
1900
                              (GANETI_RAPI_VERSION, network)), query, None)
1901

    
1902
  def GetNetworkTags(self, network):
1903
    """Gets tags for a network.
1904

1905
    @type network: string
1906
    @param network: Node group whose tags to return
1907

1908
    @rtype: list of strings
1909
    @return: tags for the network
1910

1911
    """
1912
    return self._SendRequest(HTTP_GET,
1913
                             ("/%s/networks/%s/tags" %
1914
                              (GANETI_RAPI_VERSION, network)), None, None)
1915

    
1916
  def AddNetworkTags(self, network, tags, dry_run=False):
1917
    """Adds tags to a network.
1918

1919
    @type network: str
1920
    @param network: network to add tags to
1921
    @type tags: list of string
1922
    @param tags: tags to add to the network
1923
    @type dry_run: bool
1924
    @param dry_run: whether to perform a dry run
1925

1926
    @rtype: string
1927
    @return: job id
1928

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

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

    
1937
  def DeleteNetworkTags(self, network, tags, dry_run=False):
1938
    """Deletes tags from a network.
1939

1940
    @type network: str
1941
    @param network: network to delete tags from
1942
    @type tags: list of string
1943
    @param tags: tags to delete
1944
    @type dry_run: bool
1945
    @param dry_run: whether to perform a dry run
1946
    @rtype: string
1947
    @return: job id
1948

1949
    """
1950
    query = [("tag", t) for t in tags]
1951
    _AppendDryRunIf(query, dry_run)
1952

    
1953
    return self._SendRequest(HTTP_DELETE,
1954
                             ("/%s/networks/%s/tags" %
1955
                              (GANETI_RAPI_VERSION, network)), query, None)
1956

    
1957
  def GetGroups(self, bulk=False):
1958
    """Gets all node groups in the cluster.
1959

1960
    @type bulk: bool
1961
    @param bulk: whether to return all information about the groups
1962

1963
    @rtype: list of dict or str
1964
    @return: if bulk is true, a list of dictionaries with info about all node
1965
        groups in the cluster, else a list of names of those node groups
1966

1967
    """
1968
    query = []
1969
    _AppendIf(query, bulk, ("bulk", 1))
1970

    
1971
    groups = self._SendRequest(HTTP_GET, "/%s/groups" % GANETI_RAPI_VERSION,
1972
                               query, None)
1973
    if bulk:
1974
      return groups
1975
    else:
1976
      return [g["name"] for g in groups]
1977

    
1978
  def GetGroup(self, group):
1979
    """Gets information about a node group.
1980

1981
    @type group: str
1982
    @param group: name of the node group whose info to return
1983

1984
    @rtype: dict
1985
    @return: info about the node group
1986

1987
    """
1988
    return self._SendRequest(HTTP_GET,
1989
                             "/%s/groups/%s" % (GANETI_RAPI_VERSION, group),
1990
                             None, None)
1991

    
1992
  def CreateGroup(self, name, alloc_policy=None, dry_run=False):
1993
    """Creates a new node group.
1994

1995
    @type name: str
1996
    @param name: the name of node group to create
1997
    @type alloc_policy: str
1998
    @param alloc_policy: the desired allocation policy for the group, if any
1999
    @type dry_run: bool
2000
    @param dry_run: whether to peform a dry run
2001

2002
    @rtype: string
2003
    @return: job id
2004

2005
    """
2006
    query = []
2007
    _AppendDryRunIf(query, dry_run)
2008

    
2009
    body = {
2010
      "name": name,
2011
      "alloc_policy": alloc_policy,
2012
      }
2013

    
2014
    return self._SendRequest(HTTP_POST, "/%s/groups" % GANETI_RAPI_VERSION,
2015
                             query, body)
2016

    
2017
  def ModifyGroup(self, group, **kwargs):
2018
    """Modifies a node group.
2019

2020
    More details for parameters can be found in the RAPI documentation.
2021

2022
    @type group: string
2023
    @param group: Node group name
2024
    @rtype: string
2025
    @return: job id
2026

2027
    """
2028
    return self._SendRequest(HTTP_PUT,
2029
                             ("/%s/groups/%s/modify" %
2030
                              (GANETI_RAPI_VERSION, group)), None, kwargs)
2031

    
2032
  def DeleteGroup(self, group, dry_run=False):
2033
    """Deletes a node group.
2034

2035
    @type group: str
2036
    @param group: the node group to delete
2037
    @type dry_run: bool
2038
    @param dry_run: whether to peform a dry run
2039

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

2043
    """
2044
    query = []
2045
    _AppendDryRunIf(query, dry_run)
2046

    
2047
    return self._SendRequest(HTTP_DELETE,
2048
                             ("/%s/groups/%s" %
2049
                              (GANETI_RAPI_VERSION, group)), query, None)
2050

    
2051
  def RenameGroup(self, group, new_name):
2052
    """Changes the name of a node group.
2053

2054
    @type group: string
2055
    @param group: Node group name
2056
    @type new_name: string
2057
    @param new_name: New node group name
2058

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

2062
    """
2063
    body = {
2064
      "new_name": new_name,
2065
      }
2066

    
2067
    return self._SendRequest(HTTP_PUT,
2068
                             ("/%s/groups/%s/rename" %
2069
                              (GANETI_RAPI_VERSION, group)), None, body)
2070

    
2071
  def AssignGroupNodes(self, group, nodes, force=False, dry_run=False):
2072
    """Assigns nodes to a group.
2073

2074
    @type group: string
2075
    @param group: Node group name
2076
    @type nodes: list of strings
2077
    @param nodes: List of nodes to assign to the group
2078

2079
    @rtype: string
2080
    @return: job id
2081

2082
    """
2083
    query = []
2084
    _AppendForceIf(query, force)
2085
    _AppendDryRunIf(query, dry_run)
2086

    
2087
    body = {
2088
      "nodes": nodes,
2089
      }
2090

    
2091
    return self._SendRequest(HTTP_PUT,
2092
                             ("/%s/groups/%s/assign-nodes" %
2093
                             (GANETI_RAPI_VERSION, group)), query, body)
2094

    
2095
  def GetGroupTags(self, group):
2096
    """Gets tags for a node group.
2097

2098
    @type group: string
2099
    @param group: Node group whose tags to return
2100

2101
    @rtype: list of strings
2102
    @return: tags for the group
2103

2104
    """
2105
    return self._SendRequest(HTTP_GET,
2106
                             ("/%s/groups/%s/tags" %
2107
                              (GANETI_RAPI_VERSION, group)), None, None)
2108

    
2109
  def AddGroupTags(self, group, tags, dry_run=False):
2110
    """Adds tags to a node group.
2111

2112
    @type group: str
2113
    @param group: group to add tags to
2114
    @type tags: list of string
2115
    @param tags: tags to add to the group
2116
    @type dry_run: bool
2117
    @param dry_run: whether to perform a dry run
2118

2119
    @rtype: string
2120
    @return: job id
2121

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

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

    
2130
  def DeleteGroupTags(self, group, tags, dry_run=False):
2131
    """Deletes tags from a node group.
2132

2133
    @type group: str
2134
    @param group: group to delete tags from
2135
    @type tags: list of string
2136
    @param tags: tags to delete
2137
    @type dry_run: bool
2138
    @param dry_run: whether to perform a dry run
2139
    @rtype: string
2140
    @return: job id
2141

2142
    """
2143
    query = [("tag", t) for t in tags]
2144
    _AppendDryRunIf(query, dry_run)
2145

    
2146
    return self._SendRequest(HTTP_DELETE,
2147
                             ("/%s/groups/%s/tags" %
2148
                              (GANETI_RAPI_VERSION, group)), query, None)
2149

    
2150
  def Query(self, what, fields, qfilter=None):
2151
    """Retrieves information about resources.
2152

2153
    @type what: string
2154
    @param what: Resource name, one of L{constants.QR_VIA_RAPI}
2155
    @type fields: list of string
2156
    @param fields: Requested fields
2157
    @type qfilter: None or list
2158
    @param qfilter: Query filter
2159

2160
    @rtype: string
2161
    @return: job id
2162

2163
    """
2164
    body = {
2165
      "fields": fields,
2166
      }
2167

    
2168
    _SetItemIf(body, qfilter is not None, "qfilter", qfilter)
2169
    # TODO: remove "filter" after 2.7
2170
    _SetItemIf(body, qfilter is not None, "filter", qfilter)
2171

    
2172
    return self._SendRequest(HTTP_PUT,
2173
                             ("/%s/query/%s" %
2174
                              (GANETI_RAPI_VERSION, what)), None, body)
2175

    
2176
  def QueryFields(self, what, fields=None):
2177
    """Retrieves available fields for a resource.
2178

2179
    @type what: string
2180
    @param what: Resource name, one of L{constants.QR_VIA_RAPI}
2181
    @type fields: list of string
2182
    @param fields: Requested fields
2183

2184
    @rtype: string
2185
    @return: job id
2186

2187
    """
2188
    query = []
2189

    
2190
    if fields is not None:
2191
      _AppendIf(query, True, ("fields", ",".join(fields)))
2192

    
2193
    return self._SendRequest(HTTP_GET,
2194
                             ("/%s/query/%s/fields" %
2195
                              (GANETI_RAPI_VERSION, what)), query, None)