consulapi

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 30, 2014 License: MPL-2.0, GPL-2.0 Imports: 9 Imported by: 0

README

consul-api

This package provides the consulapi package which attempts to provide programmatic access to the full Consul API.

Currently, all of the Consul APIs included in version 0.3 are supported.

Documentation

The full documentation is available on Godoc

Usage

Below is an example of using the Consul client:

// Get a new client, with KV endpoints
client, _ := consulapi.NewClient(consulapi.DefaultConfig())
kv := client.KV()

// PUT a new KV pair
p := &consulapi.KVPair{Key: "foo", Value: []byte("test")}
_, err := kv.Put(p, nil)
if err != nil {
    panic(err)
}

// Lookup the pair
pair, _, err := kv.Get("foo", nil)
if err != nil {
    panic(err)
}
fmt.Printf("KV: %v", pair)

Documentation

Index

Constants

View Source 
const (
	// ACLCLientType is the client type token
	ACLClientType = "client"

	// ACLManagementType is the management type token
	ACLManagementType = "management"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type ACL 

type ACL struct {
	// contains filtered or unexported fields
}

ACL can be used to query the ACL endpoints

func (*ACL) Clone 

func (a *ACL) Clone(id string, q *WriteOptions) (string, *WriteMeta, error)

Clone is used to return a new token cloned from an existing one

func (*ACL) Create 

func (a *ACL) Create(acl *ACLEntry, q *WriteOptions) (string, *WriteMeta, error)

Create is used to generate a new token with the given parameters

func (*ACL) Destroy 

func (a *ACL) Destroy(id string, q *WriteOptions) (*WriteMeta, error)

Destroy is used to destroy a given ACL token ID

func (*ACL) Info 

func (a *ACL) Info(id string, q *QueryOptions) (*ACLEntry, *QueryMeta, error)

Info is used to query for information about an ACL token

func (*ACL) List 

func (a *ACL) List(q *QueryOptions) ([]*ACLEntry, *QueryMeta, error)

List is used to get all the ACL tokens

func (*ACL) Update 

func (a *ACL) Update(acl *ACLEntry, q *WriteOptions) (*WriteMeta, error)

Update is used to update the rules of an existing token

type ACLEntry 

type ACLEntry struct {
	CreateIndex uint64
	ModifyIndex uint64
	ID          string
	Name        string
	Type        string
	Rules       string
}

ACLEntry is used to represent an ACL entry

type Agent 

type Agent struct {
	// contains filtered or unexported fields
}

Agent can be used to query the Agent endpoints

func (*Agent) CheckDeregister 

func (a *Agent) CheckDeregister(checkID string) error

CheckDeregister is used to deregister a check with the local agent

func (*Agent) CheckRegister 

func (a *Agent) CheckRegister(check *AgentCheckRegistration) error

CheckRegister is used to register a new check with the local agent

func (*Agent) Checks 

func (a *Agent) Checks() (map[string]*AgentCheck, error)

Checks returns the locally registered checks

func (*Agent) FailTTL 

func (a *Agent) FailTTL(checkID, note string) error

FailTTL is used to set a TTL check to the failing state

func (*Agent) ForceLeave 

func (a *Agent) ForceLeave(node string) error

ForceLeave is used to have the agent eject a failed node

func (*Agent) Join 

func (a *Agent) Join(addr string, wan bool) error

Join is used to instruct the agent to attempt a join to another cluster member

func (*Agent) Members 

func (a *Agent) Members(wan bool) ([]*AgentMember, error)

Members returns the known gossip members. The WAN flag can be used to query a server for WAN members.

func (*Agent) NodeName 

func (a *Agent) NodeName() (string, error)

NodeName is used to get the node name of the agent

func (*Agent) PassTTL 

func (a *Agent) PassTTL(checkID, note string) error

PassTTL is used to set a TTL check to the passing state

func (*Agent) Self 

func (a *Agent) Self() (map[string]map[string]interface{}, error)

Self is used to query the agent we are speaking to for information about itself

func (*Agent) ServiceDeregister 

func (a *Agent) ServiceDeregister(serviceID string) error

ServiceDeregister is used to deregister a service with the local agent

func (*Agent) ServiceRegister 

func (a *Agent) ServiceRegister(service *AgentServiceRegistration) error

ServiceRegister is used to register a new service with the local agent

func (*Agent) Services 

func (a *Agent) Services() (map[string]*AgentService, error)

Services returns the locally registered services

func (*Agent) UpdateTTL 

func (a *Agent) UpdateTTL(checkID, note, status string) error

UpdateTTL is used to update the TTL of a check

func (*Agent) WarnTTL 

func (a *Agent) WarnTTL(checkID, note string) error

WarnTTL is used to set a TTL check to the warning state

type AgentCheck 

type AgentCheck struct {
	Node        string
	CheckID     string
	Name        string
	Status      string
	Notes       string
	Output      string
	ServiceID   string
	ServiceName string
}

AgentCheck represents a check known to the agent

type AgentCheckRegistration 

type AgentCheckRegistration struct {
	ID    string `json:",omitempty"`
	Name  string `json:",omitempty"`
	Notes string `json:",omitempty"`
	AgentServiceCheck
}

AgentCheckRegistration is used to register a new check

type AgentMember 

type AgentMember struct {
	Name        string
	Addr        string
	Port        uint16
	Tags        map[string]string
	Status      int
	ProtocolMin uint8
	ProtocolMax uint8
	ProtocolCur uint8
	DelegateMin uint8
	DelegateMax uint8
	DelegateCur uint8
}

AgentMember represents a cluster member known to the agent

type AgentService 

type AgentService struct {
	ID      string
	Service string
	Tags    []string
	Port    int
}

AgentService represents a service known to the agent

type AgentServiceCheck 

type AgentServiceCheck struct {
	Script   string `json:",omitempty"`
	Interval string `json:",omitempty"`
	TTL      string `json:",omitempty"`
}

AgentServiceCheck is used to create an associated check for a service

type AgentServiceRegistration 

type AgentServiceRegistration struct {
	ID    string   `json:",omitempty"`
	Name  string   `json:",omitempty"`
	Tags  []string `json:",omitempty"`
	Port  int      `json:",omitempty"`
	Check *AgentServiceCheck
}

AgentServiceRegistration is used to register a new service

type Catalog 

type Catalog struct {
	// contains filtered or unexported fields
}

Catalog can be used to query the Catalog endpoints

func (*Catalog) Datacenters 

func (c *Catalog) Datacenters() ([]string, error)

Datacenters is used to query for all the known datacenters

func (*Catalog) Deregister 

func (c *Catalog) Deregister(dereg *CatalogDeregistration, q *WriteOptions) (*WriteMeta, error)

func (*Catalog) Node 

func (c *Catalog) Node(node string, q *QueryOptions) (*CatalogNode, *QueryMeta, error)

Node is used to query for service information about a single node

func (*Catalog) Nodes 

func (c *Catalog) Nodes(q *QueryOptions) ([]*Node, *QueryMeta, error)

Nodes is used to query all the known nodes

func (*Catalog) Register 

func (c *Catalog) Register(reg *CatalogRegistration, q *WriteOptions) (*WriteMeta, error)

func (*Catalog) Service 

func (c *Catalog) Service(service, tag string, q *QueryOptions) ([]*CatalogService, *QueryMeta, error)

Service is used to query catalog entries for a given service

func (*Catalog) Services 

func (c *Catalog) Services(q *QueryOptions) (map[string][]string, *QueryMeta, error)

Services is used to query for all known services

type CatalogDeregistration 

type CatalogDeregistration struct {
	Node       string
	Address    string
	Datacenter string
	ServiceID  string
	CheckID    string
}

type CatalogNode 

type CatalogNode struct {
	Node     *Node
	Services map[string]*AgentService
}

type CatalogRegistration 

type CatalogRegistration struct {
	Node       string
	Address    string
	Datacenter string
	Service    *AgentService
	Check      *AgentCheck
}

type CatalogService 

type CatalogService struct {
	Node        string
	Address     string
	ServiceID   string
	ServiceName string
	ServiceTags []string
	ServicePort int
}

type Client 

type Client struct {
	// contains filtered or unexported fields
}

Client provides a client to the Consul API

func NewClient 

func NewClient(config *Config) (*Client, error)

NewClient returns a new client

func (*Client) ACL 

func (c *Client) ACL() *ACL

ACL returns a handle to the ACL endpoints

func (*Client) Agent 

func (c *Client) Agent() *Agent

Agent returns a handle to the agent endpoints

func (*Client) Catalog 

func (c *Client) Catalog() *Catalog

Catalog returns a handle to the catalog endpoints

func (*Client) Event 

func (c *Client) Event() *Event

Session returns a handle to the session endpoints

func (*Client) Health 

func (c *Client) Health() *Health

Health returns a handle to the health endpoints

func (*Client) KV 

func (c *Client) KV() *KV

KV is used to return a handle to the K/V apis

func (*Client) Session 

func (c *Client) Session() *Session

Session returns a handle to the session endpoints

func (*Client) Status 

func (c *Client) Status() *Status

Status returns a handle to the status endpoints

type Config 

type Config struct {
	// Address is the address of the Consul server
	Address string

	// Datacenter to use. If not provided, the default agent datacenter is used.
	Datacenter string

	// HttpClient is the client to use. Default will be
	// used if not provided.
	HttpClient *http.Client

	// WaitTime limits how long a Watch will block. If not provided,
	// the agent default values will be used.
	WaitTime time.Duration

	// Token is used to provide a per-request ACL token
	// which overrides the agent's default token.
	Token string
}

Config is used to configure the creation of a client

func DefaultConfig 

func DefaultConfig() *Config

DefaultConfig returns a default configuration for the client

type Event 

type Event struct {
	// contains filtered or unexported fields
}

Event can be used to query the Event endpoints

func (*Event) Fire 

func (e *Event) Fire(params *UserEvent, q *WriteOptions) (string, *WriteMeta, error)

Fire is used to fire a new user event. Only the Name, Payload and Filters are respected. This returns the ID or an associated error. Cross DC requests are supported.

func (*Event) IDToIndex 

func (e *Event) IDToIndex(uuid string) uint64

IDToIndex is a bit of a hack. This simulates the index generation to convert an event ID into a WaitIndex.

func (*Event) List 

func (e *Event) List(name string, q *QueryOptions) ([]*UserEvent, *QueryMeta, error)

List is used to get the most recent events an agent has received. This list can be optionally filtered by the name. This endpoint supports quasi-blocking queries. The index is not monotonic, nor does it provide provide LastContact or KnownLeader.

type Health 

type Health struct {
	// contains filtered or unexported fields
}

Health can be used to query the Health endpoints

func (*Health) Checks 

func (h *Health) Checks(service string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)

Checks is used to return the checks associated with a service

func (*Health) Node 

func (h *Health) Node(node string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)

Node is used to query for checks belonging to a given node

func (*Health) Service 

func (h *Health) Service(service, tag string, passingOnly bool, q *QueryOptions) ([]*ServiceEntry, *QueryMeta, error)

Service is used to query health information along with service info for a given service. It can optionally do server-side filtering on a tag or nodes with passing health checks only.

func (*Health) State 

func (h *Health) State(state string, q *QueryOptions) ([]*HealthCheck, *QueryMeta, error)

State is used to retreive all the checks in a given state. The wildcard "any" state can also be used for all checks.

type HealthCheck 

type HealthCheck struct {
	Node        string
	CheckID     string
	Name        string
	Status      string
	Notes       string
	Output      string
	ServiceID   string
	ServiceName string
}

HealthCheck is used to represent a single check

type KV 

type KV struct {
	// contains filtered or unexported fields
}

KV is used to manipulate the K/V API

func (*KV) Acquire 

func (k *KV) Acquire(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)

Acquire is used for a lock acquisiiton operation. The Key, Flags, Value and Session are respected. Returns true on success or false on failures.

func (*KV) CAS 

func (k *KV) CAS(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)

CAS is used for a Check-And-Set operation. The Key, ModifyIndex, Flags and Value are respected. Returns true on success or false on failures.

func (*KV) Delete 

func (k *KV) Delete(key string, w *WriteOptions) (*WriteMeta, error)

Delete is used to delete a single key

func (*KV) DeleteTree 

func (k *KV) DeleteTree(prefix string, w *WriteOptions) (*WriteMeta, error)

DeleteTree is used to delete all keys under a prefix

func (*KV) Get 

func (k *KV) Get(key string, q *QueryOptions) (*KVPair, *QueryMeta, error)

Get is used to lookup a single key

func (*KV) Keys 

func (k *KV) Keys(prefix, separator string, q *QueryOptions) ([]string, *QueryMeta, error)

Keys is used to list all the keys under a prefix. Optionally, a separator can be used to limit the responses.

func (*KV) List 

func (k *KV) List(prefix string, q *QueryOptions) (KVPairs, *QueryMeta, error)

List is used to lookup all keys under a prefix

func (*KV) Put 

func (k *KV) Put(p *KVPair, q *WriteOptions) (*WriteMeta, error)

Put is used to write a new value. Only the Key, Flags and Value is respected.

func (*KV) Release 

func (k *KV) Release(p *KVPair, q *WriteOptions) (bool, *WriteMeta, error)

Release is used for a lock release operation. The Key, Flags, Value and Session are respected. Returns true on success or false on failures.

type KVPair 

type KVPair struct {
	Key         string
	CreateIndex uint64
	ModifyIndex uint64
	LockIndex   uint64
	Flags       uint64
	Value       []byte
	Session     string
}

KVPair is used to represent a single K/V entry

type KVPairs 

type KVPairs []*KVPair

KVPairs is a list of KVPair objects

type Node 

type Node struct {
	Node    string
	Address string
}

type QueryMeta 

type QueryMeta struct {
	// LastIndex. This can be used as a WaitIndex to perform
	// a blocking query
	LastIndex uint64

	// Time of last contact from the leader for the
	// server servicing the request
	LastContact time.Duration

	// Is there a known leader
	KnownLeader bool

	// How long did the request take
	RequestTime time.Duration
}

QueryMeta is used to return meta data about a query

type QueryOptions 

type QueryOptions struct {
	// Providing a datacenter overwrites the DC provided
	// by the Config
	Datacenter string

	// AllowStale allows any Consul server (non-leader) to service
	// a read. This allows for lower latency and higher throughput
	AllowStale bool

	// RequireConsistent forces the read to be fully consistent.
	// This is more expensive but prevents ever performing a stale
	// read.
	RequireConsistent bool

	// WaitIndex is used to enable a blocking query. Waits
	// until the timeout or the next index is reached
	WaitIndex uint64

	// WaitTime is used to bound the duration of a wait.
	// Defaults to that of the Config, but can be overriden.
	WaitTime time.Duration

	// Token is used to provide a per-request ACL token
	// which overrides the agent's default token.
	Token string
}

QueryOptions are used to parameterize a query

type ServiceEntry 

type ServiceEntry struct {
	Node    *Node
	Service *AgentService
	Checks  []*HealthCheck
}

ServiceEntry is used for the health service endpoint

type Session 

type Session struct {
	// contains filtered or unexported fields
}

Session can be used to query the Session endpoints

func (*Session) Create 

func (s *Session) Create(se *SessionEntry, q *WriteOptions) (string, *WriteMeta, error)

Create makes a new session. Providing a session entry can customize the session. It can also be nil to use defaults.

func (*Session) CreateNoChecks 

func (s *Session) CreateNoChecks(se *SessionEntry, q *WriteOptions) (string, *WriteMeta, error)

CreateNoChecks is like Create but is used specifically to create a session with no associated health checks.

func (*Session) Destroy 

func (s *Session) Destroy(id string, q *WriteOptions) (*WriteMeta, error)

Destroy invalides a given session

func (*Session) Info 

func (s *Session) Info(id string, q *QueryOptions) (*SessionEntry, *QueryMeta, error)

Info looks up a single session

func (*Session) List 

func (s *Session) List(q *QueryOptions) ([]*SessionEntry, *QueryMeta, error)

List gets all active sessions

func (*Session) Node 

func (s *Session) Node(node string, q *QueryOptions) ([]*SessionEntry, *QueryMeta, error)

List gets sessions for a node

type SessionEntry 

type SessionEntry struct {
	CreateIndex uint64
	ID          string
	Name        string
	Node        string
	Checks      []string
	LockDelay   time.Duration
}

SessionEntry represents a session in consul

type Status 

type Status struct {
	// contains filtered or unexported fields
}

Status can be used to query the Status endpoints

func (*Status) Leader 

func (s *Status) Leader() (string, error)

Leader is used to query for a known leader

func (*Status) Peers 

func (s *Status) Peers() ([]string, error)

Peers is used to query for a known raft peers

type UserEvent 

type UserEvent struct {
	ID            string
	Name          string
	Payload       []byte
	NodeFilter    string
	ServiceFilter string
	TagFilter     string
	Version       int
	LTime         uint64
}

UserEvent represents an event that was fired by the user

type WriteMeta 

type WriteMeta struct {
	// How long did the request take
	RequestTime time.Duration
}

WriteMeta is used to return meta data about a write

type WriteOptions 

type WriteOptions struct {
	// Providing a datacenter overwrites the DC provided
	// by the Config
	Datacenter string

	// Token is used to provide a per-request ACL token
	// which overrides the agent's default token.
	Token string
}

WriteOptions are used to parameterize a write

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.