From 955c5a79336ce2d595c65239366de6a35fdb8fac Mon Sep 17 00:00:00 2001 From: joehuang Date: Wed, 15 Feb 2017 20:12:11 -0500 Subject: [PATCH] Update installation guide and usage guide Currently the oslo.messaging has update its configuration to use transport_url for message bus configuration, and openstack endpoint creation aslo has new strutucture, need to update the installation guide to make it work in new release. python-kingbirdclient was introduced, 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: I725da3a8dbb83109130473d9bc86381303d2c174 Signed-off-by: joehuang --- doc/source/installation.rst | 21 +-- doc/source/usage.rst | 310 +++++++++++++++++++++++++++--------- 2 files changed, 241 insertions(+), 90 deletions(-) diff --git a/doc/source/installation.rst b/doc/source/installation.rst index da47ef9..449b4ee 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -132,6 +132,9 @@ 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 @@ -219,16 +222,7 @@ 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 = / + 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: @@ -243,10 +237,9 @@ 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 + 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: diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 339249c..2bedc80 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,5 +1,5 @@ =================== -Kingbird User Guide +Kingbird user guide =================== Quota management for OpenStack multi-region deployments @@ -47,6 +47,8 @@ Following quota items are supported to be managed in Kingbird: - **backup_gigabytes**: Total amount of storage, in gigabytes, allowed for volume backups per project. +Key pair is the only resource type supported in resource synchronization. + Only restful APIs are provided for Kingbird in Colorado release, so curl or other http client can be used to call Kingbird API. @@ -58,103 +60,180 @@ management and $kb_ip_addr for the kingbird service endpoint ip address. Note: To view all tenants (projects), run: -.. code-block:: bash + .. code-block:: bash - openstack project list + openstack project list To get token, run: -.. code-block:: bash + .. code-block:: bash - openstack token issue + openstack token issue To get Kingbird service endpoint, run: -.. code-block:: bash + .. code-block:: bash - openstack endpoint list + 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota update $tenant_id --port 10 --security_groups 10 + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota show --tenant $tenant_id + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota show + + Use curl: + + .. code-block:: bash + + 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota defaults + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota detail --tenant $tenant_id + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota detail + + Use curl: + + .. code-block:: bash + + 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota sync $tenant_id + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -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 + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota delete $tenant_id + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -X DELETE \ + http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-sets/$tenant_id Quota Class API @@ -162,27 +241,106 @@ 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota-class update --port 10 --security_groups 10 + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota-class show default + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + 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 + Use python-kingbirdclient: + + .. code-block:: bash + + kingbird quota-class delete default + + Use curl: + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -X DELETE \ + http://$kb_ip_addr:8118/v1.0/$admin_tenant_id/os-quota-class-sets/default + + +Resource Synchronization API +----------------------------- + +1. Create synchronization job + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -X POST -d \ + '{"resource_set":{"resources": [""],"force":,"resource_type": "keypair","source": <"Source_Region">,"target": [<"List_of_target_regions">]}}' \ + http://$kb_ip_addr:8118/v1.0/$tenant_id/os-sync + +2. Get synchronization job + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + http://$kb_ip_addr:8118/v1.0/$tenant_id/os-sync/ + +3. Get active synchronization job + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + http://$kb_ip_addr:8118/v1.0/$tenant_id/os-sync/active + +4. Get detail information of a synchronization job + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + http://$kb_ip_addr:8118/v1.0/$tenant_id/os-sync/$job_id + +5. Delete a synchronization job + + .. code-block:: bash + + curl \ + -H "Content-Type: application/json" \ + -H "X-Auth-Token: $kb_token" \ + -X DELETE \ + http://$kb_ip_addr:8118/v1.0/$tenant_id/os-sync/$job_id