diff --git a/.gitignore b/.gitignore index bd18a90..b88a057 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,4 @@ debian/python-libraclient.substvars debian/python-libraclient/ AUTHORS ChangeLog +doc/api diff --git a/doc/command.rst b/doc/command.rst index f536706..802b76e 100644 --- a/doc/command.rst +++ b/doc/command.rst @@ -1,5 +1,5 @@ -Libra Client -============ +Usage +===== Synopsis -------- diff --git a/doc/conf.py b/doc/conf.py index abd5909..772c340 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -50,13 +50,13 @@ copyright = u'2012, Andrew Hutchings' # built documents. # # The short X.Y version. -version = "%d-%02d-%02d-alpha1" % ( +version = "%d-%02d-%02d-beta" % ( datetime.datetime.now().year, datetime.datetime.now().month, datetime.datetime.now().day ) # The full version, including alpha/beta/rc tags. -release = "%d-%02d-%02d-alpha1" % ( +release = "%d-%02d-%02d-beta" % ( datetime.datetime.now().year, datetime.datetime.now().month, datetime.datetime.now().day diff --git a/doc/examples.rst b/doc/examples.rst new file mode 100644 index 0000000..670c288 --- /dev/null +++ b/doc/examples.rst @@ -0,0 +1,80 @@ +Examples +======== + +Create Load Balancer +-------------------- + +.. code-block:: bash + + libra_client --os_auth_url=https://company.com/openstack/auth/url \ + --os_username=username --os_password=pasword --os_tenant_name=tenant \ + --os_region_name=region create --name=my_load_balancer \ + --node 192.168.1.1:80 --node 192.168.1.2:80 + +This example will create a basic load balancer which will listen on port 80 and +direct traffic in a round-robin fashion to two nodes, 192.168.1.1 and +192.168.1.2. Both these nodes are web servers listening on port 80. The Libra +Client will then return a table similar to the below: + ++------+------------------+----------+------+-------------+--------+-------------------+-------------------+ +| ID | Name | Protocol | Port | Algorithm | Status | Created | Updated | ++------+------------------+----------+------+-------------+--------+-------------------+-------------------+ +| 1157 | my_load_balancer | HTTP | 80 | ROUND_ROBIN | BUILD | 2013-01-10T14:41Z | 2013-01-10T14:41Z | ++------+------------------+----------+------+-------------+--------+-------------------+-------------------+ + ++--------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| IPs | Nodes | ++--------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| [{u'ipVersion': u'IPV_4', u'type': u'PUBLIC', u'id': u'52', u'address': u'15.185.224.62'}] | [{u'status': u'ONLINE', u'id': u'2311', u'port': u'80', u'condition': u'ENABLED', u'address': u'192.168.1.1'}, {u'status': u'ONLINE', u'id': u'2312', u'port': u'80', u'condition': u'ENABLED', u'address': u'192.168.1.2'}] | ++--------------------------------------------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Create a Shared Load Balancer +----------------------------- + +It is possible for a single logical load balancer to balancer traffic for both +HTTP and HTTPS for a site. For this example we will add an HTTPS load balancer +to the load balancer we created previously: + +.. code-block:: bash + + libra_client --os_auth_url=https://company.com/openstack/auth/url \ + --os_username=username --os_password=pasword --os_tenant_name=tenant \ + --os_region_name=region create --name=my_load_balancer \ + --node 192.168.1.1:443 --node 192.168.1.2:443 --protocol=TCP --port=443 \ + --vip=52 + +We have taken the IP ID which was provided in the original create and given this +as a VIP number in the command. We are also setting to TCP mode so the SSL +termination happens at the web server and set the load balancer to listen on +port 443. The result is as follows: + ++------+------------------+----------+------+-------------+--------+-------------------+-------------------+ +| ID | Name | Protocol | Port | Algorithm | Status | Created | Updated | ++------+------------------+----------+------+-------------+--------+-------------------+-------------------+ +| 1158 | my_load_balancer | TCP | 443 | ROUND_ROBIN | BUILD | 2013-01-10T14:44Z | 2013-01-10T14:44Z | ++------+------------------+----------+------+-------------+--------+-------------------+-------------------+ + ++--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| IPs | Nodes | ++--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ +| [{u'ipVersion': u'IPV_4', u'type': u'PUBLIC', u'id': u'52', u'address': u'15.185.224.62'}] | [{u'status': u'ONLINE', u'id': u'2313', u'port': u'443', u'condition': u'ENABLED', u'address': u'192.168.1.1'}, {u'status': u'ONLINE', u'id': u'2314', u'port': u'443', u'condition': u'ENABLED', u'address': u'192.168.1.2'}] | ++--------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ + +Add a Node +---------- + +.. code-block:: bash + + libra_client --os_auth_url=https://company.com/openstack/auth/url \ + --os_username=username --os_password=pasword --os_tenant_name=tenant \ + --os_region_name=region node-add --id=1158 --node=192.168.1.3:443 + +In this example we have take the ID of the load balancer of the previos example +to add a web server to. The result should look something like this: + ++----+-------------+------+-----------+--------+ +| ID | Address | Port | Condition | Status | ++----+-------------+------+-----------+--------+ +| | 192.168.1.3 | 443 | | | ++----+-------------+------+-----------+--------+ + diff --git a/doc/index.rst b/doc/index.rst index 8a3c222..54e0e22 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -4,4 +4,7 @@ Libra Command Line Client .. toctree:: :maxdepth: 2 + introduction + installation command + examples diff --git a/doc/installation.rst b/doc/installation.rst new file mode 100644 index 0000000..74c283c --- /dev/null +++ b/doc/installation.rst @@ -0,0 +1,19 @@ +Installation +============ + +From Ubuntu Package +------------------- + +.. code-block:: bash + + sudo dpkg -i python-libraclient + +From Source +----------- + +The python-setuptools package needs to be installed on your system before +installing the client from source. + +.. code-block:: bash + + sudo python setup.py install diff --git a/doc/introduction.rst b/doc/introduction.rst new file mode 100644 index 0000000..1d88fee --- /dev/null +++ b/doc/introduction.rst @@ -0,0 +1,8 @@ +Introduction +============ + +Libra Client is a Python command line client which is used to manipulate Atlas +API compatible OpenStack Load Balancer as a Service installations. + +It is designed to be similar to the Python Nova client and in fact uses this +as a common base code. diff --git a/setup.cfg b/setup.cfg new file mode 100644 index 0000000..b93812f --- /dev/null +++ b/setup.cfg @@ -0,0 +1,4 @@ +[build_sphinx] +source-dir = doc +build-dir = build/html +all_files = 1