Ganeti remote API ================= Documents Ganeti version |version| .. contents:: Introduction ------------ Ganeti supports a remote API for enable external tools to easily retrieve information about a cluster's state. The remote API daemon, *ganeti-rapi*, is automatically started on the master node. By default it runs on TCP port 5080, but this can be changed either in ``.../constants.py`` or via the command line parameter *-p*. SSL mode, which is used by default, can also be disabled by passing command line parameters. Protocol -------- The protocol used is JSON_ over HTTP designed after the REST_ principle. .. _JSON: http://www.json.org/ .. _REST: http://en.wikipedia.org/wiki/Representational_State_Transfer Usage examples -------------- You can access the API using your favorite programming language as long as it supports network connections. Shell +++++ .. highlight:: sh Using wget:: wget -q -O - https://CLUSTERNAME:5080/2/info or curl:: curl https://CLUSTERNAME:5080/2/info Python ++++++ .. highlight: python import urllib2 f = urllib2.urlopen('https://CLUSTERNAME:5080/2/info') print f.read() JavaScript ++++++++++ .. warning:: While it's possible to use JavaScript, it poses several potential problems, including browser blocking request due to non-standard ports or different domain names. Fetching the data on the webserver is easier. .. highlight:: javascript :: var url = 'https://CLUSTERNAME:5080/2/info'; var info; var xmlreq = new XMLHttpRequest(); xmlreq.onreadystatechange = function () { if (xmlreq.readyState != 4) return; if (xmlreq.status == 200) { info = eval("(" + xmlreq.responseText + ")"); alert(info); } else { alert('Error fetching cluster info'); } xmlreq = null; }; xmlreq.open('GET', url, true); xmlreq.send(null); Resources --------- .. highlight:: javascript ``/`` +++++ The root resource. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Shows the list of mapped resources. Returns: a dictionary with 'name' and 'uri' keys for each of them. ``/2`` ++++++ The ``/2`` resource, the root of the version 2 API. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Show the list of mapped resources. Returns: a dictionary with ``name`` and ``uri`` keys for each of them. ``/2/info`` +++++++++++ Cluster information resource. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Returns cluster information. Example:: { "config_version": 2000000, "name": "cluster", "software_version": "2.0.0~beta2", "os_api_version": 10, "export_version": 0, "candidate_pool_size": 10, "enabled_hypervisors": [ "fake" ], "hvparams": { "fake": {} }, "default_hypervisor": "fake", "master": "node1.example.com", "architecture": [ "64bit", "x86_64" ], "protocol_version": 20, "beparams": { "default": { "auto_balance": true, "vcpus": 1, "memory": 128 } } } ``/2/instances`` ++++++++++++++++ The instances resource. It supports the following commands: ``GET``, ``POST``. ``GET`` ~~~~~~~ Returns a list of all available instances. Example:: [ { "name": "web.example.com", "uri": "\/instances\/web.example.com" }, { "name": "mail.example.com", "uri": "\/instances\/mail.example.com" } ] If the optional *bulk* argument is provided and set to a true value (i.e ``?bulk=1``), the output contains detailed information about instances as a list. Example:: [ { "status": "running", "disk_usage": 20480, "nic.bridges": [ "xen-br0" ], "name": "web.example.com", "tags": ["tag1", "tag2"], "beparams": { "vcpus": 2, "memory": 512 }, "disk.sizes": [ 20480 ], "pnode": "node1.example.com", "nic.macs": ["01:23:45:67:89:01"], "snodes": ["node2.example.com"], "disk_template": "drbd", "admin_state": true, "os": "debian-etch", "oper_state": true }, ... ] ``POST`` ~~~~~~~~ Creates an instance. Returns: a job ID that can be used later for polling. ``/2/instances/[instance_name]`` ++++++++++++++++++++++++++++++++ Instance-specific resource. It supports the following commands: ``GET``, ``DELETE``. ``GET`` ~~~~~~~ Returns information about an instance, similar to the bulk output from the instance list. ``DELETE`` ~~~~~~~~~~ Deletes an instance. ``/2/instances/[instance_name]/reboot`` +++++++++++++++++++++++++++++++++++++++ Reboots URI for an instance. It supports the following commands: ``POST``. ``POST`` ~~~~~~~~ Reboots the instance. The URI takes optional ``type=hard|soft|full`` and ``ignore_secondaries=False|True`` parameters. ``/2/instances/[instance_name]/shutdown`` +++++++++++++++++++++++++++++++++++++++++ Instance shutdown URI. It supports the following commands: ``PUT``. ``PUT`` ~~~~~~~ Shutdowns an instance. ``/2/instances/[instance_name]/startup`` ++++++++++++++++++++++++++++++++++++++++ Instance startup URI. It supports the following commands: ``PUT``. ``PUT`` ~~~~~~~ Startup an instance. The URI takes an optional ``force=False|True`` parameter to start the instance if even if secondary disks are failing. ``/2/instances/[instance_name]/tags`` +++++++++++++++++++++++++++++++++++++ Manages per-instance tags. It supports the following commands: ``GET``, ``PUT``, ``DELETE``. ``GET`` ~~~~~~~ Returns a list of tags. Example:: ["tag1", "tag2", "tag3"] ``PUT`` ~~~~~~~ Add a set of tags. The request as a list of strings should be ``PUT`` to this URI. The result willl be a job id. ``DELETE`` ~~~~~~~~~~ Delete a tag. In order to delete a set of tags, the DELETE request should be addressed to URI like:: /tags?tag=[tag]&tag=[tag] ``/2/jobs`` +++++++++++ The ``/2/jobs`` resource. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Returns a dictionary of jobs. Returns: a dictionary with jobs id and uri. ``/2/jobs/[job_id]`` ++++++++++++++++++++ Individual job URI. It supports the following commands: ``GET``, ``DELETE``. ``GET`` ~~~~~~~ Returns a job status. Returns: a dictionary with job parameters. The result includes: - id: job ID as a number - status: current job status as a string - ops: involved OpCodes as a list of dictionaries for each opcodes in the job - opstatus: OpCodes status as a list - opresult: OpCodes results as a list of lists ``DELETE`` ~~~~~~~~~~ Cancel a not-yet-started job. ``/2/nodes`` ++++++++++++ Nodes resource. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Returns a list of all nodes. Example:: [ { "id": "node1.example.com", "uri": "\/instances\/node1.example.com" }, { "id": "node2.example.com", "uri": "\/instances\/node2.example.com" } ] If the optional 'bulk' argument is provided and set to 'true' value (i.e '?bulk=1'), the output contains detailed information about nodes as a list. Example:: [ { "pinst_cnt": 1, "mfree": 31280, "mtotal": 32763, "name": "www.example.com", "tags": [], "mnode": 512, "dtotal": 5246208, "sinst_cnt": 2, "dfree": 5171712, "offline": false }, ... ] ``/2/nodes/[node_name]/tags`` +++++++++++++++++++++++++++++ Manages per-node tags. It supports the following commands: ``GET``, ``PUT``, ``DELETE``. ``GET`` ~~~~~~~ Returns a list of tags. Example:: ["tag1", "tag2", "tag3"] ``PUT`` ~~~~~~~ Add a set of tags. The request as a list of strings should be PUT to this URI. The result will be a job id. ``DELETE`` ~~~~~~~~~~ Deletes tags. In order to delete a set of tags, the DELETE request should be addressed to URI like:: /tags?tag=[tag]&tag=[tag] ``/2/os`` +++++++++ OS resource. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Return a list of all OSes. Can return error 500 in case of a problem. Since this is a costly operation for Ganeti 2.0, it is not recommended to execute it too often. Example:: ["debian-etch"] ``/2/tags`` +++++++++++ Manages cluster tags. It supports the following commands: ``GET``, ``PUT``, ``DELETE``. ``GET`` ~~~~~~~ Returns the cluster tags. Example:: ["tag1", "tag2", "tag3"] ``PUT`` ~~~~~~~ Adds a set of tags. The request as a list of strings should be PUT to this URI. The result will be a job id. ``DELETE`` ~~~~~~~~~~ Deletes tags. In order to delete a set of tags, the DELETE request should be addressed to URI like:: /tags?tag=[tag]&tag=[tag] ``/version`` ++++++++++++ The version resource. This resource should be used to determine the remote API version and to adapt clients accordingly. It supports the following commands: ``GET``. ``GET`` ~~~~~~~ Returns the remote API version. Ganeti 1.2 returned ``1`` and Ganeti 2.0 returns ``2``.