A GitHub Enterprise Server instance in a cluster configuration assigns each task to a node according to the node's role. This assignment is called an allocation.
If a cluster node is unreachable by other nodes due to a hardware or software failure, your instance creates a new allocation to distribute jobs from the unhealthy node to another node that can handle the workload. In some situations, this distribution does not occur automatically, and a single node may run more jobs than expected.
You can manage allocations using the
ghe-cluster-balance utility, which can display the status of existing allocations or force your instance to balance allocations. For example, you should balance allocations after you add a new node to the cluster. Optionally, you can schedule regular balancing.
You can run the following commands from any node in your cluster using the administrative shell. For more information, see "Accessing the administrative shell (SSH)."
In some cases, such as hardware failure, the underlying software that that manages allocations will migrate tasks from the unhealthy node to a healthy node. If the unhealthy node recovers, the task may remain assigned to the recovered node, which can result in unbalanced load. The risk of job failure may increase if allocations are unbalanced and additional nodes fail. You can check the distribution of allocations using the
ghe-cluster-balance status utility.
To see a list of allocations, run the following command. The utility displays healthy allocations in green. If any jobs are not properly distributed, the utility displays the allocation's count in red.
If a job is not properly distributed, inspect the allocations by running the following command. Replace JOB with a single job or comma-delimited list of jobs.
ghe-cluster-balance status -j JOB
For example, to see the status of allocations for your instance's HTTP server and authorization service, you can run
ghe-cluster-balance status -j github-unicorn,authzd.
After you determine which jobs are unbalanced across your cluster's nodes, you can rebalance allocations using the
ghe-cluster-balance rebalance utility. The utility checks the distribution of existing jobs. If any jobs are unbalanced, the utility displays the jobs and prompts you to continue. If you continue, the utility creates new allocations to redistribute the jobs.
To perform a dry run and see the result of rebalancing without making changes, run the following command. Replace JOB with a single job or comma-delimited list of jobs.
ghe-cluster-balance rebalance --dry-run -j JOB
For example, to perform a dry run of rebalancing jobs for your instance's HTTP server and authorization service, you can run
ghe-cluster-balance rebalance --dry-run -j github-unicorn,authzd.
To rebalance, run the following command. Replace JOB with a single job or comma-delimited list of jobs.
ghe-cluster-balance rebalance -j JOB
You can schedule rebalancing of jobs on your cluster by setting and applying configuration values for your GitHub Enterprise Server instance.
Note: Currently, you can only schedule reallocation of jobs for the HTTP server,
To configure automatic, hourly balancing of jobs, run the following command.
ghe-config app.cluster-rebalance.enabled true
Optionally, you can override the default schedule by defining a cron expression. For example, run the following command to balance jobs every three hours.
ghe-config app.cluster-rebalance.schedule '0 */3 * * *'
To apply the configuration, run the following command.
Note: During a configuration run, services on your GitHub Enterprise Server instance may restart, which can cause brief downtime for users.
Wait for the configuration run to complete.