github.com/m3db/m3@v1.5.1-0.20231129193456-75a402aa583b/src/m3em/cluster/types.go (about) 1 // Copyright (c) 2017 Uber Technologies, Inc. 2 // 3 // Permission is hereby granted, free of charge, to any person obtaining a copy 4 // of this software and associated documentation files (the "Software"), to deal 5 // in the Software without restriction, including without limitation the rights 6 // to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 7 // copies of the Software, and to permit persons to whom the Software is 8 // furnished to do so, subject to the following conditions: 9 // 10 // The above copyright notice and this permission notice shall be included in 11 // all copies or substantial portions of the Software. 12 // 13 // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 14 // IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 15 // FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 16 // AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 17 // LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 18 // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 19 // THE SOFTWARE. 20 21 package cluster 22 23 import ( 24 "time" 25 26 "github.com/m3db/m3/src/cluster/placement" 27 "github.com/m3db/m3/src/m3em/build" 28 "github.com/m3db/m3/src/m3em/node" 29 "github.com/m3db/m3/src/x/instrument" 30 xretry "github.com/m3db/m3/src/x/retry" 31 ) 32 33 // Status indicates the different states a Cluster can be in. Refer to the 34 // state diagram below to understand transitions. Note, all states can transition 35 // to `ClusterStatusError`, these edges are skipped below. 36 // ╔══════════════════╗ 37 // ║ ║ 38 // ║ Uninitialized ║────────────Setup()────┐ 39 // ║ ║ │ 40 // ╚══════════════════╝ │ 41 // ▲ │ 42 // │ │ 43 // │ │ 44 // │ Teardown() │ 45 // ├────────────────────────┐ │ 46 // │ │ │ 47 // ┌───────┘ │ │ 48 // │ │ ▼ 49 // ╔═════╩════════════╗◀────Start()─────╦═╩════════════════╗ 50 // ║ ║ ║ ║ 51 // ┌──║ Running ║ ║ Setup ║──┐ 52 // │ ║ ║ ║ ║ │ 53 // │ ╚══════════════════╝──────Stop()────▶╚══════════════════╝ │ 54 // AddInstance() ▲ ▲ AddInstance() 55 // RemoveInstance() │ │ RemoveInstance() 56 // ReplaceInstance()──┘ └────ReplaceInstance() 57 type Status int 58 59 const ( 60 // ClusterStatusUninitialized refers to the state of an un-initialized cluster. 61 ClusterStatusUninitialized Status = iota 62 63 // ClusterStatusSetup refers to the state of a cluster whose nodes have 64 // been setup, and the cluster has an assigned placement. 65 ClusterStatusSetup 66 67 // ClusterStatusRunning refers to the state of a cluster with running nodes. 68 // There is no restriction on the number of nodes running, or assigned within 69 // the cluster placement. 70 ClusterStatusRunning 71 72 // ClusterStatusError refers to a cluster in error. 73 ClusterStatusError 74 ) 75 76 // Cluster is a collection of ServiceNodes with a m3cluster Placement 77 type Cluster interface { 78 // Setup sets up the service placement for the specified numNodes. 79 Setup(numNodes int) ([]node.ServiceNode, error) 80 81 // Teardown releases the resources acquired during Setup(). 82 Teardown() error 83 84 // AddNode adds a node to the service placement. The node to add is chosen from 85 // amongst // available spares, by the placementservice. It does NOT alter the 86 // state of the ServiceNode (i.e. does not start/stop it). 87 AddNode() (node.ServiceNode, error) 88 89 // AddSpecifiedNode adds the specified node to the service placement. It does 90 // NOT alter the state of the ServiceNode (i.e. does not start/stop it). 91 AddSpecifiedNode(node.ServiceNode) error 92 93 // RemoveNode removes the specified node from the service placement. It does 94 // NOT alter the state of the ServiceNode (i.e. does not start/stop it). 95 RemoveNode(node.ServiceNode) error 96 97 // ReplaceNode replaces the specified node with new node(s) in the service 98 // placement. It does NOT alter the state of the ServiceNode (i.e. does not start/stop it). 99 ReplaceNode(oldNode node.ServiceNode) ([]node.ServiceNode, error) 100 101 // Start starts all nodes used in current service placement. 102 Start() error 103 104 // Stop stops all nodes used in current service placement. 105 Stop() error 106 107 // SpareNodes returns the list of known nodes which are not part of the defined placement 108 // in the cluster. 109 SpareNodes() []node.ServiceNode 110 111 // ActiveNodes returns the list of known nodes which are part of the defined placement 112 // in the cluster. 113 ActiveNodes() []node.ServiceNode 114 115 // KnownNodes returns the list of known nodes 116 KnownNodes() []node.ServiceNode 117 118 // Placement returns the current placement 119 Placement() placement.Placement 120 121 // Status returns the cluster status 122 Status() Status 123 } 124 125 // Options represents the options to configure a `Cluster` 126 type Options interface { 127 // Validate validates the Options 128 Validate() error 129 130 // SetInstrumentOptions sets the instrumentation options 131 SetInstrumentOptions(instrument.Options) Options 132 133 // InstrumentOptions returns the instrumentation options 134 InstrumentOptions() instrument.Options 135 136 // SetServiceBuild sets the service build used to configure 137 // the cluster 138 SetServiceBuild(build.ServiceBuild) Options 139 140 // ServiceBuild returns the service build used in the cluster 141 ServiceBuild() build.ServiceBuild 142 143 // SetServiceConfig sets the default service configuration to 144 // be used in setting up the cluster 145 SetServiceConfig(build.ServiceConfiguration) Options 146 147 // ServiceConfig returns the default service configuration to 148 // used in setting up the cluster 149 ServiceConfig() build.ServiceConfiguration 150 151 // SetSessionToken sets the token used for interactions with remote m3em agents 152 SetSessionToken(string) Options 153 154 // SessionToken returns the token used for interactions with remote m3em agents 155 SessionToken() string 156 157 // SetSessionOverride sets a flag indicating if m3em agent operations 158 // are permitted to override clashing resources 159 SetSessionOverride(bool) Options 160 161 // SessionOverride returns a flag indicating if m3em agent operations 162 // are permitted to override clashing resources 163 SessionOverride() bool 164 165 // SetReplication sets the replication factor for the cluster 166 SetReplication(int) Options 167 168 // Replication returns the replication factor by the cluster 169 Replication() int 170 171 // SetNumShards sets the number of shards used in the cluster 172 SetNumShards(int) Options 173 174 // NumShards returns the number of shards used in the cluster 175 NumShards() int 176 177 // SetPlacementService returns the PlacementService to use for cluster 178 // configuration 179 SetPlacementService(placement.Service) Options 180 181 // PlacementService returns the PlacementService to use for cluster 182 // configuration 183 PlacementService() placement.Service 184 185 // SetPlacementServiceRetrier sets the retrier to use for placement 186 // service operations 187 SetPlacementServiceRetrier(xretry.Retrier) Options 188 189 // PlacementServiceRetrier returns the retrier to use for placement 190 // service operations 191 PlacementServiceRetrier() xretry.Retrier 192 193 // SetNodeConcurrency sets the number of nodes to operate upon 194 // concurrently 195 SetNodeConcurrency(int) Options 196 197 // NodeConcurrency returns the number of nodes to operate upon 198 // concurrently 199 NodeConcurrency() int 200 201 // SetNodeOperationTimeout sets the timeout for a node operation 202 SetNodeOperationTimeout(time.Duration) Options 203 204 // NodeOperationTimeout returns the timeout for a node operation 205 NodeOperationTimeout() time.Duration 206 207 // SetNodeListener sets default node listener 208 SetNodeListener(node.Listener) Options 209 210 // NodeListener returns the node listener 211 NodeListener() node.Listener 212 }