Documentation
¶
Index ¶
Constants ¶
View Source
const ( DefaultServerWatchDisabledInterval = 1 * time.Minute DefaultBackOffInitialInterval = 500 * time.Millisecond DefaultBackOffMaxInterval = 60 * time.Second DefaultBackOffMultiplier = 1.5 DefaultBackOffRandomizationFactor = 0.5 DefaultBackOffResetInterval = 3 * DefaultBackOffMaxInterval )
Variables ¶
View Source
var ( ErrAlreadyLoggedOut = errors.New("already logged out") ErrAlreadyLoggedIn = errors.New("already logged in") )
View Source
var Gauges = []prometheus.GaugeDefinition{ { Name: []string{"consul_connected"}, Help: "This will either be 0 or 1 depending on whether the dataplane is currently connected to a Consul server.", }, { Name: []string{"connection_errors"}, Help: "This will track the number of errors encountered during the stream connection", }, }
View Source
var Summaries = []prometheus.SummaryDefinition{ { Name: []string{"connect_duration"}, Help: "This will be a sample of the time it takes to get connected to a server. This duration will cover everything from making the server features request all the way through to opening an xDS session with a server", }, { Name: []string{"discover_servers_duration"}, Help: "This will be a sample of the time it takes to discover Consul server IPs.", }, { Name: []string{"login_duration"}, Help: "This will be a sample of the time it takes to login to Consul.", }, }
Functions ¶
This section is empty.
Types ¶
type BackOffConfig ¶
type BackOffConfig struct {
// InitialInterval is initial backoff retry interval for exponential backoff. Default: 500ms.
InitialInterval time.Duration
// Multiplier is the factor by which the backoff retry interval increases on each subsequent
// retry. Default: 1.5.
Multiplier float64
// MaxInterval is the maximum backoff interval for exponential backoff. Default: 1m.
MaxInterval time.Duration
// RandomizationFactor randomizes the backoff retry interval using the formula:
// RetryInterval * (random value in range [1-RandomizationFactor, 1+RandomizationFactor])
// Default: 0.5.
RandomizationFactor float64
// ResetInterval determines how long before resetting the backoff policy, If we are in a good
// state for at least this interval, then exponential backoff is reset. Default: 3m.
ResetInterval time.Duration
}
type Config ¶
type Config struct {
// Addresses is a DNS name or exec command for go-netaddrs.
Addresses string
// GRPCPort is the gRPC port to connect to. This must be the
// same for all Consul servers for now. Defaults to 8502.
GRPCPort int
// ServerWatchDisabled disables opening the ServerWatch gRPC stream. This
// should be used when your Consul servers are behind a load balancer, for
// example, since the server addresses returned in the ServerWatch stream
// will differ from the load balancer address.
ServerWatchDisabled bool
// ServerWatchDisabledInterval is the amount of time to sleep if
// ServerWatchDisabled=true or when connecting to a server that does not
// support the server watch stream. When the Watcher wakes up, it will
// check that the current server is still OK and then continue sleeping. If
// the current server is not OK, then it will switch to another server.
//
// This defaults to 1 minute.
ServerWatchDisabledInterval time.Duration
// ServerEvalFn is optional. It can be used to exclude servers based on
// custom criteria. If not nil, it is called after connecting to a server
// but prior to marking the server "current". When this returns false,
// the Watcher will skip the server.
//
// The State passed to this function will be valid. The GRPCConn will be
// valid to use and DataplaneFeatures will be populated and the Address
// and Token (if applicable) will be set.
//
// This is called synchronously in the same goroutine as Watcher.Run(),
// so it should not block, or at least not for too long.
//
// To filter dataplane features, you can use the SupportsDataplaneFeatures
// helper, `cfg.ServerEvalFn = SupportsDataplaneFeatures("<feature-name>")`.
ServerEvalFn ServerEvalFn
// TLS contains the TLS settings to use for the gRPC connections to the
// Consul servers. By default this is nil, indicating that TLS is disabled.
//
// If unset, the ServerName field is automatically set if Addresses
// contains a DNS hostname. The ServerName field is only set if TLS and TLS
// verification are enabled.
TLS *tls.Config
Credentials Credentials
BackOff BackOffConfig
}
type Credentials ¶
type Credentials struct {
// Type is either "static" for a statically-configured ACL
// token, or "login" to obtain an ACL token by logging into a
// Consul auth method.
Type CredentialsType
// Static is used if Type is "static".
Static StaticTokenCredential
// Login is used if Type is "login".
Login LoginCredential
}
type CredentialsType ¶
type CredentialsType string
const ( CredentialsTypeStatic CredentialsType = "static" CredentialsTypeLogin CredentialsType = "login" )
type LoginCredential ¶
type LoginCredential struct {
// AuthMethod is the name of the Consul auth method.
AuthMethod string
// Namespace is the namespace containing the auth method.
Namespace string
// Partition is the partition containing the auth method.
Partition string
// Datacenter is the datacenter containing the auth method.
Datacenter string
// BearerToken is the bearer token presented to the auth method.
BearerToken string
// Meta is the arbitrary set of key-value pairs to attach to the
// token. These are included in the Description field of the token.
Meta map[string]string
}
type NetaddrsDiscoverer ¶
type NetaddrsDiscoverer struct {
// contains filtered or unexported fields
}
func NewNetaddrsDiscoverer ¶
func NewNetaddrsDiscoverer(config Config, log hclog.Logger) *NetaddrsDiscoverer
type ServerEvalFn ¶
func SupportsDataplaneFeatures ¶
func SupportsDataplaneFeatures(names ...string) ServerEvalFn
SupportsDataplaneFeatures returns a ServerEvalFn that selects Consul servers that support a list of given dataplane features.
The following are dataplane feature name strings:
"DATAPLANE_FEATURES_WATCH_SERVERS" "DATAPLANE_FEATURES_EDGE_CERTIFICATE_MANAGEMENT" "DATAPLANE_FEATURES_ENVOY_BOOTSTRAP_CONFIGURATION"
See the hashicorp/consul/proto-public package for a up-to-date list.
type State ¶
type State struct {
// GRPCConn is the gRPC connection shared with this library. Use
// this to create your gRPC clients. The gRPC connection is
// automatically updated to switch to a new server, so you can
// use this connection for the lifetime of the associated
// Watcher.
GRPCConn *grpc.ClientConn
// Token is the ACL token obtain from logging in (if applicable).
// If login is not supported this will be set to the static token
// from the Config object.
Token string
// Address is the address of current the Consul server the Watcher is using.
Address Addr
// DataplaneFeatures contains the dataplane features supported by the
// current Consul server.
DataplaneFeatures map[string]bool
}
State is the info a caller wants to know after initialization.
type StaticTokenCredential ¶
type StaticTokenCredential struct {
// Token is a static ACL token used for gRPC requests to the
// Consul servers.
Token string
}
type SystemClock ¶
type SystemClock struct{}
func (*SystemClock) Now ¶
func (*SystemClock) Now() time.Time
func (*SystemClock) Sleep ¶
func (*SystemClock) Sleep(d time.Duration)
type Watcher ¶
type Watcher struct {
// contains filtered or unexported fields
}
func NewWatcher ¶
func (*Watcher) Run ¶
func (w *Watcher) Run()
Run watches for Consul server set changes forever. Run should be called in a goroutine. Run can be aborted by cancelling the context passed to NewWatcher or by calling Stop. Call State after Run in order to wait for initialization to complete.
w, _ := NewWatcher(ctx, ...) go w.Run() state, err := w.State()
func (*Watcher) State ¶
State returns the current state. This blocks for initialization to complete, after which it will have found a Consul server, completed ACL token login (if applicable), and retrieved supported dataplane features.
Run must be called or State will never return. State can be aborted by cancelling the context passed to NewWatcher or by calling Stop.
func (*Watcher) Stop ¶
func (w *Watcher) Stop()
Stop stops the Watcher after Run is called. This logs out of the auth method, if applicable, waits for the Watcher's Run method to return, and closes the gRPC connection. After calling Stop, the Watcher and the gRPC connection are no longer valid to use.
Source Files
Click to show internal directories.
Click to hide internal directories.