6.5. Gear Placement Algorithm

Prerequisites:

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 OpenShift Enterprise Deployment Guide for more information on using a custom algorithm.
This section details the default gear placement algorithm and assumes the use of districts, which are required for production deployments and enabled by default.
Gear Placement and Districts

MongoDB configures district capacity. Gear status does not affect district capacity, because districts reserve resources; they do not account for actual usage. In the JSON record for a district, max_capacity indicates the maximum number of gears that can be placed in the district, while available_capacity indicates the number of gears still available in that district. See Section 6.3.3, “Viewing District Information” for details on viewing the JSON record of a district.

Districts have a hard limit of 6000 gears, because each member node reserves resources for the entire district to ensure availability when a gear moves between nodes. This limit means that in a district with only one node, the district is full and cannot accept additional gears if that node reaches 6000 gears. Consider a district with more than one node full when each node has a number of gears equal to 6000 divided by the number of nodes. For example, the default gear placement algorithm keeps a district with two nodes at approximately 3000 gears on each node.
Use caution when manually migrating, as well. For example, starting with three nodes in a district then removing one manually can result in the remaining two nodes being unbalanced with 4000 and 2000 gears each.
Least Preferred and Restricted Servers

When choosing nodes for new gears, the default gear placement algorithm also considers any least preferred servers and restricted servers to help maintain high availability for applications. Least preferred servers are nodes that already have gears on them for the given application gear group; it is preferable to find other nodes instead so that high availability is ensured. Restricted servers are nodes that should not be chosen at all. For example, restricted servers would be identified for high-availability applications when two HAProxy gears are created to ensure they are placed on different nodes.

If no other nodes are available, a least preferred server can be chosen, however a restricted node cannot, resulting in the failure of the gear creation process and a rollback of the operation.
Default Gear Placement Algorithm

The following steps describe the default algorithm for selecting a node on which to place a new gear for an application:

  1. Find all the districts.
  2. Find the nodes that have the least active_capacity.
  3. Filter nodes based on given criteria to ensure gears within scalable applications are spread across multiple nodes.
  4. Filter non-districted nodes when districts are required.
  5. When regions and zones are present:
    1. Filter nodes without zones when zones are required.
    2. If the application already has gears on a node tagged with a region, exclude nodes that do not belong to the current region.
    3. Verify whether the minimum required number of zones for application gear groups is met.
    4. Filter zones to ensure that gears within the application gear group do not exist solely in a single zone.
    5. Choose zones that are least consumed to evenly distribute gears among zones.
    6. When zone nodes available, exclude nodes without zones.
  6. When districted nodes are available, exclude nodes without districts.
  7. Among remaining nodes, choose the ones with plenty of available capacity that are in districts with available UIDs.
  8. Randomly choose one of the nodes with the lower levels of active_capacity.