akanda/docs/source/operation.rst

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 :pyakanda.rug, it can be invoked as:

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

The :pyakanda.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

rug-ctl is a tool which can be used to send manual instructions to a running :pyakanda.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.

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

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 :pyakanda.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>