.. _es-tool: `es` - Danube Cloud command-line tool ************************************* `es` is a Swiss Army Knife command-line interface (CLI) for the Danube Cloud API. Installation ============ Requirements ------------ - **Python >= 2.6** - **Python requests** - http://python-requests.org/ - Python tabulate (optional) - https://bitbucket.org/astanin/python-tabulate Download -------- - `es `_ (python script) - `es bash completion `_ (shell script, optional) Configuration ------------- Shell variables used by `es`: ============= =============== **Variable** **Description** ------------- --------------- ES_API_KEY Optional API key used to perform authenticated requests. ============= =============== You can further customize the downloaded `es` python script by opening it in a text editor and changing the following configuration variables: ============= =============== **Variable** **Description** ------------- --------------- API_URL URL of your *Danube Cloud* installation (`SITE_URL`) with `/api` path appended to it. API_KEY Optional API key used to perform authenticated requests (may be read from ``ES_API_KEY`` environment variable). TOKEN_STORE `es` session file location. SSL_VERIFY Whether to verify server SSL certificate. TIMEOUT HTTP connect and read timeout in seconds. ============= =============== .. note:: Always use **HTTPS** for API_URL to achieve optimal transport security. Usage ===== .. sourcecode:: text es action [/resource] [parameters] [output format] action: {login|logout|get|create|set|delete|options} resource: /some/resource/in/api parameters: -foo baz -bar qux ... output format: --json (default) --csv --tabulate --tabulate- .. note:: The tabulate output format will be only available if python-tabulate package is installed. Input ===== .. _es-actions: Actions ------- Action is a command translated into a HTTP method according to this table: ============= ======================================================= **es action** **HTTP method** ------------- ------------------------------------------------------- get GET create POST set PUT delete DELETE options OPTIONS login :http:post:`POST /api/accounts/login ` logout :http:get:`GET /api/accounts/logout ` ============= ======================================================= .. _es-resources: Resources --------- Every resource begins with a slash and is represented by a path which is used to create a URL. Most of the available resources are bound to a :ref:`virtual datacenter ` and should be prefixed with a ``/dc/(dc)/`` path. .. note:: Please check the `routing table `_ for all available resources. .. _es-parameters: Parameters ---------- Parameters begin with a single dash followed by the name of the parameter, then followed by a value. Parameters are internally translated into :http:method:`POST`/:http:method:`PUT`/:http:method:`DELETE` JSON encoded data or :http:method:`GET` query strings and sent to the server. Some parameters require JSON objects as values, which cannot be expressed as strings or numbers from the command line. It is possible to specify a JSON object as a value by using the ``json::`` prefix. For example, the following command will create a simple template: .. sourcecode:: bash es create /template/small-server -vm_define "json::{\"vcpus\": 1, \"ram\": 512}" The ``file::`` prefix followed by a path leading to the file can be used to load contents of a file as a value for a parameter. .. note:: A special parameter ``-api-key`` can be used to perform an authenticated request without the need to log in. Output ====== `es` supports different output formatters. The default output formatter is `json`_ and it can be changed by using the ``--`` command-line parameter. Some output formatters may require additional python dependencies. json ---- The default output is a JSON object with following attributes: * url - full URL built from the :ref:`resource ` (and parameters if the :ref:`get action ` is specified) * status - response HTTP status code * method - `es` action translated to HTTP method * text - HTTP output in JSON format |es example top|: .. sourcecode:: bash es login -username admin -password Passw0rd .. sourcecode:: json { "url": "https://my.erigones.com/api/accounts/login/", "status": 200, "method": "POST", "text": { "detail": "Welcome to Danube Cloud API." } } csv --- Uses the python built-in csv module to print the API results in CSV (Comma Separated Values) format using the semicolon (``;``) as a field delimiter. |es example top|: .. sourcecode:: bash es get /image -full --csv .. sourcecode:: bash name;deploy;access;alias;version;ostype;owner;size;desc centos-6.4;True;1;centos-6.4;1.0.3;1;admin;10240;CentOS Linux 6.4 64-bit scientific-6.4;True;1;scientific-6.4;1.0.3;1;admin;10240;Scientific Linux 6.4 64-bit ubuntu-12.04;True;1;ubuntu-12.04;1.0.3;1;admin;10240;Ubuntu Linux 12.04.2 LTS 64-bit tabulate -------- The tabulate output formatter requires `python tabulate `_ to be installed. Following table formats are supported: * plain * simple (default) * grid * pipe * orgtbl * rst * mediawiki * latex * latex_booktabs |es example top|: .. sourcecode:: bash es get /image -full --tabulate-grid .. sourcecode:: bash +----------------+----------+----------+----------------+-----------+----------+---------+--------+---------------------------------+ | name | deploy | access | alias | version | ostype | owner | size | desc | +================+==========+==========+================+===========+==========+=========+========+=================================+ | centos-6.4 | 1 | 1 | centos-6.4 | 1.0.3 | 1 | admin | 10240 | CentOS Linux 6.4 64-bit | +----------------+----------+----------+----------------+-----------+----------+---------+--------+---------------------------------+ | scientific-6.4 | 1 | 1 | scientific-6.4 | 1.0.3 | 1 | admin | 10240 | Scientific Linux 6.4 64-bit | +----------------+----------+----------+----------------+-----------+----------+---------+--------+---------------------------------+ | ubuntu-12.04 | 1 | 1 | ubuntu-12.04 | 1.0.3 | 1 | admin | 10240 | Ubuntu Linux 12.04.2 LTS 64-bit | +----------------+----------+----------+----------------+-----------+----------+---------+--------+---------------------------------+