Add kingbird installation, configuration and user guide

Kingbird is a sub-project in multisite, and will be released
as part of OPNFV Colorado release, add Kingbird installation
, configuration and user guide to the Multisite repository, and
in later patch includes them into OPNFV documentation.

Change-Id: I3f8f3528c495f6f10bfa790763cc7c69017d7bdb
Signed-off-by: joehuang <joehuang@huawei.com>

3 files changed, 210 insertions, 19 deletions

diff --git a/docs/userguide/index.rst b/docs/userguide/index.rst
index 3eeedcb..1429b33 100644
--- a/docs/userguide/index.rst
+++ b/docs/userguide/index.rst
@@ -10,3 +10,4 @@ Multisite Admin User Guide
    :maxdepth: 4
 
    multisite-admin-user-guide.rst
+   multisite.kingbird.user.guide.rst
diff --git a/docs/userguide/multisite-admin-user-guide.rst b/docs/userguide/multisite-admin-user-guide.rst
index a0e9b58..41f23c0 100644
--- a/docs/userguide/multisite-admin-user-guide.rst
+++ b/docs/userguide/multisite-admin-user-guide.rst
@@ -211,6 +211,7 @@ Cons:
   * Need to be aware of the chanllenge of key distribution and rotation
     for Fernet token.
 
+Note: PKI token will be deprecated soon, so Fernet token is encouraged.
 
 Multisite VNF Geo site disaster recovery
 ========================================
@@ -262,14 +263,10 @@ The disater recovery process will work like this:
   2) DR software boot VMs from bootable volumes from the remote Cinder in
      the backup site and attach the regarding data volumes.
 
-Note: It’s up to the DR policy and VNF character how to use the API. Some
-VNF may allow the standby of the VNF or member of the cluster to do
-quiece/unquiece to avoid interfering the service provided by the VNF. Some
-other VNF may afford short unavailable for DR purpose.
-
-This option provides application level consistency disaster recovery.
-This feature is WIP in OpenStack Mitaka release, and will be avaialle in next
-OPNFV release.
+Note: Quiesce/Unquiesce spec was approved in Mitaka, but code not get merged in
+time, https://blueprints.launchpad.net/nova/+spec/expose-quiesce-unquiesce-api
+The spec was rejected in Newton when it was reproposed:
+https://review.openstack.org/#/c/295595/. So this option will not work any more.
 
 Option2, Vitrual Machine Snapshot
 ---------------------------------
@@ -321,8 +318,7 @@ Cons:
   * "Standard" support in Openstack for Disaster Recovery currently fairly
     limited, though active work in this area.
 
-This feature is in discussion in OpenStack Mitaka release, and hopefully will
-be avaialle in next OPNFV release.
+Note: Volume replication v2.1 support project level replication.
 
 
 VNF high availability across VIM
@@ -373,21 +369,22 @@ plane. There are some interesting/hard requirements on the networking (L2/L3)
 between OpenStack instances, at lease the backup plane across different
 OpenStack instances:
 
-1) Overlay L2 networking or shared L2 provider networks as the backup plane
-   for heartbeat or state replication. Overlay L2 network is preferred, the
-   reason is:
+1) Overlay L2 networking is prefered as the backup plane for heartbeat or state
+   replication, the reason is:
 
    a) Support legacy compatibility: Some telecom app with built-in internal L2
    network, for easy to move these app to virtualized telecom application, it
    would be better to provide L2 network.
 
    b) Support IP overlapping: multiple telecom applications may have
-      overlapping IP address for cross OpenStack instance networking Therefore,
-      over L2 networking across Neutron feature is required in OpenStack.
+   overlapping IP address for cross OpenStack instance networking.
+   Therefore over L2 networking across Neutron feature is required
+   in OpenStack.
 
 2) L3 networking cross OpenStack instance for heartbeat or state replication.
-   For L3 networking, we can leverage the floating IP provided in current
-   Neutron, so no new feature requirement to OpenStack.
+   Can leverage FIP or vRouter inter-connected with overlay L2 network to
+   establish overlay L3 networking.
 
-Overlay L2 networking across OpenStack instances is in discussion with Neutron
-community.
+Note: L2 border gateway spec was merged in L2GW project:
+https://review.openstack.org/#/c/270786/. Code will be availabe in later
+release.
diff --git a/docs/userguide/multisite.kingbird.user.guide.rst b/docs/userguide/multisite.kingbird.user.guide.rst
new file mode 100644
index 0000000..6ae3881
--- /dev/null
+++ b/docs/userguide/multisite.kingbird.user.guide.rst
@@ -0,0 +1,193 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. (c) OPNFV
+
+=============================
+Multisite.Kingbird user guide
+=============================
+
+Quota management for OpenStack multi-region deployments
+-------------------------------------------------------
+Kingbird is centralized synchronization service for multi-region OpenStack
+deployments. In OPNFV Colorado release, Kingbird provides centralized quota
+management feature. Administrator can set quota per project based in Kingbird
+and sync the quota limit to multi-region OpenStack periodiclly or on-demand.
+The tenant can check the total quota limit and usage from Kingbird for all
+regions. Administrator can aslo manage the default quota by quota class
+setting.
+
+Following quota items are supported to be managed in Kingbird:
+
+- **instances**: Number of instances allowed per project.
+- **cores**: Number of instance cores allowed per project.
+- **ram**: Megabytes of instance RAM allowed per project.
+- **metadata_items**: Number of metadata items allowed per instance.
+- **key_pairs**: Number of key pairs per user.
+- **fixed_ips**: Number of fixed IPs allowed per project,
+  valid if Nova Network is used.
+- **security_groups**: Number of security groups per project,
+  valid if Nova Network is used.
+- **floating_ips**: Number of floating IPs allowed per project,
+  valid if Nova Network is used.
+- **network**: Number of networks allowed per project,
+  valid if Neutron is used.
+- **subnet**: Number of subnets allowed per project,
+  valid if Neutron is used.
+- **port**: Number of ports allowed per project,
+  valid if Neutron is used.
+- **security_group**: Number of security groups allowed per project,
+  valid if Neutron is used.
+- **security_group_rule**: Number of security group rules allowed per project,
+  valid if Neutron is used.
+- **router**: Number of routers allowed per project,
+  valid if Neutron is used.
+- **floatingip**: Number of floating IPs allowed per project,
+  valid if Neutron is used.
+- **volumes**: Number of volumes allowed per project.
+- **snapshots**: Number of snapshots allowed per project.
+- **gigabytes**: Total amount of storage, in gigabytes, allowed for volumes
+  and snapshots per project.
+- **backups**: Number of volume backups allowed per project.
+- **backup_gigabytes**: Total amount of storage, in gigabytes, allowed for volume
+  backups per project.
+
+Only restful APIs are provided for Kingbird in Colorado release, so curl or
+other http client can be used to call Kingbird API.
+
+Before use the following command, get token, project id, and kingbird service
+endpoint first. Use $kb_token to repesent the token, and $admin_tenant_id as
+administrator project_id, and $tenant_id as the target project_id for quota
+management and $kb_ip_addr for the kingbird service endpoint ip address.
+
+Note:
+To view all tenants (projects), run:
+
+.. code-block:: bash
+
+    openstack project list
+
+To get token, run:
+
+.. code-block:: bash
+
+    openstack token issue
+
+To get Kingbird service endpoint, run:
+
+.. code-block:: bash
+
+    openstack endpoint list
+
+Quota Management API
+--------------------
+
+1. Update global limit for a tenant
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "ROLE: dmin" \
+   -X PUT \
+   -d '{"quota_set":{"cores": 10,"ram": 51200, "metadata_items": 100,"key_pairs": 100, "network":20,"security_group": 20,"security_group_rule": 20}}' \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id
+
+2. Get global limit for a tenant
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "X_ROLE: admin" \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id
+
+3. A tenant can also get the global limit by himself
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   http://$kb_ip_addr:8118/v1.0/$tenant_id/os-quota-sets/$tenant_id
+
+4. Get defaults limits
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "X_ROLE: admin" \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/defaults
+
+5. Get total usage for a tenant
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "X_ROLE: admin" \
+   -X GET \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id/detail
+
+6. A tenant can also get the total usage by himself
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -X GET \
+   http://$kb_ip_addr:8118/v1.0/$tenant_id/os-quota-sets/$tenant_id/detail
+
+7. On demand quota sync
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "X_ROLE: admin" \
+   -X PUT \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id/sync
+
+
+8. Delete specific global limit for a tenant
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "X_ROLE: admin" \
+   -X DELETE \
+   -d '{"quota_set": [ "cores", "ram"]}' \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id
+
+9. Delete all kingbird global limit for a tenant
+
+  curl \
+  -H "Content-Type: application/json" \
+  -H "X-Auth-Token: $kb_token" \
+  -H  "X_ROLE: admin" \
+  -X DELETE \
+  http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id
+
+
+Quota Class API
+---------------
+
+1. Update default quota class
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "ROLE: dmin" \
+   -X PUT \
+   -d '{"quota_class_set":{"cores": 100, "network":50,"security_group": 50,"security_group_rule": 50}}' \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-class-sets/default
+
+2. Get default quota class
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "X_ROLE: admin" \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-class-sets/default
+
+3. Delete default quota class
+
+   curl \
+   -H "Content-Type: application/json" \
+   -H "X-Auth-Token: $kb_token" \
+   -H  "ROLE: dmin" \
+   -X DELETE \
+   http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-class-sets/default
+