6.2.2. Purpose of Districts

Districts define a set of node hosts that gears can reliably move between to manage node host resource usage. Red Hat requires using districts for production deployments, and they are enabled by default for deploying gears on new installations.

OpenShift Enterprise allocates resources to gears including an external port range and IP address range, calculated according to their numeric Linux user ID (UID) on the node. A gear can only move to a node where its UID is not already in use. Districts reserve a UID for the gear across all nodes in the district, meaning only the node hosting the gear uses its UID. This allows the gear to maintain the same UID and related resources when moved to any other node within the district.

A district's UID pool includes 6000 UIDs due to the limited range of external ports. Districts allocate these UIDs to gears randomly rather than sequentially. This random allocation method makes the availability of a gear's UID more likely, even when moving the gear to a new district. Without districts, nodes allocate gear UIDs locally and sequentially, making it extremely likely that a gear's UID will be in use on other nodes.

In previous versions of OpenShift Enterprise, it was possible to change a gear's UID on a gear move. However, this required reconfiguration of the related resources, impeded cartridge maintenance, and caused trouble for application developers with hard-coded resource settings, which could not be updated automatically. Disallowing UID changes during a gear move and using districts to reserve UIDs saves developers and administrators time and trouble.

Districts also allow you to mark a node as deactivated to ensure it receives no additional gears from the broker host. The existing gears continue to run until they are destroyed or moved to another node. This enables the decommissioning of a node with minimal disruption to its gears.