Documentation

Overview

    Package identity contains code for managing security identities in Cilium. +groupName=pkg

    Index

    Constants

    View Source
    const (
    	// ClusterIDShift specifies the number of bits the cluster ID will be
    	// shifted
    	ClusterIDShift = 16
    
    	// LocalIdentityFlag is the bit in the numeric identity that identifies
    	// a numeric identity to have local scope
    	LocalIdentityFlag = NumericIdentity(1 << 24)
    
    	// MinimalNumericIdentity represents the minimal numeric identity not
    	// used for reserved purposes.
    	MinimalNumericIdentity = NumericIdentity(256)
    
    	// MinimalAllocationIdentity is the minimum numeric identity handed out
    	// by the identity allocator.
    	MinimalAllocationIdentity = MinimalNumericIdentity
    
    	// MaximumAllocationIdentity is the maximum numeric identity handed out
    	// by the identity allocator
    	MaximumAllocationIdentity = NumericIdentity(^uint16(0))
    
    	// UserReservedNumericIdentity represents the minimal numeric identity that
    	// can be used by users for reserved purposes.
    	UserReservedNumericIdentity = NumericIdentity(128)
    
    	// InvalidIdentity is the identity assigned if the identity is invalid
    	// or not determined yet
    	InvalidIdentity = NumericIdentity(0)
    )

    Variables

    View Source
    var (
    
    	// WellKnown identities stores global state of all well-known identities.
    	WellKnown = wellKnownIdentities{}
    
    	// ErrNotUserIdentity is an error returned for an identity that is not user
    	// reserved.
    	ErrNotUserIdentity = errors.New("not a user reserved identity")
    )
    View Source
    var (
    	// ReservedIdentityCache that maps all reserved identities from their
    	// numeric identity to their corresponding identity.
    	ReservedIdentityCache = map[NumericIdentity]*Identity{}
    )

    Functions

    func AddReservedIdentity

    func AddReservedIdentity(ni NumericIdentity, lbl string)

      AddReservedIdentity adds the reserved numeric identity with the respective label into the map of reserved identity cache.

      func AddUserDefinedNumericIdentity

      func AddUserDefinedNumericIdentity(identity NumericIdentity, label string) error

        AddUserDefinedNumericIdentity adds the given numeric identity and respective label to the list of reservedIdentities. If the numeric identity is not between UserReservedNumericIdentity and MinimalNumericIdentity it will return ErrNotUserIdentity. Is not safe for concurrent use.

        func AddUserDefinedNumericIdentitySet

        func AddUserDefinedNumericIdentitySet(m map[string]string) error

          AddUserDefinedNumericIdentitySet adds all key-value pairs from the given map to the map of user defined numeric identities and reserved identities. The key-value pairs should map a numeric identity to a valid label. Is not safe for concurrent use.

          func DelReservedNumericIdentity

          func DelReservedNumericIdentity(identity NumericIdentity) error

            DelReservedNumericIdentity deletes the given Numeric Identity from the list of reservedIdentities. If the numeric identity is not between UserReservedNumericIdentity and MinimalNumericIdentity it will return ErrNotUserIdentity. Is not safe for concurrent use.

            func IdentityAllocationIsLocal

            func IdentityAllocationIsLocal(lbls labels.Labels) bool

              IdentityAllocationIsLocal returns true if a call to AllocateIdentity with the given labels would not require accessing the KV store to allocate the identity. Currently, this function returns true only if the labels are those of a reserved identity, i.e. if the slice contains a single reserved "reserved:*" label.

              func InitWellKnownIdentities

              func InitWellKnownIdentities(c Configuration) int

                InitWellKnownIdentities establishes all well-known identities. Returns the number of well-known identities initialized.

                func IsUserReservedIdentity

                func IsUserReservedIdentity(id NumericIdentity) bool

                  IsUserReservedIdentity returns true if the given NumericIdentity belongs to the space reserved for users.

                  func IterateReservedIdentities

                  func IterateReservedIdentities(f func(key string, value NumericIdentity))

                    IterateReservedIdentities iterates over all reservedIdentities and executes the given function for each key, value pair in reservedIdentities.

                    func RequiresGlobalIdentity

                    func RequiresGlobalIdentity(lbls labels.Labels) bool

                      RequiresGlobalIdentity returns true if the label combination requires a global identity

                      func SetLocalNodeID

                      func SetLocalNodeID(nodeid uint32)

                        SetLocalNodeID sets the local node id. Note that currently changes to the local node id only take effect during agent bootstrap

                        Types

                        type Configuration

                        type Configuration interface {
                        	LocalClusterName() string
                        	CiliumNamespaceName() string
                        }

                        type IPIdentityPair

                        type IPIdentityPair struct {
                        	IP           net.IP          `json:"IP"`
                        	Mask         net.IPMask      `json:"Mask"`
                        	HostIP       net.IP          `json:"HostIP"`
                        	ID           NumericIdentity `json:"ID"`
                        	Key          uint8           `json:"Key"`
                        	Metadata     string          `json:"Metadata"`
                        	K8sNamespace string          `json:"K8sNamespace,omitempty"`
                        	K8sPodName   string          `json:"K8sPodName,omitempty"`
                        	NamedPorts   []NamedPort     `json:"NamedPorts,omitempty"`
                        }

                          IPIdentityPair is a pairing of an IP and the security identity to which that IP corresponds. May include an optional Mask which, if present, denotes that the IP represents a CIDR with the specified Mask.

                          WARNING - STABLE API This structure is written as JSON to the key-value store. Do NOT modify this structure in ways which are not JSON forward compatible.

                          func (*IPIdentityPair) IsHost

                          func (pair *IPIdentityPair) IsHost() bool

                            IsHost determines whether the IP in the pair represents a host (true) or a CIDR prefix (false)

                            func (*IPIdentityPair) PrefixString

                            func (pair *IPIdentityPair) PrefixString() string

                              PrefixString returns the IPIdentityPair's IP as either a host IP in the format w.x.y.z if 'host' is true, or as a prefix in the format the w.x.y.z/N if 'host' is false.

                              type Identity

                              type Identity struct {
                              	// Identity's ID.
                              	ID NumericIdentity `json:"id"`
                              	// Set of labels that belong to this Identity.
                              	Labels labels.Labels `json:"labels"`
                              
                              	// SHA256 of labels.
                              	LabelsSHA256 string `json:"labelsSHA256"`
                              
                              	// LabelArray contains the same labels as Labels in a form of a list, used
                              	// for faster lookup.
                              	LabelArray labels.LabelArray `json:"-"`
                              
                              	// CIDRLabel is the primary identity label when the identity represents
                              	// a CIDR. The Labels field will consist of all matching prefixes, e.g.
                              	// 10.0.0.0/8
                              	// 10.0.0.0/7
                              	// 10.0.0.0/6
                              	// [...]
                              	// reserved:world
                              	//
                              	// The CIDRLabel field will only contain 10.0.0.0/8
                              	CIDRLabel labels.Labels `json:"-"`
                              
                              	// ReferenceCount counts the number of references pointing to this
                              	// identity. This field is used by the owning cache of the identity.
                              	ReferenceCount int `json:"-"`
                              	// contains filtered or unexported fields
                              }

                                Identity is the representation of the security context for a particular set of labels.

                                func LookupReservedIdentity

                                func LookupReservedIdentity(ni NumericIdentity) *Identity

                                  LookupReservedIdentity looks up a reserved identity by its NumericIdentity and returns it if found. Returns nil if not found.

                                  func LookupReservedIdentityByLabels

                                  func LookupReservedIdentityByLabels(lbls labels.Labels) *Identity

                                    LookupReservedIdentityByLabels looks up a reserved identity by its labels and returns it if found. Returns nil if not found.

                                    func NewIdentity

                                    func NewIdentity(id NumericIdentity, lbls labels.Labels) *Identity

                                      NewIdentity creates a new identity

                                      func NewIdentityFromLabelArray

                                      func NewIdentityFromLabelArray(id NumericIdentity, lblArray labels.LabelArray) *Identity

                                        NewIdentityFromLabelArray creates a new identity

                                        func (*Identity) GetLabelsSHA256

                                        func (id *Identity) GetLabelsSHA256() string

                                          GetLabelsSHA256 returns the SHA256 of the labels associated with the identity. The SHA is calculated if not already cached.

                                          func (*Identity) IsFixed

                                          func (id *Identity) IsFixed() bool

                                            IsFixed returns whether the identity represents a fixed identity (true), or not (false).

                                            func (*Identity) IsReserved

                                            func (id *Identity) IsReserved() bool

                                              IsReserved returns whether the identity represents a reserved identity (true), or not (false).

                                              func (*Identity) IsWellKnown

                                              func (id *Identity) IsWellKnown() bool

                                                IsWellKnown returns whether the identity represents a well known identity (true), or not (false).

                                                func (*Identity) Sanitize

                                                func (id *Identity) Sanitize()

                                                  Sanitize takes a partially initialized Identity (for example, deserialized from json) and reconstitutes the full object from what has been restored.

                                                  func (*Identity) String

                                                  func (id *Identity) String() string

                                                    StringID returns the identity identifier as string

                                                    func (*Identity) StringID

                                                    func (id *Identity) StringID() string

                                                      StringID returns the identity identifier as string

                                                      type NamedPort

                                                      type NamedPort struct {
                                                      	Name     string `json:"Name"`
                                                      	Port     uint16 `json:"Port"`
                                                      	Protocol string `json:"Protocol"`
                                                      }

                                                        NamedPort is a mapping from a port name to a port number and protocol.

                                                        WARNING - STABLE API This structure is written as JSON to the key-value store. Do NOT modify this structure in ways which are not JSON forward compatible.

                                                        type NumericIdentity

                                                        type NumericIdentity uint32

                                                          NumericIdentity is the numeric representation of a security identity.

                                                          Bits:

                                                           0-15: identity identifier
                                                          16-23: cluster identifier
                                                             24: LocalIdentityFlag: Indicates that the identity has a local scope
                                                          
                                                          const (
                                                          	// IdentityUnknown represents an unknown identity
                                                          	IdentityUnknown NumericIdentity = iota
                                                          
                                                          	// ReservedIdentityHost represents the local host
                                                          	ReservedIdentityHost
                                                          
                                                          	// ReservedIdentityWorld represents any endpoint outside of the cluster
                                                          	ReservedIdentityWorld
                                                          
                                                          	// ReservedIdentityUnmanaged represents unmanaged endpoints.
                                                          	ReservedIdentityUnmanaged
                                                          
                                                          	// ReservedIdentityHealth represents the local cilium-health endpoint
                                                          	ReservedIdentityHealth
                                                          
                                                          	// ReservedIdentityInit is the identity given to endpoints that have not
                                                          	// received any labels yet.
                                                          	ReservedIdentityInit
                                                          
                                                          	// ReservedIdentityRemoteNode is the identity given to all nodes in
                                                          	// local and remote clusters except for the local node.
                                                          	ReservedIdentityRemoteNode
                                                          
                                                          	// ReservedETCDOperator is the reserved identity used for the etcd-operator
                                                          	// managed by Cilium.
                                                          	ReservedETCDOperator NumericIdentity = 100
                                                          
                                                          	// ReservedCiliumKVStore is the reserved identity used for the kvstore
                                                          	// managed by Cilium (etcd-operator).
                                                          	ReservedCiliumKVStore NumericIdentity = 101
                                                          
                                                          	// ReservedKubeDNS is the reserved identity used for kube-dns.
                                                          	ReservedKubeDNS NumericIdentity = 102
                                                          
                                                          	// ReservedEKSKubeDNS is the reserved identity used for kube-dns on EKS
                                                          	ReservedEKSKubeDNS NumericIdentity = 103
                                                          
                                                          	// ReservedCoreDNS is the reserved identity used for CoreDNS
                                                          	ReservedCoreDNS NumericIdentity = 104
                                                          
                                                          	// ReservedCiliumOperator is the reserved identity used for the Cilium operator
                                                          	ReservedCiliumOperator NumericIdentity = 105
                                                          
                                                          	// ReservedEKSCoreDNS is the reserved identity used for CoreDNS on EKS
                                                          	ReservedEKSCoreDNS NumericIdentity = 106
                                                          
                                                          	// ReservedCiliumEtcdOperator is the reserved identity used for the Cilium etcd operator
                                                          	ReservedCiliumEtcdOperator NumericIdentity = 107
                                                          )

                                                          func GetAllReservedIdentities

                                                          func GetAllReservedIdentities() []NumericIdentity

                                                            GetAllReservedIdentities returns a list of all reserved numeric identities.

                                                            func GetLocalNodeID

                                                            func GetLocalNodeID() NumericIdentity

                                                              GetLocalNodeID returns the configured local node numeric identity that is set in tunnel headers when encapsulating packets originating from the local node.

                                                              func GetReservedID

                                                              func GetReservedID(name string) NumericIdentity

                                                              func ParseNumericIdentity

                                                              func ParseNumericIdentity(id string) (NumericIdentity, error)

                                                              func (NumericIdentity) ClusterID

                                                              func (id NumericIdentity) ClusterID() int

                                                                ClusterID returns the cluster ID associated with the identity

                                                                func (NumericIdentity) HasLocalScope

                                                                func (id NumericIdentity) HasLocalScope() bool

                                                                  HasLocalScope returns true if the identity has a local scope

                                                                  func (NumericIdentity) IsReservedIdentity

                                                                  func (id NumericIdentity) IsReservedIdentity() bool

                                                                    IsReservedIdentity returns whether id is one of the special reserved identities.

                                                                    func (NumericIdentity) String

                                                                    func (id NumericIdentity) String() string

                                                                    func (NumericIdentity) StringID

                                                                    func (id NumericIdentity) StringID() string

                                                                    func (NumericIdentity) Uint32

                                                                    func (id NumericIdentity) Uint32() uint32

                                                                      Uint32 normalizes the ID for use in BPF program.

                                                                      Directories

                                                                      Path Synopsis
                                                                      Package identitymanager tracks which global identities are being used by the currently running cilium-agent
                                                                      Package identitymanager tracks which global identities are being used by the currently running cilium-agent