9.14. Configuring Districts

An OpenShift Enterprise district defines a set of node hosts and the resource definitions they must share to enable transparent migration of gears between hosts. Using districts, a gear can keep the same UUID (and related IP addresses, ports, etc.) when moved from one node host to another node host within the same district. This means that applications are not disrupted during a migration. This is true even if applications have specific values that are hard-coded, as many do, rather than sourcing environment variables.
Districts are enabled and required by default for deploying gears. Red Hat requires that you create at least one district before you deploy an OpenShift Enterprise installation to production. See the OpenShift Enterprise Administration Guide [8] for more information on resource management, including capacity planning and using districts.

9.14.1. Creating a District

All node hosts in a district must have the same gear profile, so at least one district is required for each gear profile that is defined. At least two or more node hosts are required in each district to move gears from one node host to another. When capacity planning, you must take into account that districts currently have a hard limit of 6000 gears.
Districts are defined by the broker host in the MongoDB datastore. The following instructions describe how to create a district and add a new node host to it.

Procedure 9.13. To Create a District and Add a Node Host:

  1. Create an empty district and specify the gear profile with: 
    # oo-admin-ctl-district -c create -n district_name -p gear_profile
  2. Add an empty node host to the district. Only node hosts that do not have any gears can be added to a district, and the node host must have the same gear profile as the district: 
    # oo-admin-ctl-district -c add-node -n district_name -i hostname
    The following example shows how to create an empty district, then add an empty node host to it.

    Example 9.8. Creating an Empty District and Adding a Node Host

    # oo-admin-ctl-district -c create -n small_district -p small
				
Successfully created district: 7521a7801686477f8409e74f67b693f4

{"active_server_identities_size"=>0,
"node_profile"=>"small",
"creation_time"=>"2012-10-24T02:14:48-04:00",
"name"=>"small_district",
"externally_reserved_uids_size"=>0,
"uuid"=>"7521a7801686477f8409e74f67b693f4",
"max_capacity"=>6000,
"available_uids"=>"<6000 uids hidden>",
"max_uid"=>6999,
"available_capacity"=>6000,
"server_identities"=>{}}

    # oo-admin-ctl-district -c add-node -n small_district -i node1.example.com
				
Success!
{...
"server_identities"=>{"node1.example.com"=>{"active"=>true}},
"uuid"=>"7521a7801686477f8409e74f67b693f4",
"name"=>"small_district",
...}

    Note

    The command outputs in the previous example show the JSON object representing the district in the MongoDB.