From b6bdaab8fe5cd06252331a0c59fb4f3d90aaac99 Mon Sep 17 00:00:00 2001 From: RHE Date: Wed, 27 Sep 2017 15:31:49 +0200 Subject: Moon Euphrase documentation Change-Id: Ic92d95b10e14299813b1b1b963c3562f37eacc8b Signed-off-by: RHE --- docs/release/installation/index.rst | 20 ++++ docs/release/installation/installation.md | 160 +++++++++++++++++++++++++++ docs/release/release-notes/index.rst | 15 +++ docs/release/release-notes/release-notes.rst | 89 +++++++++++++++ docs/release/userguide/index.rst | 13 +++ docs/release/userguide/userguide.md | 114 +++++++++++++++++++ 6 files changed, 411 insertions(+) create mode 100644 docs/release/installation/index.rst create mode 100644 docs/release/installation/installation.md create mode 100644 docs/release/release-notes/index.rst create mode 100644 docs/release/release-notes/release-notes.rst create mode 100644 docs/release/userguide/index.rst create mode 100644 docs/release/userguide/userguide.md (limited to 'docs/release') diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst new file mode 100644 index 00000000..1311b248 --- /dev/null +++ b/docs/release/installation/index.rst @@ -0,0 +1,20 @@ +.. 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 new file mode 100644 index 00000000..70bcc4fc --- /dev/null +++ b/docs/release/installation/installation.md @@ -0,0 +1,160 @@ +# 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 new file mode 100644 index 00000000..83291051 --- /dev/null +++ b/docs/release/release-notes/index.rst @@ -0,0 +1,15 @@ +****************** +Moon Release Notes +****************** + +.. toctree:: + :numbered: + :maxdepth: 4 + + moon-release.rst + +Revision: _sha1_ + +:Author: Ruan He (ruan.he@orange.com) + +Build date: |today| \ No newline at end of file diff --git a/docs/release/release-notes/release-notes.rst b/docs/release/release-notes/release-notes.rst new file mode 100644 index 00000000..a14a6ed7 --- /dev/null +++ b/docs/release/release-notes/release-notes.rst @@ -0,0 +1,89 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Ruan HE (Orange) and Thomas Duval (Orange) + +Release Note for the Euphrates release of OPNFV when using Moon as a security management tool. + +Abstract +======== + +This document provides the release notes for Euphrates release of Moon project. + +Introduction +============ + +Moon is an OPNFV security management project which provides automated security management +toolset for OpenStack and other SDN controllers like OpenDaylight. +Please carefully follow the Installation Instructions to install and configure Moon. + +Release Data +============ + ++--------------------------------------+--------------------------------------+ +| **Project** | Moon | +| | | ++--------------------------------------+--------------------------------------+ +| **Repo/tag** | Moon/Euphrates.1.0 | +| | | ++--------------------------------------+--------------------------------------+ +| **Release designation** | Euphrates.1.0 | +| | | ++--------------------------------------+--------------------------------------+ +| **Release date** | September 2017 | +| | | ++--------------------------------------+--------------------------------------+ +| **Purpose of the delivery** | OPNFV Euphrates release | +| | | ++--------------------------------------+--------------------------------------+ + +Deliverables +------------ + +Software deliverables +~~~~~~~~~~~~~~~~~~~~~ + +Moon provides a security management framework for the OPNFV infrastructure. +It includes a set of software modules. + +The internal software modules are: + + - keystone-moon: https://git.opnfv.org/cgit/moon/tree/moonv4 + + - moonclient: https://git.opnfv.org/cgit/moon/tree/moonclient + + - tests: https://git.opnfv.org/cgit/moon/tree/tests + + +The OPNFV projects installs Moon is: + + * Compass4NFV + + +The OPNFV projects tests Moon are: + + * Functest + +Documentation deliverables +~~~~~~~~~~~~~~~~~~~~~~~~~~ + + - OPNFV(Euphrates) Moon installation instructions: http://artifacts.opnfv.org/moon/euphrates/docs/installationprocedure/index.html + + - OPNFV(Euphrates) Moon configuration guide: http://artifacts.opnfv.org/moon/euphrates/docs/configurationguide/index.html + + - OPNFV(Euphrates) Moon user guide: http://artifacts.opnfv.org/moon/euphrates/docs/userguide/index.html + +Version change +-------------- +.. This section describes the changes made since the last version of this document. + +Feature evolution +~~~~~~~~~~~~~~~~~ + +This is the second tracked release of Moon + +References +========== + +For more information on the Moon Colorado release, please see: + +https://wiki.opnfv.org/display/moon/ \ No newline at end of file diff --git a/docs/release/userguide/index.rst b/docs/release/userguide/index.rst new file mode 100644 index 00000000..501a5ef5 --- /dev/null +++ b/docs/release/userguide/index.rst @@ -0,0 +1,13 @@ +.. 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 + +********************* +OPNFV MOON user guide +********************* + +.. toctree:: + :numbered: + :maxdepth: 2 + + feature.usage.rst diff --git a/docs/release/userguide/userguide.md b/docs/release/userguide/userguide.md new file mode 100644 index 00000000..6c65320c --- /dev/null +++ b/docs/release/userguide/userguide.md @@ -0,0 +1,114 @@ +# 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 +``` -- cgit 1.2.3-korg