move docs into new structure and fix links

also moved old release notes from doc to releasenotes

Partial-Bug: 1706158

Change-Id: I2643b377a82d40a570fd51bdb3de5a550fc8ce84
This commit is contained in:
Eric Kao 2017-08-03 14:37:49 -07:00 committed by Akihiro Motoki
parent 981e7211bc
commit 84eafe69ca
27 changed files with 514 additions and 517 deletions

View File

@ -3,23 +3,19 @@ Contributing
============
The Congress wiki page is the authoritative starting point.
https://wiki.openstack.org/wiki/Congress
https://wiki.openstack.org/wiki/Congress
If you would like to contribute to the development of any OpenStack
project including Congress,
you must follow the steps in this page:
https://docs.openstack.org/infra/manual/developers.html
https://docs.openstack.org/infra/manual/developers.html
Once those steps have been completed, changes to OpenStack
should be submitted for review via the Gerrit tool, following
the workflow documented at:
https://docs.openstack.org/infra/manual/developers.html#development-workflow
https://docs.openstack.org/infra/manual/developers.html#development-workflow
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

View File

@ -1,4 +1,7 @@
========================
===================
Welcome to Congress
===================
Team and repository tags
========================
@ -10,12 +13,9 @@ Team and repository tags
.. _readme:
======================================
Congress Introduction and Installation
======================================
1. What is Congress
===================
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
@ -27,8 +27,8 @@ 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**.
2. Why is Policy Important
==========================
Why is Policy Important
=======================
The cloud is a collection of autonomous
services that constantly change the state of the cloud, and it can be
@ -57,8 +57,8 @@ configured correctly. For example,
Congress's job is to help people manage that plethora of state across
all cloud services with a succinct policy language.
3. Using Congress
=================
Using Congress
==============
Setting up Congress involves writing policies and configuring Congress
to fetch input data from the cloud services. The cloud operator
@ -91,375 +91,8 @@ Congress is free software and is licensed with Apache.
* Free software: Apache license
4. Installing Congress
======================
Installing Congress
===================
There are 2 ways to install Congress.
* As part of DevStack. Get Congress running alongside other OpenStack services like Nova
and Neutron, all on a single machine. This is a great way to try out Congress for the
first time.
* Separate install. Get Congress running alongside an existing OpenStack
deployment
4.1 Devstack-install
--------------------
For integrating Congress with DevStack:
1. Download DevStack
.. code-block:: console
$ git clone https://git.openstack.org/openstack-dev/devstack.git
$ cd devstack
2. Configure DevStack to use Congress and any other service you want. To do that, modify
the ``local.conf`` file (inside the DevStack directory). Here is what
our file looks like:
.. code-block:: console
[[local|localrc]]
enable_plugin congress https://git.openstack.org/openstack/congress
enable_plugin heat https://git.openstack.org/openstack/heat
enable_plugin aodh https://git.openstack.org/openstack/aodh
enable_plugin ceilometer https://git.openstack.org/openstack/ceilometer
enable_service s-proxy s-object s-container s-account
3. Run ``stack.sh``. The default configuration expects the passwords to be 'password'
without the quotes
.. code-block:: console
$ ./stack.sh
4.2 Separate install
--------------------
Install the following software, if you haven't already.
* python 2.7: https://www.python.org/download/releases/2.7/
* pip: https://pip.pypa.io/en/latest/installing.html
* java: https://java.com (any reasonably current version should work)
On Ubuntu: console apt-get install default-jre
On Federa: console yum install jre
* Additionally
.. code-block:: console
$ sudo apt-get install git gcc python-dev python-antlr3 libxml2 libxslt1-dev libzip-dev build-essential libssl-dev libffi-dev
$ sudo apt install python-setuptools
$ sudo pip install --upgrade pip virtualenv pbr tox
Clone Congress
.. code-block:: console
$ git clone https://github.com/openstack/congress.git
$ cd congress
Install requirements
.. code-block:: console
$ sudo pip install .
Install Source code
.. code-block:: console
$ sudo python setup.py install
Configure Congress (Assume you put config files in /etc/congress)
.. code-block:: console
$ sudo mkdir -p /etc/congress
$ sudo mkdir -p /etc/congress/snapshot
$ sudo cp etc/api-paste.ini /etc/congress
$ sudo cp etc/policy.json /etc/congress
Set-up Policy Library [optional]
This step copies the bundled collection Congress policies into the Congress
policy library for easy activation by an administrator. The policies in the
library do not become active until explicitly activated by an administrator.
The step may be skipped if you do not want to load the bundled policies into
the policy library.
.. code-block:: console
$ sudo cp -r library /etc/congress/.
Generate a configuration file as outlined in the Configuration Options section
of the :ref:`Deployment <deployment>` document. Note: you may have to run the command with sudo.
There are several sections in the congress/etc/congress.conf.sample file you may want to change:
* [DEFAULT] Section
- drivers
- auth_strategy
* "From oslo.log" Section
- log_file
- log_dir (remember to create the directory)
* [database] Section
- connection
Add drivers:
.. code-block:: text
drivers = congress.datasources.neutronv2_driver.NeutronV2Driver,congress.datasources.glancev2_driver.GlanceV2Driver,congress.datasources.nova_driver.NovaDriver,congress.datasources.keystone_driver.KeystoneDriver,congress.datasources.ceilometer_driver.CeilometerDriver,congress.datasources.cinder_driver.CinderDriver,congress.datasources.swift_driver.SwiftDriver,congress.datasources.plexxi_driver.PlexxiDriver,congress.datasources.vCenter_driver.VCenterDriver,congress.datasources.murano_driver.MuranoDriver,congress.datasources.ironic_driver.IronicDriver
The default auth_strategy is keystone. To set Congress to use no authorization strategy:
.. code-block:: text
auth_strategy = noauth
If you use noauth, you might want to delete or comment out the [keystone_authtoken] section.
Set the database connection string in the [database] section (adapt MySQL root password):
.. code-block:: text
connection = mysql+pymysql://root:password@127.0.0.1/congress?charset=utf8
To use RabbitMQ with Congress, set the transport_url in the "From oslo.messaging" section according to your setup:
.. code-block:: text
transport_url = rabbit://$RABBIT_USERID:$RABBIT_PASSWORD@$RABBIT_HOST:5672
A bare-bones congress.conf is as follows:
.. code-block:: text
[DEFAULT]
auth_strategy = noauth
drivers = congress.datasources.neutronv2_driver.NeutronV2Driver,congress.datasources.glancev2_driver.GlanceV2Driver,congress.datasources.nova_driver.NovaDriver,congress.datasources.keystone_driver.KeystoneDriver,congress.datasources.ceilometer_driver.CeilometerDriver,congress.datasources.cinder_driver.CinderDriver,congress.datasources.swift_driver.SwiftDriver,congress.datasources.plexxi_driver.PlexxiDriver,congress.datasources.vCenter_driver.VCenterDriver,congress.datasources.murano_driver.MuranoDriver,congress.datasources.ironic_driver.IronicDriver
log_file=congress.log
log_dir=/var/log/congress
[database]
connection = mysql+pymysql://root:password@127.0.0.1/congress?charset=utf8
When you are finished editing congress.conf.sample, copy it to the /etc/congress directory.
.. code-block:: console
sudo cp etc/congress.conf.sample /etc/congress/congress.conf
Create database
.. code-block:: console
$ mysql -u root -p
$ mysql> CREATE DATABASE congress;
$ mysql> GRANT ALL PRIVILEGES ON congress.* TO 'congress'@'localhost' IDENTIFIED BY 'CONGRESS_DBPASS';
$ mysql> GRANT ALL PRIVILEGES ON congress.* TO 'congress'@'%' IDENTIFIED BY 'CONGRESS_DBPASS';
Push down schema
.. code-block:: console
$ sudo congress-db-manage --config-file /etc/congress/congress.conf upgrade head
Set up Congress accounts
Use your OpenStack RC file to set and export required environment variables:
OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_TENANT_NAME, OS_AUTH_URL.
(Adapt parameters according to your environment)
.. code-block:: console
$ ADMIN_ROLE=$(openstack role list | awk "/ admin / { print \$2 }")
$ SERVICE_TENANT=$(openstack project list | awk "/ service / { print \$2 }")
$ CONGRESS_USER=$(openstack user create --password password --project service --email "congress@example.com" congress | awk "/ id / {print \$4 }")
$ openstack role add $ADMIN_ROLE --user $CONGRESS_USER --project $SERVICE_TENANT
$ CONGRESS_SERVICE=$(openstack service create policy --name congress --description "Congress Service" | awk "/ id / { print \$4 }")
Create the Congress Service Endpoint
Endpoint creation differs based upon the Identity version. Please see the `endpoint <https://docs.openstack.org/developer/python-openstackclient/command-objects/endpoint.html>`_ documentation for details.
.. code-block:: console
Identity v2:
$ openstack endpoint create $CONGRESS_SERVICE --region RegionOne --publicurl https://127.0.0.1:1789/ --adminurl https://127.0.0.1:1789/ --internalurl https://127.0.0.1:1789/
.. code-block:: console
Identity v3:
$ openstack endpoint create --region $OS_REGION_NAME $CONGRESS_SERVICE public https://$SERVICE_HOST:1789
$ openstack endpoint create --region $OS_REGION_NAME $CONGRESS_SERVICE admin https://$SERVICE_HOST:1789
$ openstack endpoint create --region $OS_REGION_NAME $CONGRESS_SERVICE internal https://$SERVICE_HOST:1789
Start Congress
The default behavior is to start the Congress API, Policy Engine, and
Datasource in a single node. For HAHT deployment options, please see the
:ref:`HA Overview <ha_overview>` document.
.. code-block:: console
$ sudo /usr/local/bin/congress-server --debug
Install the Congress Client
The command line interface (CLI) for Congress resides in a project called python-congressclient.
Follow the installation instructions on the `GitHub page <https://github.com/openstack/python-congressclient>`_.
Configure datasource drivers
For this you must have the Congress CLI installed. Run this command for every
service that Congress will poll for data.
Please note that the service name $SERVICE should match the ID of the
datasource driver, e.g. "neutronv2" for Neutron and "glancev2" for Glance;
$OS_USERNAME, $OS_TENANT_NAME, $OS_PASSWORD and $SERVICE_HOST are used to
configure the related datasource driver so that congress knows how to
talk with the service.
.. code-block:: console
$ openstack congress datasource create $SERVICE $"SERVICE" \
--config username=$OS_USERNAME \
--config tenant_name=$OS_TENANT_NAME
--config password=$OS_PASSWORD
--config auth_url=https://$SERVICE_HOST:5000/v2.0
Install the Congress Dashboard in Horizon
Clone congress-dashboard repo, located here https://github.com/openstack/congress-dashboard
Follow the instructions in the README file located in https://github.com/openstack/congress-dashboard/blob/master/README.rst
for further installation.
Note: After you install the Congress Dashboard and restart apache, the OpenStack Dashboard may throw
a "You have offline compression enabled..." error, follow the instructions in the error message.
You may have to:
.. code-block:: console
$ cd /opt/stack/horizon
$ python manage.py compress
$ sudo service apache2 restart
Read the HTML documentation
Install python-sphinx and the oslosphinx extension if missing and build the docs.
After building, open congress/doc/html/index.html in a browser.
.. code-block:: console
$ sudo pip install sphinx
$ sudo pip install oslosphinx
$ make docs
Test Using the Congress CLI
If you are not familiar with using the OpenStack command-line clients, please read the `OpenStack documentation <https://docs.openstack.org/user-guide/cli.html>`_ before proceeding.
Once you have set up or obtained credentials to use the OpenStack command-line clients, you may begin testing Congress. During installation a number of policies are created.
To view policies: $ openstack congress policy list
To view installed datasources: $ openstack congress datasource list
To list available commands: $ openstack congress --help
4.3 Unit Tests
------------------------
Run unit tests in the Congress directory
.. code-block:: console
$ tox -epy27
In order to break into the debugger from a unit test we need to insert
a break point to the code:
.. code-block:: python
import pdb; pdb.set_trace()
Then run ``tox`` with the debug environment as one of the following::
tox -e debug
tox -e debug test_file_name.TestClass.test_name
For more information see the `oslotest documentation
<https://docs.openstack.org/developer/oslotest/features.html#debugging-with-oslo-debug-helper>`_.
4.4 Upgrade
-----------
Here are the instructions for upgrading to a new release of the
Congress server.
1. Stop the Congress server.
2. Update the Congress git repo
.. code-block:: console
$ cd /path/to/congress
$ git fetch origin
3. Checkout the release you are interested in, say Mitaka. Note that this
step will not succeed if you have any uncommitted changes in the repo.
.. code-block:: console
$ git checkout origin/stable/mitaka
If you have changes committed locally that are not merged into the public
repository, you now need to cherry-pick those changes onto the new
branch.
4. Install dependencies
.. code-block:: console
$ sudo pip install
5. Install source code
.. code-block:: console
$ sudo python setup.py install
6. Migrate the database schema
.. code-block:: console
$ sudo congress-db-manage --config-file /etc/congress/congress.conf upgrade head
7. (optional) Check if the configuration options you are currently using are
still supported and whether there are any new configuration options you
would like to use. To see the current list of configuration options,
use the following command, which will create a sample configuration file
in ``etc/congress.conf.sample`` for you to examine.
.. code-block:: console
$ tox -egenconfig
8. Restart Congress, e.g.
.. code-block:: console
$ sudo /usr/local/bin/congress-server --debug
Please refer to the
`installation guide <https://docs.openstack.org/congress/latest/install/>`_

View File

@ -1 +0,0 @@
.. include:: ../../README.rst

View File

@ -97,9 +97,9 @@ are specified in the [DEFAULT] section of the configuration file.
[DEFAULT]
transport_url = rabbit://<rabbit-userid>:<rabbit-password>@<rabbit-host-address>:<port>
=============
-------------
HA Deployment
=============
-------------
.. toctree::
:maxdepth: 2

View File

@ -30,7 +30,7 @@ All the Congress nodes share a database backend. To setup a database backend
for Congress, please follow the database portion of
`separate install instructions`__.
__ http://docs.openstack.org/developer/congress/README.html?highlight=readme#separate-install
__ https://docs.openstack.org/congress/latest/README.html?highlight=readme#separate-install
Various solutions exist to avoid creating a single point of failure with the
database backend.
@ -52,7 +52,7 @@ Congress should be installed on each host expected to run a Congress node.
Please follow the directions in `separate install instructions`__ to install
Congress on each host, skipping the local database portion.
__ http://docs.openstack.org/developer/congress/README.html?highlight=readme#separate-install
__ https://docs.openstack.org/congress/latest/README.html?highlight=readme#separate-install
In the configuration file, a ``transport_url`` should be specified to use the
RabbitMQ messaging service configured in step 1.
@ -75,7 +75,7 @@ All hosts should be configured with a database connection that points to the
shared database deployed in step 1, not the local address shown in
`separate install instructions`__.
__ http://docs.openstack.org/developer/congress/README.html?highlight=readme#separate-install
__ https://docs.openstack.org/congress/latest/README.html?highlight=readme#separate-install
For example:
@ -92,9 +92,9 @@ In this step, we deploy a single datasource-drivers node in warm-standby style.
The datasource-drivers node can be started directly with the following command:
.. code-block:: console
.. code-block:: console
$ python /usr/local/bin/congress-server --datasources --node-id=<unique_node_id>
$ python /usr/local/bin/congress-server --datasources --node-id=<unique_node_id>
A unique node-id (distinct from all the policy-engine nodes) must be specified.
@ -158,9 +158,9 @@ In this step, we deploy N (at least 2) policy-engine nodes, each with an
associated API server. This step should be done only after the
`Datasource Drivers Node`_ is deployed. Each node can be started as follows:
.. code-block:: console
.. code-block:: console
$ python /usr/local/bin/congress-server --api --policy-engine --node-id=<unique_node_id>
$ python /usr/local/bin/congress-server --api --policy-engine --node-id=<unique_node_id>
Each node must have a unique node-id specified as a commandline option.
@ -182,4 +182,4 @@ to out-of-sync artifacts when the user hits different policy-engine nodes.
purpose. The HAProxy section of the `OpenStack High Availability Guide`__
has instructions for deploying HAProxy for high availability.
__ http://docs.openstack.org/ha-guide/index.html
__ http://docs.openstack.org/ha-guide/index.html

View File

@ -0,0 +1,8 @@
====================================
Congress Administrator Documentation
====================================
.. toctree::
:maxdepth: 2
deployment

View File

@ -1 +0,0 @@
.. include:: ../../CONTRIBUTING.rst

View File

@ -9,8 +9,8 @@ This page gives a brief overview of the code structure that implements
Congress.
1. External information
=======================
External information
====================
The main source of information is the Congress wiki. There are two separate
codebases that implement Congress: the server and the python client bindings.
@ -25,8 +25,8 @@ within the server. The remainder of this page describes the layout
of the server code.
2. Server directory structure
=============================
Server directory structure
==========================
Here are the most important components of the code, described by how they are
laid out in the repository.
@ -44,8 +44,8 @@ laid out in the repository.
* ``contrib``: code for integrating into other services
3. Datalog
==========
Datalog
=======
First is a description of the files and folders in congress/datalog. These files
implement Datalog: the language Congress uses for describing policies.
@ -111,16 +111,16 @@ these are called 'theories'.
MaterializedViewTheory internally. Not actively maintained.
4. Policy engines
=================
Policy engines
==============
The congress/policy_engines directory contains implementations and wrappers for
policy engines. At the time of writing, there are 2 policy engines in this
directory: the domain-agnostic policy engine (agnostic.py) and the skeleton
of a policy engine specialized for VM-placement (vm_placement.py). We
detail only the domain-agnostic policy engine.
4.1 Domain-agnostic policy engine
---------------------------------
Domain-agnostic policy engine
-----------------------------
Source code found in ``congress/policy_engines/agnostic.py``.
@ -148,6 +148,3 @@ Runtime class---the top-level class for the domain agnostic policy engine.
(the mechanism used to implement manual-reactive-enforcement rules).
See ``initialize_tables`` and ``_update_obj`` to see how and when
triggers are executed.

View File

@ -0,0 +1 @@
.. include:: ../../../CONTRIBUTING.rst

View File

@ -0,0 +1,10 @@
==================================
Congress Contributor Documentation
==================================
.. toctree::
:maxdepth: 2
contributing
codeoverview
tests

View File

@ -0,0 +1,23 @@
Unit Tests
------------------------
Run unit tests in the Congress directory
.. code-block:: console
$ tox -epy27
In order to break into the debugger from a unit test we need to insert
a break point to the code:
.. code-block:: python
import pdb; pdb.set_trace()
Then run ``tox`` with the debug environment as one of the following::
tox -e debug
tox -e debug test_file_name.TestClass.test_name
For more information see the `oslotest documentation
<https://docs.openstack.org/developer/oslotest/features.html#debugging-with-oslo-debug-helper>`_.

View File

@ -6,42 +6,15 @@
Welcome to Congress!
====================
**For Users**
.. toctree::
:maxdepth: 2
README
Introduction <user/readme>
User Documentation <user/index>
Installation Documentation <install/index>
Administrator Documentation <admin/index>
Contributor Documentation <contributor/index>
architecture
cloudservices
policy
enforcement
api
tutorial-tenant-sharing
troubleshooting
**For Operators**
.. toctree::
:maxdepth: 2
deployment
release
**For Developers**
.. toctree::
:maxdepth: 2
contributing
codeoverview
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`

View File

@ -0,0 +1,350 @@
===================================
Congress Installation Documentation
===================================
There are 2 ways to install Congress.
* As part of DevStack. Get Congress running alongside other OpenStack services like Nova
and Neutron, all on a single machine. This is a great way to try out Congress for the
first time.
* Separate install. Get Congress running alongside an existing OpenStack
deployment
Devstack-install
--------------------
For integrating Congress with DevStack:
1. Download DevStack
.. code-block:: console
$ git clone https://git.openstack.org/openstack-dev/devstack.git
$ cd devstack
2. Configure DevStack to use Congress and any other service you want. To do that, modify
the ``local.conf`` file (inside the DevStack directory). Here is what
our file looks like:
.. code-block:: console
[[local|localrc]]
enable_plugin congress https://git.openstack.org/openstack/congress
enable_plugin heat https://git.openstack.org/openstack/heat
enable_plugin aodh https://git.openstack.org/openstack/aodh
enable_plugin ceilometer https://git.openstack.org/openstack/ceilometer
enable_service s-proxy s-object s-container s-account
3. Run ``stack.sh``. The default configuration expects the passwords to be 'password'
without the quotes
.. code-block:: console
$ ./stack.sh
Separate install
--------------------
Install the following software, if you haven't already.
* python 2.7: https://www.python.org/download/releases/2.7/
* pip: https://pip.pypa.io/en/latest/installing.html
* java: https://java.com (any reasonably current version should work)
On Ubuntu: console apt-get install default-jre
On Federa: console yum install jre
* Additionally
.. code-block:: console
$ sudo apt-get install git gcc python-dev python-antlr3 libxml2 libxslt1-dev libzip-dev build-essential libssl-dev libffi-dev
$ sudo apt install python-setuptools
$ sudo pip install --upgrade pip virtualenv pbr tox
Clone Congress
.. code-block:: console
$ git clone https://github.com/openstack/congress.git
$ cd congress
Install requirements
.. code-block:: console
$ sudo pip install .
Install Source code
.. code-block:: console
$ sudo python setup.py install
Configure Congress (Assume you put config files in /etc/congress)
.. code-block:: console
$ sudo mkdir -p /etc/congress
$ sudo mkdir -p /etc/congress/snapshot
$ sudo cp etc/api-paste.ini /etc/congress
$ sudo cp etc/policy.json /etc/congress
Set-up Policy Library [optional]
This step copies the bundled collection Congress policies into the Congress
policy library for easy activation by an administrator. The policies in the
library do not become active until explicitly activated by an administrator.
The step may be skipped if you do not want to load the bundled policies into
the policy library.
.. code-block:: console
$ sudo cp -r library /etc/congress/.
Generate a configuration file as outlined in the Configuration Options section
of the :ref:`Deployment <deployment>` document. Note: you may have to run the command with sudo.
There are several sections in the congress/etc/congress.conf.sample file you may want to change:
* [DEFAULT] Section
- drivers
- auth_strategy
* "From oslo.log" Section
- log_file
- log_dir (remember to create the directory)
* [database] Section
- connection
Add drivers:
.. code-block:: text
drivers = congress.datasources.neutronv2_driver.NeutronV2Driver,congress.datasources.glancev2_driver.GlanceV2Driver,congress.datasources.nova_driver.NovaDriver,congress.datasources.keystone_driver.KeystoneDriver,congress.datasources.ceilometer_driver.CeilometerDriver,congress.datasources.cinder_driver.CinderDriver,congress.datasources.swift_driver.SwiftDriver,congress.datasources.plexxi_driver.PlexxiDriver,congress.datasources.vCenter_driver.VCenterDriver,congress.datasources.murano_driver.MuranoDriver,congress.datasources.ironic_driver.IronicDriver
The default auth_strategy is keystone. To set Congress to use no authorization strategy:
.. code-block:: text
auth_strategy = noauth
If you use noauth, you might want to delete or comment out the [keystone_authtoken] section.
Set the database connection string in the [database] section (adapt MySQL root password):
.. code-block:: text
connection = mysql+pymysql://root:password@127.0.0.1/congress?charset=utf8
To use RabbitMQ with Congress, set the transport_url in the "From oslo.messaging" section according to your setup:
.. code-block:: text
transport_url = rabbit://$RABBIT_USERID:$RABBIT_PASSWORD@$RABBIT_HOST:5672
A bare-bones congress.conf is as follows:
.. code-block:: text
[DEFAULT]
auth_strategy = noauth
drivers = congress.datasources.neutronv2_driver.NeutronV2Driver,congress.datasources.glancev2_driver.GlanceV2Driver,congress.datasources.nova_driver.NovaDriver,congress.datasources.keystone_driver.KeystoneDriver,congress.datasources.ceilometer_driver.CeilometerDriver,congress.datasources.cinder_driver.CinderDriver,congress.datasources.swift_driver.SwiftDriver,congress.datasources.plexxi_driver.PlexxiDriver,congress.datasources.vCenter_driver.VCenterDriver,congress.datasources.murano_driver.MuranoDriver,congress.datasources.ironic_driver.IronicDriver
log_file=congress.log
log_dir=/var/log/congress
[database]
connection = mysql+pymysql://root:password@127.0.0.1/congress?charset=utf8
When you are finished editing congress.conf.sample, copy it to the /etc/congress directory.
.. code-block:: console
sudo cp etc/congress.conf.sample /etc/congress/congress.conf
Create database
.. code-block:: console
$ mysql -u root -p
$ mysql> CREATE DATABASE congress;
$ mysql> GRANT ALL PRIVILEGES ON congress.* TO 'congress'@'localhost' IDENTIFIED BY 'CONGRESS_DBPASS';
$ mysql> GRANT ALL PRIVILEGES ON congress.* TO 'congress'@'%' IDENTIFIED BY 'CONGRESS_DBPASS';
Push down schema
.. code-block:: console
$ sudo congress-db-manage --config-file /etc/congress/congress.conf upgrade head
Set up Congress accounts
Use your OpenStack RC file to set and export required environment variables:
OS_USERNAME, OS_PASSWORD, OS_PROJECT_NAME, OS_TENANT_NAME, OS_AUTH_URL.
(Adapt parameters according to your environment)
.. code-block:: console
$ ADMIN_ROLE=$(openstack role list | awk "/ admin / { print \$2 }")
$ SERVICE_TENANT=$(openstack project list | awk "/ service / { print \$2 }")
$ CONGRESS_USER=$(openstack user create --password password --project service --email "congress@example.com" congress | awk "/ id / {print \$4 }")
$ openstack role add $ADMIN_ROLE --user $CONGRESS_USER --project $SERVICE_TENANT
$ CONGRESS_SERVICE=$(openstack service create policy --name congress --description "Congress Service" | awk "/ id / { print \$4 }")
Create the Congress Service Endpoint
Endpoint creation differs based upon the Identity version. Please see the `endpoint <https://docs.openstack.org/developer/python-openstackclient/command-objects/endpoint.html>`_ documentation for details.
.. code-block:: console
Identity v2:
$ openstack endpoint create $CONGRESS_SERVICE --region RegionOne --publicurl https://127.0.0.1:1789/ --adminurl https://127.0.0.1:1789/ --internalurl https://127.0.0.1:1789/
.. code-block:: console
Identity v3:
$ openstack endpoint create --region $OS_REGION_NAME $CONGRESS_SERVICE public https://$SERVICE_HOST:1789
$ openstack endpoint create --region $OS_REGION_NAME $CONGRESS_SERVICE admin https://$SERVICE_HOST:1789
$ openstack endpoint create --region $OS_REGION_NAME $CONGRESS_SERVICE internal https://$SERVICE_HOST:1789
Start Congress
The default behavior is to start the Congress API, Policy Engine, and
Datasource in a single node. For HAHT deployment options, please see the
:ref:`HA Overview <ha_overview>` document.
.. code-block:: console
$ sudo /usr/local/bin/congress-server --debug
Install the Congress Client
The command line interface (CLI) for Congress resides in a project called python-congressclient.
Follow the installation instructions on the `GitHub page <https://github.com/openstack/python-congressclient>`_.
Configure datasource drivers
For this you must have the Congress CLI installed. Run this command for every
service that Congress will poll for data.
Please note that the service name $SERVICE should match the ID of the
datasource driver, e.g. "neutronv2" for Neutron and "glancev2" for Glance;
$OS_USERNAME, $OS_TENANT_NAME, $OS_PASSWORD and $SERVICE_HOST are used to
configure the related datasource driver so that congress knows how to
talk with the service.
.. code-block:: console
$ openstack congress datasource create $SERVICE $"SERVICE" \
--config username=$OS_USERNAME \
--config tenant_name=$OS_TENANT_NAME
--config password=$OS_PASSWORD
--config auth_url=https://$SERVICE_HOST:5000/v2.0
Install the Congress Dashboard in Horizon
Clone congress-dashboard repo, located here https://github.com/openstack/congress-dashboard
Follow the instructions in the README file located in https://github.com/openstack/congress-dashboard/blob/master/README.rst
for further installation.
Note: After you install the Congress Dashboard and restart apache, the OpenStack Dashboard may throw
a "You have offline compression enabled..." error, follow the instructions in the error message.
You may have to:
.. code-block:: console
$ cd /opt/stack/horizon
$ python manage.py compress
$ sudo service apache2 restart
Read the HTML documentation
Install python-sphinx and the oslosphinx extension if missing and build the docs.
After building, open congress/doc/html/index.html in a browser.
.. code-block:: console
$ sudo pip install sphinx
$ sudo pip install oslosphinx
$ make docs
Test Using the Congress CLI
If you are not familiar with using the OpenStack command-line clients, please read the `OpenStack documentation <https://docs.openstack.org/user-guide/cli.html>`_ before proceeding.
Once you have set up or obtained credentials to use the OpenStack command-line clients, you may begin testing Congress. During installation a number of policies are created.
To view policies: $ openstack congress policy list
To view installed datasources: $ openstack congress datasource list
To list available commands: $ openstack congress --help
Upgrade
-----------
Here are the instructions for upgrading to a new release of the
Congress server.
1. Stop the Congress server.
2. Update the Congress git repo
.. code-block:: console
$ cd /path/to/congress
$ git fetch origin
3. Checkout the release you are interested in, say Mitaka. Note that this
step will not succeed if you have any uncommitted changes in the repo.
.. code-block:: console
$ git checkout origin/stable/mitaka
If you have changes committed locally that are not merged into the public
repository, you now need to cherry-pick those changes onto the new
branch.
4. Install dependencies
.. code-block:: console
$ sudo pip install
5. Install source code
.. code-block:: console
$ sudo python setup.py install
6. Migrate the database schema
.. code-block:: console
$ sudo congress-db-manage --config-file /etc/congress/congress.conf upgrade head
7. (optional) Check if the configuration options you are currently using are
still supported and whether there are any new configuration options you
would like to use. To see the current list of configuration options,
use the following command, which will create a sample configuration file
in ``etc/congress.conf.sample`` for you to examine.
.. code-block:: console
$ tox -egenconfig
8. Restart Congress, e.g.
.. code-block:: console
$ sudo /usr/local/bin/congress-server --debug

View File

@ -1,58 +0,0 @@
.. _release:
=============
Release Notes
=============
Newer release notes (after Mitaka) are published in OpenStack official
release notes.
To see the latest updates, please visit here:
[OpenStack official release notes](http://docs.openstack.org/)
Liberty
-------
**Main updates**
* Added datasource driver for Heat
* Designed and began implementation of new distributed architecture
* Added API call to list available actions for manual reactive enforcement
* Refactored all datasource drivers for improved consistency
* Extended grammar to include insert and delete events
* Improved tempest/devstack support for running in gate
* Added version API
* Improved support for python3
* Reduced debug log volume by reducing messages sent on message bus
* Enabled action execution for all datasources
* Eliminated busy-loop in message bus for reduced cpu consumption
* Improved unit test coverage for API
* Added experimental vm-migration policy enforcement engine
Kilo
----
**Main features**
* Datalog: basic rules, column references, multiple policies,
action-execution rules
* Monitoring: check for policy violations by asking for the rows of
the ``error`` table
* Proactive enforcement: prevent violations by asking Congress before making
changes using the ``simulate`` API call
* Manual reactive enforcement: correct violations by writing Datalog
statements that say which actions to execute to eliminate violations
* Datasource drivers for Ceilometer, Cinder, CloudFoundry, Glance, Ironic,
Keystone, Murano, Neutron, Nova, Plexxi, Swift, vCenter
**Known issues**
* ``GET /v1/policies/<policy-name>/rules`` fails to return 404 if the policy name
is not found. There are similar issues for other
``/v1/policies/<policy-name>/rules`` API calls.
* Within a policy, you may not use both ``execute[<table>(<args>)]`` and
``<table>(<args>)`` in the heads of rules.

View File

@ -85,10 +85,10 @@ In this writeup we assume you are using the python-client.
Suppose you want to know the policy violations after making the following
changes.
1. insert a row into the *nova:servers* table with ID uuid1, 2TB of disk,
and 10GB of memory
2. delete the row from *neutron:security_groups* with the ID “uuid2” and name
“alice_default_group”
1. insert a row into the *nova:servers* table with ID uuid1, 2TB of disk,
and 10GB of memory
2. delete the row from *neutron:security_groups* with the ID “uuid2” and name
“alice_default_group”
(Here we assume the nova:servers table has columns ID, disk-size, and memory
and that neutron:security groups has columns ID, and name.)

15
doc/source/user/index.rst Normal file
View File

@ -0,0 +1,15 @@
===========================
Congress User Documentation
===========================
.. toctree::
:maxdepth: 2
architecture
cloudservices
policy
enforcement
api
tutorial-tenant-sharing
troubleshooting

View File

@ -208,7 +208,9 @@ This is called a *join* in the realm of relational databases and SQL.
that have NOT been assigned any IP address. We can use the *not* operator to
check if a row fails to belong to a table.
no_ip(port) :- neutron:port(port), not has_ip(port)
.. code-block:: none
no_ip(port) :- neutron:port(port), not has_ip(port)
There are special restrictions that you must be aware of when using *not*.
See the next section for details.
@ -512,7 +514,9 @@ the internet *connected_to_internet*, then as a
cloud administrator, you might write a policy that says there is an error
whenever a server is insecure and connected to the internet.
error(x) :- compute:insecure(x), network:connected_to_internet(x)
.. code-block:: none
error(x) :- compute:insecure(x), network:connected_to_internet(x)
Notice that this is exactly the same syntax you use to reference tables exported
directly by cloud services::

View File

@ -0,0 +1 @@
.. include:: ../../../README.rst

View File

@ -297,11 +297,11 @@ the documentation says should be exported::
To fix connection problems, do both of the following.
* Ensure the datasource component is enabled in devstack (if you're using devstack)
* Fix the configuration of the datasource by asking to see its current configuration,
and if it is wrong, delete that datasource and create a new one with the proper
configuration. Don't forget that datasources sometimes return different
information for different username/password combinations.
* Ensure the datasource component is enabled in devstack (if you're using devstack)
* Fix the configuration of the datasource by asking to see its current configuration,
and if it is wrong, delete that datasource and create a new one with the proper
configuration. Don't forget that datasources sometimes return different
information for different username/password combinations.
Below are examples of how to list datasource configuration, delete an existing datasource,
and create a new datasource::

View File

@ -36,11 +36,11 @@ The first step is to install and configure Devstack + Congress:
2) The Devstack installation script will automatically create a data source
instance of the neutronv2 driver. If you are not using Devstack, you will
need to create the data source:
a.) If your environment supports identity v3 then,
a.) If your environment supports identity v3 then::
$ AUTH_URL=`openstack endpoint list --service identity | grep "public" | awk '{print $14}'`
b.) If your environment only supports identity v2 then,
b.) If your environment only supports identity v2 then::
$ AUTH_URL=`openstack endpoint show identity | grep "public" | awk '{print $4}'`

View File

@ -24,6 +24,8 @@ Contents
unreleased
ocata
newton
liberty
kilo
Indices and tables

View File

@ -0,0 +1,25 @@
===================================
Kilo Series Release Notes
===================================
**Main features**
* Datalog: basic rules, column references, multiple policies,
action-execution rules
* Monitoring: check for policy violations by asking for the rows of
the ``error`` table
* Proactive enforcement: prevent violations by asking Congress before making
changes using the ``simulate`` API call
* Manual reactive enforcement: correct violations by writing Datalog
statements that say which actions to execute to eliminate violations
* Datasource drivers for Ceilometer, Cinder, CloudFoundry, Glance, Ironic,
Keystone, Murano, Neutron, Nova, Plexxi, Swift, vCenter
**Known issues**
* ``GET /v1/policies/<policy-name>/rules`` fails to return 404 if the policy name
is not found. There are similar issues for other
``/v1/policies/<policy-name>/rules`` API calls.
* Within a policy, you may not use both ``execute[<table>(<args>)]`` and
``<table>(<args>)`` in the heads of rules.

View File

@ -0,0 +1,19 @@
===================================
Liberty Series Release Notes
===================================
**Main updates**
* Added datasource driver for Heat
* Designed and began implementation of new distributed architecture
* Added API call to list available actions for manual reactive enforcement
* Refactored all datasource drivers for improved consistency
* Extended grammar to include insert and delete events
* Improved tempest/devstack support for running in gate
* Added version API
* Improved support for python3
* Reduced debug log volume by reducing messages sent on message bus
* Enabled action execution for all datasources
* Eliminated busy-loop in message bus for reduced cpu consumption
* Improved unit test coverage for API
* Added experimental vm-migration policy enforcement engine