You have considerable control over which members become captain, through these methods:
- You can designate members as either "preferred captains" or "not preferred captains." When the cluster assigns captaincy, it attempts to assign it to a member with a preferred captain designation.
- You can transfer captaincy from one member to another.
It can be useful to control captaincy to handle a number of situations. For example:
- You have one member that you want to always use as captain. Or conversely, you have one member that you never want to be captain.
- You do not want the captain to perform any user-initiated ad hoc jobs. You can achieve this by designating one specific member as captain and keeping your third-party load balancer ignorant of that member.
- You want to repair the state of the cluster. A quick way to do this is to switch to a new captain, because members join a new captain in a clean state.
The twin tools of preferred captaincy and captaincy transfer give you flexibility when you need to control captaincy. Although neither one can guarantee that you always maintain complete control over the location of your captain, they do limit the likelihood that the captain will reside on a member that is not optimal for your needs. And captaincy transfer offers the ability to transfer the captain to a new member as needed.
Specify captaincy preference
You can designate some members as preferred captains and others as non-preferred captains. When the cluster assigns captaincy, it attempts to assign it to a member with a preferred captain designation.
Designate captaincy preference
To specify a member's preference for captaincy, set the
preferred_captain attribute in that member's
preferred_captain = true|false
This attribute defaults to true, which means that, by default, all members are preferred captains.
To limit the likelihood that the cluster will assign captaincy to a particular member, set that member's
preferred_captain attribute to false:
preferred_captain = false
The cluster attempts to respect the captaincy preference.
Limitations of captaincy preference
The cluster tries to assign captaincy to a member with
preferred_captain=true. However, it might not always be possible to assign captaincy to a preferred-captain member. For example, if none of the preferred-captain members are reachable over the network, then captaincy might be assigned to a member with
During an election for a new captain, a non-preferred-captain member can briefly become the captain before captaincy transfers to a preferred-captain member. If no preferred-captain members are available, the non-preferred-captain member remains captain until a preferred-captain member becomes available.
You can transfer captaincy from one member to another.
The use of captaincy transfer does not interfere with the normal captain election process, which always proceeds in response to the circumstances described in Captain election. If an election occurs and results in the captain moving to a member other than the one you want it to reside on, you can then invoke captaincy transfer to relocate the captain.
Change the captain
To transfer captaincy to a different member, run this command from the current captain:
splunk transfer shcluster-captain -mgmt_uri <URI>:<management_port> -auth <username>:<password>
Note the following:
-mgmt_uriparameter specifies the URI and management port for the member that you want to transfer captaincy to. You must use the fully qualified domain name.
- You must run this command on the current captain. If you run this command on any other member, such as the intended captain, you get an error message.
- You do not need to restart any member after running the command.
To confirm that the captaincy transfer was successful, run the
splunk show shcluster-status command from any member:
splunk show shcluster-status -auth <username>:<password>
Among other information returned, this command identifies the current captain.
Some ways to employ captaincy transfer in scripts
splunk transfer shcluster-captain command can be useful for scripting certain cluster behavior. For example:
- To ensure that captaincy stays with a particular member, you can implement a cron job that monitors the captain on a periodic basis. If the check detects a change in captain, it can automatically run the
splunk transfer shcluster-captaincommand to return captaincy to the preferred member.
- To implement rolling-restart-style functionality (for example, if deploying cluster updates through some third-party tool), you can transfer captaincy to another member prior to restarting the current captain.
Captaincy transfer and rolling-restarts
As of 6.3, the rolling-restart process automatically invokes captaincy transfer to prevent captaincy from changing during the restart process. Because of this action, the member that was captain prior to the restart ordinarily continues as captain after the restart. See Restart the search head cluster.
Captaincy transfer and static captain
Captaincy transfer is available only with a dynamic captain. For information on the use of a static captain for disaster recovery, see Use static captain to recover from loss of majority.
Configure a cluster member to run ad hoc searches only
Handle failure of a search head cluster member
This documentation applies to the following versions of Splunk® Enterprise: 6.5.0, 6.5.1, 6.5.2, 6.5.3