api

package
v0.0.0-...-cf83b6a Latest Latest
Warning

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

 Go to latest Published: Oct 15, 2016 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package api implements the struct definitions used on the northbound client API.

In particular this includes:

  • The various resource types as exposed on the Northbound API. The valid resource types are:
  • BGPPeer
  • HostEndpoint
  • Policy
  • Pool
  • Profile
  • The client configuration

The resource structures include the JSON tags for each exposed field. These are standard go-lang tags that define the JSON format of the structures as used by calicoctl. The YAML format also used by calicoctl is directly mapped from the JSON.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BGPPeer 

type BGPPeer struct {
	unversioned.TypeMetadata

	// Metadata for a BGPPeer.
	Metadata BGPPeerMetadata `json:"metadata,omitempty"`

	// Specification for a BGPPeer.
	Spec BGPPeerSpec `json:"spec,omitempty"`
}

BGPPeer contains information about a BGP peer resource that is a peer of a Calico compute node.

func NewBGPPeer 

func NewBGPPeer() *BGPPeer

NewBGPPeer creates a new (zeroed) BGPPeer struct with the TypeMetadata initialised to the current version.

type BGPPeerList 

type BGPPeerList struct {
	unversioned.TypeMetadata
	Metadata unversioned.ListMetadata `json:"metadata,omitempty"`
	Items    []BGPPeer                `json:"items" validate:"dive"`
}

BGPPeerList contains a list of BGP Peer resources. List types are returned from List() enumerations in the client interface.

func NewBGPPeerList 

func NewBGPPeerList() *BGPPeerList

NewBGPPeerList creates a new (zeroed) BGPPeerList struct with the TypeMetadata initialised to the current version.

type BGPPeerMetadata 

type BGPPeerMetadata struct {
	unversioned.ObjectMetadata

	// The scope of the peer.  This may be global or node.  A global peer is a
	// BGP device that peers with all Calico nodes.  A node peer is a BGP device that
	// peers with the specified Calico node (specified by the node hostname).
	Scope scope.Scope `json:"scope" validate:"omitempty,scopeglobalornode"`

	// The hostname of the compute server that is peering with this peer.  When modifying a
	// BGP peer, the hostname must be specified when the scope is `node`, and must
	// be omitted when the scope is `global`.
	Hostname string `json:"hostname,omitempty" validate:"omitempty,name"`

	// The IP address of the peer.
	PeerIP net.IP `json:"peerIP" validate:"omitempty,ip"`
}

BGPPeerMetadata contains the metadata for a BGPPeer resource.

type BGPPeerSpec 

type BGPPeerSpec struct {
	// The AS Number of the peer.
	ASNumber numorstring.ASNumber `json:"asNumber"`
}

BGPPeerSpec contains the specification for a BGPPeer resource.

type BackendType 

type BackendType string
const (
	EtcdV2 BackendType = "etcdv2"
)

func (BackendType) NewConfig 

func (b BackendType) NewConfig() interface{}

NewConfig returns a pointer to a new config struct for the relevant datastore.

type ClientConfig 

type ClientConfig struct {
	BackendType   BackendType `json:"datastoreType" envconfig:"DATASTORE_TYPE" default:"etcdv2"`
	BackendConfig interface{} `json:"-"`
}

Client configuration required to instantiate a Calico client interface.

type EntityRule 

type EntityRule struct {
	// Tag is an optional field that restricts the rule to only apply to traffic that
	// originates from (or terminates at) endpoints that have profiles with the given tag
	// in them.
	Tag string `json:"tag,omitempty" validate:"omitempty,tag"`

	// Net is an optional field that restricts the rule to only apply to traffic that
	// originates from (or terminates at) IP addresses in the given subnet.
	Net *net.IPNet `json:"net,omitempty" validate:"omitempty"`

	// Selector is an optional field that contains a selector expression (see Policy for
	// sample syntax).  Only traffic that originates from (terminates at) endpoints matching
	// the selector will be matched.
	//
	// Note that: in addition to the negated version of the Selector (see NotSelector below), the
	// selector expression syntax itself supports negation.  The two types of negation are subtly
	// different. One negates the set of matched endpoints, the other negates the whole match:
	//
	//	Selector = "!has(my_label)" matches packets that are from other Calico-controlled
	// 	endpoints that do not have the label “my_label”.
	//
	// 	NotSelector = "has(my_label)" matches packets that are not from Calico-controlled
	// 	endpoints that do have the label “my_label”.
	//
	// The effect is that the latter will accept packets from non-Calico sources whereas the
	// former is limited to packets from Calico-controlled endpoints.
	Selector string `json:"selector,omitempty" validate:"omitempty,selector"`

	// Ports is an optional field that restricts the rule to only apply to traffic that has a
	// source (destination) port that matches one of these ranges/values. This value is a
	// list of integers or strings that represent ranges of ports.
	//
	// Since only some protocols have ports, if any ports are specified it requires the
	// Protocol match in the Rule to be set to "tcp" or "udp".
	Ports []numorstring.Port `json:"ports,omitempty" validate:"omitempty,dive"`

	// NotTag is the negated version of the Tag field.
	NotTag string `json:"!tag,omitempty" validate:"omitempty,tag"`

	// NotNet is the negated version of the Net field.
	NotNet *net.IPNet `json:"!net,omitempty" validate:"omitempty"`

	// NotSelector is the negated version of the Selector field.  See Selector field for
	// subtleties with negated selectors.
	NotSelector string `json:"!selector,omitempty" validate:"omitempty,selector"`

	// NotPorts is the negated version of the Ports field.
	//
	// Since only some protocols have ports, if any ports are specified it requires the
	// Protocol match in the Rule to be set to "tcp" or "udp".
	NotPorts []numorstring.Port `json:"!ports,omitempty" validate:"omitempty,dive"`
}

An EntityRule is a sub-component of a Rule comprising the match criteria specific to a particular entity (that is either the source or destination).

A source EntityRule matches the source endpoint and originating traffic. A desination EntityRule matches the destination endpoint and terminating traffic.

type HostEndpoint 

type HostEndpoint struct {
	unversioned.TypeMetadata
	Metadata HostEndpointMetadata `json:"metadata,omitempty"`
	Spec     HostEndpointSpec     `json:"spec,omitempty"`
}

HostEndpoint contains information about a “bare-metal” interfaces attached to the host that is running Calico’s agent, Felix. By default, Calico doesn’t apply any policy to such interfaces.

func NewHostEndpoint 

func NewHostEndpoint() *HostEndpoint

NewHostEndpoint creates a new (zeroed) HostEndpoint struct with the TypeMetadata initialised to the current version.

type HostEndpointList 

type HostEndpointList struct {
	unversioned.TypeMetadata
	Metadata unversioned.ListMetadata `json:"metadata,omitempty"`
	Items    []HostEndpoint           `json:"items" validate:"dive"`
}

HostEndpointList contains a list of Host Endpoint resources. List types are returned from List() enumerations in the client interface.

func NewHostEndpointList 

func NewHostEndpointList() *HostEndpointList

NewHostEndpoint creates a new (zeroed) HostEndpointList struct with the TypeMetadata initialised to the current version.

type HostEndpointMetadata 

type HostEndpointMetadata struct {
	unversioned.ObjectMetadata

	// The name of the endpoint.
	Name string `json:"name,omitempty" validate:"omitempty,name"`

	// The hostname of the compute server.
	Hostname string `json:"hostname,omitempty" validate:"omitempty,name"`

	// The labels applied to the host endpoint.  It is expected that many endpoints share
	// the same labels. For example, they could be used to label all “production” workloads
	// with “deployment=prod” so that security policy can be applied to production workloads.
	Labels map[string]string `json:"labels,omitempty" validate:"omitempty,labels"`
}

HostEndpointMetadata contains the Metadata for a HostEndpoint resource.

type HostEndpointSpec 

type HostEndpointSpec struct {
	// The name of the linux interface to apply policy to; for example “eth0”.
	// If "InterfaceName" is not present then at least one expected IP must be specified.
	InterfaceName string `json:"interfaceName,omitempty" validate:"omitempty,interface"`

	// The expected IP addresses (IPv4 and IPv6) of the endpoint.
	// If "InterfaceName" is not present, Calico will look for an interface matching any
	// of the IPs in the list and apply policy to that.
	//
	// Note:
	// 	When using the selector|tag match criteria in an ingress or egress security Policy
	// 	or Profile, Calico converts the selector into a set of IP addresses. For host
	// 	endpoints, the ExpectedIPs field is used for that purpose. (If only the interface
	// 	name is specified, Calico does not learn the IPs of the interface for use in match
	// 	criteria.)
	ExpectedIPs []net.IP `json:"expectedIPs,omitempty" validate:"omitempty,dive,ip"`

	// A list of identifiers of security Profile objects that apply to this endpoint. Each
	// profile is applied in the order that they appear in this list.  Profile rules are applied
	// after the label-based security policy.
	Profiles []string `json:"profiles,omitempty" validate:"omitempty,dive,name"`
}

HostEndpointSpec contains the specification for a HostEndpoint resource.

type ICMPFields 

type ICMPFields struct {
	// Match on a specific ICMP type.  For example a value of 8 refers to ICMP Echo Request
	// (i.e. pings).
	Type *int `json:"type,omitempty" validate:"omitempty,gte=0,lte=254"`

	// Match on a specific ICMP code.  If specified, the Type value must also be specified.
	// This is a technical limitation imposed by the kernel’s iptables firewall, which
	// Calico uses to enforce the rule.
	Code *int `json:"code,omitempty" validate:"omitempty,gte=0,lte=255"`
}

ICMPFields defines structure for ICMP and NotICMP sub-struct for ICMP code and type

type IPIPConfiguration 

type IPIPConfiguration struct {
	// When enabled is true, ipip tunneling will be used to deliver packets to
	// destinations within this pool.
	Enabled bool `json:"enabled,omitempty"`
}

type IPNAT 

type IPNAT struct {
	// The internal IP address which must be associated with the owning endpoint via the
	// configured IPNetworks for the endpoint.
	InternalIP net.IP `json:"internalIP" validate:"ip"`

	// The external IP address.
	ExternalIP net.IP `json:"externalIP" validate:"ip"`
}

IPNat contains a single NAT mapping for a WorkloadEndpoint resource.

func (IPNAT) String 

func (i IPNAT) String() string

String returns a friendly form of an IPNAT.

type Policy 

type Policy struct {
	unversioned.TypeMetadata
	Metadata PolicyMetadata `json:"metadata,omitempty"`
	Spec     PolicySpec     `json:"spec,omitempty"`
}

Policy contains information about a security Policy resource. This contains a set of security rules to apply. Security policies allow a label-based security model which can override the security profiles directly referenced by an endpoint.

Each policy must do one of the following:

  • Match the packet and apply an “allow” action; this immediately accepts the packet, skipping all further policies and profiles. This is not recommended in general, because it prevents further policy from being executed.
  • Match the packet and apply a “deny” action; this drops the packet immediately, skipping all further policy and profiles.
  • Fail to match the packet; in which case the packet proceeds to the next policy. If there are no more policies then the packet is dropped.

Calico implements the security policy for each endpoint individually and only the policies that have matching selectors are implemented. This ensures that the number of rules that actually need to be inserted into the kernel is proportional to the number of local endpoints rather than the total amount of policy.

func NewPolicy 

func NewPolicy() *Policy

NewPolicy creates a new (zeroed) Policy struct with the TypeMetadata initialised to the current version.

type PolicyList 

type PolicyList struct {
	unversioned.TypeMetadata
	Metadata unversioned.ListMetadata `json:"metadata,omitempty"`
	Items    []Policy                 `json:"items" validate:"dive"`
}

PolicyList contains a list of label-based security Policy resources. List types are returned from List() enumerations on the client interface.

func NewPolicyList 

func NewPolicyList() *PolicyList

NewPolicyList creates a new (zeroed) PolicyList struct with the TypeMetadata initialised to the current version.

type PolicyMetadata 

type PolicyMetadata struct {
	unversioned.ObjectMetadata

	// The name of the label-based security policy.
	Name string `json:"name,omitempty" validate:"omitempty,name"`
}

PolicyMetadata contains the metadata for a label-based security Policy resource.

type PolicySpec 

type PolicySpec struct {
	// Order is an optional field that specifies the order in which the policy is applied.
	// Policies with higher "order" are applied after those with lower
	// order.  If the order is omitted, it may be considered to be "infinite" - i.e. the
	// policy will be applied last.  Policies with identical order will be applied in
	// alphanumerical order based on the Policy "Name".
	Order *float64 `json:"order,omitempty"`

	// The ordered set of ingress rules.  Each rule contains a set of packet match criteria and
	// a corresponding action to apply.
	IngressRules []Rule `json:"ingress,omitempty" validate:"omitempty,dive"`

	// The ordered set of egress rules.  Each rule contains a set of packet match criteria and
	// a corresponding action to apply.
	EgressRules []Rule `json:"egress,omitempty" validate:"omitempty,dive"`

	// The selector is an expression used to pick pick out the endpoints that the policy should
	// be applied to.
	//
	// Selector expressions follow this syntax:
	//
	// 	label == "string_literal"  ->  comparison, e.g. my_label == "foo bar"
	// 	label != "string_literal"   ->  not equal; also matches if label is not present
	// 	label in { "a", "b", "c", ... }  ->  true if the value of label X is one of "a", "b", "c"
	// 	label not in { "a", "b", "c", ... }  ->  true if the value of label X is not one of "a", "b", "c"
	// 	has(label_name)  -> True if that label is present
	// 	! expr -> negation of expr
	// 	expr && expr  -> Short-circuit and
	// 	expr || expr  -> Short-circuit or
	// 	( expr ) -> parens for grouping
	// 	all() or the empty selector -> matches all endpoints.
	//
	// Label names are allowed to contain alphanumerics, -, _ and /. String literals are more permissive
	// but they do not support escape characters.
	//
	// Examples (with made-up labels):
	//
	// 	type == "webserver" && deployment == "prod"
	// 	type in {"frontend", "backend"}
	// 	deployment != "dev"
	// 	! has(label_name)
	Selector string `json:"selector" validate:"selector"`
}

PolicySpec contains the specification for a label-based security Policy resource.

type Pool 

type Pool struct {
	unversioned.TypeMetadata
	Metadata PoolMetadata `json:"metadata,omitempty"`
	Spec     PoolSpec     `json:"spec,omitempty"`
}

Pool contains the details of a Calico IP pool resource. A pool resource is used by Calico in two ways:

  • to provide a set of IP addresses from which Calico IPAM assigns addresses for workloads.
  • to provide configuration specific to IP address range, such as configuration for the BGP daemon (e.g. when to use a GRE tunnel to encapsulate packets between compute hosts).

func NewPool 

func NewPool() *Pool

NewPool creates a new (zeroed) Pool struct with the TypeMetadata initialised to the current version.

type PoolList 

type PoolList struct {
	unversioned.TypeMetadata
	Metadata unversioned.ListMetadata `json:"metadata,omitempty"`
	Items    []Pool                   `json:"items" validate:"dive"`
}

PoolList contains a list of IP pool resources. List types are returned from List() enumerations in the client interface.

func NewPoolList 

func NewPoolList() *PoolList

NewPool creates a new (zeroed) PoolList struct with the TypeMetadata initialised to the current version.

type PoolMetadata 

type PoolMetadata struct {
	unversioned.ObjectMetadata
	CIDR net.IPNet `json:"cidr"`
}

PoolMetadata contains the metadata for an IP pool resource.

type PoolSpec 

type PoolSpec struct {
	// Contains configuration for ipip tunneling for this pool. If not specified,
	// then ipip tunneling is disabled for this pool.
	IPIP *IPIPConfiguration `json:"ipip,omitempty"`

	// When nat-outgoing is true, packets sent from Calico networked containers in
	// this pool to destinations outside of this pool will be masqueraded.
	NATOutgoing bool `json:"nat-outgoing,omitempty"`

	// When disabled is true, Calico IPAM will not assign addresses from this pool.
	Disabled bool `json:"disabled,omitempty"`
}

PoolSpec contains the specification for an IP pool resource.

type Profile 

type Profile struct {
	unversioned.TypeMetadata
	Metadata ProfileMetadata `json:"metadata,omitempty"`
	Spec     ProfileSpec     `json:"spec,omitempty"`
}

Profile contains the details a security profile resource. A profile is set of security rules to apply on an endpoint. An endpoint (either a host endpoint or an endpoint on a workload) can reference zero or more profiles. The profile rules are applied directly to the endpoint *after* the label-based security policy has been applied, and in the order the profiles are declared on the endpoint.

func NewProfile 

func NewProfile() *Profile

NewProfile creates a new (zeroed) Profile struct with the TypeMetadata initialised to the current version.

type ProfileList 

type ProfileList struct {
	unversioned.TypeMetadata
	Metadata unversioned.ListMetadata `json:"metadata,omitempty"`
	Items    []Profile                `json:"items" validate:"dive,omitempty"`
}

A ProfileList contains a list of security Profile resources. List types are returned from List() enumerations on the client interface.

func NewProfileList 

func NewProfileList() *ProfileList

NewProfile creates a new (zeroed) Profile struct with the TypeMetadata initialised to the current version.

type ProfileMetadata 

type ProfileMetadata struct {
	unversioned.ObjectMetadata

	// The name of the endpoint.
	Name string `json:"name,omitempty" validate:"omitempty,name"`

	// The labels to apply to each endpoint that references this profile.  It is expected
	// that many endpoints share the same labels. For example, they could be used to label all
	// “production” workloads with “deployment=prod” so that security policy can be applied
	// to production workloads.
	Labels map[string]string `json:"labels,omitempty" validate:"omitempty,labels"`
}

ProfileMetadata contains the metadata for a security Profile resource.

type ProfileSpec 

type ProfileSpec struct {
	// The ordered set of ingress rules.  Each rule contains a set of packet match criteria and
	// a corresponding action to apply.
	IngressRules []Rule `json:"ingress,omitempty" validate:"omitempty,dive"`

	// The ordered set of egress rules.  Each rule contains a set of packet match criteria and
	// a corresponding action to apply.
	EgressRules []Rule `json:"egress,omitempty" validate:"omitempty,dive"`

	// A list of tags that are applied to each endpoint that references this profile.
	Tags []string `json:"tags,omitempty" validate:"omitempty,dive,tag"`
}

ProfileSpec contains the specification for a security Profile resource.

type Rule 

type Rule struct {
	Action string `json:"action" validate:"action"`

	// IPVersion is an optional field that restricts the rule to only match a specific IP
	// version.
	IPVersion *int `json:"ip_version,omitempty" validate:"omitempty,ipversion"`

	// Protocol is an optional field that restricts the rule to only apply to traffic of
	// a specific IP protocol. Required if any of the EntityRules contain Ports
	// (because ports only apply to certain protocols).
	//
	// Must be one of these string values: "tcp", "udp", "icmp", "icmpv6", "sctp", "udplite"
	// or an integer in the range 1-255.
	Protocol *numorstring.Protocol `json:"protocol,omitempty" validate:"omitempty"`

	// ICMP is an optional field that restricts the rule to apply to a specific type and
	// code of ICMP traffic.  This should only be specified if the Protocol field is set to
	// "icmp" or "icmpv6".
	ICMP *ICMPFields `json:"icmp,omitempty" validate:"omitempty"`

	// NotProtocol is the negated version of the Protocol field.
	NotProtocol *numorstring.Protocol `json:"!protocol,omitempty" validate:"omitempty"`

	// NotICMP is the negated version of the ICMP field.
	NotICMP *ICMPFields `json:"!icmp,omitempty" validate:"omitempty"`

	// Source contains the match criteria that apply to source entity.
	Source EntityRule `json:"source,omitempty" validate:"omitempty"`

	// Destination contains the match criteria that apply to destination entity.
	Destination EntityRule `json:"destination,omitempty" validate:"omitempty"`
}

A Rule encapsulates a set of match criteria and an action. Both label-based security Policy and security Profiles reference rules - separated out as a list of rules for both ingress and egress packet matching.

Each positive match criteria has a negated version, prefixed with ”Not”. All the match criteria within a rule must be satisfied for a packet to match. A single rule can contain the positive and negative version of a match and both must be satisfied for the rule to match.

type WorkloadEndpoint 

type WorkloadEndpoint struct {
	unversioned.TypeMetadata
	Metadata WorkloadEndpointMetadata `json:"metadata,omitempty"`
	Spec     WorkloadEndpointSpec     `json:"spec,omitempty"`
}

func NewWorkloadEndpoint 

func NewWorkloadEndpoint() *WorkloadEndpoint

NewWorkloadEndpoint creates a new (zeroed) WorkloadEndpoint struct with the TypeMetadata initialised to the current version.

type WorkloadEndpointList 

type WorkloadEndpointList struct {
	unversioned.TypeMetadata
	Metadata unversioned.ListMetadata `json:"metadata,omitempty"`
	Items    []WorkloadEndpoint       `json:"items" validate:"dive"`
}

WorkloadEndpointList contains a list of Host Endpoint resources. List types are returned from List() enumerations in the client interface.

func NewWorkloadEndpointList 

func NewWorkloadEndpointList() *WorkloadEndpointList

NewWorkloadEndpointList creates a new (zeroed) NodeList struct with the TypeMetadata initialised to the current version.

type WorkloadEndpointMetadata 

type WorkloadEndpointMetadata struct {
	unversioned.ObjectMetadata

	// The name of the endpoint.  This may be omitted on a create, in which case an endpoint
	// ID will be automatically created, and the endpoint ID will be included in the response.
	Name string `json:"name,omitempty" validate:"omitempty,name"`

	// The name of the workload.
	WorkloadID string `json:"workloadID,omitempty" valid:"omitempty,name"`

	// The name of the orchestrator.
	OrchestratorID string `json:"orchestratorID,omitempty" valid:"omitempty,name"`

	// The name of the node.
	Hostname string `json:"hostname,omitempty" valid:"omitempty,name"`

	// The labels applied to the workload endpoint.  It is expected that many endpoints share
	// the same labels. For example, they could be used to label all “production” workloads
	// with “deployment=prod” so that security policy can be applied to production workloads.
	Labels map[string]string `json:"labels,omitempty" validate:"omitempty,labels"`
}

WorkloadEndpointMetadata contains the Metadata for a WorkloadEndpoint resource.

type WorkloadEndpointSpec 

type WorkloadEndpointSpec struct {
	// IPNetworks is a list of subnets allocated to this endpoint. IP packets will only be
	// allowed to leave this interface if they come from an address in one of these subnets.
	//
	// Currently only /32 for IPv4 and /128 for IPv6 networks are supported.
	IPNetworks []net.IPNet `json:"ipNetworks,omitempty" validate:"omitempty,dive,cidr"`

	// IPNATs is a list of 1:1 NAT mappings to apply to the endpoint. Inbound connections
	// to the external IP will be forwarded to the internal IP. Connections initiated from the
	// internal IP will not have their source address changed, except when an endpoint attempts
	// to connect one of its own external IPs. Each internal IP must be associated with the same
	// endpoint via the configured IPNetworks.
	IPNATs []IPNAT `json:"ipNATs,omitempty" validate:"omitempty,dive"`

	// IPv4Gateway is the gateway IPv4 address for traffic from the workload.
	IPv4Gateway net.IP `json:"ipv4Gateway,omitempty" validate:"omitempty,ipv4"`

	// IPv6Gateway is the gateway IPv6 address for traffic from the workload.
	IPv6Gateway net.IP `json:"ipv6Gateway,omitempty" validate:"omitempty,ipv6"`

	// A list of security Profile resources that apply to this endpoint. Each profile is
	// applied in the order that they appear in this list.  Profile rules are applied
	// after the label-based security policy.
	Profiles []string `json:"profiles,omitempty" validate:"omitempty,dive,name"`

	// InterfaceName the name of the Linux interface on the host: for example, tap80.
	InterfaceName string `json:"interfaceName,omitempty" validate:"interface"`

	// MAC is the MAC address of the endpoint interface.
	MAC net.MAC `json:"mac,omitempty" validate:"omitempty,mac"`
}

WorkloadEndpointMetadata contains the specification for a WorkloadEndpoint resource.

Source Files

View all Source files

Directories

Path Synopsis

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.