diff options
Diffstat (limited to 'docs/installationprocedure')
| -rw-r--r-- | docs/installationprocedure/index.rst | 19 | ||||
| -rw-r--r-- | docs/installationprocedure/multisite.configuration.rst | 110 | ||||
| -rw-r--r-- | docs/installationprocedure/multisite.kingbird.configuration.rst | 264 | ||||
| -rw-r--r-- | docs/installationprocedure/multisite.kingbird.installation.rst | 305 |
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. |