.. _operator_tools:

Operation and Deployment
========================

Installation
------------

You can install from GitHub directly with ``pip``::

    $ pip install -e git://github.com/stackforge/akanda-rug.git@stable/kilo#egg=akanda-rug

After installing :py:mod:`akanda.rug`, it can be invoked as::

    $ akanda-rug-service --config-file /etc/akanda-rug/rug.ini

The :py:mod:`akanda.rug` service is intended to run on a management network (a
separate network for use by your cloud operators).  This segregation prevents
system administration and the monitoring of system access from being disrupted
by traffic generated by guests.

Operator Tools
--------------

rug-ctl
+++++++

:program:`rug-ctl` is a tool which can be used to send manual instructions to
a running :py:mod:`akanda.rug` via AMQP::

    $ rug-ctl browse
    A curses console interface for browsing the state
    of every Neutron router and issuing `rebuild` commands

    $ rug-ctl poll
    Sends a POLL instruction to every router to check health

    $ rug-ctl router rebuild <router-id>
    Sends a REBUILD instruction to a specific router

    $ rug-ctl router update <router-id>
    Sends an UPDATE instruction to a specific router

    $ rug-ctl router debug <router-id>
    Places a specific router in `debug mode`.
    This causes the rug to ignore messages for the specified
    router (so that, for example, operators can investigate
    troublesome routers).

    $ rug-ctl router manage <router-id>
    Removes a specific router from `debug mode` and places
    it back under akanda-rug management.

    $ rug-ctl tenant debug <tenant-id>
    Places a specific tenant in `debug mode`.
    This causes the rug to ignore messages for the specified
    tenant.
    troublesome routers).

    $ rug-ctl tenant manage <tenant-id>
    Removes every router for a specific tenant from `debug mode`
    and places the tenant back under akanda-rug management.

    $ rug-ctl ssh <router-id>
    Establishes an ssh connection with a specified Service VM.

    $ rug-ctl workers debug
    Causes the rug to print debugging diagnostics about the
    current state of its worker processes and the state machines
    under their management.

:program:`akanda-rug` also exposes an RPC API on the management network,
which allows non-interactive `rug-ctl` commands to be issued via HTTP, e.g.,

::

    $ curl -X PUT -g6 "http://[fdca:3ba5:a17a:acda::1]:44250/poll/"
    $ curl -X PUT -g6 "http://[fdca:3ba5:a17a:acda::1]:44250/workers/debug/"
    $ curl -X PUT -g6 "http://[fdca:3ba5:a17a:acda::1]:44250/router/rebuild/<ID>"



akanda-debug-router
+++++++++++++++++++

:program:`akanda-debug-router` is a diagnostic tool which can be used to
analyze the state machine flow of any router and step through its operation
using Python's debugger.  This is particularly useful for development purposes
and understanding the nature of the :py:mod:`akanda.rug` state machine, but it's
also useful for debugging problematic routers as an operator; a common pattern
for determining why a Service VM won't boot is to place the router in `debug
mode`::

    $ rug-ctl router debug <router-id>

...and then step through the handling of a manual ``UPDATE`` event to see where
it fails::

    $ akanda-debug-router --router-id <router-id>