From 29cdab640fea67115032a34ce9a5a109ee44b6ee Mon Sep 17 00:00:00 2001 From: Sofia Wallin Date: Wed, 18 Oct 2017 12:43:47 +0200 Subject: Various corrections Adjusted structure and enabled referencing. Change-Id: I23a8afd08ebb013d772314b450497c17bfdfc4fc Signed-off-by: Sofia Wallin (cherry picked from commit e493f6692072574d339972f0db3adb8270bdeccd) --- docs/release/configguide/index.rst | 22 +++ docs/release/configguide/installation.rst | 156 ++++++++++++++++++++ docs/release/installation/index.rst | 20 --- docs/release/installation/installation.md | 160 --------------------- docs/release/release-notes/index.rst | 8 +- docs/release/release-notes/release-notes.rst | 3 +- docs/release/scenarios/os-odl_l2-moon-ha/index.rst | 16 +++ .../os-odl_l2-moon-ha/os-odl_l2-moon-ha.rst | 101 +++++++++++++ docs/release/userguide/index.rst | 2 + docs/release/userguide/userguide.md | 114 --------------- docs/release/userguide/userguide.rst | 124 ++++++++++++++++ 11 files changed, 430 insertions(+), 296 deletions(-) create mode 100644 docs/release/configguide/index.rst create mode 100644 docs/release/configguide/installation.rst delete mode 100644 docs/release/installation/index.rst delete mode 100644 docs/release/installation/installation.md create mode 100644 docs/release/scenarios/os-odl_l2-moon-ha/index.rst create mode 100644 docs/release/scenarios/os-odl_l2-moon-ha/os-odl_l2-moon-ha.rst delete mode 100644 docs/release/userguide/userguide.md create mode 100644 docs/release/userguide/userguide.rst (limited to 'docs/release') diff --git a/docs/release/configguide/index.rst b/docs/release/configguide/index.rst new file mode 100644 index 00000000..329a7231 --- /dev/null +++ b/docs/release/configguide/index.rst @@ -0,0 +1,22 @@ +.. _moon-configguide: + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) ruan.he@orange.com & thomas.duval@orange.com + + +*********************************************** +Moon installation and configuration instruction +*********************************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + feature.configuration.rst + + + + + + diff --git a/docs/release/configguide/installation.rst b/docs/release/configguide/installation.rst new file mode 100644 index 00000000..e37193b3 --- /dev/null +++ b/docs/release/configguide/installation.rst @@ -0,0 +1,156 @@ +Build Python Packages and Docker Images +======================================= + +Python Package +-------------- + +pre-requist +~~~~~~~~~~~ + +Get the code + + git clone https://git.opnfv.org/moon + cd moon/moonv4 + export MOON_HOME=$(pwd) + sudo ln -s $(pwd)/conf /etc/moon + + +Install python wheel + + sudo apt install python3-wheel + +Install pip twine + + sudo pip install twine + +Package code, wheel is a new format instead of `tar.gz` + + python setup.py sdist bdist_wheel + +Upload to PyPi + + twine upload dist/moon_xxx-y.y.y.whl + twine upload dist/moon_xxx-y.y.y.tar.gz + +Install a package from PyPi + + sudo pypi install moon_xxx --upgrade + +moon_db +~~~~~~~ + +- change version in `moon_db/__init__.py` +- add `Changelog` + +moon_utilities +~~~~~~~~~~~~~~ + +- change version in `moon_utilities/__init__.py` +- add `Changelog` + +moon_orchestrator +~~~~~~~~~~~~~~~~~ + +- change version in `moon_orchestrator/__init__.py` +- add `Changelog` + + +Build All Pip +~~~~~~~~~~~~~ + + sudo pip3 install pip --upgrade + cd ${MOON_HOME}/bin + source build_all_pip.sh + +Container +--------- + +keystone_mitaka +~~~~~~~~~~~~~~~ + +see `templates/docker/keystone/README.md` to build the `keystone_mitaka` container + + +How to hack the Moon platform +----------------------------- + +Force the build of components +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you want to rebuild one or more component, you have to modify the configuration file `moon.conf`. + +For example, if you want to rebuild the moon_interface, got to the `[interface]` section and delete the +value of the container key like this: + + [interface] + host=172.18.0.11 + port=38001 + # Name of the container to download (if empty build from scratch) + # example: container=moon/moon_interface:latest + container= + +You can configure the interface, the router and both the security_function and security_policy. +You can also force the version of the component like this: `container=moon/moon_interface:4.0.0` + +Update the moon_interface +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Go to the directory `${MOON_HOME}/moon_interface` and update the code accordingly to your needs, +then update the python package. + + cd ${MOON_HOME}/moon_interface + python setup.py sdist + cp dist/moon_interface_* ../moon_orchestrator/dist + # kill moon_orchestrator if needed and restart it + +Update the moon_secrouter +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Go to the directory `${MOON_HOME}/moon_secrouter` and update the code accordingly to your needs, +then update the python package. + + cd ${MOON_HOME}/moon_secrouter + python setup.py sdist + cp dist/moon_secrouter* ../moon_orchestrator/dist + # kill moon_orchestrator if needed and restart it + +Problems that may arise +----------------------- + +If the moon_orchestrator doesn't want to start +(with, for example, the following error: `docker.errors.APIError: 409 Client Error: Conflict`), +check if the router and interface containers still exist and kill and delete them: + + docker kill moon_interface + docker kill moon_router + docker rm moon_interface + docker rm moon_router + +If the moon_orchestrator complains that it cannot request the RabbitMQ server, +check if the messenger server is up and running: + + docker ps + # you must see the messenger running here + # if not, restart it + docker run -dti --net=moon --hostname messenger --name messenger --link messenger:messenger \ + -e RABBITMQ_DEFAULT_USER=moon -e RABBITMQ_DEFAULT_PASS=password -e RABBITMQ_NODENAME=rabbit@messenger \ + -e RABBITMQ_DEFAULT_VHOST=moon -p 5671:5671 -p 5672:5672 rabbitmq:3-management + +Configure DB +------------ + +Relaunch Keystone docker +~~~~~~~~~~~~~~~~~~~~~~~~ + +If error of `get_keystone_projects()`, then relaunch the Keystone docker, and wait 40 seconds!!! + + docker rm -f keystone + docker run -dti --net moon --name keystone --hostname=keystone -e DB_HOST=db -e DB_PASSWORD_ROOT=p4sswOrd1 -p 35357:35357 -p 5000:5000 keystone:mitaka + +Add default data in DB +~~~~~~~~~~~~~~~~~~~~~~ + +Pre-fill the DB with a RBAC policy + + cd ${MOON_HOME}/moon_interface/tests/apitests + python3 populate_default_values.py scenario/ rbac.py diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst deleted file mode 100644 index 1311b248..00000000 --- a/docs/release/installation/index.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. This work is licensed under a Creative Commons Attribution 4.0 International License. -.. http://creativecommons.org/licenses/by/4.0 -.. (c) ruan.he@orange.com & thomas.duval@orange.com - - -*********************************************** -Moon installation and configuration instruction -*********************************************** - -.. toctree:: - :numbered: - :maxdepth: 2 - - feature.configuration.rst - - - - - - diff --git a/docs/release/installation/installation.md b/docs/release/installation/installation.md deleted file mode 100644 index 70bcc4fc..00000000 --- a/docs/release/installation/installation.md +++ /dev/null @@ -1,160 +0,0 @@ -# Build Python Packages and Docker Images - -## Python Package -### pre-requist -Get the code -```bash -git clone https://git.opnfv.org/moon -cd moon/moonv4 -export MOON_HOME=$(pwd) -sudo ln -s $(pwd)/conf /etc/moon -``` - -Install python wheel -```bash -sudo apt install python3-wheel -``` - -Install pip twine -```bash -sudo pip install twine -``` - -Package code, wheel is a new format instead of `tar.gz` -```bash -python setup.py sdist bdist_wheel -``` - -Upload to PyPi -```bash -twine upload dist/moon_xxx-y.y.y.whl -twine upload dist/moon_xxx-y.y.y.tar.gz -``` - -Install a package from PyPi -```bash -sudo pypi install moon_xxx --upgrade -``` - -### moon_db -- change version in `moon_db/__init__.py` -- add `Changelog` - -### moon_utilities -- change version in `moon_utilities/__init__.py` -- add `Changelog` - -### moon_orchestrator -- change version in `moon_orchestrator/__init__.py` -- add `Changelog` - - -### Build All Pip -```bash -sudo pip3 install pip --upgrade -cd ${MOON_HOME}/bin -source build_all_pip.sh -``` - - -## Container -## keystone_mitaka -see `templates/docker/keystone/README.md` to build the `keystone_mitaka` container - - -### moon_router - - -### moon_interface - - -### moon_manager - - -### moon_authz - - -### moon_gui - - -## How to hack the Moon platform -### Force the build of components - -If you want to rebuild one or more component, you have to modify the configuration file `moon.conf`. - -For example, if you want to rebuild the moon_interface, got to the `[interface]` section and delete the -value of the container key like this: - -``` -[interface] -host=172.18.0.11 -port=38001 -# Name of the container to download (if empty build from scratch) -# example: container=moon/moon_interface:latest -container= -``` - -You can configure the interface, the router and both the security_function and security_policy. -You can also force the version of the component like this: `container=moon/moon_interface:4.0.0` - -### Update the moon_interface - -Go to the directory `${MOON_HOME}/moon_interface` and update the code accordingly to your needs, -then update the python package. - -```bash -cd ${MOON_HOME}/moon_interface -python setup.py sdist -cp dist/moon_interface_* ../moon_orchestrator/dist -# kill moon_orchestrator if needed and restart it -``` - -### Update the moon_secrouter - -Go to the directory `${MOON_HOME}/moon_secrouter` and update the code accordingly to your needs, -then update the python package. - -```bash -cd ${MOON_HOME}/moon_secrouter -python setup.py sdist -cp dist/moon_secrouter* ../moon_orchestrator/dist -# kill moon_orchestrator if needed and restart it -``` - -## Problems that may arise - -If the moon_orchestrator doesn't want to start -(with, for example, the following error: `docker.errors.APIError: 409 Client Error: Conflict`), -check if the router and interface containers still exist and kill and delete them: - -```bash -docker kill moon_interface -docker kill moon_router -docker rm moon_interface -docker rm moon_router -``` - -If the moon_orchestrator complains that it cannot request the RabbitMQ server, -check if the messenger server is up and running: - -```bash -docker ps -# you must see the messenger running here -# if not, restart it -docker run -dti --net=moon --hostname messenger --name messenger --link messenger:messenger -e RABBITMQ_DEFAULT_USER=moon -e RABBITMQ_DEFAULT_PASS=password -e RABBITMQ_NODENAME=rabbit@messenger -e RABBITMQ_DEFAULT_VHOST=moon -p 5671:5671 -p 5672:5672 rabbitmq:3-management -``` - -## Configure DB -### Relaunch Keystone docker -If error of `get_keystone_projects()`, then relaunch the Keystone docker, and wait 40 seconds!!! -```bash -docker rm -f keystone -docker run -dti --net moon --name keystone --hostname=keystone -e DB_HOST=db -e DB_PASSWORD_ROOT=p4sswOrd1 -p 35357:35357 -p 5000:5000 keystone:mitaka -``` - -### Add default data in DB -Pre-fill the DB with a RBAC policy -```bash -cd ${MOON_HOME}/moon_interface/tests/apitests -python3 populate_default_values.py scenario/ rbac.py -``` diff --git a/docs/release/release-notes/index.rst b/docs/release/release-notes/index.rst index 83291051..4d5e869a 100644 --- a/docs/release/release-notes/index.rst +++ b/docs/release/release-notes/index.rst @@ -1,3 +1,9 @@ +.. _moon-releasenotes: + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) ruan.he@orange.com & thomas.duval@orange.com + ****************** Moon Release Notes ****************** @@ -12,4 +18,4 @@ Revision: _sha1_ :Author: Ruan He (ruan.he@orange.com) -Build date: |today| \ No newline at end of file +Build date: |today| diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst index a14a6ed7..4823c8a4 100644 --- a/docs/release/release-notes/release-notes.rst +++ b/docs/release/release-notes/release-notes.rst @@ -86,4 +86,5 @@ References For more information on the Moon Colorado release, please see: -https://wiki.opnfv.org/display/moon/ \ No newline at end of file +https://wiki.opnfv.org/display/moon/ + diff --git a/docs/release/scenarios/os-odl_l2-moon-ha/index.rst b/docs/release/scenarios/os-odl_l2-moon-ha/index.rst new file mode 100644 index 00000000..ba990850 --- /dev/null +++ b/docs/release/scenarios/os-odl_l2-moon-ha/index.rst @@ -0,0 +1,16 @@ +.. _os-odl_l2-moon-ha: + +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) ruan.he@orange.com & thomas.duval@orange.com + + +****************************************** +os-odl_l2-moon-ha Overview and Description +****************************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + os-odl_l2-moon-ha.rst diff --git a/docs/release/scenarios/os-odl_l2-moon-ha/os-odl_l2-moon-ha.rst b/docs/release/scenarios/os-odl_l2-moon-ha/os-odl_l2-moon-ha.rst new file mode 100644 index 00000000..11c0eee7 --- /dev/null +++ b/docs/release/scenarios/os-odl_l2-moon-ha/os-odl_l2-moon-ha.rst @@ -0,0 +1,101 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) ruan.he@orange.com & thomas.duval@orange.com + + +Introduction +============ + +This guide presents the use of the Moon platform. +The MoonClient script allows the administrator/user to drive the Moon platform and +some parts of the Keystone server itself. + +Scenario components and composition +=================================== + +###Functional architecture +Moon can be considered as a management layer over OpenStack. +We can dynamically create security modules in Moon and assign these modules to protect different +tenants in OpenStack. +![](../img/moon_infra.png) + +###Policy engine +The core part of the security management layer is its policy engine. +The policy engine should be at same time generic to support a large set of security models +used by consumers and robust so that all the manipulations on the policy engine need to be proved correct. +For all these purposes, we designed EMTAC (Extensible Multi-tenancy Access Control) meta-model, +which defines policy specification, policy administration, inter-policy collaboration and administration +over this collaboration. +![](../img/policy_engine.png) + +###User-centric +At the same time, Moon enables administrators or a third-party application to define, configure and manage +its policies. Such a user-centric aspect helps users to define their own manner in using +OpenStack’s resources. + +###Authorization enforcement in OpenStack +As the first step, the security policy in Moon is enforced by authorization mechanism in Keystone and Nova +and Swift. +All the operations in Keystone and Nova and Swift are controlled and validated by Moon. +In OpenStack, we implemented 3 hooks respectively for Keystone and Nova and Swift, the hooks will +redirect all authorization requests to Moon and return decision from Moon. + +###Log System +Traceability and accountability are also handled in Moon, all the operations and interactions +are logged and can be consulted for any purpose. + +###Separation of management layer from OpenStack +The separation of management layer from OpenStack makes the management system totally +independent from OpenStack. We can install Moon in client’s local so that Moon can be +locally administrated by clients and remotely project their data which are hosted in +Cloud Service Provider’s datacenter. + +Scenario usage overview +======================= + +The Moon platform is built on the OpenStack Keystone component. While Keystone manages the identification +and the authentication process, Moon manages the authorisation process for all actions that comes through it. +The current version of Moon can only manage a subset of actions: actions from Nova and Swift. +For example, when a user wanted to stop a virtual machine with Nova, the authorisation for that action of stopping +is delegated through KeystoneMiddleware to the Moon platform. + +The MoonClient script helps administrators to configure the Moon platform and the authorisation rules. +It can be used like the OpenStack client with the same environment variables. + +Each OpenStack project (or tenant) car be mapped to an intra-extension. +That intra-extension will contain the configuration for the authorisation process for that tenant. +Each intra-extension is configured with subjects, objects and actions. A subject makes an action on an object. +Those elements can be placed into categories, for example a subject can have a value on the role category. +Those values are saved into the scope element. +For example, the subject (which is also called user) "admin" can have the role "admin" and "dev" on the project "admin". +The same mapping applies to the object and the action element. +For example, the action "stop a VM" can be place in a particular category "access" with the scope "write". +The action "stop a VM" is considered as the user has a write access to the VM. + +In order to grant or not an action in the system, Moon uses rules built with the scope values. +If we consider that a rule is constituted with a role for the subject category, +an ID and a security level for the object category and an access value for the action category, we can built rules +with values like the following ones: + +- admin, id1, level_high, write +- admin, id1, level_low, read +- dev, id2, level_high, read + +All configuration can be done with the MoonClient script. +If a project is not mapped to a intra-extension, it can be used as if the Moon platform doesn't exist. + +Limitations, Issues and Workarounds +=================================== + +The Moon platform can only be used to authorize Nova and Swift actions. In future releases, it could manage +more OpenStack components like Neutron, Glance, ... + +References +========== + +For more information on the OPNFV Colorado release, please visit +http://www.opnfv.org/colorado + +Revision: _sha1_ + +Build date: |today| diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst index 501a5ef5..aa568017 100644 --- a/docs/release/userguide/index.rst +++ b/docs/release/userguide/index.rst @@ -1,3 +1,5 @@ +.. _moon-userguide: + .. This work is licensed under a Creative Commons Attribution 4.0 International License. .. http://creativecommons.org/licenses/by/4.0 .. (c) ruan.he@orange.com & thomas.duval@orange.com diff --git a/docs/release/userguide/userguide.md b/docs/release/userguide/userguide.md deleted file mode 100644 index 6c65320c..00000000 --- a/docs/release/userguide/userguide.md +++ /dev/null @@ -1,114 +0,0 @@ -# Moon Version 4 - -This directory contains all the modules for MoonV4 - - -## Installation -### Prerequisite -```bash -sudo apt install python3-dev python3-pip -sudo pip3 install pip --upgrade -sudo apt -y install docker-engine # ([Get Docker](https://docs.docker.com/engine/installation/)) -echo 127.0.0.1 messenger db keystone interface manager | sudo tee -a /etc/hosts -``` - - -### Docker Engine Configuration -```bash -cat </dev/null -docker container rm -f messenger db keystone consul 2>/dev/null -``` - - -### Internal Network Creation -Create an internal Docker network called `moon` -```bash -docker network create -d bridge --subnet=172.88.88.0/16 --gateway=172.88.88.1 moon -``` - -### Install Moon_DB -Install the moon_db library -```bash -sudo pip3 install moon_db -``` - -## Starting containers manually - -### MySql -Run the standard `MySql` container in the `moon` network and configure it -```bash -docker container run -dti --net=moon --hostname db --name db -e MYSQL_ROOT_PASSWORD=p4sswOrd1 -e MYSQL_DATABASE=moon -e MYSQL_USER=moon -e MYSQL_PASSWORD=p4sswOrd1 -p 3306:3306 mysql:latest -moon_db_manager upgrade -``` - -### moon_keystone -Run the `keystone` container (created by the `Moon` project) in the `moon` network -```bash -docker container run -dti --net moon --hostname keystone --name keystone -e DB_HOST=db -e DB_PASSWORD_ROOT=p4sswOrd1 -p 35357:35357 -p 5000:5000 wukongsun/moon_keystone:ocata -``` - -### Consul -Run the standard `Consul` container in the `moon` network -```bash -docker run -d --net=moon --name=consul --hostname=consul -p 8500:8500 consul -``` - -### Moon platform - -```bash -docker container run -dti --net moon --hostname manager --name manager wukongsun/moon_manager:v4.1 -docker container run -dti --net moon --hostname interface --name interface wukongsun/moon_interface:v4.1 -``` - -## Starting containers automatically - -To start the `Moon` framework, you only have to run the `bootstrap` script -```bash -python3 bin/bootstrap.py -``` -The script will ask you to start one or more Moon containers - -### Tests -```bash -sudo pip3 install pytest -cd tests -pytest -``` - -### Run scenario -```bash -sudo pip3 install requests -cd tests -python3 populate_default_values.py -v scenario/rbac.py -python3 send_authz.py -v scenario/rbac.py -``` - - - -## Log -### Get some logs -```bash -docker container ps -docker logs db -docker logs messenger -docker logs keystone -docker logs router -docker logs manager -docker logs interface -``` diff --git a/docs/release/userguide/userguide.rst b/docs/release/userguide/userguide.rst new file mode 100644 index 00000000..dee626c8 --- /dev/null +++ b/docs/release/userguide/userguide.rst @@ -0,0 +1,124 @@ +Moon Version 4 +============== + +This directory contains all the modules for MoonV4 + +Installation +------------ + +Prerequisite +~~~~~~~~~~~~ + + sudo apt install python3-dev python3-pip + sudo pip3 install pip --upgrade + sudo apt -y install docker-engine # ([Get Docker](https://docs.docker.com/engine/installation/)) + echo 127.0.0.1 messenger db keystone interface manager | sudo tee -a /etc/hosts + +Docker Engine Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + cat </dev/null + docker container rm -f messenger db keystone consul 2>/dev/null + + +Internal Network Creation +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Create an internal Docker network called `moon` + + docker network create -d bridge --subnet=172.88.88.0/16 --gateway=172.88.88.1 moon + +Install Moon_DB +--------------- + +Install the moon_db library + + sudo pip3 install moon_db + +Starting containers manually +---------------------------- + +MySql +~~~~~ + +Run the standard `MySql` container in the `moon` network and configure it + + docker container run -dti --net=moon --hostname db --name db -e MYSQL_ROOT_PASSWORD=p4sswOrd1 -e MYSQL_DATABASE=moon -e MYSQL_USER=moon -e MYSQL_PASSWORD=p4sswOrd1 -p 3306:3306 mysql:latest + moon_db_manager upgrade + +moon_keystone +~~~~~~~~~~~~~ + +Run the `keystone` container (created by the `Moon` project) in the `moon` network + + docker container run -dti --net moon --hostname keystone --name keystone -e DB_HOST=db -e DB_PASSWORD_ROOT=p4sswOrd1 -p 35357:35357 -p 5000:5000 wukongsun/moon_keystone:ocata + +Consul +~~~~~~ + +Run the standard `Consul` container in the `moon` network + + docker run -d --net=moon --name=consul --hostname=consul -p 8500:8500 consul + +Moon platform +~~~~~~~~~~~~~ + + docker container run -dti --net moon --hostname manager --name manager wukongsun/moon_manager:v4.1 + docker container run -dti --net moon --hostname interface --name interface wukongsun/moon_interface:v4.1 + +Starting containers automatically +--------------------------------- + +To start the `Moon` framework, you only have to run the `bootstrap` script + + python3 bin/bootstrap.py + +The script will ask you to start one or more Moon containers + +Tests +~~~~~ + + sudo pip3 install pytest + cd tests + pytest + +Run scenario +~~~~~~~~~~~~ + + sudo pip3 install requests + cd tests + python3 populate_default_values.py -v scenario/rbac.py + python3 send_authz.py -v scenario/rbac.py + +Log +--- + +Get some logs +~~~~~~~~~~~~~ + + docker container ps + docker logs db + docker logs messenger + docker logs keystone + docker logs router + docker logs manager + docker logs interface -- cgit 1.2.3-korg