beam 0.6.0
A lightweight wrapper for the SolusVM client API.
License: MIT

beam
====

.. image:: https://img.shields.io/pypi/status/beam.svg
   :target: https://pypi.python.org/pypi/beam
.. image:: https://img.shields.io/pypi/v/beam.svg
   :target: https://pypi.python.org/pypi/beam
.. image:: https://img.shields.io/pypi/pyversions/beam.svg
   :target: https://pypi.python.org/pypi/beam
.. image:: https://travis-ci.org/gebn/beam.svg?branch=master
   :target: https://travis-ci.org/gebn/beam
.. image:: https://coveralls.io/repos/github/gebn/beam/badge.svg?branch=master
   :target: https://coveralls.io/github/gebn/beam?branch=master

A lightweight wrapper for the SolusVM client API.

Features
--------

-  Query a host's memory, bandwidth, IP addresses and storage usage.
-  Boot, reboot and shutdown machines.
-  Configurable to work with any SolusVM provider.
-  Command line client and intuitive Python module for your own scripts.

Setup
-----

1. Run ``pip install beam`` to download the module.
2. Create your ``.beam.ini`` inventory file as below.

Inventory
~~~~~~~~~

The inventory file holds information about your hosting provider(s) and host(s),
so beam knows how to contact the relevant API endpoints and what credentials to
use. Here's a sample file:

.. code::

   [special:vendors]
   ramnode = https://vpscp.ramnode.com
   vendor2 = https://vendor2-panel.com
   default = ramnode

   [nyc-1]
   key = nyc-1_host_key
   hash = nyc-1_host_hash

   [ams-1]
   key = ams-1_host_key
   hash = ams-1_host_hash
   vendor = vendor2

This file defines two hosts, ``nyc-1``, hosted with RamNode, and ``ams-1``,
hosted with FlipHost. At the top are the vendor names in a special vendors
section (all other sections are assumed to represent hosts). The format maps a
vendor name to their base endpoint for the SolusVM API. The ``default``
directive indicates the implicit vendor of every host, and must be specified if
more than one vendor is defined.

Each host has its own section. The correct ``key`` and ``hash`` values can be
optained from the SolusVM control panel used by your vendor. If a host is not
provided by the default vendor, a ``vendor`` directive specifies the correct
one.

Usage
-----

Beam provides both a Python library for programmatic access to your hosts, and
a simple CLI that wraps it in a couple of lines of code.

CLI
~~~

The CLI client can be used to find information about a single host.

.. code::

    $ beam --help
    usage: beam [-h] [-V]
                (-A {boot,reboot,shutdown} | -a ATTRIBUTES [ATTRIBUTES ...])
                [host]

    A lightweight wrapper for the SolusVM client API.

    positional arguments:
      host                  the identifier of the host whose information to
                            retrieve

    optional arguments:
      -h, --help            show this help message and exit
      -V, --version         show program's version number and exit
      -A {boot,reboot,shutdown}, --action {boot,reboot,shutdown}
                            an action to execute against the host
      -a ATTRIBUTES [ATTRIBUTES ...], --attributes ATTRIBUTES [ATTRIBUTES ...]
                            one or more attributes of the host to retrieve
    $ beam -a bandwidth.free_percentage nyc-1
    0.4983459835
    $ beam -a primary_ip lon-1
    2604:180:2:32b::498b
    $ beam -a is_online memory.used_bytes ams-1
    True
    34578234983
    $ beam -A shutdown nyc-1
    OK

Library
~~~~~~~

.. code:: python

    import beam

    # shutdown a specific host
    host = beam.host('nyc-1')  # name, key or hash
    if host.is_online:
        host.shutdown()

    # boot all offline hosts
    [host.boot() for host in beam.hosts() if not host.is_online]

    # get a list of hosts using above 90% of their memory
    hosts = [host for host in beam.hosts()
             if host.memory.used_percentage > .9]

    # get a list of hosts with less than 10 GiB of storage left
    hosts = [host for host in beam.hosts()
             if host.storage.free_bytes < 1024 ** 3 * 10]

Roadmap
-------

-  Generate documentation.
-  Increase unit test coverage to 100%, and implement some integration tests.

Etymology
---------

Although "solus" means alone, that's a tad depressing. Solus also conjures up
images of the sun for me. The sun *beam*\ s down - and the name was available on
PyPI - so beam it was.