From d8ca55b11dd426d263ae27985b3e507c923a3d9d Mon Sep 17 00:00:00 2001 From: Ryan Petrello Date: Fri, 3 Apr 2015 12:23:37 -0400 Subject: [PATCH] More verbiage tinkering. --- docs/source/appliance.rst | 14 ++++++++------ docs/source/architecture.rst | 4 ++-- docs/source/operation.rst | 4 ++-- docs/source/rug.rst | 18 +++++++++--------- docs/source/worker_diagram.dot | 6 +++--- 5 files changed, 24 insertions(+), 22 deletions(-) diff --git a/docs/source/appliance.rst b/docs/source/appliance.rst index 969ee57..d04e35d 100644 --- a/docs/source/appliance.rst +++ b/docs/source/appliance.rst @@ -1,12 +1,14 @@ .. _appliance: -Virtual Software Router (the Akanda Appliance) -============================================== +The Service VM (the Akanda Appliance) +===================================== -Akanda uses Linux-based software router images (stored in OpenStack Glance) -to provide layer 3 routing and advanced networking services. While it's -possible to build your own custom image, Akanda provides stable image releases -for download at `akanda.io `_. +Akanda uses Linux-based images (stored in OpenStack Glance) to provide layer +3 routing and advanced networking services. Akanda, Inc provides stable image +releases for download at `akanda.io `_, but it's also +possible to build your own custom Service VM image (running additional +services of your own on top of the routing and other default services provided +by Akanda). .. _appliance_rest: diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst index 2f20b2f..520e3dc 100644 --- a/docs/source/architecture.rst +++ b/docs/source/architecture.rst @@ -40,7 +40,7 @@ From an architectural perspective, Akanda is composed of a few subprojects: a replacement for Neutron's various L3-L7 agents by listening for Neutron AMQP events and coalescing them into software router API calls (which configure and manage embedded services on the - router VM). Additionally, :py:mod:`akanda-rug` contains a health monitoring + Service VM). Additionally, :py:mod:`akanda-rug` contains a health monitoring component which monitors health and guarantees uptime for existing software routers. @@ -73,7 +73,7 @@ transitions, modifying its virtualized router in a variety of ways, such as: * Booting a virtual machine for the router via the Nova API (if one doesn't exist). * Checking for aliveness of the router via the :ref:`REST API - ` on the router VM. + ` on the Service VM. * Pushing configuration updates via the :ref:`REST API ` to configure routing and manage services (such as ``iptables``, ``dnsmasq``, ``bird6``, diff --git a/docs/source/operation.rst b/docs/source/operation.rst index 9c81322..e8c2ce8 100644 --- a/docs/source/operation.rst +++ b/docs/source/operation.rst @@ -62,7 +62,7 @@ a running :py:mod:`akanda.rug` via AMQP:: and places the tenant back under akanda-rug management. $ rug-ctl ssh - Establishes an ssh connection with a specified router VM. + Establishes an ssh connection with a specified Service VM. $ rug-ctl workers debug Causes the rug to print debugging diagnostics about the @@ -77,7 +77,7 @@ 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 router VM won't boot is to place the router in `debug +for determining why a Service VM won't boot is to place the router in `debug mode`:: $ rug-ctl router debug diff --git a/docs/source/rug.rst b/docs/source/rug.rst index 40c060c..c9d4682 100644 --- a/docs/source/rug.rst +++ b/docs/source/rug.rst @@ -23,8 +23,8 @@ several event types: * ``UPDATE`` - services on a router need to be reconfigured * ``DELETE`` - a router was deleted * ``POLL`` - used by the :ref:`health monitor` for checking aliveness - of a router VM - * ``REBUILD`` - a router VM should be destroyed and recreated + of a Service VM + * ``REBUILD`` - a Service VM should be destroyed and recreated As events are normalized and shuttled onto the :py:mod:`multiprocessing.Queue`, :py:mod:`akanda.rug.scheduler` shards (by Tenant ID, by default) and @@ -57,32 +57,32 @@ State Machine Flow The supported states in the state machine are: :CalcAction: The entry point of the state machine. Depending on the - current status of the router VM (e.g., ``ACTIVE``, ``BUILD``, ``SHUTDOWN``) + current status of the Service VM (e.g., ``ACTIVE``, ``BUILD``, ``SHUTDOWN``) and the current event, determine the first step in the state machine to transition to. - :Alive: Check aliveness of the router VM by attempting to communicate with + :Alive: Check aliveness of the Service VM by attempting to communicate with it via its REST HTTP API. - :CreateVM: Call ``nova boot`` to boot a new router VM. This will attempt - to boot a router VM up to a (configurable) number of times before + :CreateVM: Call ``nova boot`` to boot a new Service VM. This will attempt + to boot a Service VM up to a (configurable) number of times before placing the router into ``ERROR`` state. :CheckBoot: Check aliveness (up to a configurable number of seconds) of the router until the VM is responsive and ready for initial configuration. - :ConfigureVM: Configure the router VM and its services. This is generally + :ConfigureVM: Configure the Service VM and its services. This is generally the final step in the process of booting and configuring a router. This step communicates with the Neutron API to generate a comprehensive network configuration for the router (which is pushed to the router via its REST API). On success, the state machine yields control back to the worker thread and that thread handles the next event in its queue (likely for - a different router VM and its state machine). + a different Service VM and its state machine). :ReplugVM: Attempt to hot-plug/unplug a network from the router via ``nova interface-attach`` or ``nova-interface-detach``. - :StopVM: Terminate a running router VM. This is generally performed when + :StopVM: Terminate a running Service VM. This is generally performed when a Neutron router is deleted or via explicit operator tools. :ClearError: After a (configurable) number of ``nova boot`` failures, Neutron diff --git a/docs/source/worker_diagram.dot b/docs/source/worker_diagram.dot index 34c7ac9..fb508e6 100644 --- a/docs/source/worker_diagram.dot +++ b/docs/source/worker_diagram.dot @@ -18,9 +18,9 @@ digraph sample_boot { "Worker 1" -> "Thread N" } - "Thread 1" -> "Router VM 1"; - "Thread 1" -> "Router VM ..." [ label = "Appliance REST API" ]; - "Thread 1" -> "Router VM N"; + "Thread 1" -> "Service VM 1"; + "Thread 1" -> "Service VM ..." [ label = "Appliance REST API" ]; + "Thread 1" -> "Service VM N"; "Thread 1" -> "Nova" [ label = "Nova API" ]; "Thread 1" -> "Neutron" [ label = "Neutron API" ];