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
|
Contributing
|
||||||
=============
|
============
|
||||||
|
|
||||||
The Congress wiki page is the authoritative starting point.
|
The Congress wiki page is the authoritative starting point.
|
||||||
|
|
||||||
|
@ -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/)
|
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.
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
@ -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
|
||||||
|
@ -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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
@ -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**
|
||||||
|
|
||||||
|
@ -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
|
||||||
|
Loading…
Reference in New Issue
Block a user