client

Documentation

Overview

Package client implements the northbound client used to manage Calico configuration.

This client is the main entry point for applications that are managing or querying Calico configuration.

This client provides a typed interface for managing different resource types. The definitions for each resource type are defined in the following package:

github.com/projectcalico/libcalico-go/lib/api

The client has a number of methods that return interfaces for managing:

• BGP Peer resources
• Policy resources
• IP Pool resources
• Host endpoint resources
• Workload endpoint resources
• Profile resources
• IP Address Management (IPAM)

See [resource definitions](http://docs.projectcalico.org/latest/reference/calicoctl/resources/) for details about the set of management commands for each resource type.

The resource management interfaces have a common set of commands to create, delete, update and retrieve resource instances. For example, an application using this client to manage host endpoint resources would create an instance of this client, create a new HostEndpoints interface and call the appropriate methods on that interface. For example:

// NewFromEnv() creates a new client and defaults to access an etcd backend datastore at
// http://127.0.0.1:2379.  For alternative backend access details, set the appropriate
// ENV variables specified in the CalicoAPIConfigSpec structure.
client, err := client.NewFromEnv()

// Obtain the interface for managing host endpoint resources.
hostendpoints := client.HostEndpoints()

// Create a new host endpoint.  All Create() methods return an error of type
// common.ErrorResourceAlreadyExists if the resource specified by its
// unique identifiers already exists.
hostEndpoint, err := hostEndpoints.Create(&api.HostEndpoint{
	Metadata: api.HostEndpointMetadata{
		Name: "endpoint1",
		Nodename: "hostname1",
	},
	Spec: api.HostEndpointSpec{
		InterfaceName: "eth0"
	},
}

// Update an existing host endpoint.  All Update() methods return an error of type
// common.ErrorResourceDoesNotExist if the resource specified by its
// unique identifiers does not exist.
hostEndpoint, err = hostEndpoints.Update(&api.HostEndpoint{
	Metadata: api.HostEndpointMetadata{
		Name: "endpoint1",
		Nodename: "hostname1",
	},
	Spec: api.HostEndpointSpec{
		InterfaceName: "eth0",
		Profiles: []string{"profile1"},
	},
}

// Apply (update or create) a hostEndpoint.  All Apply() methods will update a resource
// if it already exists, and will create a new resource if it does not.
hostEndpoint, err = hostEndpoints.Apply(&api.HostEndpoint{
	Metadata: api.HostEndpointMetadata{
		Name: "endpoint1",
		Nodename: "hostname1",
	},
	Spec: api.HostEndpointSpec{
		InterfaceName: "eth1",
		Profiles: []string{"profile1"},
	},
}

// Delete a hostEndpoint.  All Delete() methods return an error of type
// common.ErrorResourceDoesNotExist if the resource specified by its
// unique identifiers does not exist.
hostEndpoint, err = hostEndpoints.Delete(api.HostEndpointMetadata{
	Name: "endpoint1",
	Nodename: "hostname1",
})

// Get a hostEndpoint.  All Get() methods return an error of type
// common.ErrorResourceDoesNotExist if the resource specified by its
// unique identifiers does not exist.
hostEndpoint, err = hostEndpoints.Get(api.HostEndpointMetadata{
	Name: "endpoint1",
	Nodename: "hostname1",
})

// List all hostEndpoints.  All List() methods take a (sub-)set of the resource
// identifiers and return the corresponding list resource type that has an
// Items field containing a list of resources that match the supplied
// identifiers.
hostEndpointList, err := hostEndpoints.List(api.HostEndpointMetadata{})

Index

• Constants
• func LoadClientConfig(filename string) (*api.CalicoAPIConfig, error)
• func LoadClientConfigFromBytes(b []byte) (*api.CalicoAPIConfig, error)
• func LoadClientConfigFromEnvironment() (*api.CalicoAPIConfig, error)
• type BGPPeerInterface
• type Client
  • func New(config apiconfig.CalicoAPIConfig) (*Client, error)
  • func NewFromEnv() (*Client, error)
  • func (c *Client) BGPPeers() BGPPeerInterface
  • func (c *Client) Config() ConfigInterface
  • func (c *Client) EnsureInitialized() error
  • func (c *Client) HostEndpoints() HostEndpointInterface
  • func (c *Client) IPPools() IPPoolInterface
  • func (c *Client) Nodes() NodeInterface
  • func (c *Client) Policies() PolicyInterface
  • func (c *Client) Profiles() ProfileInterface
  • func (c *Client) WorkloadEndpoints() WorkloadEndpointInterface
• type ConfigInterface
• type ConfigLocation
• type HostEndpointInterface
• type IPPoolInterface
• type NodeInterface
• type PolicyInterface
• type ProfileInterface
• type WorkloadEndpointInterface

Constants

const (
	GlobalDefaultASNumber       = 64512
	GlobalDefaultLogLevel       = "info"
	GlobalDefaultIPIP           = false
	GlobalDefaultNodeToNodeMesh = true
)

Functions

func LoadClientConfig

func LoadClientConfig(filename string) (*api.CalicoAPIConfig, error)

LoadClientConfig loads the ClientConfig from the specified file (if specified) or from environment variables (if the file is not specified).

func LoadClientConfigFromBytes

func LoadClientConfigFromBytes(b []byte) (*api.CalicoAPIConfig, error)

LoadClientConfig loads the ClientConfig from the supplied bytes containing YAML or JSON format data.

func LoadClientConfigFromEnvironment

func LoadClientConfigFromEnvironment() (*api.CalicoAPIConfig, error)

LoadClientConfig loads the ClientConfig from the specified file (if specified) or from environment variables (if the file is not specified).

Types

type BGPPeerInterface

type BGPPeerInterface interface {
	List(api.BGPPeerMetadata) (*api.BGPPeerList, error)
	Get(api.BGPPeerMetadata) (*api.BGPPeer, error)
	Create(*api.BGPPeer) (*api.BGPPeer, error)
	Update(*api.BGPPeer) (*api.BGPPeer, error)
	Apply(*api.BGPPeer) (*api.BGPPeer, error)
	Delete(api.BGPPeerMetadata) error
}

BGPPeerInterface has methods to work with BGPPeer resources.

type Client

type Client struct {
	// The backend client is currently public to allow access to datastore
	// specific functions that are used by calico/node.  This is a temporary
	// measure and users of the client API should not assume that the backend
	// will be available in the future.
	Backend bapi.Client
}

Client contains

func New

func New(config apiconfig.CalicoAPIConfig) (*Client, error)

New returns a connected Client. The ClientConfig can either be created explicitly, or can be loaded from a config file or environment variables using the LoadClientConfig() function.

func NewFromEnv

func NewFromEnv() (*Client, error)

NewFromEnv loads the config from ENV variables and returns a connected Client.

func (*Client) BGPPeers

func (c *Client) BGPPeers() BGPPeerInterface

BGPPeers returns an interface for managing BGP peer resources.

func (*Client) Config

func (c *Client) Config() ConfigInterface

Config returns an interface for managing system configuration..

func (*Client) EnsureInitialized

func (c *Client) EnsureInitialized() error

EnsureInitialized is used to ensure the backend datastore is correctly initialized for use by Calico. This method may be called multiple times, and will have no effect if the datastore is already correctly initialized.

Most Calico deployment scenarios will automatically implicitly invoke this method and so a general consumer of this API can assume that the datastore is already initialized.

func (*Client) HostEndpoints

func (c *Client) HostEndpoints() HostEndpointInterface

HostEndpoints returns an interface for managing host endpoint resources.

func (*Client) IPPools

func (c *Client) IPPools() IPPoolInterface

IPPools returns an interface for managing IP pool resources.

func (*Client) Nodes

func (c *Client) Nodes() NodeInterface

Nodes returns an interface for managing node resources.

func (*Client) Policies

func (c *Client) Policies() PolicyInterface

Policies returns an interface for managing policy resources.

func (*Client) Profiles

func (c *Client) Profiles() ProfileInterface

Profiles returns an interface for managing profile resources.

func (*Client) WorkloadEndpoints

func (c *Client) WorkloadEndpoints() WorkloadEndpointInterface

WorkloadEndpoints returns an interface for managing workload endpoint resources.

type ConfigInterface

type ConfigInterface interface {
	SetNodeToNodeMesh(bool) error
	GetNodeToNodeMesh() (bool, error)
	SetGlobalASNumber(numorstring.ASNumber) error
	GetGlobalASNumber() (numorstring.ASNumber, error)
	SetGlobalIPIP(bool) error
	GetGlobalIPIP() (bool, error)
	SetNodeIPIPTunnelAddress(string, *net.IP) error
	GetNodeIPIPTunnelAddress(string) (*net.IP, error)
	SetGlobalLogLevel(string) error
	GetGlobalLogLevel() (string, error)
	SetNodeLogLevel(string, string) error
	SetNodeLogLevelUseGlobal(string) error
	GetNodeLogLevel(string) (string, ConfigLocation, error)
	GetFelixConfig(string, string) (string, bool, error)
	SetFelixConfig(string, string, string) error
	UnsetFelixConfig(string, string) error
	GetBGPConfig(string, string) (string, bool, error)
	SetBGPConfig(string, string, string) error
	UnsetBGPConfig(string, string) error
}

ConfigInterface provides methods for setting, unsetting and retrieving low level config options.

type ConfigLocation

type ConfigLocation int8

const (
	ConfigLocationNone ConfigLocation = iota
	ConfigLocationNode
	ConfigLocationGlobal
)

type HostEndpointInterface

type HostEndpointInterface interface {

	// List enumerates host endpoint resources matching the supplied metadata and
	// wildcarding missing identifiers.
	List(api.HostEndpointMetadata) (*api.HostEndpointList, error)

	// Get returns the host endpoint resource matching the supplied metadata.  The metadata
	// should contain all identifiers to uniquely identify a single resource.  If the
	// resource does not exist, a errors.ErrorResourceNotFound error is returned.
	Get(api.HostEndpointMetadata) (*api.HostEndpoint, error)

	// Create will create a new host endpoint resource.  If the resource already exists,
	// a errors.ErrorResourceAlreadyExists error is returned.
	Create(*api.HostEndpoint) (*api.HostEndpoint, error)

	// Update will update an existing host endpoint resource.  If the resource does not exist,
	// a errors.ErrorResourceDoesNotExist error is returned.
	Update(*api.HostEndpoint) (*api.HostEndpoint, error)

	// Apply with update an existing host endpoint resource, or create a new one if it does
	// not exist.
	Apply(*api.HostEndpoint) (*api.HostEndpoint, error)

	// Delete will delete a host endpoint resource.  The metadata should contain all identifiers
	// to uniquely identify a single resource.  If the resource does not exist, a
	// errors.ErrorResourceDoesNotExist error is returned.
	Delete(api.HostEndpointMetadata) error
}

HostEndpointInterface has methods to work with host endpoint resources.

type IPPoolInterface

type IPPoolInterface interface {
	List(api.IPPoolMetadata) (*api.IPPoolList, error)
	Get(api.IPPoolMetadata) (*api.IPPool, error)
	Create(*api.IPPool) (*api.IPPool, error)
	Update(*api.IPPool) (*api.IPPool, error)
	Apply(*api.IPPool) (*api.IPPool, error)
	Delete(api.IPPoolMetadata) error
}

PoolInterface has methods to work with Pool resources.

type NodeInterface

type NodeInterface interface {
	List(api.NodeMetadata) (*api.NodeList, error)
	Get(api.NodeMetadata) (*api.Node, error)
	Create(*api.Node) (*api.Node, error)
	Update(*api.Node) (*api.Node, error)
	Apply(*api.Node) (*api.Node, error)
	Delete(api.NodeMetadata) error
}

NodeInterface has methods to work with Node resources.

type PolicyInterface

type PolicyInterface interface {
	List(api.PolicyMetadata) (*api.PolicyList, error)
	Get(api.PolicyMetadata) (*api.Policy, error)
	Create(*api.Policy) (*api.Policy, error)
	Update(*api.Policy) (*api.Policy, error)
	Apply(*api.Policy) (*api.Policy, error)
	Delete(api.PolicyMetadata) error
}

PolicyInterface has methods to work with Policy resources.

type ProfileInterface

type ProfileInterface interface {
	List(api.ProfileMetadata) (*api.ProfileList, error)
	Get(api.ProfileMetadata) (*api.Profile, error)
	Create(*api.Profile) (*api.Profile, error)
	Update(*api.Profile) (*api.Profile, error)
	Apply(*api.Profile) (*api.Profile, error)
	Delete(api.ProfileMetadata) error
}

ProfileInterface has methods to work with Profile resources.

type WorkloadEndpointInterface

type WorkloadEndpointInterface interface {
	List(api.WorkloadEndpointMetadata) (*api.WorkloadEndpointList, error)
	Get(api.WorkloadEndpointMetadata) (*api.WorkloadEndpoint, error)
	Create(*api.WorkloadEndpoint) (*api.WorkloadEndpoint, error)
	Update(*api.WorkloadEndpoint) (*api.WorkloadEndpoint, error)
	Apply(*api.WorkloadEndpoint) (*api.WorkloadEndpoint, error)
	Delete(api.WorkloadEndpointMetadata) error
}

WorkloadEndpointInterface has methods to work with WorkloadEndpoint resources.