=================== Manual Installation =================== The Tricircle works with Neutron to provide networking automation functionality across Neutron in multi-region OpenStack deployment. In this guide we discuss how to manually install the Tricircle with local and central Neutron server. Local Neutron server, running with the Tricircle local plugin, is responsible for triggering cross-Neutron networking automation. Every OpenStack instance has one local Neutron service, registered in the same region with other core services like Nova, Cinder, Glance, etc. Central Neutron server, running with the Tricircle central plugin, is responsible for unified resource allocation and cross-Neutron networking building. Besides regions for each OpenStack instance, we also need one specific region for central Neutron service. Only the Tricircle administrator service needs to be registered in this region along with central Neutron service while other core services are not mandatory. Installation with Central Neutron Server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 1 Install the Tricircle package:: git clone https://github.com/openstack/tricircle.git cd tricircle pip install -e . - 2 Register the Tricircle administrator API to Keystone:: openstack user create tricircle --password password openstack role add --project service --user tricircle service openstack service create tricircle --name tricircle --description "Cross Neutron Networking Automation Service" service_id=$(openstack service show tricircle -f value -c id) service_host=162.3.124.201 service_port=19999 service_region=CentralRegion service_url=http://$service_host:$service_port/v1.0 openstack endpoint create $service_id public $service_url --region $service_region openstack endpoint create $service_id admin $service_url --region $service_region openstack endpoint create $service_id internal $service_url --region $service_region change password, service_host, service_port and service_region in the above commands to adapt your deployment. OpenStack CLI tool will automatically find the endpoints to send to registration requests. If you would like to specify the region for endpoints, use:: openstack --os-region-name - 3 Generate the Tricircle configuration sample:: cd tricircle oslo-config-generator --config-file=etc/api-cfg-gen.conf oslo-config-generator --config-file=etc/xjob-cfg-gen.conf The generated sample files are located in tricircle/etc - 4 Configure the Tricircle administrator API:: cd tricircle/etc cp api.conf.sample api.conf Edit etc/api.conf, for detail configuration information, please refer to the configuration guide. Below only options necessary to be changed are listed. .. csv-table:: :header: "Option", "Description", "Example" [DEFAULT] tricircle_db_connection, "database connection string for tricircle", mysql+pymysql://root:password@ 127.0.0.1/tricircle?charset=utf8 [DEFAULT] transport_url, "a URL representing the used messaging driver and its full configuration", rabbit://user:password@ 127.0.0.1:5672 [keystone_authtoken] auth_type, "authentication method", password [keystone_authtoken] auth_url, "keystone authorization url", http://$keystone_service_host/identity [keystone_authtoken] username, "username of service account, needed for password authentication", tricircle [keystone_authtoken] password, "password of service account, needed for password authentication", password [keystone_authtoken] user_domain_name, "user domain name of service account, needed for password authentication", Default [keystone_authtoken] project_name, "project name of service account, needed for password authentication", service [keystone_authtoken] project_domain_name, "project domain name of service account, needed for password authentication", Default [keystone_authtoken] www_authenticate_uri, "complete public Identity API endpoint", http://$keystone_service_host/identity [keystone_authtoken] cafile, "A PEM encoded Certificate Authority to use when verifying HTTPs", /opt/stack/data/ca-bundle.pem [keystone_authtoken] signing_dir, "Directory used to cache files related to PKI tokens", /var/cache/tricircle [keystone_authtoken] memcached_servers, "Optionally specify a list of memcached server(s) to use for caching", $keystone_service_host:11211 [client] auth_url, "keystone authorization url", http://$keystone_service_host/identity [client] identity_url, "keystone service url", http://$keystone_service_host/identity/v3 [client] auto_refresh_endpoint, "if set to True, endpoint will be automatically refreshed if timeout accessing", True [client] top_region_name, "name of central region which client needs to access", CentralRegion [client] admin_username, "username of admin account", admin [client] admin_password, "password of admin account", password [client] admin_tenant, "project name of admin account", demo [client] admin_user_domain_name, "user domain name of admin account", Default [client] admin_tenant_domain_name, "project name of admin account", Default .. note:: The Tricircle utilizes the Oslo library to setup service, database, log and RPC, please refer to the configuration guide of the corresponding Oslo library if you need further configuration of these modules. Change keystone_service_host to the address of Keystone service. .. note:: It's worth explaining the following options that can easily make users confused. **keystone_authtoken.auth_url** is the keystone endpoint url used by services to validate user tokens. **keystone_authtoken.www_authenticate_uri** will be put in the "WWW-Authenticate: Keystone uri=%s" header in the 401 response to tell users where they can get authentication. These two URLs can be the same, but sometimes people would like to use an internal URL for auth_url and a public URL for www_authenticate_uri. **client.auth_url** is used by the common.client module to construct a client to get authentication and access other services, it can be the either internal or public endpoint of keystone, depends on how the module can reach keystone. **client.identity_url** is no longer used in code since Pike release so you can simply ignore it, we will deprecate and remove this option later. - 5 Create the Tricircle database(take mysql as an example):: mysql -uroot -p -e "create database tricircle character set utf8;" cd tricircle tricircle-db-manage --config-file etc/api.conf db_sync - 6 Start the Tricircle administrator API:: sudo mkdir /var/cache/tricircle sudo chown $(whoami) /var/cache/tricircle/ cd tricircle tricircle-api --config-file etc/api.conf - 7 Configure the Tricircle Xjob daemon:: cd tricircle/etc cp xjob.conf.sample xjob.conf Edit etc/xjob.conf, for detail configuration information, please refer to the configuration guide. Below only options necessary to be changed are listed. .. csv-table:: :header: "Option", "Description", "Example" [DEFAULT] tricircle_db_connection, "database connection string for tricircle", mysql+pymysql://root:password@ 127.0.0.1/tricircle?charset=utf8 [DEFAULT] transport_url, "a URL representing the used messaging driver and its full configuration", rabbit://user:password@ 127.0.0.1:5672 [client] auth_url, "keystone authorization url", http://$keystone_service_host/identity [client] identity_url, "keystone service url", http://$keystone_service_host/identity/v3 [client] auto_refresh_endpoint, "if set to True, endpoint will be automatically refreshed if timeout accessing", True [client] top_region_name, "name of central region which client needs to access", CentralRegion [client] admin_username, "username of admin account", admin [client] admin_password, "password of admin account", password [client] admin_tenant, "project name of admin account", demo [client] admin_user_domain_name, "user domain name of admin account", Default [client] admin_tenant_domain_name, "project name of admin account", Default .. note:: The Tricircle utilizes the Oslo library to setup service, database, log and RPC, please refer to the configuration guide of the corresponding Oslo library if you need further configuration of these modules. Change keystone_service_host to the address of Keystone service. - 8 Start the Tricircle Xjob daemon:: cd tricircle tricircle-xjob --config-file etc/xjob.conf - 9 Setup central Neutron server In this guide we assume readers are familiar with how to install Neutron server, so we just briefly discuss the steps and extra configuration needed by central Neutron server. For detail information about the configuration options in "client" and "tricircle" groups, please refer to the configuration guide. Neutron server can be installed alone, or you can install a full OpenStack instance then remove or stop other services. - install Neutron package - configure central Neutron server edit neutron.conf .. csv-table:: :header: "Option", "Description", "Example" [database] connection, "database connection string for central Neutron server", mysql+pymysql://root:password@ 127.0.0.1/neutron?charset=utf8 [DEFAULT] bind_port, "Port central Neutron server binds to", change to a different value rather than 9696 if you run central and local Neutron server in the same host [DEFAULT] core_plugin, "core plugin central Neutron server uses", tricircle.network.central_plugin. TricirclePlugin [DEFAULT] service_plugins, "service plugin central Neutron server uses", "(leave empty)" [DEFAULT] tricircle_db_connection, "database connection string for tricircle", mysql+pymysql://root:password@ 127.0.0.1/tricircle?charset=utf8 [client] auth_url, "keystone authorization url", http://$keystone_service_host/identity [client] identity_url, "keystone service url", http://$keystone_service_host/identity/v3 [client] auto_refresh_endpoint, "if set to True, endpoint will be automatically refreshed if timeout accessing", True [client] top_region_name, "name of central region which client needs to access", CentralRegion [client] admin_username, "username of admin account", admin [client] admin_password, "password of admin account", password [client] admin_tenant, "project name of admin account", demo [client] admin_user_domain_name, "user domain name of admin account", Default [client] admin_tenant_domain_name, "project name of admin account", Default [tricircle] type_drivers, "list of network type driver entry points to be loaded", "vxlan,vlan,flat,local" [tricircle] tenant_network_types, "ordered list of network_types to allocate as tenant networks", "vxlan,vlan,flat,local" [tricircle] network_vlan_ranges, "physical network names and VLAN tags range usable of VLAN provider", "bridge:2001:3000" [tricircle] vni_ranges, "VxLAN VNI range", "1001:2000" [tricircle] flat_networks, "physical network names with which flat networks can be created", bridge [tricircle] bridge_network_type, "l3 bridge network type which is enabled in tenant_network_types and is not local type", vxlan [tricircle] default_region_for_external_network, "Default Region where the external network belongs to", RegionOne [tricircle] enable_api_gateway, "whether the API gateway is enabled", False .. note:: Change keystone_service_host to the address of Keystone service. - create database for central Neutron server - register central Neutron server endpoint in Keystone, central Neutron should be registered in the same region with the Tricircle - start central Neutron server Installation with Local Neutron Server ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - 1 Install the Tricircle package:: git clone https://github.com/openstack/tricircle.git cd tricircle pip install -e . - 2 Setup local Neutron server In this guide we assume readers have already installed a complete OpenStack instance running services like Nova, Cinder, Neutron, etc, so we just discuss how to configure Neutron server to work with the Tricircle. For detail information about the configuration options in "client" and "tricircle" groups, please refer to the configuration guide. After the change, you just restart the Neutron server. edit neutron.conf. .. note:: Pay attention to the service_plugins configuration item, make sure the plugin which is configured can support the association of floating IP to a port whose network is not directly attached to the router. To support it, TricircleL3Plugin is inherited from Neutron original L3RouterPlugin and overrides the original "get_router_for_floatingip" implementation. In order to configure local Neutron to use original L3RouterPlugin, you will need to patch the function "get_router_for_floatingip" in the same way that has been done for TricircleL3Plugin. It's not necessary to configure the service plugins if cross Neutron L2 networking is the only need in the deployment. .. csv-table:: :header: "Option", "Description", "Example" [DEFAULT] core_plugin, "core plugin local Neutron server uses", tricircle.network.local_plugin. TricirclePlugin [DEFAULT] service_plugins, "service plugins local Neutron server uses", tricircle.network.local_l3_plugin. TricircleL3Plugin [client] auth_url, "keystone authorization url", http://$keystone_service_host/identity [client] identity_url, "keystone service url", http://$keystone_service_host/identity/v3 [client] auto_refresh_endpoint, "if set to True, endpoint will be automatically refreshed if timeout accessing", True [client] top_region_name, "name of central region which client needs to access", CentralRegion [client] admin_username, "username of admin account", admin [client] admin_password, "password of admin account", password [client] admin_tenant, "project name of admin account", demo [client] admin_user_domain_name, "user domain name of admin account", Default [client] admin_tenant_domain_name, "project name of admin account", Default [tricircle] real_core_plugin, "the core plugin the Tricircle local plugin invokes", neutron.plugins.ml2.plugin. Ml2Plugin [tricircle] central_neutron_url, "central Neutron server url", http://$neutron_service_host :9696 .. note:: Change keystone_service_host to the address of Keystone service, and neutron_service_host to the address of central Neutron service. edit ml2_conf.ini .. list-table:: :header-rows: 1 * - Option - Description - Example * - [ml2] mechanism_drivers - add l2population if vxlan network is used - openvswitch,l2population * - [agent] l2_population - set to True if vxlan network is used - True * - [agent] tunnel_types - set to vxlan if vxlan network is used - vxlan * - [ml2_type_vlan] network_vlan_ranges - for a specific physical network, the vlan range should be the same with tricircle.network_vlan_ranges option for central Neutron, configure this option if vlan network is used - bridge:2001:3000 * - [ml2_type_vxlan] vni_ranges - should be the same with tricircle.vni_ranges option for central Neutron, configure this option if vxlan network is used - 1001:2000 * - [ml2_type_flat] flat_networks - should be part of the tricircle.network_vlan_ranges option for central Neutron, configure this option if flat network is used - bridge * - [ovs] bridge_mappings - map the physical network to an ovs bridge - bridge:br-bridge .. note:: In tricircle.network_vlan_ranges option for central Neutron, all the available physical networks in all pods and their vlan ranges should be configured without duplication. It's possible that one local Neutron doesn't contain some of the physical networks configured in tricircle.network_vlan_ranges, in this case, users need to specify availability zone hints when creating network or booting instances in the correct pod, to ensure that the required physical network is available in the target pod.