openstack
/
congress
Code Issues Proposed changes

Fix few typos 

Removed the extra underlines for headings and
Renamed one readme.rst file

Change-Id: I889b122689b2ff03b3bed77134fb59609c6b3995
This commit is contained in:
venkatamahesh 2015-09-19 00:04:34 +05:30
parent 266b04070d
commit 5dec41a35b
9 changed files with 52 additions and 55 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
CONTRIBUTING.rst
View File

@ -1,5 +1,6 @@
============
Contributing Contributing
============= ============
The Congress wiki page is the authoritative starting point. The Congress wiki page is the authoritative starting point.
@ -21,4 +22,4 @@ Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub: Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/congress https://bugs.launchpad.net/congress

7
HACKING.rst
View File

@ -1,4 +1,5 @@
congress Style Commandments ===========================
=============================================== Congress style commandments
===========================
Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/

0
doc/source/readme.rst → doc/source/README.rst
View File

14
doc/source/api.rst
View File

@ -21,7 +21,7 @@ There are two top-level concepts in today's API: Policies and Data-sources.
1. Policy (/v1/) 1. Policy (/v1/)
================= ================
You can create and delete policies. Two policies are provided by You can create and delete policies. Two policies are provided by
the system, and you are not permitted to delete them: *classification* the system, and you are not permitted to delete them: *classification*
@ -59,7 +59,7 @@ more details and examples::
2. Policy Rules (/v1/policies/<policy-id>/...) 2. Policy Rules (/v1/policies/<policy-id>/...)
=============================================== ==============================================
Each policy is a collection of rules. Congress supports the usual CRUD Each policy is a collection of rules. Congress supports the usual CRUD
operations for changing that collection. A rule has the following fields: operations for changing that collection. A rule has the following fields:
@ -110,7 +110,7 @@ GET .../rows?trace=true List rows with explanation (use 'printf' to displ
5. DEPRECATED: Drivers (/v1/system/) 5. DEPRECATED: Drivers (/v1/system/)
====================================== ====================================
A driver is a piece of code that once instantiated and configured interacts with A driver is a piece of code that once instantiated and configured interacts with
a specific cloud service like Nova or Neutron. A driver has the following fields. a specific cloud service like Nova or Neutron. A driver has the following fields.
@ -129,7 +129,7 @@ API-level datasource management with configuration-level datasource management.
6. Data sources (/v1/) 6. Data sources (/v1/)
======================== ======================
A data source is an instantiated and configured driver that interacts with a particular A data source is an instantiated and configured driver that interacts with a particular
instance of a cloud service (like Nova or Neutron). You can construct multiple datasources using instance of a cloud service (like Nova or Neutron). You can construct multiple datasources using
@ -167,7 +167,7 @@ configuration-level datasource management.
7. Data source Tables (/v1/data-sources/<ds-id>/...) 7. Data source Tables (/v1/data-sources/<ds-id>/...)
======================================================== ====================================================
Each data source maintains a collection of tables (very similar to a Policy). Each data source maintains a collection of tables (very similar to a Policy).
The list of available tables for each data source is available via the API. The list of available tables for each data source is available via the API.
@ -184,7 +184,7 @@ GET .../tables/<table-id>/spec Show a table schema
8. Data source Table Rows (/v1/data-sources/<ds-id>/tables/<table-id>/...) 8. Data source Table Rows (/v1/data-sources/<ds-id>/tables/<table-id>/...)
============================================================================ ==========================================================================
The contents of each data source table (the rows of each table) can be queried The contents of each data source table (the rows of each table) can be queried
via the API as well. A row has just a Data field, which is a list of values. via the API as well. A row has just a Data field, which is a list of values.
@ -198,7 +198,7 @@ GET .../rows List rows
9. Versions (/) 9. Versions (/)
================ ===============
You can see the supported API versions. You can see the supported API versions.

28
doc/source/cloudservices.rst
View File

@ -2,12 +2,12 @@
.. _cloudservices: .. _cloudservices:
=============== ==============
Cloud Services Cloud Services
=============== ==============
1. Congress Works With All Services 1. Congress Works With All Services
==================================== ===================================
Congress will work with any cloud service, as long as Congress can Congress will work with any cloud service, as long as Congress can
represent the service's state in *table* format. A table is a represent the service's state in *table* format. A table is a
@ -27,7 +27,7 @@ following table.::
====================================== ========== ====================================== ==========
2. Drivers 2. Drivers
==================================== ==========
To plug a new service into Congress, you write a small piece of code, To plug a new service into Congress, you write a small piece of code,
called a *driver*, that queries the new service (usually through API calls) called a *driver*, that queries the new service (usually through API calls)
@ -104,7 +104,7 @@ API-level datasource management with configuration-level datasource management.
3. Currently Supported Drivers 3. Currently Supported Drivers
==================================== ==============================
Congress currently has drivers for each of the following services. Each driver Congress currently has drivers for each of the following services. Each driver
has a differing degree of coverage for the available API calls. has a differing degree of coverage for the available API calls.
@ -168,13 +168,13 @@ For example::
.. _datasource_driver: .. _datasource_driver:
4. Writing a Datasource Driver 4. Writing a Datasource Driver
==================================== ==============================
This section is a tutorial for those of you interested in writing your own This section is a tutorial for those of you interested in writing your own
datasource driver. It can be safely skipped otherwise. datasource driver. It can be safely skipped otherwise.
4.1 Implementing a Datasource Driver 4.1 Implementing a Datasource Driver
-------------------------------------- ------------------------------------
All the Datasource drivers extend the code found in:: All the Datasource drivers extend the code found in::
@ -228,13 +228,13 @@ The following steps detail how to implement a datasource driver.
API results along with the tables that were generated. API results along with the tables that were generated.
4.2 Converting API results into Tables 4.2 Converting API results into Tables
----------------------------------------- --------------------------------------
Since Congress requires the state of each dataservice to be represented as Since Congress requires the state of each dataservice to be represented as
tables, we must convert the results of each API call (which may be comprised tables, we must convert the results of each API call (which may be comprised
of dictionaries, lists, dictionaries embedded within lists, etc.) into tables. of dictionaries, lists, dictionaries embedded within lists, etc.) into tables.
4.2.1 Convenience translators 4.2.1 Convenience translators
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Congress provides a translation method to make the translation from API Congress provides a translation method to make the translation from API
results into tables convenient. The translation method takes a description of results into tables convenient. The translation method takes a description of
@ -280,7 +280,7 @@ translate_objs() which is defined in congress/datasources/datasource_driver.py
See congress/datasources/neutron_driver.py as an example. See congress/datasources/neutron_driver.py as an example.
4.2.2 Custom data conversion 4.2.2 Custom data conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The convenience translators may be insufficient in some cases, for example, The convenience translators may be insufficient in some cases, for example,
@ -411,7 +411,7 @@ flatten that subobject into tables.
*Note* : uuid* are congress generated uuids *Note* : uuid* are congress generated uuids
4.3 Writing a Datasource driver test 4.3 Writing a Datasource driver test
-------------------------------------- ------------------------------------
Once you've written a driver, you'll want to add a unit test for it. To help, this section describes how the unit test for the Glance driver works. Here are the relevant files. Once you've written a driver, you'll want to add a unit test for it. To help, this section describes how the unit test for the Glance driver works. Here are the relevant files.
@ -421,7 +421,7 @@ Once you've written a driver, you'll want to add a unit test for it. To help, t
The test code has two methods: setUp() and test_update_from_datasource(). The test code has two methods: setUp() and test_update_from_datasource().
4.3.1 Glance setup 4.3.1 Glance setup
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~
We begin our description with the setUp() method of the test. We begin our description with the setUp() method of the test.
@ -465,7 +465,7 @@ Next the test defines which value it wants <glance-client>.images.list() to retu
4.3.2 Glance test 4.3.2 Glance test
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~
test_update_from_datasource() is the actual test, where we have the datasource driver grab the list of Glance images and translate them to tables. The test runs the update_from_datasource() method like normal except it ensures the return value of <glance-client>.images.list() is self.mock_images. test_update_from_datasource() is the actual test, where we have the datasource driver grab the list of Glance images and translate them to tables. The test runs the update_from_datasource() method like normal except it ensures the return value of <glance-client>.images.list() is self.mock_images.
@ -516,7 +516,7 @@ At this point in the test, update_from_datasource() has already been run, so all
4.3.3 Glance test code in full 4.3.3 Glance test code in full
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. code-block:: python .. code-block:: python

12
doc/source/enforcement.rst
View File

@ -3,9 +3,9 @@
.. _enforcement: .. _enforcement:
=========================== ==========================
Monitoring and Enforcement Monitoring and Enforcement
=========================== ==========================
Congress is given two inputs: the other cloud Congress is given two inputs: the other cloud
services in the datacenter and a policy describing the desired state of those services in the datacenter and a policy describing the desired state of those
@ -17,7 +17,7 @@ to ensure that the actual state of the other cloud services is also a desired
state (i.e. that the other services obey policy). state (i.e. that the other services obey policy).
1. Monitoring 1. Monitoring
=========================== =============
Recall from :ref:`Policy <policy>` that policy violations are represented with the Recall from :ref:`Policy <policy>` that policy violations are represented with the
table *error*. To ask Congress for a list of all policy violations, we table *error*. To ask Congress for a list of all policy violations, we
simply ask it for the contents of the *error* table. simply ask it for the contents of the *error* table.
@ -58,7 +58,7 @@ contents of the error table.
2. Proactive Enforcement 2. Proactive Enforcement
===================================== ========================
Often we want policy to be enforced, not just monitored. *Proactive Often we want policy to be enforced, not just monitored. *Proactive
enforcement* is the term we use to mean preventing policy violations before enforcement* is the term we use to mean preventing policy violations before
they occur. Proactive enforcement requires having enforcement points in the they occur. Proactive enforcement requires having enforcement points in the
@ -222,7 +222,7 @@ description rules.
2.1 Simulation with Actions 2.1 Simulation with Actions
------------------------------------------ ---------------------------
The downside to the simulation functionality just described is that the The downside to the simulation functionality just described is that the
cloud service wanting to prevent policy violations would need to compute the cloud service wanting to prevent policy violations would need to compute the
@ -312,7 +312,7 @@ d) **Mixing actions and state-changes**. Simulate changing 101:9 and adding val
3. Manual Reactive Enforcement 3. Manual Reactive Enforcement
================================= ==============================
Not all policies can be enforced proactively on all clouds, which means that sometimes Not all policies can be enforced proactively on all clouds, which means that sometimes
the cloud will violate policy. Once policy violations happen, Congress can take action the cloud will violate policy. Once policy violations happen, Congress can take action
to transition the cloud back into one of the states permitted by policy. We call this to transition the cloud back into one of the states permitted by policy. We call this

23
doc/source/policy.rst
View File

@ -2,9 +2,9 @@
.. _policy: .. _policy:
======= ======
Policy Policy
======= ======
1. What Does a Policy Look Like 1. What Does a Policy Look Like
=============================== ===============================
@ -99,7 +99,7 @@ the subject of research and development for decades.
.. _datalog: .. _datalog:
2. Datalog Policy Language 2. Datalog Policy Language
================================= ==========================
As a policy writer, your goal is to define the contents of the *error* table, and As a policy writer, your goal is to define the contents of the *error* table, and
in so doing to describe exactly those conditions that must be true in so doing to describe exactly those conditions that must be true
@ -129,7 +129,7 @@ go beyond toy examples.
2.1 Core Datalog Features 2.1 Core Datalog Features
--------------------------- -------------------------
Since Datalog is entirely concerned with tables, it's not surprising that Since Datalog is entirely concerned with tables, it's not surprising that
Datalog allows us to represent concrete tables directly in the language. Datalog allows us to represent concrete tables directly in the language.
@ -229,7 +229,7 @@ These rules happen to have only one atom in each of their bodies, but there is
no requirement for that. no requirement for that.
2.2 Extended Datalog Features 2.2 Extended Datalog Features
------------------------------- -----------------------------
In addition writing basic rules with and/or/not, the version of Datalog used In addition writing basic rules with and/or/not, the version of Datalog used
by Congress includes the features described in this section. by Congress includes the features described in this section.
@ -313,7 +313,7 @@ We discuss this modal operator in greater detail in Section 3.
2.3 Datalog Syntax Restrictions 2.3 Datalog Syntax Restrictions
--------------------------------- -------------------------------
There are a number of syntactic restrictions on Datalog that are, for the most There are a number of syntactic restrictions on Datalog that are, for the most
part, common sense. part, common sense.
@ -385,7 +385,7 @@ or the wrong column names.
2.4 Datalog builtins 2.4 Datalog builtins
----------------------- --------------------
Here is a list of the currently supported builtins. A builtin that has Here is a list of the currently supported builtins. A builtin that has
N inputs means that the leftmost N columns are the inputs, and the N inputs means that the leftmost N columns are the inputs, and the
@ -447,7 +447,7 @@ datetime_equal(x, y) 2 True if x == y
3. Multiple Policies 3. Multiple Policies
===================== ====================
One of the goals of Congress is for several different people in an organization One of the goals of Congress is for several different people in an organization
to collaboratively define a single, overarching policy that governs a cloud. to collaboratively define a single, overarching policy that governs a cloud.
@ -501,7 +501,7 @@ populating policies.
3.1 Syntactic Restrictions for Multiple Policies 3.1 Syntactic Restrictions for Multiple Policies
-------------------------------------------------- ------------------------------------------------
There are a couple of additional syntactic restrictions imposed when using There are a couple of additional syntactic restrictions imposed when using
multiple policies. multiple policies.
@ -532,8 +532,3 @@ head of the rule::
Congress will stop you from inserting rules that violate these restrictions. Congress will stop you from inserting rules that violate these restrictions.

8
doc/source/release.rst
View File

@ -2,12 +2,12 @@
.. _release: .. _release:
================ =============
Release Notes Release Notes
================ =============
Liberty Liberty
-------- -------
**Main updates** **Main updates**
* Added datasource driver for Heat * Added datasource driver for Heat
@ -26,7 +26,7 @@ Liberty
Kilo Kilo
-------- ----
**Main features** **Main features**

10
doc/source/troubleshooting.rst
View File

@ -2,9 +2,9 @@
.. _troubleshooting: .. _troubleshooting:
=============================== ===============
Troubleshooting Troubleshooting
=============================== ===============
So you've installed Congress with devstack as per the README, So you've installed Congress with devstack as per the README,
and now something is not behaving the way you think it should. and now something is not behaving the way you think it should.
@ -35,7 +35,7 @@ of problems and tips for how to fix them. ::
Policy-engine troubleshooting Policy-engine troubleshooting
--------------------------------- -----------------------------
Make sure the policy engine knows about the rules you think it knows about. Make sure the policy engine knows about the rules you think it knows about.
It is possible that the policy engine rejected a rule because of a syntax It is possible that the policy engine rejected a rule because of a syntax
@ -283,7 +283,7 @@ not the rules.
Datasource troubleshooting Datasource troubleshooting
--------------------------- --------------------------
At this point, you believe the problem is with one of the datasources. The first At this point, you believe the problem is with one of the datasources. The first
thing to consider is whether Congress can properly connect to the associated cloud service. thing to consider is whether Congress can properly connect to the associated cloud service.
@ -488,7 +488,7 @@ problems.
Production troubleshooting Production troubleshooting
---------------------------- --------------------------
Another class of problems arises most often in production deployments. Another class of problems arises most often in production deployments.
Here we give a couple of problems encountered in production deployments Here we give a couple of problems encountered in production deployments