stackforge/satori
Code Issues Proposed changes

Added detailed and consistent examples to docs

Browse Source 
Added detailed and consistent examples in the docs for Satori.
You now see exactly what Satori does, how you get it and why we're
working on it by scanning the README or readthedocs page.
Also cleaned up the getting started examples and put some of that on the wiki.

Change-Id: I256d008149b94bd3537c8e8532d6c2d604ee5211
This commit is contained in:
Gus Maskowitz 2014-03-07 16:04:21 -06:00
parent eb115508a2
commit cfe4d3b8c3
6 changed files with 148 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
README.rst
View File

@ -24,17 +24,26 @@ Configuration discovery output could be used for:
Getting Started
===============
Run::
Run WITHOUT OpenStack credentials::
$ pip install satori
$ satori foo.com
$ satori www.foo.com
Address:
foo.com resolves to IPv4 address 4.4.4.4
www.foo.com resolves to IPv4 address 4.4.4.4
Domain: foo.com
Registrar: TUCOWS, INC.
Nameservers: NS1.DIGIMEDIA.COM, NS2.DIGIMEDIA.COM
Expires: 457 days
Host not found
Deeper discovery is available if the network location (IP or hostname) is
hosted on an OpenStack cloud tenant that Satori can access. Cloud settings can
be passed in on the command line or via `OpenStack tenant environment
variables`_::
hosted on an OpenStack cloud tenant that Satori can access.
Cloud settings can be passed in on the command line or via `OpenStack tenant environment
variables`_.
Run WITH OpenStack credentials::
$ satori foo.com --os-username yourname --os-password yadayadayada --os-tenant-name myproject --os-auth-url http://...
@ -48,13 +57,20 @@ Or::
Notice the discovery result now contains a ``Host`` section::
$ satori discover www.foo.com
Domain: foo.com
Registered at TUCOWS DOMAINS INC.
Expires in 475 days.
Name servers:
DNS1.STABLETRANSIT.COM
DNS2.STABLETRANSIT.COM
Address:
www.foo.com resolves to IPv4 address 4.4.4.4
Host:
4.4.4.4 (www.foo.com) is hosted on a Nova Instance
Instance Information:
URI: https://nova.api.somecloud.com/v2/111222/servers/d9119040-f767-
4141-95a4-d4dbf452363a
URI: https://nova.api.somecloud.com/v2/111222/servers/d9119040-f767-414
1-95a4-d4dbf452363a
Name: sampleserver01.foo.com
ID: d9119040-f767-4141-95a4-d4dbf452363a
ip-addresses:
@ -63,7 +79,16 @@ Notice the discovery result now contains a ``Host`` section::
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
Documentation
=============
@ -89,10 +114,18 @@ Unit tests can be ran simply by running::
Links
=====
- `OpenStack Wiki`_
- `Documentation`_
- `Code`_
- `Launchpad Project`_
- `Features`_
- `Issues`_
.. _OpenStack Wiki: https://wiki.openstack.org/Satori
.. _Launchpad Project: https://launchpad.net/satori
.. _Documentation: http://satori.readthedocs.org/
.. _OpenStack tenant environment variables: http://docs.openstack.org/developer/python-novaclient/shell.html
.. _related OpenStack project: https://wiki.openstack.org/wiki/ProjectTypes
.. _install virtualenv: https://github.com/rackerlabs/satori/blob/master/tools/install_venv.py
.. _install virtualenv: https://github.com/stackforge/satori/blob/master/tools/install_venv.py
.. _Code: https://github.com/stackforge/satori
.. _Launchpad Project: https://launchpad.net/satori
.. _Features: https://blueprints.launchpad.net/satori
.. _Issues: https://bugs.launchpad.net/satori/

2
doc/source/contributing.rst
View File

@ -15,5 +15,5 @@ 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`_
.. _GitHub: https://github.com/rackerlabs/satori
.. _GitHub: https://github.com/stackforge/satori
.. _Launchpad: https://launchpad.net/satori

29
doc/source/getting_started.rst
View File

@ -1,29 +0,0 @@
===============
Getting Started
===============
Satori is currently a simple command-line tool so that new users can discover
a configuration without needing to setup additional infrastructure:
::
$ satori --os-username <username> --os-password <password> --os-tenant-id\
<tenant-id> --os-auth-url <auth-endpoint> --os-region-name <region> www.example.com
Address:
www.example.com resolves to IPv4 address 10.1.0.44
Domain: www.example.com
Registrar: TUCOWS, INC.
Nameservers: DNS1.EXAMPLE.COM, DNS2.EXAMPLE.COM
Expires: 256 days
Host:
10.1.0.44 (www.example.com) is hosted on a Nova instance
Instance Information:
URI: https://<region>.servers.api.example.com/v2/123456/servers/fb52d194-1f60-4d23-b35f-d13e7bef9381
Name: www.example.com
ID: fb52d194-1f60-4d23-b35f-d13e7bef9381
ip-addresses:
public:
2001:0db8:85a3:0042:1000:8a2e:0370:7334:
10.1.0.44:
private:
10.2.99.140:

71
doc/source/index.rst
View File

@ -2,32 +2,83 @@
OpenStack Configuration Discovery
=================================
This is a configuration discovery tool for OpenStack.
Contents:
Satori is a configuration discovery tool for OpenStack and OpenStack tenant hosted applications.
.. toctree::
:maxdepth: 1
getting_started
contributing
releases
terminology
Installation
Get Satori
------------
To install satori, simply run `pip install`.
To install satori, simply run pip install.
::
$ pip install satori
Concept
-------
Use Satori
-----------
* `Wiki`_
::
.. _Wiki: https://wiki.openstack.org/Satori
$ satori discover www.foo.com
Domain: foo.com
Registered at TUCOWS DOMAINS INC.
Expires in 475 days.
Name servers:
DNS1.STABLETRANSIT.COM
DNS2.STABLETRANSIT.COM
Address:
www.foo.com resolves to IPv4 address 4.4.4.4
Host:
4.4.4.4 (www.foo.com) is hosted on a Nova Instance
Instance Information:
URI: https://nova.api.somecloud.com/v2/111222/servers/d9119040-f767-414
1-95a4-d4dbf452363a
Name: sampleserver01.foo.com
ID: d9119040-f767-4141-95a4-d4dbf452363a
ip-addresses:
public:
::ffff:404:404
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
=====
- `OpenStack Wiki`_
- `Code`_
- `Launchpad Project`_
- `Features`_
- `Issues`_
.. _OpenStack Wiki: https://wiki.openstack.org/Satori
.. _OpenStack tenant environment variables: http://docs.openstack.org/developer/python-novaclient/shell.html
.. _related OpenStack project: https://wiki.openstack.org/wiki/ProjectTypes
.. _install virtualenv: https://github.com/stackforge/satori/blob/master/tools/install_venv.py
.. _Code: https://github.com/stackforge/satori
.. _Launchpad Project: https://launchpad.net/satori
.. _Features: https://blueprints.launchpad.net/satori
.. _Issues: https://bugs.launchpad.net/satori/
Index
-----

6
doc/source/releases.rst
View File

@ -2,6 +2,12 @@
Release Notes
=============
0.1.3 (18 Feb 2014)
===================
* Bug fixes
* DNS added among other things
0.1.0 (28 Jan 2014)
===================

23
doc/source/terminology.rst Normal file
View File

@ -0,0 +1,23 @@
=============
Terminalogy
=============
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.
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.
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.