From 7dbbb63739db4aac973fb6d5f3f16b5e9206ce14 Mon Sep 17 00:00:00 2001 From: joehuang Date: Tue, 7 Feb 2017 04:17:31 -0500 Subject: Update the multisite documentations to reflect the progress in D As some changes in OpenStack projects like KeyStone PKI token deprecation, L2GW moved away from Neutron stadium, Tricircle shrinked scope and became OpenStack big-tent project, and Kingbird has made great progress in feature development after the initial requirements discussion. Documents need to update to reflect these recent changes. python-kingbirdclient was introduced recently, so the usage guide is updated to use python-kingbirdclient. The new feature key pair synchronization is also included in the usage guide. Change-Id: Iad9fbd441d191defa5e8793633a626ab5a24f217 Signed-off-by: joehuang --- docs/release/installation/index.rst | 15 ++ .../multisite.kingbird.installation.rst | 298 +++++++++++++++++++++ 2 files changed, 313 insertions(+) create mode 100644 docs/release/installation/index.rst create mode 100644 docs/release/installation/multisite.kingbird.installation.rst (limited to 'docs/release/installation') diff --git a/docs/release/installation/index.rst b/docs/release/installation/index.rst new file mode 100644 index 0000000..0687f6c --- /dev/null +++ b/docs/release/installation/index.rst @@ -0,0 +1,15 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. (c) Sofia Wallin Ericsson AB +.. (c) Chaoyi Huang, Huawei Technologies Co., Ltd. + +******************************** +Multisite Installation procedure +******************************** + +.. toctree:: + :numbered: + :maxdepth: 2 + + abstract.rst + multisite.kingbird.installation.rst diff --git a/docs/release/installation/multisite.kingbird.installation.rst b/docs/release/installation/multisite.kingbird.installation.rst new file mode 100644 index 0000000..54b622d --- /dev/null +++ b/docs/release/installation/multisite.kingbird.installation.rst @@ -0,0 +1,298 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 + +================================= +Kingbird installation instruction +================================= + +Abstract +-------- +This document will give the user instructions on how to deploy +available scenarios verified for the Colorado release of OPNFV +platform. + + +Preparing the installation +-------------------------- +Kingbird is centralized synchronization service for multi-region OpenStack +deployments. In OPNFV Colorado release, Kingbird provides centralized quota +management feature. At least two OpenStack regions with shared KeyStone should +be installed first. + +Kingbird includes kingbird-api and kingbird-engine, kingbird-api and +kingbird-engine which talk to each other through message bus, and both +services access the database. Kingbird-api receives the RESTful +API request for quota management and forward the request to kingbird-engine +to do quota synchronization etc task. + +Therefore install Kingbird on the controller nodes of one of the OpenStack +region, these two services could be deployed in same node or different node. +Both kingbird-api and kingbird-engine can run in multiple nodes with +multi-workers mode. It's up to you how many nodes you want to deploy +kingbird-api and kingbird-engine and they can work in same node or +different nodes. + +HW requirements +--------------- +No special hardware requirements + +Installation instruction +------------------------ + +In colorado release, Kingbird is recommended to be installed in a python +virtual environment. So install and activate virtualenv first. + +.. code-block:: bash + + sudo pip install virtualenv + virtualenv venv + source venv/bin/activate + +Get the latest code of Kingbird from git repository: + +.. code-block:: bash + + git clone https://github.com/openstack/kingbird.git + cd kingbird/ + pip install -e . + + +or get the stable release from PyPI repository: + +.. code-block:: bash + + pip install kingbird + +In case of the database package are not installed, you may need to install: + +.. code-block:: bash + + pip install mysql + pip install pymysql + +In the Kingbird root folder, where you can find the source code of Kingbird, +generate the configuration sample file for Kingbird: + +.. code-block:: bash + + oslo-config-generator --config-file=./tools/config-generator.conf + +prepare the folder used for cache, log and configuration for Kingbird: + +.. code-block:: bash + + sudo rm -rf /var/cache/kingbird + sudo mkdir -p /var/cache/kingbird + sudo chown `whoami` /var/cache/kingbird + sudo rm -rf /var/log/kingbird + sudo mkdir -p /var/log/kingbird + sudo chown `whoami` /var/log/kingbird + sudo rm -rf /etc/kingbird + sudo mkdir -p /etc/kingbird + sudo chown `whoami` /etc/kingbird + +Copy the sample configuration to the configuration folder /etc/kingbird: + +.. code-block:: bash + + cp etc/kingbird/kingbird.conf.sample /etc/kingbird/kingbird.conf + +Before editing the configuration file, prepare the database info for Kingbird. + +.. code-block:: bash + + mysql -uroot -e "CREATE DATABASE $kb_db CHARACTER SET utf8;" + mysql -uroot -e "GRANT ALL PRIVILEGES ON $kb_db.* TO '$kb_db_user'@'%' IDENTIFIED BY '$kb_db_pwd';" + +For example, the following command will create database "kingbird", and grant the +privilege for the db user "kingbird" with password "password": + +.. code-block:: bash + + mysql -uroot -e "CREATE DATABASE kingbird CHARACTER SET utf8;" + mysql -uroot -e "GRANT ALL PRIVILEGES ON kingbird.* TO 'kingbird'@'%' IDENTIFIED BY 'password';" + +Create the service user in OpenStack: + +.. code-block:: bash + + source openrc admin admin + openstack user create --project=service --password=$kb_svc_pwd $kb_svc_user + openstack role add --user=$kb_svc_user --project=service admin + +For example, the following command will create service user "kingbird", +and grant the user "kingbird" with password "password" the role of admin +in service project: + +.. code-block:: bash + + source openrc admin admin + openstack user create --project=service --password=password kingbird + openstack role add --user=kingbird --project=service admin + + + +Then edit the configuration file for Kingbird: + +.. code-block:: bash + + vim /etc/kingbird/kingbird.conf + +By default, the bind_host of kingbird-api is local_host(127.0.0.1), and the +port for the service is 8118, you can leave it as the default if no port +conflict happened. + +Please replace the address of Kingbird service "127.0.0.1" which is mentioned +below to the address you get from OpenStack Kingbird endpoint. + +To make the Kingbird work normally, you have to edit these configuration +items. The [cache] section is used by kingbird engine to access the quota +information of Nova, Cinder, Neutron in each region, replace the +auth_uri to the keystone service in your environment, +especially if the keystone service is not located in the same node, and +also for the account to access the Nova, Cinder, Neutron in each region, +in the following configuration, user "admin" with password "password" of +the tenant "admin" is configured to access other Nova, Cinder, Neutron in +each region: + +.. code-block:: bash + + [cache] + auth_uri = http://127.0.0.1:5000/v3 + admin_tenant = admin + admin_password = password + admin_username = admin + +Configure the database section with the service user "kingbird" and its +password, to access database "kingbird". For detailed database section +configuration, please refer to http://docs.openstack.org/developer/oslo.db/opts.html, +and change the following configuration accordingly based on your +environment. + +.. code-block:: bash + + [database] + connection = mysql+pymysql://$kb_db_user:$kb_db_pwd@127.0.0.1/$kb_db?charset=utf8 + +For example, if the database is "kingbird", and the db user "kingbird" with +password "password", then the configuration is as following: + +.. code-block:: bash + + [database] + connection = mysql+pymysql://kingbird:password@127.0.0.1/kingbird?charset=utf8 + +The [keystone_authtoken] section is used by keystonemiddleware for token +validation during the API request to the kingbird-api, please refer to +http://docs.openstack.org/developer/keystonemiddleware/middlewarearchitecture.html +on how to configure the keystone_authtoken section for the keystonemiddleware +in detail, and change the following configuration accordingly based on your +environment: + +*please specify the region_name where you want the token will be validated if the +KeyStone is deployed in multiple regions* + +.. code-block:: bash + + [keystone_authtoken] + signing_dir = /var/cache/kingbird + cafile = /opt/stack/data/ca-bundle.pem + auth_uri = http://127.0.0.1:5000/v3 + project_domain_name = Default + project_name = service + user_domain_name = Default + password = $kb_svc_pwd + username = $kb_svc_user + auth_url = http://127.0.0.1:35357/v3 + auth_type = password + region_name = RegionOne + +For example, if the service user is "kingbird, and the password for the user +is "password", then the configuration will look like this: + +.. code-block:: bash + + [keystone_authtoken] + signing_dir = /var/cache/kingbird + cafile = /opt/stack/data/ca-bundle.pem + auth_uri = http://127.0.0.1:5000/v3 + project_domain_name = Default + project_name = service + user_domain_name = Default + password = password + username = kingbird + auth_url = http://127.0.0.1:35357/v3 + auth_type = password + region_name = RegionOne + + +And also configure the message bus connection, you can refer to the message +bus configuration in Nova, Cinder, Neutron configuration file. + +.. code-block:: bash + + [DEFAULT] + transport_url = rabbit://stackrabbit:password@127.0.0.1:5672/ + +After these basic configuration items configured, now the database schema of +"kingbird" should be created: + +.. code-block:: bash + + python kingbird/cmd/manage.py --config-file=/etc/kingbird/kingbird.conf db_sync + +And create the service and endpoint for Kingbird, please change the endpoint url +according to your cloud planning: + +.. code-block:: bash + + openstack service create --name=kingbird synchronization + openstack endpoint create --region=RegionOne kingbird public http://127.0.0.1:8118/v1.0 + openstack endpoint create --region=RegionOne kingbird admin http://127.0.0.1:8118/v1.0 + openstack endpoint create --region=RegionOne kingbird internal http://127.0.0.1:8118/v1.0 + +Now it's ready to run kingbird-api and kingbird-engine: + +.. code-block:: bash + + nohup python kingbird/cmd/api.py --config-file=/etc/kingbird/kingbird.conf & + nohup python kingbird/cmd/engine.py --config-file=/etc/kingbird/kingbird.conf & + +Run the following command to check whether kingbird-api and kingbird-engine +are running: + +.. code-block:: bash + + ps aux|grep python + + +Post-installation activities +---------------------------- + +Run the following commands to check whether kingbird-api is serving, please +replace $mytoken to the token you get from "openstack token issue": + +.. code-block:: bash + + openstack token issue + curl -H "Content-Type: application/json" -H "X-Auth-Token: $mytoken" \ + http://127.0.0.1:8118/ + +If the response looks like following: {"versions": [{"status": "CURRENT", +"updated": "2016-03-07", "id": "v1.0", "links": [{"href": +"http://127.0.0.1:8118/v1.0/", "rel": "self"}]}]}, +then that means the kingbird-api is working normally. + +Run the following commands to check whether kingbird-engine is serving, please +replace $mytoken to the token you get from "openstack token issue", and the +$admin_project_id to the admin project id in your environment: + +.. code-block:: bash + + curl -H "Content-Type: application/json" -H "X-Auth-Token: $mytoken" \ + -X PUT \ + http://127.0.0.1:8118/v1.0/$admin_project_id/os-quota-sets/$admin_project_id/sync + +If the response looks like following: "triggered quota sync for +0320065092b14f388af54c5bd18ab5da", then that means the kingbird-engine +is working normally. -- cgit 1.2.3-korg