4 # Copyright (C) 2010, 2011 Google Inc.
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.
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.
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
22 """Ganeti RAPI client.
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}
33 # No Ganeti-specific modules should be imported. The RAPI client is supposed to
45 from cStringIO import StringIO
47 from StringIO import StringIO
50 GANETI_RAPI_PORT = 5080
51 GANETI_RAPI_VERSION = 2
53 HTTP_DELETE = "DELETE"
59 HTTP_APP_JSON = "application/json"
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"
66 NODE_EVAC_PRI = "primary-only"
67 NODE_EVAC_SEC = "secondary-only"
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"
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_FINALIZED = frozenset([
88 JOB_STATUS_ALL = frozenset([
93 ]) | JOB_STATUS_FINALIZED
96 JOB_STATUS_WAITLOCK = JOB_STATUS_WAITING
99 _REQ_DATA_VERSION_FIELD = "__version__"
100 _INST_NIC_PARAMS = frozenset(["mac", "ip", "mode", "link"])
101 _INST_CREATE_V0_DISK_PARAMS = frozenset(["size"])
102 _INST_CREATE_V0_PARAMS = frozenset([
103 "os", "pnode", "snode", "iallocator", "start", "ip_check", "name_check",
104 "hypervisor", "file_storage_dir", "file_driver", "dry_run",
106 _INST_CREATE_V0_DPARAMS = frozenset(["beparams", "hvparams"])
107 _QPARAM_DRY_RUN = "dry-run"
108 _QPARAM_FORCE = "force"
111 INST_CREATE_REQV1 = "instance-create-reqv1"
112 INST_REINSTALL_REQV1 = "instance-reinstall-reqv1"
113 NODE_MIGRATE_REQV1 = "node-migrate-reqv1"
114 NODE_EVAC_RES1 = "node-evac-res1"
116 # Old feature constant names in case they're references by users of this module
117 _INST_CREATE_REQV1 = INST_CREATE_REQV1
118 _INST_REINSTALL_REQV1 = INST_REINSTALL_REQV1
119 _NODE_MIGRATE_REQV1 = NODE_MIGRATE_REQV1
120 _NODE_EVAC_RES1 = NODE_EVAC_RES1
122 # Older pycURL versions don't have all error constants
124 _CURLE_SSL_CACERT = pycurl.E_SSL_CACERT
125 _CURLE_SSL_CACERT_BADFILE = pycurl.E_SSL_CACERT_BADFILE
126 except AttributeError:
127 _CURLE_SSL_CACERT = 60
128 _CURLE_SSL_CACERT_BADFILE = 77
130 _CURL_SSL_CERT_ERRORS = frozenset([
132 _CURLE_SSL_CACERT_BADFILE,
136 class Error(Exception):
137 """Base error class for this module.
143 class CertificateError(Error):
144 """Raised when a problem is found with the SSL certificate.
150 class GanetiApiError(Error):
151 """Generic error raised from Ganeti API.
154 def __init__(self, msg, code=None):
155 Error.__init__(self, msg)
159 def _AppendIf(container, condition, value):
160 """Appends to a list if a condition evaluates to truth.
164 container.append(value)
169 def _AppendDryRunIf(container, condition):
170 """Appends a "dry-run" parameter if a condition evaluates to truth.
173 return _AppendIf(container, condition, (_QPARAM_DRY_RUN, 1))
176 def _AppendForceIf(container, condition):
177 """Appends a "force" parameter if a condition evaluates to truth.
180 return _AppendIf(container, condition, (_QPARAM_FORCE, 1))
183 def _SetItemIf(container, condition, item, value):
184 """Sets an item if a condition evaluates to truth.
188 container[item] = value
193 def UsesRapiClient(fn):
194 """Decorator for code using RAPI client to initialize pycURL.
197 def wrapper(*args, **kwargs):
198 # curl_global_init(3) and curl_global_cleanup(3) must be called with only
199 # one thread running. This check is just a safety measure -- it doesn't
201 assert threading.activeCount() == 1, \
202 "Found active threads when initializing pycURL"
204 pycurl.global_init(pycurl.GLOBAL_ALL)
206 return fn(*args, **kwargs)
208 pycurl.global_cleanup()
213 def GenericCurlConfig(verbose=False, use_signal=False,
214 use_curl_cabundle=False, cafile=None, capath=None,
215 proxy=None, verify_hostname=False,
216 connect_timeout=None, timeout=None,
217 _pycurl_version_fn=pycurl.version_info):
218 """Curl configuration function generator.
221 @param verbose: Whether to set cURL to verbose mode
222 @type use_signal: bool
223 @param use_signal: Whether to allow cURL to use signals
224 @type use_curl_cabundle: bool
225 @param use_curl_cabundle: Whether to use cURL's default CA bundle
227 @param cafile: In which file we can find the certificates
229 @param capath: In which directory we can find the certificates
231 @param proxy: Proxy to use, None for default behaviour and empty string for
232 disabling proxies (see curl_easy_setopt(3))
233 @type verify_hostname: bool
234 @param verify_hostname: Whether to verify the remote peer certificate's
236 @type connect_timeout: number
237 @param connect_timeout: Timeout for establishing connection in seconds
238 @type timeout: number
239 @param timeout: Timeout for complete transfer in seconds (see
240 curl_easy_setopt(3)).
243 if use_curl_cabundle and (cafile or capath):
244 raise Error("Can not use default CA bundle when CA file or path is set")
246 def _ConfigCurl(curl, logger):
247 """Configures a cURL object
249 @type curl: pycurl.Curl
250 @param curl: cURL object
253 logger.debug("Using cURL version %s", pycurl.version)
255 # pycurl.version_info returns a tuple with information about the used
256 # version of libcurl. Item 5 is the SSL library linked to it.
257 # e.g.: (3, '7.18.0', 463360, 'x86_64-pc-linux-gnu', 1581, 'GnuTLS/2.0.4',
259 sslver = _pycurl_version_fn()[5]
261 raise Error("No SSL support in cURL")
263 lcsslver = sslver.lower()
264 if lcsslver.startswith("openssl/"):
266 elif lcsslver.startswith("gnutls/"):
268 raise Error("cURL linked against GnuTLS has no support for a"
269 " CA path (%s)" % (pycurl.version, ))
271 raise NotImplementedError("cURL uses unsupported SSL version '%s'" %
274 curl.setopt(pycurl.VERBOSE, verbose)
275 curl.setopt(pycurl.NOSIGNAL, not use_signal)
277 # Whether to verify remote peer's CN
279 # curl_easy_setopt(3): "When CURLOPT_SSL_VERIFYHOST is 2, that
280 # certificate must indicate that the server is the server to which you
281 # meant to connect, or the connection fails. [...] When the value is 1,
282 # the certificate must contain a Common Name field, but it doesn't matter
283 # what name it says. [...]"
284 curl.setopt(pycurl.SSL_VERIFYHOST, 2)
286 curl.setopt(pycurl.SSL_VERIFYHOST, 0)
288 if cafile or capath or use_curl_cabundle:
289 # Require certificates to be checked
290 curl.setopt(pycurl.SSL_VERIFYPEER, True)
292 curl.setopt(pycurl.CAINFO, str(cafile))
294 curl.setopt(pycurl.CAPATH, str(capath))
295 # Not changing anything for using default CA bundle
297 # Disable SSL certificate verification
298 curl.setopt(pycurl.SSL_VERIFYPEER, False)
300 if proxy is not None:
301 curl.setopt(pycurl.PROXY, str(proxy))
304 if connect_timeout is not None:
305 curl.setopt(pycurl.CONNECTTIMEOUT, connect_timeout)
306 if timeout is not None:
307 curl.setopt(pycurl.TIMEOUT, timeout)
312 class GanetiRapiClient(object): # pylint: disable=R0904
313 """Ganeti RAPI client.
316 USER_AGENT = "Ganeti RAPI Client"
317 _json_encoder = simplejson.JSONEncoder(sort_keys=True)
319 def __init__(self, host, port=GANETI_RAPI_PORT,
320 username=None, password=None, logger=logging,
321 curl_config_fn=None, curl_factory=None):
322 """Initializes this class.
325 @param host: the ganeti cluster master to interact with
327 @param port: the port on which the RAPI is running (default is 5080)
328 @type username: string
329 @param username: the username to connect with
330 @type password: string
331 @param password: the password to connect with
332 @type curl_config_fn: callable
333 @param curl_config_fn: Function to configure C{pycurl.Curl} object
334 @param logger: Logging object
337 self._username = username
338 self._password = password
339 self._logger = logger
340 self._curl_config_fn = curl_config_fn
341 self._curl_factory = curl_factory
344 socket.inet_pton(socket.AF_INET6, host)
345 address = "[%s]:%s" % (host, port)
347 address = "%s:%s" % (host, port)
349 self._base_url = "https://%s" % address
351 if username is not None:
353 raise Error("Password not specified")
355 raise Error("Specified password without username")
357 def _CreateCurl(self):
358 """Creates a cURL object.
361 # Create pycURL object if no factory is provided
362 if self._curl_factory:
363 curl = self._curl_factory()
367 # Default cURL settings
368 curl.setopt(pycurl.VERBOSE, False)
369 curl.setopt(pycurl.FOLLOWLOCATION, False)
370 curl.setopt(pycurl.MAXREDIRS, 5)
371 curl.setopt(pycurl.NOSIGNAL, True)
372 curl.setopt(pycurl.USERAGENT, self.USER_AGENT)
373 curl.setopt(pycurl.SSL_VERIFYHOST, 0)
374 curl.setopt(pycurl.SSL_VERIFYPEER, False)
375 curl.setopt(pycurl.HTTPHEADER, [
376 "Accept: %s" % HTTP_APP_JSON,
377 "Content-type: %s" % HTTP_APP_JSON,
380 assert ((self._username is None and self._password is None) ^
381 (self._username is not None and self._password is not None))
384 # Setup authentication
385 curl.setopt(pycurl.HTTPAUTH, pycurl.HTTPAUTH_BASIC)
386 curl.setopt(pycurl.USERPWD,
387 str("%s:%s" % (self._username, self._password)))
389 # Call external configuration function
390 if self._curl_config_fn:
391 self._curl_config_fn(curl, self._logger)
396 def _EncodeQuery(query):
397 """Encode query values for RAPI URL.
399 @type query: list of two-tuples
400 @param query: Query arguments
402 @return: Query list with encoded values
407 for name, value in query:
409 result.append((name, ""))
411 elif isinstance(value, bool):
412 # Boolean values must be encoded as 0 or 1
413 result.append((name, int(value)))
415 elif isinstance(value, (list, tuple, dict)):
416 raise ValueError("Invalid query data type %r" % type(value).__name__)
419 result.append((name, value))
423 def _SendRequest(self, method, path, query, content):
424 """Sends an HTTP request.
426 This constructs a full URL, encodes and decodes HTTP bodies, and
427 handles invalid responses in a pythonic way.
430 @param method: HTTP method to use
432 @param path: HTTP URL path
433 @type query: list of two-tuples
434 @param query: query arguments to pass to urllib.urlencode
435 @type content: str or None
436 @param content: HTTP body content
439 @return: JSON-Decoded response
441 @raises CertificateError: If an invalid SSL certificate is found
442 @raises GanetiApiError: If an invalid response is returned
445 assert path.startswith("/")
447 curl = self._CreateCurl()
449 if content is not None:
450 encoded_content = self._json_encoder.encode(content)
455 urlparts = [self._base_url, path]
458 urlparts.append(urllib.urlencode(self._EncodeQuery(query)))
460 url = "".join(urlparts)
462 self._logger.debug("Sending request %s %s (content=%r)",
463 method, url, encoded_content)
465 # Buffer for response
466 encoded_resp_body = StringIO()
469 curl.setopt(pycurl.CUSTOMREQUEST, str(method))
470 curl.setopt(pycurl.URL, str(url))
471 curl.setopt(pycurl.POSTFIELDS, str(encoded_content))
472 curl.setopt(pycurl.WRITEFUNCTION, encoded_resp_body.write)
475 # Send request and wait for response
478 except pycurl.error, err:
479 if err.args[0] in _CURL_SSL_CERT_ERRORS:
480 raise CertificateError("SSL certificate error %s" % err)
482 raise GanetiApiError(str(err))
484 # Reset settings to not keep references to large objects in memory
486 curl.setopt(pycurl.POSTFIELDS, "")
487 curl.setopt(pycurl.WRITEFUNCTION, lambda _: None)
489 # Get HTTP response code
490 http_code = curl.getinfo(pycurl.RESPONSE_CODE)
492 # Was anything written to the response buffer?
493 if encoded_resp_body.tell():
494 response_content = simplejson.loads(encoded_resp_body.getvalue())
496 response_content = None
498 if http_code != HTTP_OK:
499 if isinstance(response_content, dict):
501 (response_content["code"],
502 response_content["message"],
503 response_content["explain"]))
505 msg = str(response_content)
507 raise GanetiApiError(msg, code=http_code)
509 return response_content
511 def GetVersion(self):
512 """Gets the Remote API version running on the cluster.
515 @return: Ganeti Remote API version
518 return self._SendRequest(HTTP_GET, "/version", None, None)
520 def GetFeatures(self):
521 """Gets the list of optional features supported by RAPI server.
524 @return: List of optional features
528 return self._SendRequest(HTTP_GET, "/%s/features" % GANETI_RAPI_VERSION,
530 except GanetiApiError, err:
531 # Older RAPI servers don't support this resource
532 if err.code == HTTP_NOT_FOUND:
537 def GetOperatingSystems(self):
538 """Gets the Operating Systems running in the Ganeti cluster.
541 @return: operating systems
544 return self._SendRequest(HTTP_GET, "/%s/os" % GANETI_RAPI_VERSION,
548 """Gets info about the cluster.
551 @return: information about the cluster
554 return self._SendRequest(HTTP_GET, "/%s/info" % GANETI_RAPI_VERSION,
557 def RedistributeConfig(self):
558 """Tells the cluster to redistribute its configuration files.
564 return self._SendRequest(HTTP_PUT,
565 "/%s/redistribute-config" % GANETI_RAPI_VERSION,
568 def ModifyCluster(self, **kwargs):
569 """Modifies cluster parameters.
571 More details for parameters can be found in the RAPI documentation.
579 return self._SendRequest(HTTP_PUT,
580 "/%s/modify" % GANETI_RAPI_VERSION, None, body)
582 def GetClusterTags(self):
583 """Gets the cluster tags.
586 @return: cluster tags
589 return self._SendRequest(HTTP_GET, "/%s/tags" % GANETI_RAPI_VERSION,
592 def AddClusterTags(self, tags, dry_run=False):
593 """Adds tags to the cluster.
595 @type tags: list of str
596 @param tags: tags to add to the cluster
598 @param dry_run: whether to perform a dry run
604 query = [("tag", t) for t in tags]
605 _AppendDryRunIf(query, dry_run)
607 return self._SendRequest(HTTP_PUT, "/%s/tags" % GANETI_RAPI_VERSION,
610 def DeleteClusterTags(self, tags, dry_run=False):
611 """Deletes tags from the cluster.
613 @type tags: list of str
614 @param tags: tags to delete
616 @param dry_run: whether to perform a dry run
621 query = [("tag", t) for t in tags]
622 _AppendDryRunIf(query, dry_run)
624 return self._SendRequest(HTTP_DELETE, "/%s/tags" % GANETI_RAPI_VERSION,
627 def GetInstances(self, bulk=False):
628 """Gets information about instances on the cluster.
631 @param bulk: whether to return all information about all instances
633 @rtype: list of dict or list of str
634 @return: if bulk is True, info about the instances, else a list of instances
638 _AppendIf(query, bulk, ("bulk", 1))
640 instances = self._SendRequest(HTTP_GET,
641 "/%s/instances" % GANETI_RAPI_VERSION,
646 return [i["id"] for i in instances]
648 def GetInstance(self, instance):
649 """Gets information about an instance.
652 @param instance: instance whose info to return
655 @return: info about the instance
658 return self._SendRequest(HTTP_GET,
659 ("/%s/instances/%s" %
660 (GANETI_RAPI_VERSION, instance)), None, None)
662 def GetInstanceInfo(self, instance, static=None):
663 """Gets information about an instance.
665 @type instance: string
666 @param instance: Instance name
671 if static is not None:
672 query = [("static", static)]
676 return self._SendRequest(HTTP_GET,
677 ("/%s/instances/%s/info" %
678 (GANETI_RAPI_VERSION, instance)), query, None)
680 def CreateInstance(self, mode, name, disk_template, disks, nics,
682 """Creates a new instance.
684 More details for parameters can be found in the RAPI documentation.
687 @param mode: Instance creation mode
689 @param name: Hostname of the instance to create
690 @type disk_template: string
691 @param disk_template: Disk template for instance (e.g. plain, diskless,
693 @type disks: list of dicts
694 @param disks: List of disk definitions
695 @type nics: list of dicts
696 @param nics: List of NIC definitions
698 @keyword dry_run: whether to perform a dry run
706 _AppendDryRunIf(query, kwargs.get("dry_run"))
708 if _INST_CREATE_REQV1 in self.GetFeatures():
709 # All required fields for request data version 1
711 _REQ_DATA_VERSION_FIELD: 1,
714 "disk_template": disk_template,
719 conflicts = set(kwargs.iterkeys()) & set(body.iterkeys())
721 raise GanetiApiError("Required fields can not be specified as"
722 " keywords: %s" % ", ".join(conflicts))
724 body.update((key, value) for key, value in kwargs.iteritems()
727 raise GanetiApiError("Server does not support new-style (version 1)"
728 " instance creation requests")
730 return self._SendRequest(HTTP_POST, "/%s/instances" % GANETI_RAPI_VERSION,
733 def DeleteInstance(self, instance, dry_run=False):
734 """Deletes an instance.
737 @param instance: the instance to delete
744 _AppendDryRunIf(query, dry_run)
746 return self._SendRequest(HTTP_DELETE,
747 ("/%s/instances/%s" %
748 (GANETI_RAPI_VERSION, instance)), query, None)
750 def ModifyInstance(self, instance, **kwargs):
751 """Modifies an instance.
753 More details for parameters can be found in the RAPI documentation.
755 @type instance: string
756 @param instance: Instance name
763 return self._SendRequest(HTTP_PUT,
764 ("/%s/instances/%s/modify" %
765 (GANETI_RAPI_VERSION, instance)), None, body)
767 def ActivateInstanceDisks(self, instance, ignore_size=None):
768 """Activates an instance's disks.
770 @type instance: string
771 @param instance: Instance name
772 @type ignore_size: bool
773 @param ignore_size: Whether to ignore recorded size
779 _AppendIf(query, ignore_size, ("ignore_size", 1))
781 return self._SendRequest(HTTP_PUT,
782 ("/%s/instances/%s/activate-disks" %
783 (GANETI_RAPI_VERSION, instance)), query, None)
785 def DeactivateInstanceDisks(self, instance):
786 """Deactivates an instance's disks.
788 @type instance: string
789 @param instance: Instance name
794 return self._SendRequest(HTTP_PUT,
795 ("/%s/instances/%s/deactivate-disks" %
796 (GANETI_RAPI_VERSION, instance)), None, None)
798 def RecreateInstanceDisks(self, instance, disks=None, nodes=None):
799 """Recreate an instance's disks.
801 @type instance: string
802 @param instance: Instance name
803 @type disks: list of int
804 @param disks: List of disk indexes
805 @type nodes: list of string
806 @param nodes: New instance nodes, if relocation is desired
812 _SetItemIf(body, disks is not None, "disks", disks)
813 _SetItemIf(body, nodes is not None, "nodes", nodes)
815 return self._SendRequest(HTTP_POST,
816 ("/%s/instances/%s/recreate-disks" %
817 (GANETI_RAPI_VERSION, instance)), None, body)
819 def GrowInstanceDisk(self, instance, disk, amount, wait_for_sync=None):
820 """Grows a disk of an instance.
822 More details for parameters can be found in the RAPI documentation.
824 @type instance: string
825 @param instance: Instance name
827 @param disk: Disk index
828 @type amount: integer
829 @param amount: Grow disk by this amount (MiB)
830 @type wait_for_sync: bool
831 @param wait_for_sync: Wait for disk to synchronize
840 _SetItemIf(body, wait_for_sync is not None, "wait_for_sync", wait_for_sync)
842 return self._SendRequest(HTTP_POST,
843 ("/%s/instances/%s/disk/%s/grow" %
844 (GANETI_RAPI_VERSION, instance, disk)),
847 def GetInstanceTags(self, instance):
848 """Gets tags for an instance.
851 @param instance: instance whose tags to return
854 @return: tags for the instance
857 return self._SendRequest(HTTP_GET,
858 ("/%s/instances/%s/tags" %
859 (GANETI_RAPI_VERSION, instance)), None, None)
861 def AddInstanceTags(self, instance, tags, dry_run=False):
862 """Adds tags to an instance.
865 @param instance: instance to add tags to
866 @type tags: list of str
867 @param tags: tags to add to the instance
869 @param dry_run: whether to perform a dry run
875 query = [("tag", t) for t in tags]
876 _AppendDryRunIf(query, dry_run)
878 return self._SendRequest(HTTP_PUT,
879 ("/%s/instances/%s/tags" %
880 (GANETI_RAPI_VERSION, instance)), query, None)
882 def DeleteInstanceTags(self, instance, tags, dry_run=False):
883 """Deletes tags from an instance.
886 @param instance: instance to delete tags from
887 @type tags: list of str
888 @param tags: tags to delete
890 @param dry_run: whether to perform a dry run
895 query = [("tag", t) for t in tags]
896 _AppendDryRunIf(query, dry_run)
898 return self._SendRequest(HTTP_DELETE,
899 ("/%s/instances/%s/tags" %
900 (GANETI_RAPI_VERSION, instance)), query, None)
902 def RebootInstance(self, instance, reboot_type=None, ignore_secondaries=None,
904 """Reboots an instance.
907 @param instance: instance to rebot
908 @type reboot_type: str
909 @param reboot_type: one of: hard, soft, full
910 @type ignore_secondaries: bool
911 @param ignore_secondaries: if True, ignores errors for the secondary node
912 while re-assembling disks (in hard-reboot mode only)
914 @param dry_run: whether to perform a dry run
920 _AppendDryRunIf(query, dry_run)
921 _AppendIf(query, reboot_type, ("type", reboot_type))
922 _AppendIf(query, ignore_secondaries is not None,
923 ("ignore_secondaries", ignore_secondaries))
925 return self._SendRequest(HTTP_POST,
926 ("/%s/instances/%s/reboot" %
927 (GANETI_RAPI_VERSION, instance)), query, None)
929 def ShutdownInstance(self, instance, dry_run=False, no_remember=False):
930 """Shuts down an instance.
933 @param instance: the instance to shut down
935 @param dry_run: whether to perform a dry run
936 @type no_remember: bool
937 @param no_remember: if true, will not record the state change
943 _AppendDryRunIf(query, dry_run)
944 _AppendIf(query, no_remember, ("no-remember", 1))
946 return self._SendRequest(HTTP_PUT,
947 ("/%s/instances/%s/shutdown" %
948 (GANETI_RAPI_VERSION, instance)), query, None)
950 def StartupInstance(self, instance, dry_run=False, no_remember=False):
951 """Starts up an instance.
954 @param instance: the instance to start up
956 @param dry_run: whether to perform a dry run
957 @type no_remember: bool
958 @param no_remember: if true, will not record the state change
964 _AppendDryRunIf(query, dry_run)
965 _AppendIf(query, no_remember, ("no-remember", 1))
967 return self._SendRequest(HTTP_PUT,
968 ("/%s/instances/%s/startup" %
969 (GANETI_RAPI_VERSION, instance)), query, None)
971 def ReinstallInstance(self, instance, os=None, no_startup=False,
973 """Reinstalls an instance.
976 @param instance: The instance to reinstall
977 @type os: str or None
978 @param os: The operating system to reinstall. If None, the instance's
979 current operating system will be installed again
980 @type no_startup: bool
981 @param no_startup: Whether to start the instance automatically
986 if _INST_REINSTALL_REQV1 in self.GetFeatures():
988 "start": not no_startup,
990 _SetItemIf(body, os is not None, "os", os)
991 _SetItemIf(body, osparams is not None, "osparams", osparams)
992 return self._SendRequest(HTTP_POST,
993 ("/%s/instances/%s/reinstall" %
994 (GANETI_RAPI_VERSION, instance)), None, body)
996 # Use old request format
998 raise GanetiApiError("Server does not support specifying OS parameters"
999 " for instance reinstallation")
1002 _AppendIf(query, os, ("os", os))
1003 _AppendIf(query, no_startup, ("nostartup", 1))
1005 return self._SendRequest(HTTP_POST,
1006 ("/%s/instances/%s/reinstall" %
1007 (GANETI_RAPI_VERSION, instance)), query, None)
1009 def ReplaceInstanceDisks(self, instance, disks=None, mode=REPLACE_DISK_AUTO,
1010 remote_node=None, iallocator=None):
1011 """Replaces disks on an instance.
1014 @param instance: instance whose disks to replace
1015 @type disks: list of ints
1016 @param disks: Indexes of disks to replace
1018 @param mode: replacement mode to use (defaults to replace_auto)
1019 @type remote_node: str or None
1020 @param remote_node: new secondary node to use (for use with
1021 replace_new_secondary mode)
1022 @type iallocator: str or None
1023 @param iallocator: instance allocator plugin to use (for use with
1034 # TODO: Convert to body parameters
1036 if disks is not None:
1037 _AppendIf(query, True,
1038 ("disks", ",".join(str(idx) for idx in disks)))
1040 _AppendIf(query, remote_node is not None, ("remote_node", remote_node))
1041 _AppendIf(query, iallocator is not None, ("iallocator", iallocator))
1043 return self._SendRequest(HTTP_POST,
1044 ("/%s/instances/%s/replace-disks" %
1045 (GANETI_RAPI_VERSION, instance)), query, None)
1047 def PrepareExport(self, instance, mode):
1048 """Prepares an instance for an export.
1050 @type instance: string
1051 @param instance: Instance name
1053 @param mode: Export mode
1058 query = [("mode", mode)]
1059 return self._SendRequest(HTTP_PUT,
1060 ("/%s/instances/%s/prepare-export" %
1061 (GANETI_RAPI_VERSION, instance)), query, None)
1063 def ExportInstance(self, instance, mode, destination, shutdown=None,
1064 remove_instance=None,
1065 x509_key_name=None, destination_x509_ca=None):
1066 """Exports an instance.
1068 @type instance: string
1069 @param instance: Instance name
1071 @param mode: Export mode
1077 "destination": destination,
1081 _SetItemIf(body, shutdown is not None, "shutdown", shutdown)
1082 _SetItemIf(body, remove_instance is not None,
1083 "remove_instance", remove_instance)
1084 _SetItemIf(body, x509_key_name is not None, "x509_key_name", x509_key_name)
1085 _SetItemIf(body, destination_x509_ca is not None,
1086 "destination_x509_ca", destination_x509_ca)
1088 return self._SendRequest(HTTP_PUT,
1089 ("/%s/instances/%s/export" %
1090 (GANETI_RAPI_VERSION, instance)), None, body)
1092 def MigrateInstance(self, instance, mode=None, cleanup=None):
1093 """Migrates an instance.
1095 @type instance: string
1096 @param instance: Instance name
1098 @param mode: Migration mode
1100 @param cleanup: Whether to clean up a previously failed migration
1106 _SetItemIf(body, mode is not None, "mode", mode)
1107 _SetItemIf(body, cleanup is not None, "cleanup", cleanup)
1109 return self._SendRequest(HTTP_PUT,
1110 ("/%s/instances/%s/migrate" %
1111 (GANETI_RAPI_VERSION, instance)), None, body)
1113 def FailoverInstance(self, instance, iallocator=None,
1114 ignore_consistency=None, target_node=None):
1115 """Does a failover of an instance.
1117 @type instance: string
1118 @param instance: Instance name
1119 @type iallocator: string
1120 @param iallocator: Iallocator for deciding the target node for
1121 shared-storage instances
1122 @type ignore_consistency: bool
1123 @param ignore_consistency: Whether to ignore disk consistency
1124 @type target_node: string
1125 @param target_node: Target node for shared-storage instances
1131 _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1132 _SetItemIf(body, ignore_consistency is not None,
1133 "ignore_consistency", ignore_consistency)
1134 _SetItemIf(body, target_node is not None, "target_node", target_node)
1136 return self._SendRequest(HTTP_PUT,
1137 ("/%s/instances/%s/failover" %
1138 (GANETI_RAPI_VERSION, instance)), None, body)
1140 def RenameInstance(self, instance, new_name, ip_check=None, name_check=None):
1141 """Changes the name of an instance.
1143 @type instance: string
1144 @param instance: Instance name
1145 @type new_name: string
1146 @param new_name: New instance name
1147 @type ip_check: bool
1148 @param ip_check: Whether to ensure instance's IP address is inactive
1149 @type name_check: bool
1150 @param name_check: Whether to ensure instance's name is resolvable
1156 "new_name": new_name,
1159 _SetItemIf(body, ip_check is not None, "ip_check", ip_check)
1160 _SetItemIf(body, name_check is not None, "name_check", name_check)
1162 return self._SendRequest(HTTP_PUT,
1163 ("/%s/instances/%s/rename" %
1164 (GANETI_RAPI_VERSION, instance)), None, body)
1166 def GetInstanceConsole(self, instance):
1167 """Request information for connecting to instance's console.
1169 @type instance: string
1170 @param instance: Instance name
1172 @return: dictionary containing information about instance's console
1175 return self._SendRequest(HTTP_GET,
1176 ("/%s/instances/%s/console" %
1177 (GANETI_RAPI_VERSION, instance)), None, None)
1180 """Gets all jobs for the cluster.
1183 @return: job ids for the cluster
1186 return [int(j["id"])
1187 for j in self._SendRequest(HTTP_GET,
1188 "/%s/jobs" % GANETI_RAPI_VERSION,
1191 def GetJobStatus(self, job_id):
1192 """Gets the status of a job.
1194 @type job_id: string
1195 @param job_id: job id whose status to query
1201 return self._SendRequest(HTTP_GET,
1202 "/%s/jobs/%s" % (GANETI_RAPI_VERSION, job_id),
1205 def WaitForJobCompletion(self, job_id, period=5, retries=-1):
1206 """Polls cluster for job status until completion.
1208 Completion is defined as any of the following states listed in
1209 L{JOB_STATUS_FINALIZED}.
1211 @type job_id: string
1212 @param job_id: job id to watch
1214 @param period: how often to poll for status (optional, default 5s)
1216 @param retries: how many time to poll before giving up
1217 (optional, default -1 means unlimited)
1220 @return: C{True} if job succeeded or C{False} if failed/status timeout
1221 @deprecated: It is recommended to use L{WaitForJobChange} wherever
1222 possible; L{WaitForJobChange} returns immediately after a job changed and
1223 does not use polling
1227 job_result = self.GetJobStatus(job_id)
1229 if job_result and job_result["status"] == JOB_STATUS_SUCCESS:
1231 elif not job_result or job_result["status"] in JOB_STATUS_FINALIZED:
1242 def WaitForJobChange(self, job_id, fields, prev_job_info, prev_log_serial):
1243 """Waits for job changes.
1245 @type job_id: string
1246 @param job_id: Job ID for which to wait
1247 @return: C{None} if no changes have been detected and a dict with two keys,
1248 C{job_info} and C{log_entries} otherwise.
1254 "previous_job_info": prev_job_info,
1255 "previous_log_serial": prev_log_serial,
1258 return self._SendRequest(HTTP_GET,
1259 "/%s/jobs/%s/wait" % (GANETI_RAPI_VERSION, job_id),
1262 def CancelJob(self, job_id, dry_run=False):
1265 @type job_id: string
1266 @param job_id: id of the job to delete
1268 @param dry_run: whether to perform a dry run
1270 @return: tuple containing the result, and a message (bool, string)
1274 _AppendDryRunIf(query, dry_run)
1276 return self._SendRequest(HTTP_DELETE,
1277 "/%s/jobs/%s" % (GANETI_RAPI_VERSION, job_id),
1280 def GetNodes(self, bulk=False):
1281 """Gets all nodes in the cluster.
1284 @param bulk: whether to return all information about all instances
1286 @rtype: list of dict or str
1287 @return: if bulk is true, info about nodes in the cluster,
1288 else list of nodes in the cluster
1292 _AppendIf(query, bulk, ("bulk", 1))
1294 nodes = self._SendRequest(HTTP_GET, "/%s/nodes" % GANETI_RAPI_VERSION,
1299 return [n["id"] for n in nodes]
1301 def GetNode(self, node):
1302 """Gets information about a node.
1305 @param node: node whose info to return
1308 @return: info about the node
1311 return self._SendRequest(HTTP_GET,
1312 "/%s/nodes/%s" % (GANETI_RAPI_VERSION, node),
1315 def EvacuateNode(self, node, iallocator=None, remote_node=None,
1316 dry_run=False, early_release=None,
1317 mode=None, accept_old=False):
1318 """Evacuates instances from a Ganeti node.
1321 @param node: node to evacuate
1322 @type iallocator: str or None
1323 @param iallocator: instance allocator to use
1324 @type remote_node: str
1325 @param remote_node: node to evaucate to
1327 @param dry_run: whether to perform a dry run
1328 @type early_release: bool
1329 @param early_release: whether to enable parallelization
1331 @param mode: Node evacuation mode
1332 @type accept_old: bool
1333 @param accept_old: Whether caller is ready to accept old-style (pre-2.5)
1336 @rtype: string, or a list for pre-2.5 results
1337 @return: Job ID or, if C{accept_old} is set and server is pre-2.5,
1338 list of (job ID, instance name, new secondary node); if dry_run was
1339 specified, then the actual move jobs were not submitted and the job IDs
1342 @raises GanetiApiError: if an iallocator and remote_node are both
1346 if iallocator and remote_node:
1347 raise GanetiApiError("Only one of iallocator or remote_node can be used")
1350 _AppendDryRunIf(query, dry_run)
1352 if _NODE_EVAC_RES1 in self.GetFeatures():
1353 # Server supports body parameters
1356 _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1357 _SetItemIf(body, remote_node is not None, "remote_node", remote_node)
1358 _SetItemIf(body, early_release is not None,
1359 "early_release", early_release)
1360 _SetItemIf(body, mode is not None, "mode", mode)
1362 # Pre-2.5 request format
1366 raise GanetiApiError("Server is version 2.4 or earlier and caller does"
1367 " not accept old-style results (parameter"
1370 # Pre-2.5 servers can only evacuate secondaries
1371 if mode is not None and mode != NODE_EVAC_SEC:
1372 raise GanetiApiError("Server can only evacuate secondary instances")
1374 _AppendIf(query, iallocator, ("iallocator", iallocator))
1375 _AppendIf(query, remote_node, ("remote_node", remote_node))
1376 _AppendIf(query, early_release, ("early_release", 1))
1378 return self._SendRequest(HTTP_POST,
1379 ("/%s/nodes/%s/evacuate" %
1380 (GANETI_RAPI_VERSION, node)), query, body)
1382 def MigrateNode(self, node, mode=None, dry_run=False, iallocator=None,
1384 """Migrates all primary instances from a node.
1387 @param node: node to migrate
1389 @param mode: if passed, it will overwrite the live migration type,
1390 otherwise the hypervisor default will be used
1392 @param dry_run: whether to perform a dry run
1393 @type iallocator: string
1394 @param iallocator: instance allocator to use
1395 @type target_node: string
1396 @param target_node: Target node for shared-storage instances
1403 _AppendDryRunIf(query, dry_run)
1405 if _NODE_MIGRATE_REQV1 in self.GetFeatures():
1408 _SetItemIf(body, mode is not None, "mode", mode)
1409 _SetItemIf(body, iallocator is not None, "iallocator", iallocator)
1410 _SetItemIf(body, target_node is not None, "target_node", target_node)
1412 assert len(query) <= 1
1414 return self._SendRequest(HTTP_POST,
1415 ("/%s/nodes/%s/migrate" %
1416 (GANETI_RAPI_VERSION, node)), query, body)
1418 # Use old request format
1419 if target_node is not None:
1420 raise GanetiApiError("Server does not support specifying target node"
1421 " for node migration")
1423 _AppendIf(query, mode is not None, ("mode", mode))
1425 return self._SendRequest(HTTP_POST,
1426 ("/%s/nodes/%s/migrate" %
1427 (GANETI_RAPI_VERSION, node)), query, None)
1429 def GetNodeRole(self, node):
1430 """Gets the current role for a node.
1433 @param node: node whose role to return
1436 @return: the current role for a node
1439 return self._SendRequest(HTTP_GET,
1440 ("/%s/nodes/%s/role" %
1441 (GANETI_RAPI_VERSION, node)), None, None)
1443 def SetNodeRole(self, node, role, force=False, auto_promote=None):
1444 """Sets the role for a node.
1447 @param node: the node whose role to set
1449 @param role: the role to set for the node
1451 @param force: whether to force the role change
1452 @type auto_promote: bool
1453 @param auto_promote: Whether node(s) should be promoted to master candidate
1461 _AppendForceIf(query, force)
1462 _AppendIf(query, auto_promote is not None, ("auto-promote", auto_promote))
1464 return self._SendRequest(HTTP_PUT,
1465 ("/%s/nodes/%s/role" %
1466 (GANETI_RAPI_VERSION, node)), query, role)
1468 def PowercycleNode(self, node, force=False):
1469 """Powercycles a node.
1472 @param node: Node name
1474 @param force: Whether to force the operation
1480 _AppendForceIf(query, force)
1482 return self._SendRequest(HTTP_POST,
1483 ("/%s/nodes/%s/powercycle" %
1484 (GANETI_RAPI_VERSION, node)), query, None)
1486 def ModifyNode(self, node, **kwargs):
1489 More details for parameters can be found in the RAPI documentation.
1492 @param node: Node name
1497 return self._SendRequest(HTTP_POST,
1498 ("/%s/nodes/%s/modify" %
1499 (GANETI_RAPI_VERSION, node)), None, kwargs)
1501 def GetNodeStorageUnits(self, node, storage_type, output_fields):
1502 """Gets the storage units for a node.
1505 @param node: the node whose storage units to return
1506 @type storage_type: str
1507 @param storage_type: storage type whose units to return
1508 @type output_fields: str
1509 @param output_fields: storage type fields to return
1512 @return: job id where results can be retrieved
1516 ("storage_type", storage_type),
1517 ("output_fields", output_fields),
1520 return self._SendRequest(HTTP_GET,
1521 ("/%s/nodes/%s/storage" %
1522 (GANETI_RAPI_VERSION, node)), query, None)
1524 def ModifyNodeStorageUnits(self, node, storage_type, name, allocatable=None):
1525 """Modifies parameters of storage units on the node.
1528 @param node: node whose storage units to modify
1529 @type storage_type: str
1530 @param storage_type: storage type whose units to modify
1532 @param name: name of the storage unit
1533 @type allocatable: bool or None
1534 @param allocatable: Whether to set the "allocatable" flag on the storage
1535 unit (None=no modification, True=set, False=unset)
1542 ("storage_type", storage_type),
1546 _AppendIf(query, allocatable is not None, ("allocatable", allocatable))
1548 return self._SendRequest(HTTP_PUT,
1549 ("/%s/nodes/%s/storage/modify" %
1550 (GANETI_RAPI_VERSION, node)), query, None)
1552 def RepairNodeStorageUnits(self, node, storage_type, name):
1553 """Repairs a storage unit on the node.
1556 @param node: node whose storage units to repair
1557 @type storage_type: str
1558 @param storage_type: storage type to repair
1560 @param name: name of the storage unit to repair
1567 ("storage_type", storage_type),
1571 return self._SendRequest(HTTP_PUT,
1572 ("/%s/nodes/%s/storage/repair" %
1573 (GANETI_RAPI_VERSION, node)), query, None)
1575 def GetNodeTags(self, node):
1576 """Gets the tags for a node.
1579 @param node: node whose tags to return
1582 @return: tags for the node
1585 return self._SendRequest(HTTP_GET,
1586 ("/%s/nodes/%s/tags" %
1587 (GANETI_RAPI_VERSION, node)), None, None)
1589 def AddNodeTags(self, node, tags, dry_run=False):
1590 """Adds tags to a node.
1593 @param node: node to add tags to
1594 @type tags: list of str
1595 @param tags: tags to add to the node
1597 @param dry_run: whether to perform a dry run
1603 query = [("tag", t) for t in tags]
1604 _AppendDryRunIf(query, dry_run)
1606 return self._SendRequest(HTTP_PUT,
1607 ("/%s/nodes/%s/tags" %
1608 (GANETI_RAPI_VERSION, node)), query, tags)
1610 def DeleteNodeTags(self, node, tags, dry_run=False):
1611 """Delete tags from a node.
1614 @param node: node to remove tags from
1615 @type tags: list of str
1616 @param tags: tags to remove from the node
1618 @param dry_run: whether to perform a dry run
1624 query = [("tag", t) for t in tags]
1625 _AppendDryRunIf(query, dry_run)
1627 return self._SendRequest(HTTP_DELETE,
1628 ("/%s/nodes/%s/tags" %
1629 (GANETI_RAPI_VERSION, node)), query, None)
1631 def GetGroups(self, bulk=False):
1632 """Gets all node groups in the cluster.
1635 @param bulk: whether to return all information about the groups
1637 @rtype: list of dict or str
1638 @return: if bulk is true, a list of dictionaries with info about all node
1639 groups in the cluster, else a list of names of those node groups
1643 _AppendIf(query, bulk, ("bulk", 1))
1645 groups = self._SendRequest(HTTP_GET, "/%s/groups" % GANETI_RAPI_VERSION,
1650 return [g["name"] for g in groups]
1652 def GetGroup(self, group):
1653 """Gets information about a node group.
1656 @param group: name of the node group whose info to return
1659 @return: info about the node group
1662 return self._SendRequest(HTTP_GET,
1663 "/%s/groups/%s" % (GANETI_RAPI_VERSION, group),
1666 def CreateGroup(self, name, alloc_policy=None, dry_run=False):
1667 """Creates a new node group.
1670 @param name: the name of node group to create
1671 @type alloc_policy: str
1672 @param alloc_policy: the desired allocation policy for the group, if any
1674 @param dry_run: whether to peform a dry run
1681 _AppendDryRunIf(query, dry_run)
1685 "alloc_policy": alloc_policy
1688 return self._SendRequest(HTTP_POST, "/%s/groups" % GANETI_RAPI_VERSION,
1691 def ModifyGroup(self, group, **kwargs):
1692 """Modifies a node group.
1694 More details for parameters can be found in the RAPI documentation.
1697 @param group: Node group name
1702 return self._SendRequest(HTTP_PUT,
1703 ("/%s/groups/%s/modify" %
1704 (GANETI_RAPI_VERSION, group)), None, kwargs)
1706 def DeleteGroup(self, group, dry_run=False):
1707 """Deletes a node group.
1710 @param group: the node group to delete
1712 @param dry_run: whether to peform a dry run
1719 _AppendDryRunIf(query, dry_run)
1721 return self._SendRequest(HTTP_DELETE,
1723 (GANETI_RAPI_VERSION, group)), query, None)
1725 def RenameGroup(self, group, new_name):
1726 """Changes the name of a node group.
1729 @param group: Node group name
1730 @type new_name: string
1731 @param new_name: New node group name
1738 "new_name": new_name,
1741 return self._SendRequest(HTTP_PUT,
1742 ("/%s/groups/%s/rename" %
1743 (GANETI_RAPI_VERSION, group)), None, body)
1745 def AssignGroupNodes(self, group, nodes, force=False, dry_run=False):
1746 """Assigns nodes to a group.
1749 @param group: Node gropu name
1750 @type nodes: list of strings
1751 @param nodes: List of nodes to assign to the group
1758 _AppendForceIf(query, force)
1759 _AppendDryRunIf(query, dry_run)
1765 return self._SendRequest(HTTP_PUT,
1766 ("/%s/groups/%s/assign-nodes" %
1767 (GANETI_RAPI_VERSION, group)), query, body)
1769 def GetGroupTags(self, group):
1770 """Gets tags for a node group.
1773 @param group: Node group whose tags to return
1775 @rtype: list of strings
1776 @return: tags for the group
1779 return self._SendRequest(HTTP_GET,
1780 ("/%s/groups/%s/tags" %
1781 (GANETI_RAPI_VERSION, group)), None, None)
1783 def AddGroupTags(self, group, tags, dry_run=False):
1784 """Adds tags to a node group.
1787 @param group: group to add tags to
1788 @type tags: list of string
1789 @param tags: tags to add to the group
1791 @param dry_run: whether to perform a dry run
1797 query = [("tag", t) for t in tags]
1798 _AppendDryRunIf(query, dry_run)
1800 return self._SendRequest(HTTP_PUT,
1801 ("/%s/groups/%s/tags" %
1802 (GANETI_RAPI_VERSION, group)), query, None)
1804 def DeleteGroupTags(self, group, tags, dry_run=False):
1805 """Deletes tags from a node group.
1808 @param group: group to delete tags from
1809 @type tags: list of string
1810 @param tags: tags to delete
1812 @param dry_run: whether to perform a dry run
1817 query = [("tag", t) for t in tags]
1818 _AppendDryRunIf(query, dry_run)
1820 return self._SendRequest(HTTP_DELETE,
1821 ("/%s/groups/%s/tags" %
1822 (GANETI_RAPI_VERSION, group)), query, None)
1824 def Query(self, what, fields, qfilter=None):
1825 """Retrieves information about resources.
1828 @param what: Resource name, one of L{constants.QR_VIA_RAPI}
1829 @type fields: list of string
1830 @param fields: Requested fields
1831 @type qfilter: None or list
1832 @param qfilter: Query filter
1842 _SetItemIf(body, qfilter is not None, "qfilter", qfilter)
1843 # TODO: remove "filter" after 2.7
1844 _SetItemIf(body, qfilter is not None, "filter", qfilter)
1846 return self._SendRequest(HTTP_PUT,
1848 (GANETI_RAPI_VERSION, what)), None, body)
1850 def QueryFields(self, what, fields=None):
1851 """Retrieves available fields for a resource.
1854 @param what: Resource name, one of L{constants.QR_VIA_RAPI}
1855 @type fields: list of string
1856 @param fields: Requested fields
1864 if fields is not None:
1865 _AppendIf(query, True, ("fields", ",".join(fields)))
1867 return self._SendRequest(HTTP_GET,
1868 ("/%s/query/%s/fields" %
1869 (GANETI_RAPI_VERSION, what)), query, None)