Installation procedure

Colorado 1.0

1. Multisite Kingbird installation instruction

1.1. Abstract

This document will give the user instructions on how to deploy available scenarios verified for the Colorado release of OPNFV platform.

1.2. 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.

1.3. HW requirements

No special hardware requirements

1.4. Installation instruction

In colorado release, Kingbird is recommended to be installed in a python virtual environment. So install and activate virtualenv first.

sudo pip install virtualenv
virtualenv venv
source venv/bin/activate

Get the latest code of Kingbird from git repository:

git clone https://github.com/openstack/kingbird.git
cd kingbird/
pip install -e .

or get the stable release from PyPI repository:

pip install kingbird

In case of the database package are not installed, you may need to install:

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:

oslo-config-generator --config-file=./tools/config-generator.conf

prepare the folder used for cache, log and configuration for Kingbird:

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:

cp etc/kingbird/kingbird.conf.sample /etc/kingbird/kingbird.conf

Before editing the configuration file, prepare the database info for Kingbird.

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”:

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:

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:

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:

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.

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:

[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.

[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:

[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

[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:

[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.

[DEFAULT]
rpc_backend = rabbit
control_exchange = openstack
transport_url = None

[oslo_messaging_rabbit]
rabbit_host = 127.0.0.1
rabbit_port = 5671
rabbit_userid = guest
rabbit_password = guest
rabbit_virtual_host = /

After these basic configuration items configured, now the database schema of “kingbird” should be created:

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:

openstack service create --name=kingbird synchronization
openstack endpoint create --region=RegionOne \
--publicurl=http://127.0.0.1:8118/v1.0 \
--adminurl=http://127.0.0.1:8118/v1.0 \
--internalurl=http://127.0.0.1:8118/v1.0 kingbird

Now it’s ready to run kingbird-api and kingbird-engine:

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:

ps aux|grep python

1.5. Post-installation activities

Run the following commands to check whether kingbird-api is serving, please replace $token to the token you get from “openstack token issue”:

openstack token issue
curl  -H "Content-Type: application/json"  -H "X-Auth-Token: $token" \
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 $token to the token you get from “openstack token issue”, and the $admin_project_id to the admin project id in your environment:

curl  -H "Content-Type: application/json"  -H "X-Auth-Token: $token" \
-H  "X_ROLE: admin"  -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.

2. Multisite configuration guide

2.1. Multisite identity service management

2.1.1. Goal

A user should, using a single authentication point be able to manage virtual resources spread over multiple OpenStack regions.

2.1.2. Before you read

This chapter does not intend to cover all configuration of KeyStone and other OpenStack services to work together with KeyStone.

This chapter focuses only on the configuration part should be taken into account in multi-site scenario.

Please read the configuration documentation related to identity management of OpenStack for all configuration items.

http://docs.openstack.org/liberty/config-reference/content/ch_configuring-openstack-identity.html

How to configure the database cluster for synchronization or asynchrounous repliation in multi-site scenario is out of scope of this document. The only remainder is that for the synchronization or replication, only Keystone database is required. If you are using MySQL, you can configure like this:

In the master:

binlog-do-db=keystone

In the slave:

replicate-do-db=keystone
2.1.3. Deployment options

For each detail description of each deployment option, please refer to the admin-user-guide.

  • Distributed KeyStone service with PKI token

    In KeyStone configuration file, PKI token format should be configured

    provider = pki

    or

    provider = pkiz

    In the [keystone_authtoken] section of each OpenStack service configuration file in each site, configure the identity_url and auth_uri to the address of KeyStone service

    identity_uri = https://keystone.your.com:35357/
auth_uri = http://keystone.your.com:5000/v2.0

    It’s better to use domain name for the KeyStone service, but not to use IP address directly, especially if you deployed KeyStone service in at least two sites for site level high availability.

  • Distributed KeyStone service with Fernet token

  • Distributed KeyStone service with Fernet token + Async replication ( star-mode).

    In these two deployment options, the token validation is planned to be done in local site.

    In KeyStone configuration file, Fernet token format should be configured

    provider = fernet

    In the [keystone_authtoken] section of each OpenStack service configuration file in each site, configure the identity_url and auth_uri to the address of local KeyStone service

    identity_uri = https://local-keystone.your.com:35357/
auth_uri = http://local-keystone.your.com:5000/v2.0

    and especially, configure the region_name to your local region name, for example, if you are configuring services in RegionOne, and there is local KeyStone service in RegionOne, then

    region_name = RegionOne

3. Configuration of Multisite.Kingbird

A brief introduction to configure Multisite Kingbird service. Only the configuration items for Kingbird will be described here. Logging, messaging, database, keystonemiddleware etc configuration which are generated from OpenStack OSLO libary, will not be described here, for these configuration items are common to Nova, Cinder, Neutron. So please refer to corresponding description from Nova or Cinder or Neutron.

3.1. Configuration in [DEFAULT]

3.1.1. configuration items for kingbird-api
3.1.1.1. bind_host
  • default value: bind_host = 0.0.0.0
  • description: The host IP to bind for kingbird-api service
3.1.1.2. bind_port
  • default value: bind_port = 8118
  • description: The port to bind for kingbird-api service
3.1.1.3. api_workers
  • default value: api_workers = 2
  • description: Number of kingbird-api workers
3.1.2. configuration items for kingbird-engine
3.1.2.1. host
  • default value: host = localhost
  • description: The host name kingbird-engine service is running on
3.1.2.2. workers
  • default value: workers = 1
  • description: Number of kingbird-engine workers
3.1.2.3. report_interval
  • default value: report_interval = 60
  • description: Seconds between running periodic reporting tasks to keep the engine alive in the DB. If the engine doesn’t report its aliveness to the DB more than two intervals, then the lock accquired by the engine will be removed by other engines.
3.1.3. common configuration items for kingbird-api and kingbird-engine
3.1.3.1. use_default_quota_class
  • default value: use_default_quota_class = true
  • description: Enables or disables use of default quota class with default quota, boolean value

3.2. Configuration in [kingbird_global_limit]

For quota limit, a negative value means unlimited.

3.2.1. configuration items for kingbird-api and kingbird-engine
3.2.1.1. quota_instances
  • default value: quota_instances = 10
  • description: Number of instances allowed per project, integer value.
3.2.1.2. quota_cores
  • default value: quota_cores = 20
  • description: Number of instance cores allowed per project, integer value.
3.2.1.3. quota_ram
  • default value: quota_ram = 512
  • description: Megabytes of instance RAM allowed per project, integer value.
3.2.1.4. quota_metadata_items
  • default value: quota_metadata_items = 128
  • description: Number of metadata items allowed per instance, integer value.
3.2.1.5. quota_key_pairs
  • default value: quota_key_pairs = 10
  • description: Number of key pairs per user, integer value.
3.2.1.6. quota_fixed_ips
  • default value: quota_fixed_ips = -1
  • description: Number of fixed IPs allowed per project, this should be at least the number of instances allowed, integer value.
3.2.1.7. quota_security_groups
  • default value: quota_security_groups = 10
  • description: Number of security groups per project, integer value.
3.2.1.8. quota_floating_ips
  • default value: quota_floating_ips = 10
  • description: Number of floating IPs allowed per project, integer value.
3.2.1.9. quota_network
  • default value: quota_network = 10
  • description: Number of networks allowed per project, integer value.
3.2.1.10. quota_subnet
  • default value: quota_subnet = 10
  • description: Number of subnets allowed per project, integer value.
3.2.1.11. quota_port
  • default value: quota_port = 50
  • description: Number of ports allowed per project, integer value.
3.2.1.12. quota_security_group
  • default value: quota_security_group = 10
  • description: Number of security groups allowed per project, integer value.
3.2.1.13. quota_security_group_rule
  • default value: quota_security_group_rule = 100
  • description: Number of security group rules allowed per project, integer value.
3.2.1.14. quota_router
  • default value: quota_router = 10
  • description: Number of routers allowed per project, integer value.
3.2.1.15. quota_floatingip
  • default value: quota_floatingip = 50
  • description: Number of floating IPs allowed per project, integer value.
3.2.1.16. quota_volumes
  • default value: quota_volumes = 10
  • description: Number of volumes allowed per project, integer value.
3.2.1.17. quota_snapshots
  • default value: quota_snapshots = 10
  • description: Number of snapshots allowed per project, integer value.
3.2.1.18. quota_gigabytes
  • default value: quota_gigabytes = 1000
  • description: Total amount of storage, in gigabytes, allowed for volumes and snapshots per project, integer value.
3.2.1.19. quota_backups
  • default value: quota_backups = 10
  • description: Number of volume backups allowed per project, integer value.
3.2.1.20. quota_backup_gigabytes
  • default value: quota_backup_gigabytes = 1000
  • description: Total amount of storage, in gigabytes, allowed for volume backups per project, integer value.

3.3. Configuration in [cache]

The [cache] section is used by kingbird engine to access the quota information for Nova, Cinder, Neutron in each region in order to reduce the KeyStone load while retrieving the endpoint information each time.

3.3.1. configuration items for kingbird-engine
3.3.1.1. auth_uri
3.3.1.2. admin_username
  • default value:
  • description: Username of admin account, for example, admin.
3.3.1.3. admin_password
  • default value:
  • description: Password for admin account, for example, password.
3.3.1.4. admin_tenant
  • default value:
  • description: Tenant name of admin account, for example, admin.
3.3.1.5. admin_user_domain_name
  • default value: admin_user_domain_name = Default
  • description: User domain name of admin account.
3.3.1.6. admin_project_domain_name
  • default value: admin_project_domain_name = Default
  • description: Project domain name of admin account.

3.4. Configuration in [scheduler]

The [scheduler] section is used by kingbird engine to periodically synchronize and rebalance the quota for each project.

3.4.1. configuration items for kingbird-engine
3.4.1.1. periodic_enable
  • default value: periodic_enable = True
  • description: Boolean value for enable/disable periodic tasks.
3.4.1.2. periodic_interval
  • default value: periodic_interval = 900
  • description: Periodic time interval for automatic quota sync job, unit is seconds.

3.5. Configuration in [batch]

The [batch] section is used by kingbird engine to periodicly synchronize and rebalance the quota for each project.

  • default value: batch_size = 3
  • description: Batch size number of projects will be synced at a time.

3.6. Configuration in [locks]

The [locks] section is used by kingbird engine to periodically synchronize and rebalance the quota for each project.

  • default value: lock_retry_times = 3
  • description: Number of times trying to grab a lock.
  • default value: lock_retry_interval =10
  • description: Number of seconds between lock retries.