8.5. Installing and Configuring the Gear Placement Plug-in

When new gears are added to an application, a gear placement algorithm is used to find an available node on which to place each gear. You can either use the default algorithm or implement the gear placement plug-in to use a custom algorithm; see the OpenShift Enterprise Administration Guide for more information on the default algorithm.
The optional gear placement plug-in allows you to control the placement of gears as they are created. When in use, the plug-in receives information during gear creation about the application developer, cartridges, application, current gears that are in use, and available nodes. Then, using the configured algorithm, the plug-in is expected to return a node from the list of available nodes. An error or exception thrown by the plug-in results in the failure of the gear creation process and triggers a rollback of the operation.
You can develop a custom algorithm with a basic understanding of the Ruby programming language. This section describes how to install and configure the gear placement plug-in with default settings. After the plug-in is installed, see the following sections for information on developing custom algorithms and implementing them in your installation, including examples based on some hypothetical scenarios.

Procedure 8.15. To Install and Configure the Gear Placement Plug-in:

  1. Install the gear placement plug-in on each broker host: 
    # yum install rubygem-openshift-origin-gear-placement
    This installs a gem with a Rails engine containing the GearPlacementPlugin class.
  2. On each broker host, copy the /etc/openshift/plugins.d/openshift-origin-gear-placement.conf.example file to /etc/openshift/plugins.d/openshift-origin-gear-placement.conf: 
    # cp /etc/openshift/plugins.d/openshift-origin-gear-placement.conf.example /etc/openshift/plugins.d/openshift-origin-gear-placement.conf
    As long as this configuration file with a .conf extension exists, the broker automatically loads a gem matching the file name, and the gem can use the file to configure itself.
  3. Restart the broker service: 
    # service openshift-broker restart
    If you make further modifications to the configuration file of the gear placement plug-in, you must restart the broker service again after making your final changes.
  4. The default implementation of the plug-in simply logs the plug-in inputs and delegates the actual gear placement to the default algorithm. You can verify that the plug-in is correctly installed and configured with the default implementation by creating an application and checking the /var/log/openshift/broker/production.log file.

    Example 8.7. Checking Broker Logs for Default Gear Placement Plug-in Activity

    2014-10-17 12:53:18.476 [INFO ] Parameters: {"cartridges"=>["php-5.4"], "scale"=>true, "name"=>"mytestapp", "domain_id"=>"demo"} (pid:14508)
2014-10-17 12:53:24.715 [INFO ] Using gear placement plugin to choose node. (pid:14508)
2014-10-17 12:53:24.715 [INFO ] selecting from nodes: node2.example.com, node1.example.com (pid:14508)
2014-10-17 12:53:24.718 [INFO ] server_infos: [#<NodeProperties:0x00000007675438
  @district_available_capacity=5994,
  @district_id="5441e3896892df06a4000001",
  @name="node2.example.com",
  @node_consumed_capacity=3.3333333333333335,
  @region_id=nil,
  @zone_id=nil>,
 #<NodeProperties:0x00000006e302a0
  @district_available_capacity=5994,
  @district_id="5441e3896892df06a4000001",
  @name="node1.example.com",
  @node_consumed_capacity=6.666666666666667,
  @region_id=nil,
  @zone_id=nil>] (pid:14508)
2014-10-17 12:53:24.719 [INFO ] app_props: #<ApplicationProperties:0x000000078b97a8
 @id="54446b0e6892dff4b5000001",
 @name="mytestapp",
 @web_cartridge="php-5.4"> (pid:14508)
2014-10-17 12:53:24.720 [INFO ] current_gears: [] (pid:14508)
2014-10-17 12:53:24.721 [INFO ] comp_list: [#<ComponentProperties:0x000000076a8b08
  @cartridge_name="haproxy-1.4",
  @cartridge_vendor="redhat",
  @component_name="web_proxy",
  @version="1.4">,
 #<ComponentProperties:0x000000076a88d8
  @cartridge_name="php-5.4",
  @cartridge_vendor="redhat",
  @component_name="php-5.4",
  @version="5.4">] (pid:14508)
2014-10-17 12:53:24.724 [INFO ] user_props: #<UserProperties:0x000000078b8f38
 @capabilities=
  {"ha"=>false,
   "subaccounts"=>false,
   "gear_sizes"=>["small"],
   "max_domains"=>10,
   "max_gears"=>100,
   "max_teams"=>0,
   "view_global_teams"=>false,
   "max_storage_per_gear"=>0},
 @consumed_gears=7,
 @id="5441e5f26892df39e9000001",
 @login="demo",
 @plan_id=nil,
 @plan_state=nil> (pid:14508)
2014-10-17 12:53:24.724 [INFO ] selected node: 'node2.example.com' (pid:14508)

8.5.1. Developing and Implementing a Custom Gear Placement Algorithm

Prerequisites:

You can develop a custom gear placement algorithm with a basic understanding of the Ruby programming language. After the gear placement plug-in is installed, the plug-in's configuration files, initializers, and gear placement algorithm source files are installed on the broker host. The location of the gem and these files varies depending on the version of the RPM package. Use the following command to find out the location of these files on your broker hosts: 
# rpm -ql rubygem-openshift-origin-gear-placement
When developing a custom algorithm, you must modify the following files as required by your implementation:
Gem_Location/lib/openshift/gear_placement_plugin.rb
This contains the GearPlacementPlugin class. Modify the self.select_best_fit_node_impl method to customize the algorithm.
Gem_Location/config/initializers/openshift-origin-gear-placement.rb
This is the plug-in initializer that loads any configuration settings, if relevant.
/etc/openshift/plugins.d/openshift-origin-gear-placement.conf
This is where any relevant configuration settings for the plug-in can be defined.
Developing a Custom Algorithm

When you install the rubygem-openshift-origin-gear-placement RPM package, a gem with a Rails engine containing the GearPlacementPlugin class is also installed. The only method you must modify is self.select_best_fit_node_impl in the Gem_Location/lib/openshift/gear_placement_plugin.rb file, because it is the method invoked by the OpenShift::ApplicationContainerProxy class. Whenever a gear is created, the ApplicationContainerProxy.select_best_fit_node method is invoked, and if the gear placement plug-in is installed, that method invokes the plug-in.

A custom algorithm can be used for load balancing or to enforce constraints based on specified parameters. As seen in the self.select_best_fit_node_impl method signature, there are multiple data structures available for use in the algorithm: 
GearPlacementPlugin.select_best_fit_node_impl(server_infos, app_props,
                   current_gears, comp_list, user_props, request_time)
Ultimately, the method must return exactly one of the entries from server_infos; it cannot be a node outside of this list. The Gem_Location/lib/openshift/ directory contains several example algorithms for reference, which are also described in Section 8.5.2, “Example Gear Placement Algorithms”.
The following table describes each of the input data structures available to the algorithm:

Table 8.2. Input Data Structures

Data Structure Description Properties
server_infos Array of server information: objects of class NodeProperties. :name, :node_consumed_capacity, :district_id, :district_available_capacity, :region_id, :zone_id
app_props Properties of the application to which the gear is being added: objects of class ApplicationProperties. :id, :name, :web_cartridge
current_gears Array of existing gears in the application: objects of class GearProperties. :id, :name, :server, :district, :cartridges, :region, :zone
comp_list Array of components that will be present on the new gear: objects of class ComponentProperties. :cartridge_name, :component_name, :version, :cartridge_vendor
user_props Properties of the user: object of class UserProperties. :id, :login, :consumed_gears, :capabilities, :plan_id, :plan_state
request_time The time that the request was sent to the plug-in: Time on the OpenShift Broker host. Time.now
The default implementation of the plug-in simply logs the plug-in inputs and delegates the actual gear placement to the default algorithm, so you can check the example log output from the /var/log/openshift/broker/production.log file in Section 8.5, “Installing and Configuring the Gear Placement Plug-in” for examples of these inputs.
The server_infos entries provided to the algorithm are already filtered for compatibility with the gear request. They can be filtered by:
  • Specified profile.
  • Specified region.
  • Full, deactivated, or undistricted nodes.
  • Nodes without a region and zone, if regions and zones are in use.
  • Zones being used in a high-availability application, depending on the configuration.
  • Nodes being used in a scaled application. If this would return zero nodes, then only one is returned.
  • Availability of UID and other specified constraints when a gear is being moved.
While developing your algorithm, be careful to consider many scenarios, as the above filters' effects can be subtle, depending on the circumstances. Particularly in the last two of the above filters, it would not be unusual for the server_infos list presented to the algorithm to only contain one node when the developer might expect there to be plenty of other nodes from which to choose. The intent of the plug-in currently is not to enable complete flexibility of node choice, but rather to enforce custom constraints or to load balance based on preferred parameters.
Using Configuration Settings

Optionally, you can implement configuration settings with the plug-in. To do so, you must:

  1. Load them in the plug-in initializer in the Gem_Location/config/initializers/openshift-origin-gear-placement.rb file, and
  2. Add and define the settings in the /etc/openshift/plugins.d/openshift-origin-gear-placement.conf file.
For example, the configuration settings in the default Gem_Location/config/initializers/openshift-origin-gear-placement.rb file are loaded using the following syntax: 
 config.gear_placement = { :confkey1 => conf.get("CONFKEY1", "value1"),
                           :confkey2 => conf.get("CONFKEY2", "value2"),
                           :confkey3 => conf.get("CONFKEY3", "value3") }
Add your new configuration settings to the initializer using the same syntax as above. The Gem_Location/config/initializers/ directory contains several example initializers for use with their respective example algorithms described in Section 8.5.2, “Example Gear Placement Algorithms”.
Implementing a Custom Algorithm

Any changes to the Gem_Location/lib/openshift/gear_placement_plugin.rb, Gem_Location/config/initializers/openshift-origin-gear-placement.rb, or /etc/openshift/plugins.d/openshift-origin-gear-placement.conf files must be done equally across all broker hosts in your environment. After making the desired changes to any of these files, the broker service must be restarted to load the changes: 

# service openshift-broker restart
You can verify that the plug-in is correctly configured with your custom implementation by creating an application and checking the /var/log/openshift/broker/production.log file for the expected logs.