openstack
/
congress-specs
Code Issues Proposed changes

Enhance tox output and fix spec formatting 

Include file name for specs with missing subtitles. Include file name for specs
with docutils errors. Removed empty file.

Formatting errors fixed in specs:
* Line length past 79 characters.
* Consistent capitalization of subtitles (first word only, which was the
  majority of the existing ones).
* Missing subtitle.
* Unexpected indentation.
* Title underline length too short.

Change-Id: Ie319c80142bdc706cb849e8870d96f44b2045dcd
This commit is contained in:
Janet Yu 2014-11-21 16:15:58 -08:00
parent bcab90d57c
commit 7319e304d4
18 changed files with 180 additions and 165 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
specs/juno/Plexxi-Driver.rst
View File

@ -10,16 +10,18 @@ Plexxi Driver
https://blueprints.launchpad.net/congress/+spec/plexxi-driver
This blueprint is to layout the design of a driver that integrates PlexxiCore into congress.
This blueprint is to layout the design of a driver that integrates PlexxiCore
into congress.
Problem description
===================
A detailed description of the problem:
* A PlexxiCore Database can contain a vast wealth of information about a network that can
be an asset to a Congress system in a network where Plexxi is present, and without this
driver Congress does not have access to this data.
* A PlexxiCore Database can contain a vast wealth of information about a
network that can be an asset to a Congress system in a network where
Plexxi is present, and without this driver Congress does not have access
to this data.
Proposed change
@ -64,12 +66,15 @@ None
REST API impact
---------------
Users of Congress who have PlexxiCore integrated in their network will now be able to access data stored in their PlexxiCore database through the congress API.
Users of Congress who have PlexxiCore integrated in their network will now be
able to access data stored in their PlexxiCore database through the congress
API.
Security impact
---------------
Network data stored in the PlexxiCore Database will now be accessible through Congress
Network data stored in the PlexxiCore Database will now be accessible through
Congress
Notifications impact
--------------------
@ -81,7 +86,7 @@ Other end user impact
None
Performance Impact
Performance impact
------------------
None
@ -105,7 +110,7 @@ Assignee(s)
Primary assignee:
Conner-Ferguson
Work Items
Work items
----------
None
@ -117,10 +122,11 @@ Dependencies
Plexxi Class package
Plexxi-Core used within the network
Testing
=======
Documentation Impact
Documentation impact
====================
Documentation for the Driver is currently located in the bitbucket

12
specs/juno/cinder-datasource-driver.rst
View File

@ -71,17 +71,17 @@ Other end user impact
N/A
Performance Impact
Performance impact
------------------
N/A
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
N/A
Developer Impact
Developer impact
----------------
N/A
@ -95,7 +95,7 @@ Assignee(s)
Samta Rangare
srangare@mvista.com
Work Items
Work items
----------
- Implement cinder driver with essential tables
@ -113,7 +113,7 @@ Testing
- Will need to add unit test code
- Will add tempest tests.
Documentation Impact
Documentation impact
====================
N/A

12
specs/juno/datalog-aggregates.rst
View File

@ -38,8 +38,8 @@ form:
Example policies involving aggregates:
1. Restriction on number of ports on a subnet
error(subnet) :- neutron:networks.subnets(subnet, port), neutron:ports(port, ip),
count(num_port, port), not gt(num_port, 10)
error(subnet) :- neutron:networks.subnets(subnet, port),
neutron:ports(port, ip), count(num_port, port), not gt(num_port, 10)
2. Restriction on average CPU Load on a host
error(host) :- ceilometer:meters(host, cpu_util), nova:servers(host, vm_host),
@ -50,7 +50,7 @@ average(x, y, z) :- sum(z, cpu_util), count(y, vm_host), div(x, z, y)
the design/implementation progresses)
* The aggregates like "SUM", "COUNT" must be defined as ANTLR Terms and
Congress must be able to parse and compile these terms.
Congress must be able to parse and compile these terms.
The initial implementation will use SUM and COUNT as prototype aggregations.
Other similar aggregates can be considered as enhancements to be taken up
@ -94,7 +94,7 @@ Other end user impact
End user will be able to write policies involving aggregates.
Performance Impact
Performance impact
------------------
Evaluation of policies involving aggregates may involve additional processing
@ -119,7 +119,7 @@ Assignee(s)
Primary assignee:
Madhu Mohan (mmohan@mvista.com)
Work Items
Work items
----------
* Add new terms in Congress.g to allow ANTLR to recognize aggregate keywords
@ -141,7 +141,7 @@ Testing
* Add Tempest tests
* Create sample policies to test some real scenarios
Documentation Impact
Documentation impact
====================
* Docs for external consumption would need to be updated with explanation on

6
specs/kilo/api-validation.rst
View File

@ -104,7 +104,7 @@ Other end user impact
None.
Performance Impact
Performance impact
------------------
Validation of inputs will have a negative performance impact on latency and
@ -138,7 +138,7 @@ Primary assignee:
Other contributors:
None
Work Items
Work items
----------
* Create JSON schemas for each API resource (This is already done in the API
@ -169,7 +169,7 @@ validation is being performed by issuing requests that should and should not
validate against the schema.
Documentation Impact
Documentation impact
====================
This change itself does not impact documentation. The addition of schemas

12
specs/kilo/compromised-vm.rst
View File

@ -63,7 +63,7 @@ error(vm) :-
neutron:port(vm, src_ip), //finds out the port that has the VM’s IP
ids:ip_blacklist(dst_ip).
Policy Actions
Policy actions
-----------------
* Monitoring: report/log the incident including the VM’s IP address, external
@ -75,7 +75,7 @@ Policy Actions
access the VM) and/or a no route network or removing the VM network
interface(s).
Data Sources
Data sources
-----------------
* IDS (intrusion detection service VM): IP address of the offending VM
@ -83,7 +83,7 @@ Data Sources
* nova: VM details; instance ID, interface(s) status, instance state, security
group
Data Model Impact
Data model impact
------------------
none
@ -112,7 +112,7 @@ Other end user impact
Unknown at this time
Performance Impact
Performance impact
------------------
Unknown at this time
@ -140,7 +140,7 @@ Assignee(s)
Unknown at this time
Work Items
Work items
----------
* Congress IDS plugin
@ -169,7 +169,7 @@ Testing
TBD
Documentation Impact
Documentation impact
====================
TBD

18
specs/kilo/congress-gbp-translation.rst
View File

@ -141,18 +141,18 @@ Other end user impact
None.
Performance Impact
Performance impact
------------------
None.
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
None.
Developer Impact
Developer impact
----------------
None.
@ -170,18 +170,20 @@ Primary assignee:
Other contributors:
Work Items
Work items
----------
* Define translation functions.
* Implement the new constant tables and function tables to perform the translation.
* Implement the new constant tables and function tables to perform the
translation.
Dependencies
============
* This is dependent on the implementation of a GBP data-source driver for Congress.
* This is dependent on the implementation of a GBP data-source driver for
Congress.
@ -191,7 +193,7 @@ Testing
Some sample input tables will be created and the translation verified by
checking the contents of the output trigger tables.
Documentation Impact
Documentation impact
====================
All translation details will be documented.

45
specs/kilo/datalog-column-names.rst
View File

@ -84,30 +84,33 @@ way to spell the tablename.]
To do this, Congress would need to know which columns in a table are sufficient
to uniquely identify a row, which in most cases is just the ID.
Pros: (i) this requires only changes in the datasource drivers; everything else
Pros:
(i) this requires only changes in the datasource drivers; everything else
remains the same
(ii) still leveraging database technology under the hood
(iii) policy is robust to changes in fields of original data
Cons: (i) datasource driver can force policy writer to use wide tables
(ii) this data model is much different than the original data models
(iii) we need primary-key information about tables
(ii) still leveraging database technology under the hood
(iii) policy is robust to changes in fields of original data
Cons:
(i) datasource driver can force policy writer to use wide tables
(ii) this data model is much different than the original data models
(iii) we need primary-key information about tables
3) Enhance the Congress policy language to handle objects natively.
Instead of writing a rule like the following ...
p(port_id, name, group) :-
neutron:ports(port_id, addr_pairs, security_groups, extra_dhcp_opts,
binding_cap, status, name, admin_state_up, network_id, tenant_id,
binding_vif, device_owner, mac_address, fixed_ips, router_id, binding_host),
neutron:ports.security_groups(security_group, group)
neutron:ports(port_id, addr_pairs, security_groups, extra_dhcp_opts,
binding_cap, status, name, admin_state_up, network_id, tenant_id,
binding_vif, device_owner, mac_address, fixed_ips, router_id, binding_host),
neutron:ports.security_groups(security_group, group)
we would write a rule such as
p(port_id, name) :-
neutron:ports(port),
port.name(name),
port.id(port_id),
port.security_groups(group)
neutron:ports(port),
port.name(name),
port.id(port_id),
port.security_groups(group)
The big difference here is that the period (.) is an operator in the language,
just as in C++/Java.
@ -186,19 +189,19 @@ Other UIs can expose this enhanced syntax, but since currently all UIs
just pass policy statements as strings, they will require no actual changes
to leverage the enhancement.
Performance Impact
Performance impact
------------------
Should have no performance impact, with the possible exception that
eventually we will want to reverse the preprocessing step for tracing
so that we present users with a more intuitive trace.
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
None
Developer Impact
Developer impact
----------------
None
@ -214,13 +217,13 @@ Primary assignee:
thinrich
Work Items
Work items
----------
* Modify grammar
* Make datasource schemas available to runtime
* Add preprocessor to rule AST constructor to convert column references into
positional references.
positional references.
Dependencies
@ -237,7 +240,7 @@ Testing
No tempest tests are necessary. Unit tests only.
Documentation Impact
Documentation impact
====================
Should include modifications to docs to simplify the examples that use

16
specs/kilo/dse-dataservices-status.rst
View File

@ -87,18 +87,18 @@ Other end user impact
None
Performance Impact
Performance impact
------------------
It will be possible to turn off high-cost status computation; thus, people
can decide whether each status item is worth the cost of computing it.
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
None
Developer Impact
Developer impact
----------------
None
@ -115,12 +115,12 @@ Primary assignee:
Other contributors:
<launchpad-id or None>
Work Items
Work items
----------
- Add implementations for metrics. The decision as to whether the metric
is continually computed or computed on demand will be made on a metric-by-metric
basis.
is continually computed or computed on demand will be made on a
metric-by-metric basis.
- Add status() method to DeepSix class and return a dictionary of metrics.
@ -137,7 +137,7 @@ status metrics are as expected. Ideally would also simulate metric computation
under load.
Documentation Impact
Documentation impact
====================
None

0
specs/kilo/empty
View File

12
specs/kilo/glance-datasource-driver.rst
View File

@ -67,17 +67,17 @@ Other end user impact
N/A
Performance Impact
Performance impact
------------------
N/A
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
N/A
Developer Impact
Developer impact
----------------
N/A
@ -91,7 +91,7 @@ Assignee(s)
Primary assignee:
arosen
Work Items
Work items
----------
@ -105,7 +105,7 @@ Testing
Will add tempest tests.
Documentation Impact
Documentation impact
====================
N/A

12
specs/kilo/horizon-create-policies.rst
View File

@ -94,19 +94,19 @@ The end user will be able to go to the Policies panel in Horizon and use some
knobs to write policy rules and create a policy in Congress.
Performance Impact
Performance impact
------------------
None.
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
None.
Developer Impact
Developer impact
----------------
None.
@ -124,7 +124,7 @@ Primary assignee:
Other contributors:
<launchpad-id or None>
Work Items
Work items
----------
- Knobs and form to enter policy details and rules.
@ -150,7 +150,7 @@ Additional Tempest tests are not needed because the Congress code is not being
modified here.
Documentation Impact
Documentation impact
====================
None.

20
specs/kilo/horizon-integration.rst
View File

@ -4,9 +4,9 @@
http://creativecommons.org/licenses/by/3.0/legalcode
==========================================
================================================
Congress OpenStack Horizon Dashboard Integration
==========================================
================================================
https://blueprints.launchpad.net/congress/+spec/horizon-integration
@ -39,7 +39,7 @@ Proposed change
Horizon
* A new panel named `policies` will be added to the `admin` dashboard.
+-----------+ +------------+
+-----------+ +------------+
| ++------+ | |
| || | REST API Call| |
| || +------------------> |
@ -80,7 +80,7 @@ to integrate congress in a non openstack scenario.
Screens
------
-------
none
@ -126,17 +126,17 @@ Other end user impact
* User will be able to data exposed by the DataSources
Performance Impact
Performance impact
------------------
none
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
Integration with Devstack.
Developer Impact
Developer impact
----------------
none
@ -155,7 +155,7 @@ Primary assignee:
Other contributors:
<None>
Work Items
Work items
----------
* Add base Panel for Policies
@ -179,7 +179,7 @@ Testing
Unit testing using mocks.
Documentation Impact
Documentation impact
====================
Document the screenflow.

66
specs/kilo/multiple-policies.rst
View File

@ -66,9 +66,10 @@ nova: and neutron:) on datasource tablenames. This proposal simply
generalizes that idea.
Another approach is to put everything into a single theory and explicitly
prefix all tables with the module in which they are defined. Implementationally,
that is basically what we're doing, but leaving the policies in separate
datastructures so that they can leverage different theory types.
prefix all tables with the module in which they are defined.
Implementationally, that is basically what we're doing, but leaving the
policies in separate datastructures so that they can leverage different theory
types.
Many other module systems are available, but this is basically Python's
module system. Everything is visible to everything as long as you
@ -120,28 +121,29 @@ Each API method which is either added or changed should have the following
create_policy
* Description: create a new policy of the given name, abbreviation, and
type
type
* Method: POST
* Normal http response codes: success
* HTTP errors:
** conflict: policy already exists
** bad request: type does not exist
** conflict: policy already exists
** bad request: type does not exist
* URL: /v1/policy/
* Parameters: name, abbreviation (for traces), type (Nonrecursive, Materialized)
* Parameters: name, abbreviation (for traces), type (Nonrecursive,
Materialized)
Example:
curl -X PUT http://localhost:1789/v1/policy -d
'{"id": "test_policy",
"description": "a great policy",
"abbreviation": "test",
"type": "nonrecursive"}'
'{"id": "test_policy",
"description": "a great policy",
"abbreviation": "test",
"type": "nonrecursive"}'
Example output:
{"id": "test_policy",
"description": "a great policy",
"abbreviation": "test",
"type": "nonrecursive",
"owner": "alice"}'
{"id": "test_policy",
"description": "a great policy",
"abbreviation": "test",
"type": "nonrecursive",
"owner": "alice"}'
delete_policy: standard deletion operation
@ -165,17 +167,17 @@ Other end user impact
Users will interact with other policies when writing rules.
Performance Impact
Performance impact
------------------
None
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
None
Developer Impact
Developer impact
----------------
None
@ -191,28 +193,28 @@ Primary assignee:
thinrichs@vmware.com
Work Items
Work items
----------
- Add create_policy/delete_policy to congress/policy/policy.py:Runtime.
The arguments to create_policy should include name/abbr/type, where
type is either NonrecursiveRuleTheory or MaterializedViewTheory.
The arguments to create_policy should include name/abbr/type, where
type is either NonrecursiveRuleTheory or MaterializedViewTheory.
- Change compile.atom to a separate 'module' field and 'table' field to
avoid repeatedly parsing the tablename. The 'module' field is None if
there is none.
avoid repeatedly parsing the tablename. The 'module' field is None if
there is none.
- Modify top_down_eval so that at every point in the search, it
jumps to the policy in which the table is defined (or stays in the
current policy if 'module' is None).
jumps to the policy in which the table is defined (or stays in the
current policy if 'module' is None).
- Ensure no infinite loops across theories. We need to check
that the graph obtained by rules that cross policy boundaries
is non-recursive; we can ignore rules that do not cross policy
boundaries.
that the graph obtained by rules that cross policy boundaries
is non-recursive; we can ignore rules that do not cross policy
boundaries.
- Can leave 'includes' functionality for internal implementation.
Should not need to use it for the change above.
Should not need to use it for the change above.
- Expose this functionality through the API and CLI
@ -276,7 +278,7 @@ q(x) :- policy1:p(x)
Should throw error.
Documentation Impact
Documentation impact
====================
Need to add docs that describe new capabilities.

16
specs/kilo/persistent-storage-for-api.rst
View File

@ -37,13 +37,13 @@ Policy
N/A
Policy Actions
Policy actions
--------------
N/A
Data Sources
Data sources
------------
N/A
@ -77,17 +77,17 @@ Other end user impact
* Users will now have to deploy a db for congress to leverage.
Performance Impact
Performance impact
------------------
* Hopefully none
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
N/A
Developer Impact
Developer impact
----------------
N/A
@ -101,7 +101,7 @@ Assignee(s)
Primary assignee:
arosen
Work Items
Work items
----------
Implementation
@ -117,7 +117,7 @@ Testing
Unit tests will be provided
Documentation Impact
Documentation impact
====================
N/A

12
specs/kilo/policy-engine-trigger.rst
View File

@ -91,7 +91,7 @@ Other end user impact
None
Performance Impact
Performance impact
------------------
This added functionality may or may not come with a performance cost.
@ -104,11 +104,11 @@ MaterializedViewTheory will incur no performance cost because it already
evaluates all tables at every insert/delete.
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
None
Developer Impact
Developer impact
----------------
None outside of Congress. Developers can ignore the new interface
@ -123,7 +123,7 @@ Assignee(s)
Primary assignee:
Tim Hinrichs
Work Items
Work items
----------
- Add event-handler registry to theory base class
@ -143,7 +143,7 @@ Unit tests: register event handler, insert/delete policy data, check if
event handler actually executed
Documentation Impact
Documentation impact
====================
None

15
specs/kilo/refactor-drivers.rst
View File

@ -96,20 +96,20 @@ Other end user impact
None
Performance Impact
Performance impact
------------------
None
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
This change will have an effect as soon as it is merged, but Congress should
behave exactly as it did without the change.
Developer Impact
Developer impact
----------------
The new refactoring will change how programmers write datasource drivers. The
@ -128,7 +128,7 @@ Assignee(s)
ayip
Work Items
Work items
----------
1) Write new superclass.
@ -146,10 +146,11 @@ None
Testing
=======
Unit tests for superclass, and modify existing test cases for individual drivers.
Unit tests for superclass, and modify existing test cases for individual
drivers.
Documentation Impact
Documentation impact
====================
This change will include new documentation for how to use the new datasource

20
specs/template.rst
View File

@ -86,14 +86,14 @@ error(vm) :-
ids:ip_blacklist(dst_ip).
Policy Actions
Policy actions
--------------
Describe the policy activities in terms of monitoring, reactive, proactive,
and other ways to explain how the policy will implement it's desired state.
Data Sources
Data sources
------------
Describe which projects and/or services the data is coming from
@ -214,7 +214,7 @@ feature?
* Does this change have an impact on python-congressclient? What does the user
interface there look like?
Performance Impact
Performance impact
------------------
Describe any potential performance impact on the system, for example
@ -239,8 +239,8 @@ Examples of things to consider here include:
* Will the change include any locking, and if so what considerations are there
on holding the lock?
Other Deployer Impacts
----------------------
Other deployer impact
---------------------
Discuss things that will affect how you deploy and configure OpenStack
that have not already been mentioned, such as:
@ -263,7 +263,7 @@ that have not already been mentioned, such as:
we have a special case in the code? Do we assume that the operator will
recreate all the instances in their cloud?
Developer Impact
Developer impact
----------------
Discuss things that will affect other developers working on OpenStack,
@ -291,7 +291,7 @@ Primary assignee:
Other contributors:
<launchpad-id or None>
Work Items
Work items
----------
Work items or tasks -- break the feature up into the things that need to be
@ -302,8 +302,8 @@ but we're mostly trying to understand the timeline for implementation.
Dependencies
============
* Include specific references to specs and/or blueprints in congress, or in other
projects, that this one either depends on or is related to.
* Include specific references to specs and/or blueprints in congress, or in
other projects, that this one either depends on or is related to.
* If this requires functionality of another project that is not currently used
by congress (such as the glance v2 API when we previously only required v1),
@ -327,7 +327,7 @@ software configurations available)? If so, are there mitigation plans (3rd
party testing, gate enhancements, etc).
Documentation Impact
Documentation impact
====================
What is the impact on the docs team of this change? Some changes might require

27
tests/test_titles.py
View File

@ -41,7 +41,7 @@ class TestTitles(testtools.TestCase):
def _check_titles(self, fname, titles):
expected_titles = ('Problem description', 'Proposed change',
'Implementation', 'Dependencies',
'Testing', 'Documentation Impact',
'Testing', 'Documentation impact',
'References')
self.assertEqual(
sorted(expected_titles),
@ -49,19 +49,20 @@ class TestTitles(testtools.TestCase):
"Expected titles not found in document %s" % fname)
proposed = 'Proposed change'
self.assertIn('Alternatives', titles[proposed])
self.assertIn('Data model impact', titles[proposed])
self.assertIn('REST API impact', titles[proposed])
self.assertIn('Security impact', titles[proposed])
self.assertIn('Notifications impact', titles[proposed])
self.assertIn('Other end user impact', titles[proposed])
self.assertIn('Performance Impact', titles[proposed])
self.assertIn('Other deployer impact', titles[proposed])
self.assertIn('Developer impact', titles[proposed])
msg = 'Subtitle missing from %s' % fname
self.assertIn('Alternatives', titles[proposed], message=msg)
self.assertIn('Data model impact', titles[proposed], message=msg)
self.assertIn('REST API impact', titles[proposed], message=msg)
self.assertIn('Security impact', titles[proposed], message=msg)
self.assertIn('Notifications impact', titles[proposed], message=msg)
self.assertIn('Other end user impact', titles[proposed], message=msg)
self.assertIn('Performance impact', titles[proposed], message=msg)
self.assertIn('Other deployer impact', titles[proposed], message=msg)
self.assertIn('Developer impact', titles[proposed], message=msg)
impl = 'Implementation'
self.assertIn('Assignee(s)', titles[impl])
self.assertIn('Work Items', titles[impl])
self.assertIn('Assignee(s)', titles[impl], message=msg)
self.assertIn('Work items', titles[impl], message=msg)
def _check_lines_wrapping(self, tpl, raw):
for i, line in enumerate(raw.split("\n")):
@ -95,7 +96,7 @@ class TestTitles(testtools.TestCase):
with open(filename) as f:
data = f.read()
spec = docutils.core.publish_doctree(data)
spec = docutils.core.publish_doctree(data, source_path=filename)
titles = self._get_titles(spec)
self._check_titles(filename, titles)
self._check_lines_wrapping(filename, data)