Package consul

Overview ▹

Overview ▾

The snapshot endpoint is a special non-RPC endpoint that supports streaming
for taking and restoring snapshots for disaster recovery. This gets wired
directly into Consul's stream handler, and a new TCP connection is made for
each request.

This also includes a SnapshotRPC() function, which acts as a lightweight
client that knows the details of the stream protocol.

Internal call graph ▹

Internal call graph ▾

In the call graph viewer below, each node
is a function belonging to this package
and its children are the functions it
calls—perhaps dynamically.

The root nodes are the entry points of the
package: functions that may be called from
outside the package.
There may be non-exported or anonymous
functions among them if they are called
dynamically from another package.

Click a node to visit that function's source code.
From there you can visit its callers by
clicking its declaring func
token.

Functions may be omitted if they were
determined to be unreachable in the
particular programs or tests that were
analyzed.

These are the protocol versions that Consul can _understand_. These are
Consul-level protocol versions, that are used to configure the Serf
protocol versions.

const (
ProtocolVersionMin uint8 = 2
// Version 3 added support for network coordinates but we kept the// default protocol version at 2 to ease the transition to this new// feature. A Consul agent speaking version 2 of the protocol will// attempt to send its coordinates to a server who understands version// 3 or greater.
ProtocolVersion2Compatible = 2
ProtocolVersionMax = 3
)

const (
// StatusReap is used to update the status of a node if we// are handling a EventMemberReap
StatusReap = serf.MemberStatus(-1)
)

SnapshotRPC is a streaming client function for performing a snapshot RPC
request to a remote server. It will create a fresh connection for each
request, send the request header, and then stream in any data from the
reader (for a restore). It will then parse the received response header, and
if there's no error will return an io.ReadCloser (that you must close) with
the streaming output (for a snapshot). If the reply contains an error, this
will always return an error as well, so you don't need to check the error
inside the filled-in reply.

type Config struct {
// Bootstrap mode is used to bring up the first Consul server.// It is required so that it can elect a leader without any// other nodes being present
Bootstrap bool
// BootstrapExpect mode is used to automatically bring up a collection of// Consul servers. This can be used to automatically bring up a collection// of nodes.
BootstrapExpect int
// Datacenter is the datacenter this Consul server represents
Datacenter string
// DataDir is the directory to store our state in
DataDir string
// DevMode is used to enable a development server mode.
DevMode bool
// NodeID is a unique identifier for this node across space and time.
NodeID types.NodeID
// Node name is the name we use to advertise. Defaults to hostname.
NodeName string
// Domain is the DNS domain for the records. Defaults to "consul."
Domain string
// RaftConfig is the configuration used for Raft in the local DC
RaftConfig *raft.Config
// (Enterprise-only) NonVoter is used to prevent this server from being added// as a voting member of the Raft cluster.
NonVoter bool
// RPCAddr is the RPC address used by Consul. This should be reachable// by the WAN and LAN
RPCAddr *net.TCPAddr
// RPCAdvertise is the address that is advertised to other nodes for// the RPC endpoint. This can differ from the RPC address, if for example// the RPCAddr is unspecified "0.0.0.0:8300", but this address must be// reachable
RPCAdvertise *net.TCPAddr
// RPCSrcAddr is the source address for outgoing RPC connections.
RPCSrcAddr *net.TCPAddr
// SerfLANConfig is the configuration for the intra-dc serf
SerfLANConfig *serf.Config
// SerfWANConfig is the configuration for the cross-dc serf
SerfWANConfig *serf.Config
// SerfFloodInterval controls how often we attempt to flood local Serf// Consul servers into the global areas (WAN and user-defined areas in// Consul Enterprise).
SerfFloodInterval time.Duration
// ReconcileInterval controls how often we reconcile the strongly// consistent store with the Serf info. This is used to handle nodes// that are force removed, as well as intermittent unavailability during// leader election.
ReconcileInterval time.Duration
// LogOutput is the location to write logs to. If this is not set,// logs will go to stderr.
LogOutput io.Writer
// ProtocolVersion is the protocol version to speak. This must be between// ProtocolVersionMin and ProtocolVersionMax.
ProtocolVersion uint8
// VerifyIncoming is used to verify the authenticity of incoming connections.// This means that TCP requests are forbidden, only allowing for TLS. TLS connections// must match a provided certificate authority. This can be used to force client auth.
VerifyIncoming bool
// VerifyOutgoing is used to force verification of the authenticity of outgoing connections.// This means that TLS requests are used, and TCP requests are not made. TLS connections// must match a provided certificate authority.
VerifyOutgoing bool
// UseTLS is used to enable TLS for outgoing connections to other TLS-capable Consul// servers. This doesn't imply any verification, it only enables TLS if possible.
UseTLS bool
// VerifyServerHostname is used to enable hostname verification of servers. This// ensures that the certificate presented is valid for server.<datacenter>.<domain>.// This prevents a compromised client from being restarted as a server, and then// intercepting request traffic as well as being added as a raft peer. This should be// enabled by default with VerifyOutgoing, but for legacy reasons we cannot break// existing clients.
VerifyServerHostname bool
// CAFile is a path to a certificate authority file. This is used with VerifyIncoming// or VerifyOutgoing to verify the TLS connection.
CAFile string
// CAPath is a path to a directory of certificate authority files. This is used with// VerifyIncoming or VerifyOutgoing to verify the TLS connection.
CAPath string
// CertFile is used to provide a TLS certificate that is used for serving TLS connections.// Must be provided to serve TLS connections.
CertFile string
// KeyFile is used to provide a TLS key that is used for serving TLS connections.// Must be provided to serve TLS connections.
KeyFile string
// ServerName is used with the TLS certificate to ensure the name we// provide matches the certificate
ServerName string
// TLSMinVersion is used to set the minimum TLS version used for TLS connections.
TLSMinVersion string
// TLSCipherSuites is used to specify the list of supported ciphersuites.
TLSCipherSuites []uint16
// TLSPreferServerCipherSuites specifies whether to prefer the server's ciphersuite// over the client ciphersuites.
TLSPreferServerCipherSuites bool
// RejoinAfterLeave controls our interaction with Serf.// When set to false (default), a leave causes a Consul to not rejoin// the cluster until an explicit join is received. If this is set to// true, we ignore the leave, and rejoin the cluster on start.
RejoinAfterLeave bool
// Build is a string that is gossiped around, and can be used to help// operators track which versions are actively deployed
Build string
// ACLToken is the default token to use when making a request.// If not provided, the anonymous token is used. This enables// backwards compatibility as well.
ACLToken string
// ACLAgentToken is the default token used to make requests for the agent// itself, such as for registering itself with the catalog. If not// configured, the ACLToken will be used.
ACLAgentToken string
// ACLMasterToken is used to bootstrap the ACL system. It should be specified// on the servers in the ACLDatacenter. When the leader comes online, it ensures// that the Master token is available. This provides the initial token.
ACLMasterToken string
// ACLDatacenter provides the authoritative datacenter for ACL// tokens. If not provided, ACL verification is disabled.
ACLDatacenter string
// ACLTTL controls the time-to-live of cached ACL policies.// It can be set to zero to disable caching, but this adds// a substantial cost.
ACLTTL time.Duration
// ACLDefaultPolicy is used to control the ACL interaction when// there is no defined policy. This can be "allow" which means// ACLs are used to black-list, or "deny" which means ACLs are// white-lists.
ACLDefaultPolicy string
// ACLDownPolicy controls the behavior of ACLs if the ACLDatacenter// cannot be contacted. It can be either "deny" to deny all requests,// or "extend-cache" which ignores the ACLCacheInterval and uses// cached policies. If a policy is not in the cache, it acts like deny.// "allow" can be used to allow all requests. This is not recommended.
ACLDownPolicy string
// ACLReplicationToken is used to fetch ACLs from the ACLDatacenter in// order to replicate them locally. Setting this to a non-empty value// also enables replication. Replication is only available in datacenters// other than the ACLDatacenter.
ACLReplicationToken string
// ACLReplicationInterval is the interval at which replication passes// will occur. Queries to the ACLDatacenter may block, so replication// can happen less often than this, but the interval forms the upper// limit to how fast we will go if there was constant ACL churn on the// remote end.
ACLReplicationInterval time.Duration
// ACLReplicationApplyLimit is the max number of replication-related// apply operations that we allow during a one second period. This is// used to limit the amount of Raft bandwidth used for replication.
ACLReplicationApplyLimit int
// ACLEnforceVersion8 is used to gate a set of ACL policy features that// are opt-in prior to Consul 0.8 and opt-out in Consul 0.8 and later.
ACLEnforceVersion8 bool
// TombstoneTTL is used to control how long KV tombstones are retained.// This provides a window of time where the X-Consul-Index is monotonic.// Outside this window, the index may not be monotonic. This is a result// of a few trade offs:// 1) The index is defined by the data view and not globally. This is a// performance optimization that prevents any write from incrementing the// index for all data views.// 2) Tombstones are not kept indefinitely, since otherwise storage required// is also monotonic. This prevents deletes from reducing the disk space// used.// In theory, neither of these are intrinsic limitations, however for the// purposes of building a practical system, they are reasonable trade offs.//// It is also possible to set this to an incredibly long time, thereby// simulating infinite retention. This is not recommended however.//
TombstoneTTL time.Duration
// TombstoneTTLGranularity is used to control how granular the timers are// for the Tombstone GC. This is used to batch the GC of many keys together// to reduce overhead. It is unlikely a user would ever need to tune this.
TombstoneTTLGranularity time.Duration
// Minimum Session TTL
SessionTTLMin time.Duration
// ServerUp callback can be used to trigger a notification that// a Consul server is now up and known about.
ServerUp func()
// UserEventHandler callback can be used to handle incoming// user events. This function should not block.
UserEventHandler func(serf.UserEvent)
// CoordinateUpdatePeriod controls how long a server batches coordinate// updates before applying them in a Raft transaction. A larger period// leads to fewer Raft transactions, but also the stored coordinates// being more stale.
CoordinateUpdatePeriod time.Duration
// CoordinateUpdateBatchSize controls the maximum number of updates a// server batches before applying them in a Raft transaction.
CoordinateUpdateBatchSize int
// CoordinateUpdateMaxBatches controls the maximum number of batches we// are willing to apply in one period. After this limit we will issue a// warning and discard the remaining updates.
CoordinateUpdateMaxBatches int
// RPCHoldTimeout is how long an RPC can be "held" before it is errored.// This is used to paper over a loss of leadership by instead holding RPCs,// so that the caller experiences a slow response rather than an error.// This period is meant to be long enough for a leader election to take// place, and a small jitter is applied to avoid a thundering herd.
RPCHoldTimeout time.Duration
// AutopilotConfig is used to apply the initial autopilot config when// bootstrapping.
AutopilotConfig *structs.AutopilotConfig
// ServerHealthInterval is the frequency with which the health of the// servers in the cluster will be updated.
ServerHealthInterval time.Duration
// AutopilotInterval is the frequency with which the leader will perform// autopilot tasks, such as promoting eligible non-voters and removing// dead servers.
AutopilotInterval time.Duration
}

ScaleRaft sets the config to have Raft timing parameters scaled by the given
performance multiplier. This is done in an idempotent way so it's not tricky
to call this when composing configurations and potentially calling this
multiple times on the same structure.

ConnPool is used to maintain a connection pool to other
Consul servers. This is used to reduce the latency of
RPC requests between servers. It is only used to pool
connections in the rpcConsul mode. Raft connections
are pooled separately.

NewPool is used to make a new connection pool
Maintain at most one connection per host, for up to maxTime.
Set maxTime to 0 to disable reaping. maxStreams is used to control
the number of idle streams allowed.
If TLS settings are provided outgoing connections use TLS.

HalfCloser is an interface that exposes a TCP half-close. We need this
because we want to expose the raw TCP connection underlying a TLS one in a
way that's hard to screw up and use for anything else. There's a change
brewing that will allow us to use the TLS connection for this instead -
https://go-review.googlesource.com/#/c/25159/.

RaftRemovePeerByAddress is used to kick a stale peer (one that it in the Raft
quorum but no longer known to Serf or the catalog) by address in the form of
"IP:port". The reply argument is not used, but it required to fulfill the RPC
interface.

RaftRemovePeerByID is used to kick a stale peer (one that is in the Raft
quorum but no longer known to Serf or the catalog) by address in the form of
"IP:port". The reply argument is not used, but is required to fulfill the RPC
interface.

Execute runs a prepared query and returns the results. This will perform the
failover logic if no local results are available. This is typically called as
part of a DNS lookup, or when executing prepared queries from the HTTP API.

ExecuteRemote is used when a local node doesn't have any instances of a
service available and needs to probe remote DCs. This sends the full query
over since the remote side won't have it in its state store, and this doesn't
do the failover logic since that's already being run on the originating DC.
We don't want things to fan out further than one level.

Explain resolves a prepared query and returns the (possibly rendered template)
to the caller. This is useful for letting operators figure out which query is
picking up a given name. We can also add additional info about how the query
will be executed here.

StatsFetcher has two functions for autopilot. First, lets us fetch all the
stats in parallel so we are taking a sample as close to the same time as
possible, since we are comparing time-sensitive info for the health check.
Second, it bounds the time so that one slow RPC can't hold up the health
check loop; as a side effect of how it implements this, it also limits to
a single in-flight RPC to any given server, so goroutines don't accumulate
as we run the health check fairly frequently.

Read is used to perform a read-only transaction that doesn't modify the state
store. This is much more scaleable since it doesn't go through Raft and
supports staleness, so this should be preferred if you're just performing
reads.