About workload balance for a GitHub Enterprise Server cluster
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)."
Checking the distribution of cluster jobs
In some cases, such as hardware failure, the underlying software 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.
Shell ghe-cluster-balance status
ghe-cluster-balance status
-
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.
Shell ghe-cluster-balance status -j JOB
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
.
Rebalancing allocations
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.
Shell ghe-cluster-balance rebalance --dry-run -j JOB
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.
Shell ghe-cluster-balance rebalance -j JOB
ghe-cluster-balance rebalance -j JOB
Scheduling allocation rebalancing
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, github-unicorn
.
-
To configure automatic, hourly balancing of jobs, run the following command.
Shell ghe-config app.cluster-rebalance.enabled true
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 daily.
Shell ghe-config app.cluster-rebalance.schedule '0 0 * * *'
ghe-config app.cluster-rebalance.schedule '0 0 * * *'
-
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.
Shell ghe-config-apply
ghe-config-apply
-
Wait for the configuration run to complete.