structs

package
v1.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 12, 2018 License: MPL-2.0 Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// ACLBootstrapInit is used to perform a scan for existing tokens which
	// will decide whether bootstrapping is allowed for a cluster. This is
	// initiated by the leader when it steps up, if necessary.
	ACLBootstrapInit = "bootstrap-init"

	// ACLBootstrapNow is used to perform a one-time ACL bootstrap operation on
	// a cluster to get the first management token.
	ACLBootstrapNow = "bootstrap-now"

	// ACLSet creates or updates a token.
	ACLSet ACLOp = "set"

	// ACLForceSet is deprecated, but left for backwards compatibility.
	ACLForceSet = "force-set"

	// ACLDelete deletes a token.
	ACLDelete = "delete"
)
View Source
const (
	// ACLTypeClient tokens have rules applied
	ACLTypeClient = "client"

	// ACLTypeManagement tokens have an always allow policy, so they can
	// make other tokens and can access all resources.
	ACLTypeManagement = "management"
)
View Source
const (
	SerfCheckID           types.CheckID = "serfHealth"
	SerfCheckName                       = "Serf Health Status"
	SerfCheckAliveOutput                = "Agent alive and reachable"
	SerfCheckFailedOutput               = "Agent not live or unreachable"
)

These are used to manage the built-in "serfHealth" check that's attached to every node in the catalog.

View Source
const (
	// These are used to manage the "consul" service that's attached to every
	// Consul server node in the catalog.
	ConsulServiceID   = "consul"
	ConsulServiceName = "consul"
)
View Source
const (
	ConsulCAProvider = "consul"
	VaultCAProvider  = "vault"
)
View Source
const (
	// IntentionWildcard is the wildcard value.
	IntentionWildcard = "*"

	// IntentionDefaultNamespace is the default namespace value.
	// NOTE(mitchellh): This is only meant to be a temporary constant.
	// When namespaces are introduced, we should delete this constant and
	// fix up all the places where this was used with the proper namespace
	// value.
	IntentionDefaultNamespace = "default"
)
View Source
const (
	RegisterRequestType        MessageType = 0
	DeregisterRequestType                  = 1
	KVSRequestType                         = 2
	SessionRequestType                     = 3
	ACLRequestType                         = 4
	TombstoneRequestType                   = 5
	CoordinateBatchUpdateType              = 6
	PreparedQueryRequestType               = 7
	TxnRequestType                         = 8
	AutopilotRequestType                   = 9
	AreaRequestType                        = 10
	ACLBootstrapRequestType                = 11 // FSM snapshots only.
	IntentionRequestType                   = 12
	ConnectCARequestType                   = 13
	ConnectCAProviderStateType             = 14
)

These are serialized between Consul servers and stored in Consul snapshots, so entries must only ever be added.

View Source
const (
	// IgnoreUnknownTypeFlag is set along with a MessageType
	// to indicate that the message type can be safely ignored
	// if it is not recognized. This is for future proofing, so
	// that new commands can be added in a way that won't cause
	// old servers to crash when the FSM attempts to process them.
	IgnoreUnknownTypeFlag MessageType = 128

	// NodeMaint is the special key set by a node in maintenance mode.
	NodeMaint = "_node_maintenance"

	// ServiceMaintPrefix is the prefix for a service in maintenance mode.
	ServiceMaintPrefix = "_service_maintenance:"

	// MetaSegmentKey is the node metadata key used to store the node's network segment
	MetaSegmentKey = "consul-network-segment"

	// MaxLockDelay provides a maximum LockDelay value for
	// a session. Any value above this will not be respected.
	MaxLockDelay = 60 * time.Second
)
View Source
const (
	SessionTTLMax        = 24 * time.Hour
	SessionTTLMultiplier = 2
)
View Source
const (
	KeyringList    KeyringOp = "list"
	KeyringInstall           = "install"
	KeyringUse               = "use"
	KeyringRemove            = "remove"
)
View Source
const (
	// QueryTemplateTypeNamePrefixMatch uses the Name field of the query as
	// a prefix to select the template.
	QueryTemplateTypeNamePrefixMatch = "name_prefix_match"
)

Variables

View Source
var (
	ErrNoLeader                   = errors.New(errNoLeader)
	ErrNoDCPath                   = errors.New(errNoDCPath)
	ErrNoServers                  = errors.New(errNoServers)
	ErrNotReadyForConsistentReads = errors.New(errNotReadyForConsistentReads)
	ErrSegmentsNotSupported       = errors.New(errSegmentsNotSupported)
	ErrRPCRateExceeded            = errors.New(errRPCRateExceeded)
)
View Source
var ACLBootstrapNotAllowedErr = errors.New("ACL bootstrap no longer allowed")

ACLBootstrapNotAllowedErr is returned once we know that a bootstrap can no longer be done since the cluster was bootstrapped, or a management token was created manually.

View Source
var ACLBootstrapNotInitializedErr = errors.New("ACL bootstrap not initialized, need to force a leader election and ensure all Consul servers support this feature")

ACLBootstrapNotInitializedErr is returned when a bootstrap is attempted but we haven't yet initialized ACL bootstrap. It provides some guidance to operators on how to proceed.

Functions

func Decode

func Decode(buf []byte, out interface{}) error

Decode is used to decode a MsgPack encoded object

func Encode

func Encode(t MessageType, msg interface{}) ([]byte, error)

Encode is used to encode a MsgPack object with type prefix

func IsErrNoLeader added in v1.0.0

func IsErrNoLeader(err error) bool

func IsErrRPCRateExceeded added in v0.9.3

func IsErrRPCRateExceeded(err error) bool

func SatisfiesMetaFilters

func SatisfiesMetaFilters(meta map[string]string, filters map[string]string) bool

SatisfiesMetaFilters returns true if the metadata map contains the given filters

func ValidStatus

func ValidStatus(s string) bool

func ValidateMetadata

func ValidateMetadata(meta map[string]string, allowConsulPrefix bool) error

ValidateMeta validates a set of key/value pairs from the agent config

Types

type ACL

type ACL struct {
	ID    string
	Name  string
	Type  string
	Rules string

	RaftIndex
}

ACL is used to represent a token and its rules

func (*ACL) IsSame

func (a *ACL) IsSame(other *ACL) bool

IsSame checks if one ACL is the same as another, without looking at the Raft information (that's why we didn't call it IsEqual). This is useful for seeing if an update would be idempotent for all the functional parts of the structure.

type ACLBootstrap

type ACLBootstrap struct {
	// AllowBootstrap will only be true if no existing management tokens
	// have been found.
	AllowBootstrap bool

	RaftIndex
}

ACLBootstrap keeps track of whether bootstrapping ACLs is allowed for a cluster.

type ACLOp

type ACLOp string

ACLOp is used in RPCs to encode ACL operations.

type ACLPolicy

type ACLPolicy struct {
	ETag   string
	Parent string
	Policy *acl.Policy
	TTL    time.Duration
	QueryMeta
}

ACLPolicy is a policy that can be associated with a token.

type ACLPolicyRequest

type ACLPolicyRequest struct {
	Datacenter string
	ACL        string
	ETag       string
	QueryOptions
}

ACLPolicyRequest is used to request an ACL by ID, conditionally filtering on an ID

func (*ACLPolicyRequest) RequestDatacenter

func (r *ACLPolicyRequest) RequestDatacenter() string

RequestDatacenter returns the DC this request is targeted to.

type ACLReplicationStatus

type ACLReplicationStatus struct {
	Enabled          bool
	Running          bool
	SourceDatacenter string
	ReplicatedIndex  uint64
	LastSuccess      time.Time
	LastError        time.Time
}

ACLReplicationStatus provides information about the health of the ACL replication system.

type ACLRequest

type ACLRequest struct {
	Datacenter string
	Op         ACLOp
	ACL        ACL
	WriteRequest
}

ACLRequest is used to create, update or delete an ACL

func (*ACLRequest) RequestDatacenter

func (r *ACLRequest) RequestDatacenter() string

type ACLRequests

type ACLRequests []*ACLRequest

ACLRequests is a list of ACL change requests.

type ACLSpecificRequest

type ACLSpecificRequest struct {
	Datacenter string
	ACL        string
	QueryOptions
}

ACLSpecificRequest is used to request an ACL by ID

func (*ACLSpecificRequest) RequestDatacenter

func (r *ACLSpecificRequest) RequestDatacenter() string

RequestDatacenter returns the DC this request is targeted to.

type ACLs

type ACLs []*ACL

ACLs is a slice of ACLs.

type AutopilotSetConfigRequest

type AutopilotSetConfigRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Config is the new Autopilot configuration to use.
	Config autopilot.Config

	// CAS controls whether to use check-and-set semantics for this request.
	CAS bool

	// WriteRequest holds the ACL token to go along with this request.
	WriteRequest
}

AutopilotSetConfigRequest is used by the Operator endpoint to update the current Autopilot configuration of the cluster.

func (*AutopilotSetConfigRequest) RequestDatacenter

func (op *AutopilotSetConfigRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type CAConfiguration added in v1.2.0

type CAConfiguration struct {
	// ClusterID is a unique identifier for the cluster
	ClusterID string `json:"-"`

	// Provider is the CA provider implementation to use.
	Provider string

	// Configuration is arbitrary configuration for the provider. This
	// should only contain primitive values and containers (such as lists
	// and maps).
	Config map[string]interface{}

	RaftIndex
}

CAConfiguration is the configuration for the current CA plugin.

type CAConsulProviderState added in v1.2.0

type CAConsulProviderState struct {
	ID         string
	PrivateKey string
	RootCert   string

	RaftIndex
}

CAConsulProviderState is used to track the built-in Consul CA provider's state.

type CAOp added in v1.2.0

type CAOp string

CAOp is the operation for a request related to intentions.

const (
	CAOpSetRoots            CAOp = "set-roots"
	CAOpSetConfig           CAOp = "set-config"
	CAOpSetProviderState    CAOp = "set-provider-state"
	CAOpDeleteProviderState CAOp = "delete-provider-state"
	CAOpSetRootsAndConfig   CAOp = "set-roots-config"
)

type CARequest added in v1.2.0

type CARequest struct {
	// Op is the type of operation being requested. This determines what
	// other fields are required.
	Op CAOp

	// Datacenter is the target for this request.
	Datacenter string

	// Index is used by CAOpSetRoots and CAOpSetConfig for a CAS operation.
	Index uint64

	// Roots is a list of roots. This is used for CAOpSet. One root must
	// always be active.
	Roots []*CARoot

	// Config is the configuration for the current CA plugin.
	Config *CAConfiguration

	// ProviderState is the state for the builtin CA provider.
	ProviderState *CAConsulProviderState

	// WriteRequest is a common struct containing ACL tokens and other
	// write-related common elements for requests.
	WriteRequest
}

CARequest is used to modify connect CA data. This is used by the FSM (agent/consul/fsm) to apply changes.

func (*CARequest) RequestDatacenter added in v1.2.0

func (q *CARequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type CARoot added in v1.2.0

type CARoot struct {
	// ID is a globally unique ID (UUID) representing this CA root.
	ID string

	// Name is a human-friendly name for this CA root. This value is
	// opaque to Consul and is not used for anything internally.
	Name string

	// SerialNumber is the x509 serial number of the certificate.
	SerialNumber uint64

	// SigningKeyID is the ID of the public key that corresponds to the
	// private key used to sign the certificate.
	SigningKeyID string

	// Time validity bounds.
	NotBefore time.Time
	NotAfter  time.Time

	// RootCert is the PEM-encoded public certificate.
	RootCert string

	// IntermediateCerts is a list of PEM-encoded intermediate certs to
	// attach to any leaf certs signed by this CA.
	IntermediateCerts []string

	// SigningCert is the PEM-encoded signing certificate and SigningKey
	// is the PEM-encoded private key for the signing certificate. These
	// may actually be empty if the CA plugin in use manages these for us.
	SigningCert string `json:",omitempty"`
	SigningKey  string `json:",omitempty"`

	// Active is true if this is the current active CA. This must only
	// be true for exactly one CA. For any method that modifies roots in the
	// state store, tests should be written to verify that multiple roots
	// cannot be active.
	Active bool

	// RotatedOutAt is the time at which this CA was removed from the state.
	// This will only be set on roots that have been rotated out from being the
	// active root.
	RotatedOutAt time.Time `json:"-"`

	RaftIndex
}

CARoot represents a root CA certificate that is trusted.

type CARoots added in v1.2.0

type CARoots []*CARoot

CARoots is a list of CARoot structures.

type CASignRequest added in v1.2.0

type CASignRequest struct {
	// Datacenter is the target for this request.
	Datacenter string

	// CSR is the PEM-encoded CSR.
	CSR string

	// WriteRequest is a common struct containing ACL tokens and other
	// write-related common elements for requests.
	WriteRequest
}

CASignRequest is the request for signing a service certificate.

func (*CASignRequest) RequestDatacenter added in v1.2.0

func (q *CASignRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type CheckDefinition

type CheckDefinition struct {
	ID        types.CheckID
	Name      string
	Notes     string
	ServiceID string
	Token     string
	Status    string

	// Copied fields from CheckType without the fields
	// already present in CheckDefinition:
	//
	//   ID (CheckID), Name, Status, Notes
	//
	ScriptArgs                     []string
	HTTP                           string
	Header                         map[string][]string
	Method                         string
	TCP                            string
	Interval                       time.Duration
	DockerContainerID              string
	Shell                          string
	GRPC                           string
	GRPCUseTLS                     bool
	TLSSkipVerify                  bool
	Timeout                        time.Duration
	TTL                            time.Duration
	DeregisterCriticalServiceAfter time.Duration
}

CheckDefinition is used to JSON decode the Check definitions

func (*CheckDefinition) CheckType

func (c *CheckDefinition) CheckType() *CheckType

func (*CheckDefinition) HealthCheck

func (c *CheckDefinition) HealthCheck(node string) *HealthCheck

type CheckServiceNode

type CheckServiceNode struct {
	Node    *Node
	Service *NodeService
	Checks  HealthChecks
}

CheckServiceNode is used to provide the node, its service definition, as well as a HealthCheck that is associated.

type CheckServiceNodes

type CheckServiceNodes []CheckServiceNode

func (CheckServiceNodes) Filter

func (nodes CheckServiceNodes) Filter(onlyPassing bool) CheckServiceNodes

Filter removes nodes that are failing health checks (and any non-passing check if that option is selected). Note that this returns the filtered results AND modifies the receiver for performance.

func (CheckServiceNodes) FilterIgnore added in v1.0.7

func (nodes CheckServiceNodes) FilterIgnore(onlyPassing bool,
	ignoreCheckIDs []types.CheckID) CheckServiceNodes

FilterIgnore removes nodes that are failing health checks just like Filter. It also ignores the status of any check with an ID present in ignoreCheckIDs as if that check didn't exist. Note that this returns the filtered results AND modifies the receiver for performance.

func (CheckServiceNodes) Shuffle

func (nodes CheckServiceNodes) Shuffle()

Shuffle does an in-place random shuffle using the Fisher-Yates algorithm.

type CheckType

type CheckType struct {
	CheckID types.CheckID
	Name    string
	Status  string
	Notes   string

	ScriptArgs        []string
	HTTP              string
	Header            map[string][]string
	Method            string
	TCP               string
	Interval          time.Duration
	DockerContainerID string
	Shell             string
	GRPC              string
	GRPCUseTLS        bool
	TLSSkipVerify     bool
	Timeout           time.Duration
	TTL               time.Duration

	// DeregisterCriticalServiceAfter, if >0, will cause the associated
	// service, if any, to be deregistered if this check is critical for
	// longer than this duration.
	DeregisterCriticalServiceAfter time.Duration
}

CheckType is used to create either the CheckMonitor or the CheckTTL. Six types are supported: Script, HTTP, TCP, Docker, TTL and GRPC. Script, HTTP, Docker, TCP and GRPC all require Interval. Only one of the types may to be provided: TTL or Script/Interval or HTTP/Interval or TCP/Interval or Docker/Interval or GRPC/Interval.

func (*CheckType) Empty added in v1.0.0

func (c *CheckType) Empty() bool

Empty checks if the CheckType has no fields defined. Empty checks parsed from json configs are filtered out

func (*CheckType) IsDocker

func (c *CheckType) IsDocker() bool

IsDocker returns true when checking a docker container.

func (*CheckType) IsGRPC added in v1.0.4

func (c *CheckType) IsGRPC() bool

IsGRPC checks if this is a GRPC type

func (*CheckType) IsHTTP

func (c *CheckType) IsHTTP() bool

IsHTTP checks if this is a HTTP type

func (*CheckType) IsMonitor

func (c *CheckType) IsMonitor() bool

IsMonitor checks if this is a Monitor type

func (*CheckType) IsScript

func (c *CheckType) IsScript() bool

IsScript checks if this is a check that execs some kind of script.

func (*CheckType) IsTCP

func (c *CheckType) IsTCP() bool

IsTCP checks if this is a TCP type

func (*CheckType) IsTTL

func (c *CheckType) IsTTL() bool

IsTTL checks if this is a TTL type

func (*CheckType) Validate added in v1.0.0

func (c *CheckType) Validate() error

Validate returns an error message if the check is invalid

type CheckTypes

type CheckTypes []*CheckType

type ChecksInStateRequest

type ChecksInStateRequest struct {
	Datacenter      string
	NodeMetaFilters map[string]string
	State           string
	Source          QuerySource
	QueryOptions
}

ChecksInStateRequest is used to query for nodes in a state

func (*ChecksInStateRequest) RequestDatacenter

func (r *ChecksInStateRequest) RequestDatacenter() string

type CompoundResponse

type CompoundResponse interface {
	// Add adds a new response to the compound response
	Add(interface{})

	// New returns an empty response object which can be passed around by
	// reference, and then passed to Add() later on.
	New() interface{}
}

CompoundResponse is an interface for gathering multiple responses. It is used in cross-datacenter RPC calls where more than 1 datacenter is expected to reply.

type ConnectAuthorizeRequest added in v1.2.0

type ConnectAuthorizeRequest struct {
	// Target is the name of the service that is being requested.
	Target string

	// ClientCertURI is a unique identifier for the requesting client. This
	// is currently the URI SAN from the TLS client certificate.
	//
	// ClientCertSerial is a colon-hex-encoded of the serial number for
	// the requesting client cert. This is used to check against revocation
	// lists.
	ClientCertURI    string
	ClientCertSerial string
}

ConnectAuthorizeRequest is the structure of a request to authorize a connection.

type ConnectManagedProxy added in v1.2.0

type ConnectManagedProxy struct {
	// ExecMode is one of daemon or script.
	ExecMode ProxyExecMode

	// Command is the command to execute. Empty defaults to self-invoking the same
	// consul binary with proxy subcomand for ProxyExecModeDaemon and is an error
	// for ProxyExecModeScript.
	Command []string

	// Config is the arbitrary configuration data provided with the registration.
	Config map[string]interface{}

	// ProxyService is a pointer to the local proxy's service record for
	// convenience. The proxies ID and name etc. can be read from there. It may be
	// nil if the agent is starting up and hasn't registered the service yet. We
	// ignore it when calculating the hash value since the only thing that effects
	// the proxy's config is the ID of the target service which is already
	// represented below.
	ProxyService *NodeService `hash:"ignore"`

	// TargetServiceID is the ID of the target service on the localhost. It may
	// not exist yet since bootstrapping is allowed to happen in either order.
	TargetServiceID string
}

ConnectManagedProxy represents the agent-local state for a configured proxy instance. This is never stored or sent to the servers and is only used to store the config for the proxy that the agent needs to track. For now it's really generic with only the fields the agent needs to act on defined while the rest of the proxy config is passed as opaque bag of attributes to support arbitrary config params for third-party proxy integrations. "External" proxies by definition register themselves and manage their own config externally so are never represented in agent state.

func (*ConnectManagedProxy) ParseConfig added in v1.2.0

ParseConfig attempts to read the fields we care about from the otherwise opaque config map. They are all optional but it may fail if one is specified but an invalid value.

type ConnectManagedProxyConfig added in v1.2.0

type ConnectManagedProxyConfig struct {
	BindAddress string `mapstructure:"bind_address"`
	BindPort    int    `mapstructure:"bind_port"`
}

ConnectManagedProxyConfig represents the parts of the proxy config the agent needs to understand. It's bad UX to make the user specify these separately just to make parsing simpler for us so this encapsulates the fields in ConnectManagedProxy.Config that we care about. They are all optional anyway and this is used to decode them with mapstructure.

type ConsulCAProviderConfig added in v1.2.0

type ConsulCAProviderConfig struct {
	PrivateKey     string
	RootCert       string
	RotationPeriod time.Duration
}

type Coordinate

type Coordinate struct {
	Node    string
	Segment string
	Coord   *coordinate.Coordinate
}

Coordinate stores a node name with its associated network coordinate.

type CoordinateUpdateRequest

type CoordinateUpdateRequest struct {
	Datacenter string
	Node       string
	Segment    string
	Coord      *coordinate.Coordinate
	WriteRequest
}

CoordinateUpdateRequest is used to update the network coordinate of a given node.

func (*CoordinateUpdateRequest) RequestDatacenter

func (c *CoordinateUpdateRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given update request.

type Coordinates

type Coordinates []*Coordinate

type DCSpecificRequest

type DCSpecificRequest struct {
	Datacenter      string
	NodeMetaFilters map[string]string
	Source          QuerySource
	QueryOptions
}

DCSpecificRequest is used to query about a specific DC

func (*DCSpecificRequest) CacheInfo added in v1.2.0

func (r *DCSpecificRequest) CacheInfo() cache.RequestInfo

func (*DCSpecificRequest) CacheMinIndex added in v1.2.0

func (r *DCSpecificRequest) CacheMinIndex() uint64

func (*DCSpecificRequest) RequestDatacenter

func (r *DCSpecificRequest) RequestDatacenter() string

type DatacenterMap

type DatacenterMap struct {
	Datacenter  string
	AreaID      types.AreaID
	Coordinates Coordinates
}

DatacenterMap is used to represent a list of nodes with their raw coordinates, associated with a datacenter. Coordinates are only compatible between nodes in the same area.

type DeregisterRequest

type DeregisterRequest struct {
	Datacenter string
	Node       string
	ServiceID  string
	CheckID    types.CheckID
	WriteRequest
}

DeregisterRequest is used for the Catalog.Deregister endpoint to deregister a node as providing a service. If no service is provided the entire node is deregistered.

func (*DeregisterRequest) RequestDatacenter

func (r *DeregisterRequest) RequestDatacenter() string

type DirEntries

type DirEntries []*DirEntry

type DirEntry

type DirEntry struct {
	LockIndex uint64
	Key       string
	Flags     uint64
	Value     []byte
	Session   string `json:",omitempty"`

	RaftIndex
}

DirEntry is used to represent a directory entry. This is used for values in our Key-Value store.

func (*DirEntry) Clone

func (d *DirEntry) Clone() *DirEntry

Returns a clone of the given directory entry.

type EventFireRequest

type EventFireRequest struct {
	Datacenter string
	Name       string
	Payload    []byte

	// Not using WriteRequest so that any server can process
	// the request. It is a bit unusual...
	QueryOptions
}

EventFireRequest is used to ask a server to fire a Serf event. It is a bit odd, since it doesn't depend on the catalog or leader. Any node can respond, so it's not quite like a standard write request. This is used only internally.

func (*EventFireRequest) RequestDatacenter

func (r *EventFireRequest) RequestDatacenter() string

type EventFireResponse

type EventFireResponse struct {
	QueryMeta
}

EventFireResponse is used to respond to a fire request.

type HealthCheck

type HealthCheck struct {
	Node        string
	CheckID     types.CheckID // Unique per-node ID
	Name        string        // Check name
	Status      string        // The current check status
	Notes       string        // Additional notes with the status
	Output      string        // Holds output of script runs
	ServiceID   string        // optional associated service
	ServiceName string        // optional service name
	ServiceTags []string      // optional service tags

	Definition HealthCheckDefinition

	RaftIndex
}

HealthCheck represents a single check on a given node

func (*HealthCheck) Clone

func (c *HealthCheck) Clone() *HealthCheck

Clone returns a distinct clone of the HealthCheck.

func (*HealthCheck) IsSame

func (c *HealthCheck) IsSame(other *HealthCheck) bool

IsSame checks if one HealthCheck is the same as another, without looking at the Raft information (that's why we didn't call it IsEqual). This is useful for seeing if an update would be idempotent for all the functional parts of the structure.

type HealthCheckDefinition added in v1.0.1

type HealthCheckDefinition struct {
	HTTP                           string               `json:",omitempty"`
	TLSSkipVerify                  bool                 `json:",omitempty"`
	Header                         map[string][]string  `json:",omitempty"`
	Method                         string               `json:",omitempty"`
	TCP                            string               `json:",omitempty"`
	Interval                       api.ReadableDuration `json:",omitempty"`
	Timeout                        api.ReadableDuration `json:",omitempty"`
	DeregisterCriticalServiceAfter api.ReadableDuration `json:",omitempty"`
}

type HealthChecks

type HealthChecks []*HealthCheck

HealthChecks is a collection of HealthCheck structs.

type IndexedACLs

type IndexedACLs struct {
	ACLs ACLs
	QueryMeta
}

IndexedACLs has tokens along with the Raft metadata about them.

type IndexedCARoots added in v1.2.0

type IndexedCARoots struct {
	// ActiveRootID is the ID of a root in Roots that is the active CA root.
	// Other roots are still valid if they're in the Roots list but are in
	// the process of being rotated out.
	ActiveRootID string

	// TrustDomain is the identification root for this Consul cluster. All
	// certificates signed by the cluster's CA must have their identifying URI in
	// this domain.
	//
	// This does not include the protocol (currently spiffe://) since we may
	// implement other protocols in future with equivalent semantics. It should be
	// compared against the "authority" section of a URI (i.e. host:port).
	//
	// NOTE(banks): Later we may support explicitly trusting external domains
	// which may be encoded into the CARoot struct or a separate list but this
	// domain identifier should be immutable and cluster-wide so deserves to be at
	// the root of this response rather than duplicated through all CARoots that
	// are not externally trusted entities.
	TrustDomain string

	// Roots is a list of root CA certs to trust.
	Roots []*CARoot

	// QueryMeta contains the meta sent via a header. We ignore for JSON
	// so this whole structure can be returned.
	QueryMeta `json:"-"`
}

IndexedCARoots is the list of currently trusted CA Roots.

type IndexedCheckServiceNodes

type IndexedCheckServiceNodes struct {
	Nodes CheckServiceNodes
	QueryMeta
}

type IndexedCoordinate

type IndexedCoordinate struct {
	Coord *coordinate.Coordinate
	QueryMeta
}

IndexedCoordinate is used to represent a single node's coordinate from the state store.

type IndexedCoordinates

type IndexedCoordinates struct {
	Coordinates Coordinates
	QueryMeta
}

IndexedCoordinates is used to represent a list of nodes and their corresponding raw coordinates.

type IndexedDirEntries

type IndexedDirEntries struct {
	Entries DirEntries
	QueryMeta
}

type IndexedHealthChecks

type IndexedHealthChecks struct {
	HealthChecks HealthChecks
	QueryMeta
}

type IndexedIntentionMatches added in v1.2.0

type IndexedIntentionMatches struct {
	Matches []Intentions
	QueryMeta
}

IndexedIntentionMatches represents the list of matches for a match query.

type IndexedIntentions added in v1.2.0

type IndexedIntentions struct {
	Intentions Intentions
	QueryMeta
}

IndexedIntentions represents a list of intentions for RPC responses.

type IndexedKeyList

type IndexedKeyList struct {
	Keys []string
	QueryMeta
}

type IndexedNodeDump

type IndexedNodeDump struct {
	Dump NodeDump
	QueryMeta
}

type IndexedNodeServices

type IndexedNodeServices struct {
	// TODO: This should not be a pointer, see comments in
	// agent/catalog_endpoint.go.
	NodeServices *NodeServices
	QueryMeta
}

type IndexedNodes

type IndexedNodes struct {
	Nodes Nodes
	QueryMeta
}

type IndexedPreparedQueries

type IndexedPreparedQueries struct {
	Queries PreparedQueries
	QueryMeta
}

type IndexedServiceNodes

type IndexedServiceNodes struct {
	ServiceNodes ServiceNodes
	QueryMeta
}

type IndexedServices

type IndexedServices struct {
	Services Services
	QueryMeta
}

type IndexedSessions

type IndexedSessions struct {
	Sessions Sessions
	QueryMeta
}

type Intention added in v1.2.0

type Intention struct {
	// ID is the UUID-based ID for the intention, always generated by Consul.
	ID string

	// Description is a human-friendly description of this intention.
	// It is opaque to Consul and is only stored and transferred in API
	// requests.
	Description string

	// SourceNS, SourceName are the namespace and name, respectively, of
	// the source service. Either of these may be the wildcard "*", but only
	// the full value can be a wildcard. Partial wildcards are not allowed.
	// The source may also be a non-Consul service, as specified by SourceType.
	//
	// DestinationNS, DestinationName is the same, but for the destination
	// service. The same rules apply. The destination is always a Consul
	// service.
	SourceNS, SourceName           string
	DestinationNS, DestinationName string

	// SourceType is the type of the value for the source.
	SourceType IntentionSourceType

	// Action is whether this is a whitelist or blacklist intention.
	Action IntentionAction

	// DefaultAddr, DefaultPort of the local listening proxy (if any) to
	// make this connection.
	DefaultAddr string
	DefaultPort int

	// Meta is arbitrary metadata associated with the intention. This is
	// opaque to Consul but is served in API responses.
	Meta map[string]string

	// Precedence is the order that the intention will be applied, with
	// larger numbers being applied first. This is a read-only field, on
	// any intention update it is updated.
	Precedence int

	// CreatedAt and UpdatedAt keep track of when this record was created
	// or modified.
	CreatedAt, UpdatedAt time.Time `mapstructure:"-"`

	RaftIndex
}

Intention defines an intention for the Connect Service Graph. This defines the allowed or denied behavior of a connection between two services using Connect.

func TestIntention added in v1.2.0

func TestIntention(t testing.T) *Intention

TestIntention returns a valid, uninserted (no ID set) intention.

func (*Intention) GetACLPrefix added in v1.2.0

func (x *Intention) GetACLPrefix() (string, bool)

GetACLPrefix returns the prefix to look up the ACL policy for this intention, and a boolean noting whether the prefix is valid to check or not. You must check the ok value before using the prefix.

func (*Intention) String added in v1.2.0

func (x *Intention) String() string

String returns a human-friendly string for this intention.

func (*Intention) UpdatePrecedence added in v1.2.0

func (x *Intention) UpdatePrecedence()

UpdatePrecedence sets the Precedence value based on the fields of this structure.

func (*Intention) Validate added in v1.2.0

func (x *Intention) Validate() error

Validate returns an error if the intention is invalid for inserting or updating.

type IntentionAction added in v1.2.0

type IntentionAction string

IntentionAction is the action that the intention represents. This can be "allow" or "deny" to whitelist or blacklist intentions.

const (
	IntentionActionAllow IntentionAction = "allow"
	IntentionActionDeny  IntentionAction = "deny"
)

type IntentionMatchEntry added in v1.2.0

type IntentionMatchEntry struct {
	Namespace string
	Name      string
}

IntentionMatchEntry is a single entry for matching an intention.

type IntentionMatchType added in v1.2.0

type IntentionMatchType string

IntentionMatchType is the target for a match request. For example, matching by source will look for all intentions that match the given source value.

const (
	IntentionMatchSource      IntentionMatchType = "source"
	IntentionMatchDestination IntentionMatchType = "destination"
)

type IntentionOp added in v1.2.0

type IntentionOp string

IntentionOp is the operation for a request related to intentions.

const (
	IntentionOpCreate IntentionOp = "create"
	IntentionOpUpdate IntentionOp = "update"
	IntentionOpDelete IntentionOp = "delete"
)

type IntentionPrecedenceSorter added in v1.2.0

type IntentionPrecedenceSorter Intentions

IntentionPrecedenceSorter takes a list of intentions and sorts them based on the match precedence rules for intentions. The intentions closer to the head of the list have higher precedence. i.e. index 0 has the highest precedence.

func (IntentionPrecedenceSorter) Len added in v1.2.0

func (IntentionPrecedenceSorter) Less added in v1.2.0

func (s IntentionPrecedenceSorter) Less(i, j int) bool

func (IntentionPrecedenceSorter) Swap added in v1.2.0

func (s IntentionPrecedenceSorter) Swap(i, j int)

type IntentionQueryCheck added in v1.2.0

type IntentionQueryCheck struct {
	// SourceNS, SourceName, DestinationNS, and DestinationName are the
	// source and namespace, respectively, for the test. These must be
	// exact values.
	SourceNS, SourceName           string
	DestinationNS, DestinationName string

	// SourceType is the type of the value for the source.
	SourceType IntentionSourceType
}

IntentionQueryCheck are the parameters for performing a test request.

func (*IntentionQueryCheck) GetACLPrefix added in v1.2.0

func (q *IntentionQueryCheck) GetACLPrefix() (string, bool)

GetACLPrefix returns the prefix to look up the ACL policy for this request, and a boolean noting whether the prefix is valid to check or not. You must check the ok value before using the prefix.

type IntentionQueryCheckResponse added in v1.2.0

type IntentionQueryCheckResponse struct {
	Allowed bool
}

IntentionQueryCheckResponse is the response for a test request.

type IntentionQueryMatch added in v1.2.0

type IntentionQueryMatch struct {
	Type    IntentionMatchType
	Entries []IntentionMatchEntry
}

IntentionQueryMatch are the parameters for performing a match request against the state store.

type IntentionQueryRequest added in v1.2.0

type IntentionQueryRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// IntentionID is the ID of a specific intention.
	IntentionID string

	// Match is non-nil if we're performing a match query. A match will
	// find intentions that "match" the given parameters. A match includes
	// resolving wildcards.
	Match *IntentionQueryMatch

	// Check is non-nil if we're performing a test query. A test will
	// return allowed/deny based on an exact match.
	Check *IntentionQueryCheck

	// Options for queries
	QueryOptions
}

IntentionQueryRequest is used to query intentions.

func (*IntentionQueryRequest) CacheInfo added in v1.2.0

func (q *IntentionQueryRequest) CacheInfo() cache.RequestInfo

CacheInfo implements cache.Request

func (*IntentionQueryRequest) RequestDatacenter added in v1.2.0

func (q *IntentionQueryRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type IntentionRequest added in v1.2.0

type IntentionRequest struct {
	// Datacenter is the target for this request.
	Datacenter string

	// Op is the type of operation being requested.
	Op IntentionOp

	// Intention is the intention.
	Intention *Intention

	// WriteRequest is a common struct containing ACL tokens and other
	// write-related common elements for requests.
	WriteRequest
}

IntentionRequest is used to create, update, and delete intentions.

func (*IntentionRequest) RequestDatacenter added in v1.2.0

func (q *IntentionRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type IntentionSourceType added in v1.2.0

type IntentionSourceType string

IntentionSourceType is the type of the source within an intention.

const (
	// IntentionSourceConsul is a service within the Consul catalog.
	IntentionSourceConsul IntentionSourceType = "consul"
)

type Intentions added in v1.2.0

type Intentions []*Intention

Intentions is a list of intentions.

type IssuedCert added in v1.2.0

type IssuedCert struct {
	// SerialNumber is the unique serial number for this certificate.
	// This is encoded in standard hex separated by :.
	SerialNumber string

	// CertPEM and PrivateKeyPEM are the PEM-encoded certificate and private
	// key for that cert, respectively. This should not be stored in the
	// state store, but is present in the sign API response.
	CertPEM       string `json:",omitempty"`
	PrivateKeyPEM string `json:",omitempty"`

	// Service is the name of the service for which the cert was issued.
	// ServiceURI is the cert URI value.
	Service    string
	ServiceURI string

	// ValidAfter and ValidBefore are the validity periods for the
	// certificate.
	ValidAfter  time.Time
	ValidBefore time.Time

	RaftIndex
}

IssuedCert is a certificate that has been issued by a Connect CA.

type KVSRequest

type KVSRequest struct {
	Datacenter string
	Op         api.KVOp // Which operation are we performing
	DirEnt     DirEntry // Which directory entry
	WriteRequest
}

KVSRequest is used to operate on the Key-Value store

func (*KVSRequest) RequestDatacenter

func (r *KVSRequest) RequestDatacenter() string

type KeyListRequest

type KeyListRequest struct {
	Datacenter string
	Prefix     string
	Seperator  string
	QueryOptions
}

KeyListRequest is used to list keys

func (*KeyListRequest) RequestDatacenter

func (r *KeyListRequest) RequestDatacenter() string

type KeyRequest

type KeyRequest struct {
	Datacenter string
	Key        string
	QueryOptions
}

KeyRequest is used to request a key, or key prefix

func (*KeyRequest) RequestDatacenter

func (r *KeyRequest) RequestDatacenter() string

type KeyringOp

type KeyringOp string

type KeyringRequest

type KeyringRequest struct {
	Operation   KeyringOp
	Key         string
	Datacenter  string
	Forwarded   bool
	RelayFactor uint8
	QueryOptions
}

KeyringRequest encapsulates a request to modify an encryption keyring. It can be used for install, remove, or use key type operations.

func (*KeyringRequest) RequestDatacenter

func (r *KeyringRequest) RequestDatacenter() string

type KeyringResponse

type KeyringResponse struct {
	WAN        bool
	Datacenter string
	Segment    string
	Messages   map[string]string `json:",omitempty"`
	Keys       map[string]int
	NumNodes   int
	Error      string `json:",omitempty"`
}

KeyringResponse is a unified key response and can be used for install, remove, use, as well as listing key queries.

type KeyringResponses

type KeyringResponses struct {
	Responses []*KeyringResponse
	QueryMeta
}

KeyringResponses holds multiple responses to keyring queries. Each datacenter replies independently, and KeyringResponses is used as a container for the set of all responses.

func (*KeyringResponses) Add

func (r *KeyringResponses) Add(v interface{})

func (*KeyringResponses) New

func (r *KeyringResponses) New() interface{}

type MessageType

type MessageType uint8

type NetworkSegment added in v1.0.0

type NetworkSegment struct {
	// Name is the name of the segment.
	Name string

	// Bind is the bind address for this segment.
	Bind *net.TCPAddr

	// Advertise is the advertise address of this segment.
	Advertise *net.TCPAddr

	// RPCListener is whether to bind a separate RPC listener on the bind address
	// for this segment.
	RPCListener bool
}

(Enterprise-only) NetworkSegment is the configuration for a network segment, which is an isolated serf group on the LAN.

type Node

type Node struct {
	ID              types.NodeID
	Node            string
	Address         string
	Datacenter      string
	TaggedAddresses map[string]string
	Meta            map[string]string

	RaftIndex
}

Used to return information about a node

type NodeDump

type NodeDump []*NodeInfo

NodeDump is used to dump all the nodes with all their associated data. This is currently used for the UI only, as it is rather expensive to generate.

type NodeInfo

type NodeInfo struct {
	ID              types.NodeID
	Node            string
	Address         string
	TaggedAddresses map[string]string
	Meta            map[string]string
	Services        []*NodeService
	Checks          HealthChecks
}

NodeInfo is used to dump all associated information about a node. This is currently used for the UI only, as it is rather expensive to generate.

type NodeService

type NodeService struct {
	// Kind is the kind of service this is. Different kinds of services may
	// have differing validation, DNS behavior, etc. An empty kind will default
	// to the Default kind. See ServiceKind for the full list of kinds.
	Kind ServiceKind `json:",omitempty"`

	ID                string
	Service           string
	Tags              []string
	Address           string
	Meta              map[string]string
	Port              int
	EnableTagOverride bool

	// ProxyDestination is the name of the service that this service is
	// a Connect proxy for. This is only valid if Kind is "connect-proxy".
	// The destination may be a service that isn't present in the catalog.
	// This is expected and allowed to allow for proxies to come up
	// earlier than their target services.
	ProxyDestination string

	// Connect are the Connect settings for a service. This is purposely NOT
	// a pointer so that we never have to nil-check this.
	Connect ServiceConnect

	RaftIndex
}

NodeService is a service provided by a node

func TestNodeService added in v1.2.0

func TestNodeService(t testing.T) *NodeService

TestNodeService returns a *NodeService representing a valid regular service.

func TestNodeServiceProxy added in v1.2.0

func TestNodeServiceProxy(t testing.T) *NodeService

TestNodeServiceProxy returns a *NodeService representing a valid Connect proxy.

func (*NodeService) IsSame

func (s *NodeService) IsSame(other *NodeService) bool

IsSame checks if one NodeService is the same as another, without looking at the Raft information (that's why we didn't call it IsEqual). This is useful for seeing if an update would be idempotent for all the functional parts of the structure.

func (*NodeService) ToServiceNode

func (s *NodeService) ToServiceNode(node string) *ServiceNode

ToServiceNode converts the given node service to a service node.

func (*NodeService) Validate added in v1.2.0

func (s *NodeService) Validate() error

Validate validates the node service configuration.

NOTE(mitchellh): This currently only validates fields for a ConnectProxy. Historically validation has been directly in the Catalog.Register RPC. ConnectProxy validation was moved here for easier table testing, but other validation still exists in Catalog.Register.

type NodeServices

type NodeServices struct {
	Node     *Node
	Services map[string]*NodeService
}

type NodeSpecificRequest

type NodeSpecificRequest struct {
	Datacenter string
	Node       string
	QueryOptions
}

NodeSpecificRequest is used to request the information about a single node

func (*NodeSpecificRequest) RequestDatacenter

func (r *NodeSpecificRequest) RequestDatacenter() string

type Nodes

type Nodes []*Node

type PreparedQueries

type PreparedQueries []*PreparedQuery

type PreparedQuery

type PreparedQuery struct {
	// ID is this UUID-based ID for the query, always generated by Consul.
	ID string

	// Name is an optional friendly name for the query supplied by the
	// user. NOTE - if this feature is used then it will reduce the security
	// of any read ACL associated with this query/service since this name
	// can be used to locate nodes with supplying any ACL.
	Name string

	// Session is an optional session to tie this query's lifetime to. If
	// this is omitted then the query will not expire.
	Session string

	// Token is the ACL token used when the query was created, and it is
	// used when a query is subsequently executed. This token, or a token
	// with management privileges, must be used to change the query later.
	Token string

	// Template is used to configure this query as a template, which will
	// respond to queries based on the Name, and then will be rendered
	// before it is executed.
	Template QueryTemplateOptions

	// Service defines a service query (leaving things open for other types
	// later).
	Service ServiceQuery

	// DNS has options that control how the results of this query are
	// served over DNS.
	DNS QueryDNSOptions

	RaftIndex
}

PreparedQuery defines a complete prepared query, and is the structure we maintain in the state store.

func (*PreparedQuery) GetACLPrefix

func (pq *PreparedQuery) GetACLPrefix() (string, bool)

GetACLPrefix returns the prefix to look up the prepared_query ACL policy for this query, and whether the prefix applies to this query. You always need to check the ok value before using the prefix.

type PreparedQueryExecuteRemoteRequest

type PreparedQueryExecuteRemoteRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Query is a copy of the query to execute.  We have to ship the entire
	// query over since it won't be present in the remote state store.
	Query PreparedQuery

	// Limit will trim the resulting list down to the given limit.
	Limit int

	// Connect is the same as ExecuteRequest.
	Connect bool

	// QueryOptions (unfortunately named here) controls the consistency
	// settings for the the service lookups.
	QueryOptions
}

PreparedQueryExecuteRemoteRequest is used when running a local query in a remote datacenter.

func (*PreparedQueryExecuteRemoteRequest) RequestDatacenter

func (q *PreparedQueryExecuteRemoteRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQueryExecuteRequest

type PreparedQueryExecuteRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// QueryIDOrName is the ID of a query _or_ the name of one, either can
	// be provided.
	QueryIDOrName string

	// Limit will trim the resulting list down to the given limit.
	Limit int

	// Connect will force results to be Connect-enabled nodes for the
	// matching services. This is equivalent in semantics exactly to
	// setting "Connect" in the query template itself, but allows callers
	// to use any prepared query in a Connect setting.
	Connect bool

	// Source is used to sort the results relative to a given node using
	// network coordinates.
	Source QuerySource

	// Agent is used to carry around a reference to the agent which initiated
	// the execute request. Used to distance-sort relative to the local node.
	Agent QuerySource

	// QueryOptions (unfortunately named here) controls the consistency
	// settings for the query lookup itself, as well as the service lookups.
	QueryOptions
}

PreparedQueryExecuteRequest is used to execute a prepared query.

func (*PreparedQueryExecuteRequest) RequestDatacenter

func (q *PreparedQueryExecuteRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQueryExecuteResponse

type PreparedQueryExecuteResponse struct {
	// Service is the service that was queried.
	Service string

	// Nodes has the nodes that were output by the query.
	Nodes CheckServiceNodes

	// DNS has the options for serving these results over DNS.
	DNS QueryDNSOptions

	// Datacenter is the datacenter that these results came from.
	Datacenter string

	// Failovers is a count of how many times we had to query a remote
	// datacenter.
	Failovers int

	// QueryMeta has freshness information about the query.
	QueryMeta
}

PreparedQueryExecuteResponse has the results of executing a query.

type PreparedQueryExplainResponse

type PreparedQueryExplainResponse struct {
	// Query has the fully-rendered query.
	Query PreparedQuery

	// QueryMeta has freshness information about the query.
	QueryMeta
}

PreparedQueryExplainResponse has the results when explaining a query/

type PreparedQueryOp

type PreparedQueryOp string
const (
	PreparedQueryCreate PreparedQueryOp = "create"
	PreparedQueryUpdate PreparedQueryOp = "update"
	PreparedQueryDelete PreparedQueryOp = "delete"
)

type PreparedQueryRequest

type PreparedQueryRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Op is the operation to apply.
	Op PreparedQueryOp

	// Query is the query itself.
	Query *PreparedQuery

	// WriteRequest holds the ACL token to go along with this request.
	WriteRequest
}

QueryRequest is used to create or change prepared queries.

func (*PreparedQueryRequest) RequestDatacenter

func (q *PreparedQueryRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type PreparedQuerySpecificRequest

type PreparedQuerySpecificRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// QueryID is the ID of a query.
	QueryID string

	// QueryOptions (unfortunately named here) controls the consistency
	// settings for the query lookup itself, as well as the service lookups.
	QueryOptions
}

PreparedQuerySpecificRequest is used to get information about a prepared query.

func (*PreparedQuerySpecificRequest) RequestDatacenter

func (q *PreparedQuerySpecificRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type ProxyExecMode added in v1.2.0

type ProxyExecMode int

ProxyExecMode encodes the mode for running a managed connect proxy.

const (
	// ProxyExecModeUnspecified uses the global default proxy mode.
	ProxyExecModeUnspecified ProxyExecMode = iota

	// ProxyExecModeDaemon executes a proxy process as a supervised daemon.
	ProxyExecModeDaemon

	// ProxyExecModeScript executes a proxy config script on each change to it's
	// config.
	ProxyExecModeScript

	// ProxyExecModeTest tracks the start/stop of the proxy in-memory
	// and is only used for tests. This shouldn't be set outside of tests,
	// but even if it is it has no external effect.
	ProxyExecModeTest
)

func NewProxyExecMode added in v1.2.0

func NewProxyExecMode(raw string) (ProxyExecMode, error)

NewProxyExecMode returns the proper ProxyExecMode for the given string value.

func (ProxyExecMode) String added in v1.2.0

func (m ProxyExecMode) String() string

String implements Stringer

type QueryDNSOptions

type QueryDNSOptions struct {
	// TTL is the time to live for the served DNS results.
	TTL string
}

QueryDNSOptions controls settings when query results are served over DNS.

type QueryDatacenterOptions

type QueryDatacenterOptions struct {
	// NearestN is set to the number of remote datacenters to try, based on
	// network coordinates.
	NearestN int

	// Datacenters is a fixed list of datacenters to try after NearestN. We
	// never try a datacenter multiple times, so those are subtracted from
	// this list before proceeding.
	Datacenters []string
}

QueryDatacenterOptions sets options about how we fail over if there are no healthy nodes in the local datacenter.

type QueryMeta

type QueryMeta struct {
	// This is the index associated with the read
	Index uint64

	// If AllowStale is used, this is time elapsed since
	// last contact between the follower and leader. This
	// can be used to gauge staleness.
	LastContact time.Duration

	// Used to indicate if there is a known leader node
	KnownLeader bool

	// Consistencylevel returns the consistency used to serve the query
	// Having `discovery_max_stale` on the agent can affect whether
	// the request was served by a leader.
	ConsistencyLevel string
}

QueryMeta allows a query response to include potentially useful metadata about a query

type QueryOptions

type QueryOptions struct {
	// Token is the ACL token ID. If not provided, the 'anonymous'
	// token is assumed for backwards compatibility.
	Token string

	// If set, wait until query exceeds given index. Must be provided
	// with MaxQueryTime.
	MinQueryIndex uint64

	// Provided with MinQueryIndex to wait for change.
	MaxQueryTime time.Duration

	// If set, any follower can service the request. Results
	// may be arbitrarily stale.
	AllowStale bool

	// If set, the leader must verify leadership prior to
	// servicing the request. Prevents a stale read.
	RequireConsistent bool

	// If set and AllowStale is true, will try first a stale
	// read, and then will perform a consistent read if stale
	// read is older than value
	MaxStaleDuration time.Duration
}

QueryOptions is used to specify various flags for read queries

func (QueryOptions) ACLToken

func (q QueryOptions) ACLToken() string

func (QueryOptions) AllowStaleRead

func (q QueryOptions) AllowStaleRead() bool

func (QueryOptions) ConsistencyLevel added in v1.0.7

func (q QueryOptions) ConsistencyLevel() string

ConsistencyLevel display the consistency required by a request

func (QueryOptions) IsRead

func (q QueryOptions) IsRead() bool

IsRead is always true for QueryOption.

type QuerySource

type QuerySource struct {
	Datacenter string
	Segment    string
	Node       string
	Ip         string
}

QuerySource is used to pass along information about the source node in queries so that we can adjust the response based on its network coordinates.

type QueryTemplateOptions

type QueryTemplateOptions struct {
	// Type, if non-empty, means that this query is a template. This is
	// set to one of the QueryTemplateType* constants above.
	Type string

	// Regexp is an optional regular expression to use to parse the full
	// name, once the prefix match has selected a template. This can be
	// used to extract parts of the name and choose a service name, set
	// tags, etc.
	Regexp string

	// RemoveEmptyTags, if true, removes empty tags from matched tag list
	RemoveEmptyTags bool
}

QueryTemplateOptions controls settings if this query is a template.

type RPCInfo

type RPCInfo interface {
	RequestDatacenter() string
	IsRead() bool
	AllowStaleRead() bool
	ACLToken() string
}

RPCInfo is used to describe common information about query

type RaftConfigurationResponse

type RaftConfigurationResponse struct {
	// Servers has the list of servers in the Raft configuration.
	Servers []*RaftServer

	// Index has the Raft index of this configuration.
	Index uint64
}

RaftConfigurationResponse is returned when querying for the current Raft configuration.

type RaftIndex

type RaftIndex struct {
	CreateIndex uint64
	ModifyIndex uint64
}

RaftIndex is used to track the index used while creating or modifying a given struct type.

type RaftRemovePeerRequest

type RaftRemovePeerRequest struct {
	// Datacenter is the target this request is intended for.
	Datacenter string

	// Address is the peer to remove, in the form "IP:port".
	Address raft.ServerAddress

	// ID is the peer ID to remove.
	ID raft.ServerID

	// WriteRequest holds the ACL token to go along with this request.
	WriteRequest
}

RaftRemovePeerRequest is used by the Operator endpoint to apply a Raft operation on a specific Raft peer by address in the form of "IP:port".

func (*RaftRemovePeerRequest) RequestDatacenter

func (op *RaftRemovePeerRequest) RequestDatacenter() string

RequestDatacenter returns the datacenter for a given request.

type RaftServer

type RaftServer struct {
	// ID is the unique ID for the server. These are currently the same
	// as the address, but they will be changed to a real GUID in a future
	// release of Consul.
	ID raft.ServerID

	// Node is the node name of the server, as known by Consul, or this
	// will be set to "(unknown)" otherwise.
	Node string

	// Address is the IP:port of the server, used for Raft communications.
	Address raft.ServerAddress

	// Leader is true if this server is the current cluster leader.
	Leader bool

	// Protocol version is the raft protocol version used by the server
	ProtocolVersion string

	// Voter is true if this server has a vote in the cluster. This might
	// be false if the server is staging and still coming online, or if
	// it's a non-voting server, which will be added in a future release of
	// Consul.
	Voter bool
}

RaftServer has information about a server in the Raft configuration.

type RegisterRequest

type RegisterRequest struct {
	Datacenter      string
	ID              types.NodeID
	Node            string
	Address         string
	TaggedAddresses map[string]string
	NodeMeta        map[string]string
	Service         *NodeService
	Check           *HealthCheck
	Checks          HealthChecks

	// SkipNodeUpdate can be used when a register request is intended for
	// updating a service and/or checks, but doesn't want to overwrite any
	// node information if the node is already registered. If the node
	// doesn't exist, it will still be created, but if the node exists, any
	// node portion of this update will not apply.
	SkipNodeUpdate bool

	WriteRequest
}

RegisterRequest is used for the Catalog.Register endpoint to register a node as providing a service. If no service is provided, the node is registered.

func TestRegisterRequest added in v1.2.0

func TestRegisterRequest(t testing.T) *RegisterRequest

TestRegisterRequest returns a RegisterRequest for registering a typical service.

func TestRegisterRequestProxy added in v1.2.0

func TestRegisterRequestProxy(t testing.T) *RegisterRequest

TestRegisterRequestProxy returns a RegisterRequest for registering a Connect proxy.

func (*RegisterRequest) ChangesNode

func (r *RegisterRequest) ChangesNode(node *Node) bool

ChangesNode returns true if the given register request changes the given node, which can be nil. This only looks for changes to the node record itself, not any of the health checks.

func (*RegisterRequest) RequestDatacenter

func (r *RegisterRequest) RequestDatacenter() string

type ServiceConnect added in v1.2.0

type ServiceConnect struct {
	// Native is true when this service can natively understand Connect.
	Native bool

	// Proxy configures a connect proxy instance for the service. This is
	// only used for agent service definitions and is invalid for non-agent
	// (catalog API) definitions.
	Proxy *ServiceDefinitionConnectProxy
}

ServiceConnect are the shared Connect settings between all service definitions from the agent to the state store.

type ServiceDefinition

type ServiceDefinition struct {
	Kind              ServiceKind `json:",omitempty"`
	ID                string
	Name              string
	Tags              []string
	Address           string
	Meta              map[string]string
	Port              int
	Check             CheckType
	Checks            CheckTypes
	Token             string
	EnableTagOverride bool
	ProxyDestination  string
	Connect           *ServiceConnect
}

ServiceDefinition is used to JSON decode the Service definitions. For documentation on specific fields see NodeService which is better documented.

func TestServiceDefinition added in v1.2.0

func TestServiceDefinition(t testing.T) *ServiceDefinition

TestServiceDefinition returns a ServiceDefinition for a typical service.

func TestServiceDefinitionProxy added in v1.2.0

func TestServiceDefinitionProxy(t testing.T) *ServiceDefinition

TestServiceDefinitionProxy returns a ServiceDefinition for a proxy.

func (*ServiceDefinition) CheckTypes

func (s *ServiceDefinition) CheckTypes() (checks CheckTypes, err error)

func (*ServiceDefinition) ConnectManagedProxy added in v1.2.0

func (s *ServiceDefinition) ConnectManagedProxy() (*ConnectManagedProxy, error)

ConnectManagedProxy returns a ConnectManagedProxy from the ServiceDefinition if one is configured validly. Note that is may return nil if no proxy is configured and will also return nil error in this case too as it's an expected case. The error returned indicates that there was an attempt to configure a proxy made but that it was invalid input, e.g. invalid "exec_mode".

func (*ServiceDefinition) NodeService

func (s *ServiceDefinition) NodeService() *NodeService

func (*ServiceDefinition) Validate added in v1.2.0

func (s *ServiceDefinition) Validate() error

Validate validates the service definition. This also calls the underlying Validate method on the NodeService.

NOTE(mitchellh): This currently only validates fields related to Connect and is incomplete with regards to other fields.

type ServiceDefinitionConnectProxy added in v1.2.0

type ServiceDefinitionConnectProxy struct {
	Command  []string               `json:",omitempty"`
	ExecMode string                 `json:",omitempty"`
	Config   map[string]interface{} `json:",omitempty"`
}

ServiceDefinitionConnectProxy is the connect proxy config within a service registration. Note this is duplicated in config.ServiceConnectProxy and needs to be kept in sync.

func (*ServiceDefinitionConnectProxy) MarshalJSON added in v1.2.0

func (p *ServiceDefinitionConnectProxy) MarshalJSON() ([]byte, error)

type ServiceKind added in v1.2.0

type ServiceKind string

ServiceKind is the kind of service being registered.

const (
	// ServiceKindTypical is a typical, classic Consul service. This is
	// represented by the absence of a value. This was chosen for ease of
	// backwards compatibility: existing services in the catalog would
	// default to the typical service.
	ServiceKindTypical ServiceKind = ""

	// ServiceKindConnectProxy is a proxy for the Connect feature. This
	// service proxies another service within Consul and speaks the connect
	// protocol.
	ServiceKindConnectProxy ServiceKind = "connect-proxy"
)

type ServiceNode

type ServiceNode struct {
	ID                       types.NodeID
	Node                     string
	Address                  string
	Datacenter               string
	TaggedAddresses          map[string]string
	NodeMeta                 map[string]string
	ServiceKind              ServiceKind
	ServiceID                string
	ServiceName              string
	ServiceTags              []string
	ServiceAddress           string
	ServiceMeta              map[string]string
	ServicePort              int
	ServiceEnableTagOverride bool
	ServiceProxyDestination  string
	ServiceConnect           ServiceConnect

	RaftIndex
}

ServiceNode represents a node that is part of a service. ID, Address, TaggedAddresses, and NodeMeta are node-related fields that are always empty in the state store and are filled in on the way out by parseServiceNodes(). This is also why PartialClone() skips them, because we know they are blank already so it would be a waste of time to copy them.

func (*ServiceNode) PartialClone

func (s *ServiceNode) PartialClone() *ServiceNode

PartialClone() returns a clone of the given service node, minus the node- related fields that get filled in later, Address and TaggedAddresses.

func (*ServiceNode) ToNodeService

func (s *ServiceNode) ToNodeService() *NodeService

ToNodeService converts the given service node to a node service.

type ServiceNodes

type ServiceNodes []*ServiceNode

type ServiceQuery

type ServiceQuery struct {
	// Service is the service to query.
	Service string

	// Failover controls what we do if there are no healthy nodes in the
	// local datacenter.
	Failover QueryDatacenterOptions

	// If OnlyPassing is true then we will only include nodes with passing
	// health checks (critical AND warning checks will cause a node to be
	// discarded)
	OnlyPassing bool

	// IgnoreCheckIDs is an optional list of health check IDs to ignore when
	// considering which nodes are healthy. It is useful as an emergency measure
	// to temporarily override some health check that is producing false negatives
	// for example.
	IgnoreCheckIDs []types.CheckID

	// Near allows the query to always prefer the node nearest the given
	// node. If the node does not exist, results are returned in their
	// normal randomly-shuffled order. Supplying the magic "_agent" value
	// is supported to sort near the agent which initiated the request.
	Near string

	// Tags are a set of required and/or disallowed tags. If a tag is in
	// this list it must be present. If the tag is preceded with "!" then
	// it is disallowed.
	Tags []string

	// NodeMeta is a map of required node metadata fields. If a key/value
	// pair is in this map it must be present on the node in order for the
	// service entry to be returned.
	NodeMeta map[string]string

	// Connect if true will filter the prepared query results to only
	// include Connect-capable services. These include both native services
	// and proxies for matching services. Note that if a proxy matches,
	// the constraints in the query above (Near, OnlyPassing, etc.) apply
	// to the _proxy_ and not the service being proxied. In practice, proxies
	// should be directly next to their services so this isn't an issue.
	Connect bool
}

ServiceQuery is used to query for a set of healthy nodes offering a specific service.

type ServiceSpecificRequest

type ServiceSpecificRequest struct {
	Datacenter      string
	NodeMetaFilters map[string]string
	ServiceName     string
	ServiceTag      string
	ServiceAddress  string
	TagFilter       bool // Controls tag filtering
	Source          QuerySource

	// Connect if true will only search for Connect-compatible services.
	Connect bool

	QueryOptions
}

ServiceSpecificRequest is used to query about a specific service

func (*ServiceSpecificRequest) RequestDatacenter

func (r *ServiceSpecificRequest) RequestDatacenter() string

type Services

type Services map[string][]string

Used to return information about a provided services. Maps service name to available tags

type Session

type Session struct {
	ID        string
	Name      string
	Node      string
	Checks    []types.CheckID
	LockDelay time.Duration
	Behavior  SessionBehavior // What to do when session is invalidated
	TTL       string

	RaftIndex
}

Session is used to represent an open session in the KV store. This issued to associate node checks with acquired locks.

type SessionBehavior

type SessionBehavior string
const (
	SessionKeysRelease SessionBehavior = "release"
	SessionKeysDelete                  = "delete"
)

type SessionOp

type SessionOp string
const (
	SessionCreate  SessionOp = "create"
	SessionDestroy           = "destroy"
)

type SessionRequest

type SessionRequest struct {
	Datacenter string
	Op         SessionOp // Which operation are we performing
	Session    Session   // Which session
	WriteRequest
}

SessionRequest is used to operate on sessions

func (*SessionRequest) RequestDatacenter

func (r *SessionRequest) RequestDatacenter() string

type SessionSpecificRequest

type SessionSpecificRequest struct {
	Datacenter string
	Session    string
	QueryOptions
}

SessionSpecificRequest is used to request a session by ID

func (*SessionSpecificRequest) RequestDatacenter

func (r *SessionSpecificRequest) RequestDatacenter() string

type Sessions

type Sessions []*Session

type SnapshotOp

type SnapshotOp int
const (
	SnapshotSave SnapshotOp = iota
	SnapshotRestore
)

type SnapshotReplyFn

type SnapshotReplyFn func(reply *SnapshotResponse) error

SnapshotReplyFn gets a peek at the reply before the snapshot streams, which is useful for setting headers.

type SnapshotRequest

type SnapshotRequest struct {
	// Datacenter is the target datacenter for this request. The request
	// will be forwarded if necessary.
	Datacenter string

	// Token is the ACL token to use for the operation. If ACLs are enabled
	// then all operations require a management token.
	Token string

	// If set, any follower can service the request. Results may be
	// arbitrarily stale. Only applies to SnapshotSave.
	AllowStale bool

	// Op is the operation code for the RPC.
	Op SnapshotOp
}

SnapshotRequest is used as a header for a snapshot RPC request. This will precede any streaming data that's part of the request and is JSON-encoded on the wire.

type SnapshotResponse

type SnapshotResponse struct {
	// Error is the overall error status of the RPC request.
	Error string

	// QueryMeta has freshness information about the server that handled the
	// request. It is only filled in for a SnapshotSave.
	QueryMeta
}

SnapshotResponse is used header for a snapshot RPC response. This will precede any streaming data that's part of the request and is JSON-encoded on the wire.

type TombstoneOp

type TombstoneOp string
const (
	TombstoneReap TombstoneOp = "reap"
)

type TombstoneRequest

type TombstoneRequest struct {
	Datacenter string
	Op         TombstoneOp
	ReapIndex  uint64
	WriteRequest
}

TombstoneRequest is used to trigger a reaping of the tombstones

func (*TombstoneRequest) RequestDatacenter

func (r *TombstoneRequest) RequestDatacenter() string

type TxnError

type TxnError struct {
	OpIndex int
	What    string
}

TxnError is used to return information about an error for a specific operation.

func (TxnError) Error

func (e TxnError) Error() string

Error returns the string representation of an atomic error.

type TxnErrors

type TxnErrors []*TxnError

TxnErrors is a list of TxnError entries.

type TxnKVOp

type TxnKVOp struct {
	Verb   api.KVOp
	DirEnt DirEntry
}

TxnKVOp is used to define a single operation on the KVS inside a transaction

type TxnKVResult

type TxnKVResult *DirEntry

TxnKVResult is used to define the result of a single operation on the KVS inside a transaction.

type TxnOp

type TxnOp struct {
	KV *TxnKVOp
}

TxnOp is used to define a single operation inside a transaction. Only one of the types should be filled out per entry.

type TxnOps

type TxnOps []*TxnOp

TxnOps is a list of operations within a transaction.

type TxnReadRequest

type TxnReadRequest struct {
	Datacenter string
	Ops        TxnOps
	QueryOptions
}

TxnReadRequest is used as a fast path for read-only transactions that don't modify the state store.

func (*TxnReadRequest) RequestDatacenter

func (r *TxnReadRequest) RequestDatacenter() string

type TxnReadResponse

type TxnReadResponse struct {
	TxnResponse
	QueryMeta
}

TxnReadResponse is the structure returned by a TxnReadRequest.

type TxnRequest

type TxnRequest struct {
	Datacenter string
	Ops        TxnOps
	WriteRequest
}

TxnRequest is used to apply multiple operations to the state store in a single transaction

func (*TxnRequest) RequestDatacenter

func (r *TxnRequest) RequestDatacenter() string

type TxnResponse

type TxnResponse struct {
	Results TxnResults
	Errors  TxnErrors
}

TxnResponse is the structure returned by a TxnRequest.

type TxnResult

type TxnResult struct {
	KV TxnKVResult
}

TxnResult is used to define the result of a given operation inside a transaction. Only one of the types should be filled out per entry.

type TxnResults

type TxnResults []*TxnResult

TxnResults is a list of TxnResult entries.

type VaultCAProviderConfig added in v1.2.0

type VaultCAProviderConfig struct {
	Address             string
	Token               string
	RootPKIPath         string
	IntermediatePKIPath string
}

type WriteRequest

type WriteRequest struct {
	// Token is the ACL token ID. If not provided, the 'anonymous'
	// token is assumed for backwards compatibility.
	Token string
}

func (WriteRequest) ACLToken

func (w WriteRequest) ACLToken() string

func (WriteRequest) AllowStaleRead

func (w WriteRequest) AllowStaleRead() bool

func (WriteRequest) IsRead

func (w WriteRequest) IsRead() bool

WriteRequest only applies to writes, always false

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL