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 <joehuang@huawei.com>

4 files changed, 0 insertions, 698 deletions

diff --git a/docs/installationprocedure/index.rst b/docs/installationprocedure/index.rst
deleted file mode 100644
index 746f819..0000000
--- a/docs/installationprocedure/index.rst
+++ /dev/null
@@ -1,19 +0,0 @@
-.. 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
-
-**********************
-Installation procedure
-**********************
-Colorado 1.0
-------------
-
-.. toctree::
-   :numbered:
-   :maxdepth: 2
-
-   abstract.rst
-   multisite.kingbird.installation.rst
-   multisite.configuration.rst
-   multisite.kingbird.configuration.rst
-
diff --git a/docs/installationprocedure/multisite.configuration.rst b/docs/installationprocedure/multisite.configuration.rst
deleted file mode 100644
index c005e8d..0000000
--- a/docs/installationprocedure/multisite.configuration.rst
+++ /dev/null
@@ -1,110 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-=============================
-Multisite configuration guide
-=============================
-
-Multisite identity service management
-=====================================
-
-Goal
-----
-
-A user should, using a single authentication point be able to manage virtual
-resources spread over multiple OpenStack regions.
-
-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:
-
-   .. code-block:: bash
-
-      binlog-do-db=keystone
-
-In the slave:
-
-   .. code-block:: bash
-
-      replicate-do-db=keystone
-
-
-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
-
-   .. code-block:: bash
-
-      provider = pki
-
-   or
-
-   .. code-block:: bash
-
-      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
-
-   .. code-block:: bash
-
-      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
-
-   .. code-block:: bash
-
-      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
-
-   .. code-block:: bash
-
-      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
-
-   .. code-block:: bash
-
-      region_name = RegionOne
diff --git a/docs/installationprocedure/multisite.kingbird.configuration.rst b/docs/installationprocedure/multisite.kingbird.configuration.rst
deleted file mode 100644
index 7eb6106..0000000
--- a/docs/installationprocedure/multisite.kingbird.configuration.rst
+++ /dev/null
@@ -1,264 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-
-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.
-
-
-Configuration in [DEFAULT]
---------------------------
-
-configuration items for kingbird-api
-""""""""""""""""""""""""""""""""""""
-
-bind_host
-*********
-- default value: *bind_host = 0.0.0.0*
-- description: The host IP to bind for kingbird-api service
-
-bind_port
-*********
-- default value: *bind_port = 8118*
-- description: The port to bind for kingbird-api service
-
-api_workers
-***********
-- default value: *api_workers = 2*
-- description: Number of kingbird-api workers
-
-configuration items for kingbird-engine
-"""""""""""""""""""""""""""""""""""""""
-
-host
-****
-- default value: *host = localhost*
-- description: The host name kingbird-engine service is running on
-
-workers
-*******
-- default value: *workers = 1*
-- description: Number of kingbird-engine workers
-
-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.
-
-common configuration items for kingbird-api and kingbird-engine
-"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-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
-
-Configuration in [kingbird_global_limit]
-----------------------------------------
-
-For quota limit, a negative value means unlimited.
-
-configuration items for kingbird-api and kingbird-engine
-""""""""""""""""""""""""""""""""""""""""""""""""""""""""
-
-quota_instances
-***************
-- default value: *quota_instances = 10*
-- description: Number of instances allowed per project, integer value.
-
-quota_cores
-***********
-- default value: *quota_cores = 20*
-- description: Number of instance cores allowed per project, integer value.
-
-quota_ram
-*********
-- default value: *quota_ram = 512*
-- description: Megabytes of instance RAM allowed per project, integer value.
-
-quota_metadata_items
-********************
-- default value: *quota_metadata_items = 128*
-- description: Number of metadata items allowed per instance, integer value.
-
-quota_key_pairs
-***************
-- default value: *quota_key_pairs = 10*
-- description: Number of key pairs per user, integer value.
-
-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.
-
-quota_security_groups
-*********************
-- default value: *quota_security_groups = 10*
-- description: Number of security groups per project, integer value.
-
-quota_floating_ips
-******************
-- default value: *quota_floating_ips = 10*
-- description: Number of floating IPs allowed per project, integer value.
-
-quota_network
-***************
-- default value: *quota_network = 10*
-- description: Number of networks allowed per project, integer value.
-
-quota_subnet
-***************
-- default value: *quota_subnet = 10*
-- description: Number of subnets allowed per project, integer value.
-
-quota_port
-***************
-- default value: *quota_port = 50*
-- description: Number of ports allowed per project, integer value.
-
-quota_security_group
-********************
-- default value: *quota_security_group = 10*
-- description: Number of security groups allowed per project, integer value.
-
-quota_security_group_rule
-*************************
-- default value: *quota_security_group_rule = 100*
-- description: Number of security group rules allowed per project, integer
-  value.
-
-quota_router
-************
-- default value: *quota_router = 10*
-- description: Number of routers allowed per project, integer value.
-
-quota_floatingip
-****************
-- default value: *quota_floatingip = 50*
-- description: Number of floating IPs allowed per project, integer value.
-
-quota_volumes
-***************
-- default value: *quota_volumes = 10*
-- description: Number of volumes allowed per project, integer value.
-
-quota_snapshots
-***************
-- default value: *quota_snapshots = 10*
-- description: Number of snapshots allowed per project, integer value.
-
-quota_gigabytes
-***************
-- default value: *quota_gigabytes = 1000*
-- description: Total amount of storage, in gigabytes, allowed for volumes
-  and snapshots per project, integer value.
-
-quota_backups
-*************
-- default value: *quota_backups = 10*
-- description: Number of volume backups allowed per project, integer value.
-
-quota_backup_gigabytes
-**********************
-- default value: *quota_backup_gigabytes = 1000*
-- description: Total amount of storage, in gigabytes, allowed for volume
-  backups per project, integer value.
-
-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.
-
-configuration items for kingbird-engine
-"""""""""""""""""""""""""""""""""""""""
-
-auth_uri
-***************
-- default value:
-- description: Keystone authorization url, for example, http://127.0.0.1:5000/v3.
-
-admin_username
-**************
-- default value:
-- description: Username of admin account, for example, admin.
-
-admin_password
-**************
-- default value:
-- description: Password for admin account, for example, password.
-
-admin_tenant
-************
-- default value:
-- description: Tenant name of admin account, for example, admin.
-
-admin_user_domain_name
-**********************
-- default value: *admin_user_domain_name = Default*
-- description: User domain name of admin account.
-
-admin_project_domain_name
-*************************
-- default value: *admin_project_domain_name = Default*
-- description: Project domain name of admin account.
-
-Configuration in [scheduler]
-----------------------------------------
-
-The [scheduler] section is used by kingbird engine to periodically synchronize
-and rebalance the quota for each project.
-
-configuration items for kingbird-engine
-"""""""""""""""""""""""""""""""""""""""
-
-periodic_enable
-***************
-- default value: *periodic_enable = True*
-- description: Boolean value for enable/disable periodic tasks.
-
-periodic_interval
-*****************
-- default value: *periodic_interval = 900*
-- description: Periodic time interval for automatic quota sync job, unit is
-  seconds.
-
-Configuration in [batch]
-----------------------------------------
-
-The [batch] section is used by kingbird engine to periodicly synchronize
-and rebalance the quota for each project.
-
-batch_size
-***************
-- default value: *batch_size = 3*
-- description: Batch size number of projects will be synced at a time.
-
-Configuration in [locks]
-----------------------------------------
-
-The [locks] section is used by kingbird engine to periodically synchronize
-and rebalance the quota for each project.
-
-lock_retry_times
-****************
-- default value: *lock_retry_times = 3*
-- description: Number of times trying to grab a lock.
-
-lock_retry_interval
-*******************
-- default value: *lock_retry_interval =10*
-- description: Number of seconds between lock retries.
diff --git a/docs/installationprocedure/multisite.kingbird.installation.rst b/docs/installationprocedure/multisite.kingbird.installation.rst
deleted file mode 100644
index 9abb669..0000000
--- a/docs/installationprocedure/multisite.kingbird.installation.rst
+++ /dev/null
@@ -1,305 +0,0 @@
-.. This work is licensed under a Creative Commons Attribution 4.0 International License.
-.. http://creativecommons.org/licenses/by/4.0
-
-===========================================
-Multisite 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.
-
-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]
-    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:
-
-.. 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 \
-    --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:
-
-.. 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 $token 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: $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:
-
-.. code-block:: bash
-
-    curl  -H "Content-Type: application/json"  -H "X-Auth-Token: $token" \
-    -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.