From 49d0d52cd1fdb1853485817fb7555faa1c7800d0 Mon Sep 17 00:00:00 2001 From: Caleb Groom Date: Mon, 17 Mar 2014 09:46:05 -0500 Subject: [PATCH] Documentation updates Drops the `discover` parameter from the examples. Updated contributing document with the change to Gerrit. Also added more meat to the terminolgy. Change-Id: I092669adc07f921253e5ee5c6829b4c589507631 --- README.rst | 2 +- doc/source/contributing.rst | 22 ++++++++++------------ doc/source/index.rst | 29 ++++++++++++++--------------- doc/source/terminology.rst | 23 +++++++++++++++-------- 4 files changed, 40 insertions(+), 36 deletions(-) diff --git a/README.rst b/README.rst index 2c0010e..7b281dd 100644 --- a/README.rst +++ b/README.rst @@ -57,7 +57,7 @@ Or:: Notice the discovery result now contains a ``Host`` section:: - $ satori discover www.foo.com + $ satori www.foo.com Domain: foo.com Registered at TUCOWS DOMAINS INC. Expires in 475 days. diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 9d25b3b..ffe68aa 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -2,18 +2,16 @@ Contributing ============ -Upstream code and mirroring is hosted on `GitHub`_. Satori is -currently following Github workflow that includes: +Satori's code is hosted on `GitHub`_. Our development process follows the +`OpenStack Gerrit`_ workflow which is much different than most projects on +Github. -1. Fork code from `Github`_. -#. Create a feature branch. -#. Create awesome code. -#. Push the new feature branch to `Github`_. -#. Submit pull request through `Github`_. - -Bug tracking for the satori project is on `Launchpad`_. Submit -code to the openstack satori project using `Github`_. Feature -additions and design discussions happen using blueprints on `Launchpad`_ +If you find a problem, please `file a bug`_. Feature additions and design +discussions are taking place in `blueprints`_. `Reviewing code`_ is an easy way +to start contributing. +.. _OpenStack Gerrit: https://wiki.openstack.org/wiki/Gerrit_Workflow .. _GitHub: https://github.com/stackforge/satori -.. _Launchpad: https://launchpad.net/satori +.. _file a bug: https://bugs.launchpad.net/satori +.. _blueprints: https://blueprints.launchpad.net/satori +.. _Reviewing code: https://review.openstack.org/#/q/status:open+project:stackforge/satori,n,z diff --git a/doc/source/index.rst b/doc/source/index.rst index 0c3740f..3ae9ab1 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -15,18 +15,30 @@ Satori is a configuration discovery tool for OpenStack and OpenStack tenant host Get Satori ------------ -To install satori, simply run pip install. +Satori is distributed as a Python package. The pip command will install the +latest version. :: $ pip install satori +If you want to install from the latest source code, these commands will fetch +the code and install it. + +:: + + $ git clone https://github.com/stackforge/satori.git + $ cd satori + $ pip install -r requirements.txt + $ sudo python setup.py install + + Use Satori ----------- :: - $ satori discover www.foo.com + $ satori www.foo.com Domain: foo.com Registered at TUCOWS DOMAINS INC. Expires in 475 days. @@ -48,19 +60,6 @@ Use Satori 4.4.4.4 private: 10.1.1.156 - System Information: - Ubuntu 12.04 installed - Server was rebooted 11 days, 22 hours ago - /dev/xvda1 is using 9% of its inodes. - Running Services: - httpd on 127.0.0.1:8080 - varnishd on 0.0.0.0:80 - sshd on 0.0.0.0:22 - httpd: - Using 7 of 100 MaxClients - -Please go read more in the README in the `Code`_. -Also check the `OpenStack Wiki`_'s Getting started section. Links diff --git a/doc/source/terminology.rst b/doc/source/terminology.rst index c77c687..0beb67f 100644 --- a/doc/source/terminology.rst +++ b/doc/source/terminology.rst @@ -1,23 +1,30 @@ ============= -Terminalogy +Terminology ============= Opinions -=================== +======== Opinions are being discussed at https://wiki.openstack.org/wiki/Satori/OpinionsProposal. Control Plane Discovery ======================= -Using native bindings, client libraries (pyrax, boto, novaclient, libcloud, etc.) or cloud APIs to attain information about a configuration. This requires credentials/api tokens, and could provide: a server's image data, a server's region, a load-balancer's VIPs and nodes, networking info, etc. +Control plane discovery is the process of making API calls to management +systems like OpenStack or IT asset management systems. An external management +system can show relationships between resources that can further improve +the discovery process. For example, a data plane discovery of a single server +will reveal that a server has a storage device attached to it. Control plane +discovery using an OpenStack plugin can reveal the details of the Cinder +volume. + +Satori can load plugins that enable these systems to be queried. Data Plane Discovery ==================== -Making direct observations about a configuration by running commands/utilities directly on the system, or accessing and analyzing a system's network interface. This might require login credentials for the host resource, and could provide information ranging from disk usage to packages installed to motherboard fan speeds. +Data plane discovery is the process of connecting to a resource and using +native tools to extract information. For example, it can provide information +about the user list, installed software and processes that are running. -SysInfo Provider -================ - -One of any open source applications or utilities that will examine a host machine and return verbose information about that system. Satori will leverage/support these tools for Data Plane Discovery. +Satori can load plugins that enable data plane discovery.