openstack/congress
Code Issues Proposed changes

simplify README.rst

Browse Source 
Move some of the user intro documentation around so that the
README.rst file can be use to publish packages to PyPI. The :ref: role
for linking between pages in Sphinx is not available for use in readme
files, so most of the content is moved into the main documentation.

Change-Id: Ic7d623b3ea9f6e5485cc5bafb1475611b5fe78a7
Signed-off-by: Doug Hellmann <doug@doughellmann.com>
(cherry picked from commit b839ab565e)
This commit is contained in:
Doug Hellmann 2018-10-05 16:38:25 -04:00 committed by Eric Kao
parent db2e2812aa
commit 4c5b236657
3 changed files with 75 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

83
README.rst
View File

@ -2,21 +2,6 @@
Welcome to Congress
===================
Team and repository tags
========================
.. image:: https://governance.openstack.org/tc/badges/congress.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
.. Change things from this point on
.. _readme:
What is Congress
================
Congress is an open policy framework for the cloud. With Congress, a
cloud operator can declare, monitor, enforce, and audit "policy" in a
heterogeneous cloud environment. Congress gets inputs from a cloud's
@ -27,72 +12,10 @@ where Congress verifies that the cloud's actual state abides by the cloud
operator's policies. Congress is designed to work with **any policy** and
**any cloud service**.
Why is Policy Important
=======================
The cloud is a collection of autonomous
services that constantly change the state of the cloud, and it can be
challenging for the cloud operator to know whether the cloud is even
configured correctly. For example,
* The services are often independent from each other and do not
support transactional consistency across services, so a cloud
management system can change one service (create a VM) without also
making a necessary change to another service (attach the VM to a
network). This can lead to incorrect behavior.
* Other times, we have seen a cloud operator allocate cloud resources
and then forget to clean them up when the resources are no longer in
use, effectively leaving garbage around the system and wasting
resources.
* The desired cloud state can also change over time. For example, if
a security vulnerability is discovered in Linux version X, then all
machines with version X that were ok in the past are now in an
undesirable state. A version number policy would detect all the
machines in that undesirable state. This is a trivial example, but
the more complex the policy, the more helpful a policy system
becomes.
Congress's job is to help people manage that plethora of state across
all cloud services with a succinct policy language.
Using Congress
==============
Setting up Congress involves writing policies and configuring Congress
to fetch input data from the cloud services. The cloud operator
writes policy in the Congress policy language, which receives input
from the cloud services in the form of tables. The language itself
resembles datalog. For more detail about the policy language and data
format see :ref:`Policy <policy>`.
To add a service as an input data source, the cloud operator configures a Congress
"driver," and the driver queries the service. Congress already
has drivers for several types of service, but if a cloud operator
needs to use an unsupported service, she can write a new driver
without much effort and probably contribute the driver to the
Congress project so that no one else needs to write the same driver.
Finally, when using Congress, the cloud operator must choose what
Congress should do with the policy it has been given:
* **monitoring**: detect violations of policy and provide a list of those violations
* **proactive enforcement**: prevent violations before they happen (functionality that requires
other services to consult with Congress before making changes)
* **reactive enforcement**: correct violations after they happen (a manual process that
Congress tries to simplify)
In the future, Congress
will also help the cloud operator audit policy (analyze the history
of policy and policy violations).
.. image:: https://governance.openstack.org/tc/badges/congress.svg
:target: https://governance.openstack.org/tc/reference/tags/index.html
Congress is free software and is licensed with Apache.
* Free software: Apache license
Installing Congress
===================
Please refer to the
`installation guide <https://docs.openstack.org/congress/latest/install/>`_
* Documentation: https://docs.openstack.org/congress/latest/

3
doc/source/index.rst
View File

@ -3,8 +3,7 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Congress!
====================
.. include:: ../../README.rst
.. toctree::
:maxdepth: 2

72
doc/source/user/readme.rst
View File

@ -1 +1,71 @@
.. include:: ../../../README.rst
.. _readme:
======================
Introducing Congress
======================
Why is Policy Important
=======================
The cloud is a collection of autonomous
services that constantly change the state of the cloud, and it can be
challenging for the cloud operator to know whether the cloud is even
configured correctly. For example,
* The services are often independent from each other and do not
support transactional consistency across services, so a cloud
management system can change one service (create a VM) without also
making a necessary change to another service (attach the VM to a
network). This can lead to incorrect behavior.
* Other times, we have seen a cloud operator allocate cloud resources
and then forget to clean them up when the resources are no longer in
use, effectively leaving garbage around the system and wasting
resources.
* The desired cloud state can also change over time. For example, if
a security vulnerability is discovered in Linux version X, then all
machines with version X that were ok in the past are now in an
undesirable state. A version number policy would detect all the
machines in that undesirable state. This is a trivial example, but
the more complex the policy, the more helpful a policy system
becomes.
Congress's job is to help people manage that plethora of state across
all cloud services with a succinct policy language.
Using Congress
==============
Setting up Congress involves writing policies and configuring Congress
to fetch input data from the cloud services. The cloud operator
writes policy in the Congress policy language, which receives input
from the cloud services in the form of tables. The language itself
resembles datalog. For more detail about the policy language and data
format see :ref:`Policy <policy>`.
To add a service as an input data source, the cloud operator configures a Congress
"driver," and the driver queries the service. Congress already
has drivers for several types of service, but if a cloud operator
needs to use an unsupported service, she can write a new driver
without much effort and probably contribute the driver to the
Congress project so that no one else needs to write the same driver.
Finally, when using Congress, the cloud operator must choose what
Congress should do with the policy it has been given:
* **monitoring**: detect violations of policy and provide a list of those violations
* **proactive enforcement**: prevent violations before they happen (functionality that requires
other services to consult with Congress before making changes)
* **reactive enforcement**: correct violations after they happen (a manual process that
Congress tries to simplify)
In the future, Congress
will also help the cloud operator audit policy (analyze the history
of policy and policy violations).
Installing Congress
===================
Please refer to the
`installation guide <https://docs.openstack.org/congress/latest/install/>`_