Module org.elasticsearch.server
Package org.elasticsearch.action.support.master

Class TransportMasterNodeAction<Request extends MasterNodeRequest<Request>,Response extends ActionResponse>

java.lang.Object
org.elasticsearch.action.support.TransportAction<Request,Response>
org.elasticsearch.action.support.HandledTransportAction<Request,Response>
org.elasticsearch.action.support.master.TransportMasterNodeAction<Request,Response>
All Implemented Interfaces:
ActionWithReservedState<Request>
Direct Known Subclasses:
AcknowledgedTransportMasterNodeAction, AutoCreateAction.TransportAction, CompletionPersistentTaskAction.TransportAction, RemovePersistentTaskAction.TransportAction, StartPersistentTaskAction.TransportAction, TransportAddIndexBlockAction, TransportAddVotingConfigExclusionsAction, TransportCleanupRepositoryAction, TransportClearVotingConfigExclusionsAction, TransportCloseIndexAction, TransportClusterAllocationExplainAction, TransportClusterRerouteAction, TransportClusterUpdateSettingsAction, TransportCreateIndexAction, TransportCreateSnapshotAction, TransportDeleteDesiredBalanceAction, TransportDeleteDesiredNodesAction, TransportGetShardSnapshotAction, TransportGetSnapshotsAction, TransportIndicesAliasesAction, TransportMasterNodeReadAction, TransportOpenIndexAction, TransportRemoveIndexBlockAction, TransportResetFeatureStateAction, TransportResizeAction, TransportRestoreSnapshotAction, TransportRolloverAction, TransportSnapshotsStatusAction, TransportSnapshottableFeaturesAction, TransportUpdateDesiredNodesAction, TransportUpdateSnapshotStatusAction, TransportVerifyRepositoryAction, UpdatePersistentTaskStatusAction.TransportAction
public abstract class TransportMasterNodeAction<Request extends MasterNodeRequest<Request>,Response extends ActionResponse> extends HandledTransportAction<Request,Response> implements ActionWithReservedState<Request>
A base class for operations that need to be performed on the master node.

Many cluster operations (e.g. creating indices, managing snapshots) result in ClusterState updates and must therefore run on the elected master node. This class provides a common framework that handles routing requests to the current master, retrying when the master changes, and checking for cluster blocks.

Subclass Responsibilities

Subclasses must implement two abstract methods:

Request Types

The MasterNodeRequest is the request type this class is parameterized on. It carries two fields relevant to master routing:

  • masterNodeTimeout – how long the request will wait when no master is available or the current master is unreachable. For REST-originated requests this is set via the master_timeout query parameter and parsed via RestUtils.getMasterNodeTimeout(org.elasticsearch.rest.RestRequest). Internally-generated requests typically use INFINITE_MASTER_NODE_TIMEOUT to wait indefinitely.
  • masterTerm – the term of the cluster state used to route this request, which prevents routing loops. When a node receives a forwarded request whose masterTerm exceeds its own cluster state term, it waits for its local term to catch up before proceeding.

The localExecute(Request) method can be overridden to allow the action to run on the local node rather than being forwarded to the master (see TransportMasterNodeReadAction as an example). This is typically used for read-only operations (e.g. cluster health or cluster state queries) where a potentially stale local view is acceptable. It is conventionally controlled by the ?local request parameter.

Execution Flow

Execution is delegated to an AsyncSingleAction, which handles routing, async execution, and result listener registration.

If the local node is the master (or localExecute(Request) returns true):

  1. Cluster blocks are checked via checkBlock(Request, org.elasticsearch.cluster.ClusterState). A non-retryable block fails the request immediately. A retryable block causes a retry until the block clears.
  2. If there are no blocks, masterOperation(org.elasticsearch.tasks.Task, Request, org.elasticsearch.cluster.ClusterState, org.elasticsearch.action.ActionListener<Response>) is invoked on the configured executor.
  3. If masterOperation fails with a publish failure (NotMasterException or FailedToCommitClusterStateException), the action retries on the next master.

If the local node is not the master:

  1. If no master is known, the action retries until a master appears.
  2. If the local cluster state term is lower than the request's masterTerm, the action waits for the local term to catch up to avoid routing loops.
  3. Otherwise, the request is forwarded to the known master via the transport layer. If the connection fails (ConnectTransportException) or the target node is closing (NodeClosedException), the action retries on the next available master.

Retry Mechanism

All retries are driven by a ClusterStateObserver, which watches for cluster state changes satisfying a given predicate. The observer uses the remaining masterNodeTimeout as its deadline. If the predicate is not satisfied before the timeout expires, the request fails with a MasterNotDiscoveredException. For CancellableTasks, a cancellation listener is also registered so that the retry aborts immediately if the task is canceled. Each retry re-enters doStart with the new cluster state, re-evaluating the routing decision from scratch.