Fix few typos
Removed the extra underlines for headings and Renamed one readme.rst file Change-Id: I889b122689b2ff03b3bed77134fb59609c6b3995
This commit is contained in:
parent
266b04070d
commit
5dec41a35b
|
@ -1,5 +1,6 @@
|
|||
============
|
||||
Contributing
|
||||
=============
|
||||
============
|
||||
|
||||
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:
|
||||
|
||||
https://bugs.launchpad.net/congress
|
||||
https://bugs.launchpad.net/congress
|
||||
|
|
|
@ -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/
|
||||
|
|
|
@ -21,7 +21,7 @@ There are two top-level concepts in today's API: Policies and Data-sources.
|
|||
|
||||
|
||||
1. Policy (/v1/)
|
||||
=================
|
||||
================
|
||||
|
||||
You can create and delete policies. Two policies are provided by
|
||||
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>/...)
|
||||
===============================================
|
||||
==============================================
|
||||
|
||||
Each policy is a collection of rules. Congress supports the usual CRUD
|
||||
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/)
|
||||
======================================
|
||||
====================================
|
||||
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.
|
||||
|
||||
|
@ -129,7 +129,7 @@ API-level datasource management with configuration-level datasource management.
|
|||
|
||||
|
||||
6. Data sources (/v1/)
|
||||
========================
|
||||
======================
|
||||
|
||||
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
|
||||
|
@ -167,7 +167,7 @@ configuration-level datasource management.
|
|||
|
||||
|
||||
7. Data source Tables (/v1/data-sources/<ds-id>/...)
|
||||
========================================================
|
||||
====================================================
|
||||
|
||||
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.
|
||||
|
@ -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>/...)
|
||||
============================================================================
|
||||
==========================================================================
|
||||
|
||||
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.
|
||||
|
@ -198,7 +198,7 @@ GET .../rows List rows
|
|||
|
||||
|
||||
9. Versions (/)
|
||||
================
|
||||
===============
|
||||
|
||||
You can see the supported API versions.
|
||||
|
||||
|
|
|
@ -2,12 +2,12 @@
|
|||
|
||||
.. _cloudservices:
|
||||
|
||||
===============
|
||||
==============
|
||||
Cloud Services
|
||||
===============
|
||||
==============
|
||||
|
||||
1. Congress Works With All Services
|
||||
====================================
|
||||
===================================
|
||||
|
||||
Congress will work with any cloud service, as long as Congress can
|
||||
represent the service's state in *table* format. A table is a
|
||||
|
@ -27,7 +27,7 @@ following table.::
|
|||
====================================== ==========
|
||||
|
||||
2. Drivers
|
||||
====================================
|
||||
==========
|
||||
|
||||
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)
|
||||
|
@ -104,7 +104,7 @@ API-level datasource management with configuration-level datasource management.
|
|||
|
||||
|
||||
3. Currently Supported Drivers
|
||||
====================================
|
||||
==============================
|
||||
|
||||
Congress currently has drivers for each of the following services. Each driver
|
||||
has a differing degree of coverage for the available API calls.
|
||||
|
@ -168,13 +168,13 @@ For example::
|
|||
.. _datasource_driver:
|
||||
|
||||
4. Writing a Datasource Driver
|
||||
====================================
|
||||
==============================
|
||||
|
||||
This section is a tutorial for those of you interested in writing your own
|
||||
datasource driver. It can be safely skipped otherwise.
|
||||
|
||||
4.1 Implementing a Datasource Driver
|
||||
--------------------------------------
|
||||
------------------------------------
|
||||
|
||||
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.
|
||||
|
||||
4.2 Converting API results into Tables
|
||||
-----------------------------------------
|
||||
--------------------------------------
|
||||
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
|
||||
of dictionaries, lists, dictionaries embedded within lists, etc.) into tables.
|
||||
|
||||
4.2.1 Convenience translators
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Congress provides a translation method to make the translation from API
|
||||
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.
|
||||
|
||||
4.2.2 Custom data conversion
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
|
@ -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().
|
||||
|
||||
4.3.1 Glance setup
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
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
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
.. code-block:: python
|
||||
|
|
|
@ -3,9 +3,9 @@
|
|||
.. _enforcement:
|
||||
|
||||
|
||||
===========================
|
||||
==========================
|
||||
Monitoring and Enforcement
|
||||
===========================
|
||||
==========================
|
||||
|
||||
Congress is given two inputs: the other cloud
|
||||
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).
|
||||
|
||||
1. Monitoring
|
||||
===========================
|
||||
=============
|
||||
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
|
||||
simply ask it for the contents of the *error* table.
|
||||
|
@ -58,7 +58,7 @@ contents of the error table.
|
|||
|
||||
|
||||
2. Proactive Enforcement
|
||||
=====================================
|
||||
========================
|
||||
Often we want policy to be enforced, not just monitored. *Proactive
|
||||
enforcement* is the term we use to mean preventing policy violations before
|
||||
they occur. Proactive enforcement requires having enforcement points in the
|
||||
|
@ -222,7 +222,7 @@ description rules.
|
|||
|
||||
|
||||
2.1 Simulation with Actions
|
||||
------------------------------------------
|
||||
---------------------------
|
||||
|
||||
The downside to the simulation functionality just described is that 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
|
||||
=================================
|
||||
==============================
|
||||
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
|
||||
to transition the cloud back into one of the states permitted by policy. We call this
|
||||
|
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
.. _policy:
|
||||
|
||||
=======
|
||||
======
|
||||
Policy
|
||||
=======
|
||||
======
|
||||
|
||||
1. What Does a Policy Look Like
|
||||
===============================
|
||||
|
@ -99,7 +99,7 @@ the subject of research and development for decades.
|
|||
.. _datalog:
|
||||
|
||||
2. Datalog Policy Language
|
||||
=================================
|
||||
==========================
|
||||
|
||||
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
|
||||
|
@ -129,7 +129,7 @@ go beyond toy examples.
|
|||
|
||||
|
||||
2.1 Core Datalog Features
|
||||
---------------------------
|
||||
-------------------------
|
||||
|
||||
Since Datalog is entirely concerned with tables, it's not surprising that
|
||||
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.
|
||||
|
||||
2.2 Extended Datalog Features
|
||||
-------------------------------
|
||||
-----------------------------
|
||||
In addition writing basic rules with and/or/not, the version of Datalog used
|
||||
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
|
||||
---------------------------------
|
||||
-------------------------------
|
||||
|
||||
There are a number of syntactic restrictions on Datalog that are, for the most
|
||||
part, common sense.
|
||||
|
@ -385,7 +385,7 @@ or the wrong column names.
|
|||
|
||||
|
||||
2.4 Datalog builtins
|
||||
-----------------------
|
||||
--------------------
|
||||
|
||||
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
|
||||
|
@ -447,7 +447,7 @@ datetime_equal(x, y) 2 True if x == y
|
|||
|
||||
|
||||
3. Multiple Policies
|
||||
=====================
|
||||
====================
|
||||
|
||||
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.
|
||||
|
@ -501,7 +501,7 @@ populating policies.
|
|||
|
||||
|
||||
3.1 Syntactic Restrictions for Multiple Policies
|
||||
--------------------------------------------------
|
||||
------------------------------------------------
|
||||
There are a couple of additional syntactic restrictions imposed when using
|
||||
multiple policies.
|
||||
|
||||
|
@ -532,8 +532,3 @@ head of the rule::
|
|||
|
||||
Congress will stop you from inserting rules that violate these restrictions.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
@ -2,12 +2,12 @@
|
|||
|
||||
.. _release:
|
||||
|
||||
================
|
||||
=============
|
||||
Release Notes
|
||||
================
|
||||
=============
|
||||
|
||||
Liberty
|
||||
--------
|
||||
-------
|
||||
**Main updates**
|
||||
|
||||
* Added datasource driver for Heat
|
||||
|
@ -26,7 +26,7 @@ Liberty
|
|||
|
||||
|
||||
Kilo
|
||||
--------
|
||||
----
|
||||
|
||||
**Main features**
|
||||
|
||||
|
|
|
@ -2,9 +2,9 @@
|
|||
|
||||
.. _troubleshooting:
|
||||
|
||||
===============================
|
||||
===============
|
||||
Troubleshooting
|
||||
===============================
|
||||
===============
|
||||
|
||||
So you've installed Congress with devstack as per the README,
|
||||
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
|
||||
---------------------------------
|
||||
-----------------------------
|
||||
|
||||
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
|
||||
|
@ -283,7 +283,7 @@ not the rules.
|
|||
|
||||
|
||||
Datasource troubleshooting
|
||||
---------------------------
|
||||
--------------------------
|
||||
|
||||
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.
|
||||
|
@ -488,7 +488,7 @@ problems.
|
|||
|
||||
|
||||
Production troubleshooting
|
||||
----------------------------
|
||||
--------------------------
|
||||
|
||||
Another class of problems arises most often in production deployments.
|
||||
Here we give a couple of problems encountered in production deployments
|
||||
|
|
Loading…
Reference in New Issue