Deployment and Administration guide
Manual installation and configuration
Synergy version: service 1.5.3, scheduler 2.6.0
OpenStack supported versions: Mitaka, Newton, Ocata
Repository
Install the INDIGO repository.
Install the Synergy packages
On CentOS7:
On Ubuntu:
They can be installed in the OpenStack controller node or on another node.
Updating the Synergy packages
The Synergy project makes periodic releases. As a system administrator you can get the latest features and bug fixes by updating Synergy.
This is done using the standard update commands for your OS, as long you have the INDIGO repository set up.
On Ubuntu:
On CentOS:
Once the update is complete remember to restart the service. Follow the instructions in "Configure and start Synergy" section of this guide to see how to do it.
Setup the Synergy database
Then use the database access client to connect to the database server as the root user:
Create the synergy database:
Grant proper access to the glance database:
Replace SYNERGY_DBPASS with a suitable password.
Exit the database access client.
Add Synergy as an OpenStack endpoint and service
Source the admin credentials to gain access to admin-only CLI commands:
Register the Synergy service and endpoint in the Openstack service catalog:
Setup the Nova notifications
Make sure that nova notifications are enabled on the controller and compute node. Edit the /etc/nova/nova.conf file. The following configuration regards the OpenStack Ocata version. In the [notifications] and [oslo_messaging_notifications] sections add the following attributes:
The topics parameter is used by Nova for informing listeners about the state changes of the VMs. In case some other service (e.g. Ceilometer) is listening on the default topic notifications, to avoid the competition on consuming the notifications, please define a new topic specific for Synergy (e.g. topics = notifications,synergy_notifications).
Then restart the Nova services on the Controller and Compute node.
Setup the Keystone notifications
Synergy listens on the Keystone notification topic about the events on projects and users. Please set the keystone.conf as following:
Then restart the Keystone service.
Configure Controller to use Synergy
Perform these steps on the controller node. In /etc/nova/ create a nova-api.conf file. Edit /etc/nova/nova-api.conf file and add the following to it:
The topic must have the same value of the synergy_topic defined in the /etc/synergy/synergy_scheduler.conf file.
Only for Ubuntu 16.04, edit the /etc/init.d/nova-api file and replace
with
Restart nova-api service to enable your configuration.
On the node where it is installed RabbitMQ, run the following command to check whether your configuration is correct:
The output of the command should show something similar.
Configure and start Synergy
Configure the Synergy service, as explained in the following section.
Then start and enable the Synergy service. On CentOS:
On Ubuntu:
The Synergy configuration file
Synergy must be configured properly by filling the synergy.conf and synergy_scheduler.conf configuration files in /etc/synergy/. To apply the changes of any configuration parameter, the Synergy service must be restarted.
This is an example of the synergy.conf configuration file:
The following describes the meaning of the attributes of the synergy.conf file, for each possible section:
Section [Logger]
Attribute | Description |
filename | the name of the log file |
level | the logging level. Valid values are: CRITICAL, ERROR, WARNING, INFO, DEBUG, NOTSET |
formatter | the format of the logged messages |
maxBytes | the maximum size of a log file. When this size is reached, the log file is rotated |
backupCount | the number of log files to be kept |
Section [WSGI]
Attribute | Description |
host | the hostname where the Synergy service is deployed |
port | the port used by the Synergy service |
threads | the number of threads used by the Synergy service |
use ssl | specify if the service is secured through SSL |
ssl_ca_file | the CA certificate file to use to verify connecting clients |
ssl_cert_file | the Identifying certificate PEM file to present to clients |
ssl_key_file | the Private key PEM file used to sign cert_file certificate |
max_header_line | the maximum size of message headers to be accepted (default: 16384) |
retry_until_window | the number of seconds to keep retrying for listening (default: 30sec) |
tcp_keepidle | the value of TCP_KEEPIDLE in seconds for each server socket |
backlog | the number of backlog requests to configure the socket with (default: 4096). The listen backlog is a socket setting specifying that the kernel how to limit the number of outstanding (i.e. not yet accepted) connections in the listen queue of a listening socket. If the number of pending connections exceeds the specified size, new ones are automatically rejected |
Section [Authorization]
Attribute | Description |
plugin | Synergy has security mechanism highly configurable. The security policies are pluggable so that it is possible to define any kind of authorization checks. The simplest authorization plugin is synergy.auth.plugin.LocalHostAuthorization which denies any command coming from clients having IP address different from the Synergy's one. A more advanced security policies can be defined by using the synergy_scheduler_manager.auth.plugin.KeystoneAuthorization plugin based on the policy.json |
policy_file | set the policy.json file used by the synergy_scheduler_manager.auth.plugin.KeystoneAuthorization plugin |
This example shows how to configure the synergy_scheduler.conf file:
Attributes and their meanings are described in the following tables:
Section [SchedulerManager]
Attribute | Description |
autostart | specifies if the SchedulerManager manager should be started when Synergy starts |
rate | the time (in minutes) between two executions of the task implementing this manager |
backfill_depth | the integer value expresses the max depth used by the backfilling strategy: this allows Synergy to not check the whole queue when looking for VMs to start (default: 100) |
Section [FairShareManager]
Attribute | Description |
autostart | specifies if the FairShare manager should be started when Synergy starts |
rate | the time (in minutes) between two executions of the task implementing this manager |
period_length | The time window considered for resource usage by the fair-share algorithm used by Synergy is split in periods having all the same length, and the most recent periods are given a higher weight. This attribute specifies the length, in days, of a single period (default: 7) |
periods | the time window considered for resource usage by the fairshare algoritm used by Synergy is split in periods having all the same length, and the most recent periods are given a higher weight. This attribue specifies the number of periods to be considered (default: 3) |
default_share | specifies the default to be used for a project, if not specified in the shares attribute of the SchedulerManager section (default: 10) |
decay_weight | value between 0 and 1, used by the fairshare scheduler, to define how oldest periods should be given a less weight wrt resource usage (default: 0.5) |
vcpus_weight | the weight to be used for the attribute concerning vcpus usage in the fairshare algorithm used by Synergy (default: 100) |
age_weight | this attribute defines how oldest requests (and therefore with low priority) should have their priority increased so thay cam be eventaully served (default: 10) |
memory_weight | the weight to be used for the attribute concerning memory usage in the fairshare algorithm used by Synergy (default: 70) |
Section [KeystoneManager]
Attribute | Description |
autostart | specifies if the Keystone manager should be started when Synergy starts |
rate | the time (in minutes) between two executions of the task implementing this manage |
auth_url | the URL of the OpenStack identity service. Please note that the v3 API endpoint must be used |
username | the name of the user with admin role |
password | the password of the specified user with admin role |
project_id | the project id to request authorization on |
project_name | the project name to request authorization on |
user_domain_name | the user domain name (default: "default") |
project_domain_name | the project domain name (default: "default") |
timeout | the http connection timeout (default: 60) |
clock_skew | force the request for token, a delta time before the token expiration (default: 60 sec) |
ssl_ca_file | set the PEM encoded Certificate Authority to use when verifying HTTPs connections |
ssl_cert_file | set the SSL client certificate (PEM encoded) |
amqp_url | set the AMQP server url (e.g. rabbit://RABBIT_USER:RABBIT_PASS@RABBIT_HOST_IP) |
amqp_exchange | set the AMQP exchange (default: keystone) |
amqp_topic | set the AMQP notification topic on which Keystone communicates with Synergy. It must have the same value of the topic defined in keystone.conf file (e.g. topics = notification) (default: notification) |
Section [NovaManager]
Attribute | Description |
autostart | specifies if the nova manager should be started when Synergy starts |
rate | the time (in minutes) between two executions of the task implementing this manager |
host | the hostname where the nova-conductor service runs (default: localhost) |
timeout | the http connection timeout (default: 60) |
amqp_url | the amqp transport url |
amqp_backend | the AMQP backend tpye (rabbit or qpid) |
amqp_hosts | the AMQP HA cluster host:port pairs |
amqp_host | the server where the AMQP service runs (default: localhost) |
amqp_port | the port used by the AMQP service |
amqp_user | the AMQP userid |
amqp_password | the password of the AMQP user |
amqp_virtual_host | the AMQP virtual host |
synergy_topic | the topic on which Nova API communicates with Synergy. It must have the same value of the topic defined in nova-api.conf file (default: synergy) |
conductor_topic | the topic on which conductor nodes listen on (default: conductor) |
compute_topic | the topic on which compute nodes listen on (default: compute) |
scheduler_topic | the topic on which scheduler nodes listen on (default: scheduler) |
notification_topic | the notification topic used by Nova for informing listeners about the state changes of the VMs. In case some other service (e.g. Ceilometer) is listening on the default Nova topic (i.e. "notifications"), please define a new topic specific for Synergy (e.g. notification_topics = notifications,synergy_notifications) |
cpu_allocation_ratio | the Nova CPU allocation ratio (default: 16) |
ram_allocation_ratio | the Nova RAM allocation ratio (default: 1.5) |
metadata_proxy_shared_secret | the Nova metadata_proxy_shared_secret |
db_connection | the SQLAlchemy connection string to use to connect to the Nova database |
ssl_ca_file | set the PEM encoded Certificate Authority to use when verifying HTTPs connections |
ssl_cert_file | set the SSL client certificate (PEM encoded) |
Section [QueueManager]
Attribute | Description |
autostart | specifies if the Queue manager should be started when Synergy starts |
rate | the time (in minutes) between two executions of the task implementing this manager |
db_connection | the SQLAlchemy connection string to use to connect to the Synergy database |
db_pool_size | the number of SQL connections to be kept open (default: 10) |
db_pool_recycle | the number of seconds after which a connection is automatically recycled (default: 30) |
db_max_overflow | the max overflow with SQLAlchemy (default: 5) |
Section [QuotaManager]
Attribute | Description |
autostart | Specifies if the Quota manager should be started when Synergy starts |
rate | The time (in minutes) between two executions of the task implementing this manager |
Section [ProjectManager]
Attribute | Description |
autostart | Specifies if the Quota manager should be started when Synergy starts |
rate | The time (in minutes) between two executions of the task implementing this manager |
db_connection | the SQLAlchemy connection string to use to connect to the Synergy database |
db_pool_size | the number of SQL connections to be kept open (default: 10) |
db_pool_recycle | the number of seconds after which a connection is automatically recycled (default: 30) |
db_max_overflow | the max overflow with SQLAlchemy (default: 5) |
default_TTL | set the default max time to live (minutes) for VM/Container (default: 2880) |
default_share | set the default share value (default: 10) |
Installation and configuration using puppet
We provide a Puppet module for Synergy so users can install and configure Synergy with Puppet.
The module provides both the synergy-service
and synergy-scheduler-manager
components.
The module is available on the Puppet Forge : vll/synergy.
Install the puppet module with:
Usage example:
The Synergy command line interface
The Synergy service provides a command-line client, called synergy, which allows the Cloud administrator to control and monitor the Synergy service.
Before running the Synergy client command, you must create and source the admin-openrc.sh file to set the relevant environment variables. This is the same script used to run the OpenStack command line tools.
Note that the OS_AUTH_URL variables must refer to the v3 version of the keystone API, e.g.:
export OS_AUTH_URL=https://cloud-areapd.pd.infn.it:35357/v3
$ synergy usage
The synergy optional arguments:
-h, --help
--version
--debug
--os-username <auth-user-name>
--os-password <auth-password>
--os-project-name <auth-project-name>
--os-project-id <auth-project-id>
--os-project-domain-id <auth-project-domain-id>
--os-project-domain-name <auth-project-domain-name>
--os-user-domain-id <auth-user-domain-id>
--os-user-domain-name <auth-user-domain-name>
--os-auth-url <auth-url>
--bypass-url <bypass-url>
--os-cacert <ca-bundle-file>
$ synergy manager
This command allows to get information about the managers deployed in the Synergy service and control their execution:
The command synergy manager list provides the list of all managers deployed in the Synergy service:
To get the status about managers, use:
To control the execution of a specific manager, use the start and stop sub-commands:
$ synergy project
This command allows to manage the projects in Synergy:
To show all options related to each project command, use the --help argument, for example:
The following examples show how to use the project sub-commands (list, add, set, show, remove):
N.B. the values concerning the share attribute will be explained in the next section
$ synergy user
This command allows to get information about the users belonging to a project managed by Synergy:
The quota concept
The overall cloud resources can be grouped in:
private quota: composed of resources statically allocated and managed using the 'standard' OpenStack policies
shared quota: composed of resources non statically allocated and fairly distributed among users by Synergy
The size of the shared quota is calculated as the difference between the total amount of cloud resources (considering also the over-commitment ratios) and the total resources allocated to the private quotas. Therefore for all projects it is necessary to specify the proper quota for instances, VCPUs and RAM so that their total is less than the total amount of cloud resources.
Since Synergy is installed, the private quota of projects cannot be managed anymore by using the Horizon dashboard, but only via command line tools using the following OpenStack command:
The private and shared quotas will be updated from Synergy after a few minutes without restart it. This example shows how the private quota of the project _prj_a (id=_a5ccbaf2a9da407484de2af881198eb9) has been modified:
In this example the total amount of VCPUs allocated to the shared quota is 7 whereof have been used just 2 CPUs (similarly to the memory number). The private quota of the prja project have 2 VCPUS and 1024MB of RAM but if you check that quota by OpenStack CLI (or Horizon dashboard), you will notice that values of the _cores, ram attributes have been changed and set to -1 (i.e. unlimited). This means that Synergy is managing such resources rightly.
To know how many resources each project is consuming, use:
In this example the project prj_a is consuming just the shared quota (2 VCPUs and 1024MB of memory) while the prj_b is currently consuming just resources of its private quota (1 VCPU and 512MB of memory) while the shared quota is not used. Whenever the shared quota is saturated, all new requests for resources consuming are not rejected (as in standard OpenStack mode), but will be inserted into a persistent priority queue and processed as soon as some resources are again available.
The above table shows that the prj_a has 50 requests enqueued which corresponds to 25% of total queue usage. Analogously, the prj_b uses the 75%.
To get information about the usage of shared resources at project use:
In this case prj_a is consuming the 74.76% of resources (VCPUS and memory), while prj_b the 25.34%. The share values defined by the Cloud administrator are 10% and 30% respectivly. The table shows even the normalized values of the shares (25% and 75%). The user usage can be retrieved as following:
This example shows the usage and priority of all users. The main factors which affect the priority value are the project and user shares and their historical resource usage. The user requests having a higher the priority value will be executed first.
Open Ports
To interact with Synergy using the client tool, just one port needs to be open.
This is the port defined in the Synergy configuration file (attribute port
in the [WSGI]
section). The default value is 8051.
Last updated