.. 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 Danube release of OPNFV platform. Preparing the installation -------------------------- Kingbird is centralized synchronization service for multi-region OpenStack deployments. 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.