Documentation
¶
Overview ¶
Package ipcache provides a local cache of the mapping of IPs of endpoints managed by Cilium to their corresponding security identities.
Index ¶
- Constants
- Variables
- func AllocateCIDRs(prefixes []*net.IPNet, oldNIDs []identity.NumericIdentity, ...) ([]*identity.Identity, error)
- func AllocateCIDRsForIPs(prefixes []net.IP, newlyAllocatedIdentities map[string]*identity.Identity) ([]*identity.Identity, error)
- func DeleteIPFromKVStore(ctx context.Context, ip string) error
- func GetIDMetadataByIP(prefix string) labels.Labels
- func InitIPIdentityWatcher()
- func InjectLabels(src source.Source, updater identityUpdater, triggerer policyTriggerer) error
- func ReleaseCIDRIdentitiesByCIDR(prefixes []*net.IPNet)
- func ReleaseCIDRIdentitiesByID(ctx context.Context, identities []identity.NumericIdentity)
- func RemoveLabelsExcluded(lbls labels.Labels, toExclude map[string]struct{}, src source.Source, ...)
- func UpsertGeneratedIdentities(newlyAllocatedIdentities map[string]*identity.Identity)
- func UpsertIPToKVStore(ctx context.Context, IP, hostIP net.IP, ID identity.NumericIdentity, key uint8, ...) error
- func UpsertMetadata(prefix string, lbls labels.Labels)
- func WaitForKVStoreSync()
- type CacheModification
- type ErrInvalidIP
- type ErrOverwrite
- type IPCache
- func (ipc *IPCache) AddListener(listener IPIdentityMappingListener)
- func (ipc *IPCache) Delete(IP string, source source.Source) (namedPortsChanged bool)
- func (ipc *IPCache) DeleteOnMetadataMatch(IP string, source source.Source, namespace, name string) (namedPortsChanged bool)
- func (ipc *IPCache) DumpToListenerLocked(listener IPIdentityMappingListener)
- func (ipc *IPCache) GetK8sMetadata(ip string) *K8sMetadata
- func (ipc *IPCache) GetNamedPorts() (npm policy.NamedPortMultiMap)
- func (ipc *IPCache) Lock()
- func (ipc *IPCache) LookupByHostRLocked(hostIPv4, hostIPv6 net.IP) (cidrs []net.IPNet)
- func (ipc *IPCache) LookupByIP(IP string) (Identity, bool)
- func (ipc *IPCache) LookupByIPRLocked(IP string) (Identity, bool)
- func (ipc *IPCache) LookupByIdentity(id identity.NumericIdentity) (ips []string)
- func (ipc *IPCache) LookupByPrefix(IP string) (Identity, bool)
- func (ipc *IPCache) LookupByPrefixRLocked(prefix string) (identity Identity, exists bool)
- func (ipc *IPCache) RLock()
- func (ipc *IPCache) RUnlock()
- func (ipc *IPCache) RegisterK8sSyncedChecker(c k8sSyncedChecker)
- func (ipc *IPCache) SetListeners(listeners []IPIdentityMappingListener)
- func (ipc *IPCache) TriggerLabelInjection(src source.Source, sc identityUpdater, pt policyTriggerer)
- func (ipc *IPCache) Unlock()
- func (ipc *IPCache) UpdateController(name string, params controller.ControllerParams)
- func (ipc *IPCache) Upsert(ip string, hostIP net.IP, hostKey uint8, k8sMeta *K8sMetadata, ...) (namedPortsChanged bool, err error)
- type IPIdentityMappingListener
- type IPIdentityWatcher
- type IPKeyPair
- type Identity
- type K8sMetadata
Constants ¶
const ( // DefaultAddressSpace is the address space used if none is provided. // TODO - once pkg/node adds this to clusterConfiguration, remove. DefaultAddressSpace = "default" )
Variables ¶
var ( // IPIdentitiesPath is the path to where endpoint IPs are stored in the key-value //store. IPIdentitiesPath = path.Join(kvstore.BaseKeyPrefix, "state", "ip", "v1") // AddressSpace is the address space (cluster, etc.) in which policy is // computed. It is determined by the orchestration system / runtime. AddressSpace = DefaultAddressSpace )
var ( // ErrLocalIdentityAllocatorUninitialized is an error that's returned when // the local identity allocator is uninitialized. ErrLocalIdentityAllocatorUninitialized = errors.New("local identity allocator uninitialized") )
var ( // IPIdentityCache caches the mapping of endpoint IPs to their corresponding // security identities across the entire cluster in which this instance of // Cilium is running. IPIdentityCache = NewIPCache() )
var ( // IdentityAllocator is a package-level variable which is used to allocate // identities for CIDRs. // TODO: plumb an allocator in from callers of these functions vs. having // this as a package-level variable. IdentityAllocator cache.IdentityAllocator )
Functions ¶
func AllocateCIDRs ¶ added in v1.5.0
func AllocateCIDRs( prefixes []*net.IPNet, oldNIDs []identity.NumericIdentity, newlyAllocatedIdentities map[string]*identity.Identity, ) ([]*identity.Identity, error)
AllocateCIDRs attempts to allocate identities for a list of CIDRs. If any allocation fails, all allocations are rolled back and the error is returned. When an identity is freshly allocated for a CIDR, it is added to the ipcache if 'newlyAllocatedIdentities' is 'nil', otherwise the newly allocated identities are placed in 'newlyAllocatedIdentities' and it is the caller's responsibility to upsert them into ipcache by calling UpsertGeneratedIdentities().
Previously used numeric identities for the given prefixes may be passed in as the 'oldNIDs' parameter; nil slice must be passed if no previous numeric identities exist.
Upon success, the caller must also arrange for the resulting identities to be released via a subsequent call to ReleaseCIDRIdentitiesByCIDR().
func AllocateCIDRsForIPs ¶ added in v1.6.0
func AllocateCIDRsForIPs( prefixes []net.IP, newlyAllocatedIdentities map[string]*identity.Identity, ) ([]*identity.Identity, error)
AllocateCIDRsForIPs performs the same action as AllocateCIDRs but for IP addresses instead of CIDRs.
Upon success, the caller must also arrange for the resulting identities to be released via a subsequent call to ReleaseCIDRIdentitiesByID().
func DeleteIPFromKVStore ¶
DeleteIPFromKVStore removes the IP->Identity mapping for the specified ip from the kvstore, which will subsequently trigger an event in NewIPIdentityWatcher().
func GetIDMetadataByIP ¶ added in v1.11.0
GetIDMetadataByIP returns the associated labels with an IP. The caller must not modifying the returned object as it's a live reference to the underlying map.
func InitIPIdentityWatcher ¶ added in v1.5.0
func InitIPIdentityWatcher()
InitIPIdentityWatcher initializes the watcher for ip-identity mapping events in the key-value store.
func InjectLabels ¶ added in v1.11.0
InjectLabels injects labels from the identityMetadata (IDMD) map into the identities used for the prefixes in the IPCache. The given source is the source of the caller, as inserting into the IPCache requires knowing where this updated information comes from. Conversely, RemoveLabelsExcluded() performs the inverse: removes labels from the IDMD map and releases identities allocated by this function.
Note that as this function iterates through the IDMD, if it detects a change in labels for a given prefix, then this might allocate a new identity. If a prefix was previously associated with an identity, it will get deallocated, so a balance is kept, ensuring a one-to-one mapping between prefix and identity.
func ReleaseCIDRIdentitiesByCIDR ¶ added in v1.10.6
ReleaseCIDRIdentitiesByCIDR releases the identities of a list of CIDRs. When the last use of the identity is released, the ipcache entry is deleted.
func ReleaseCIDRIdentitiesByID ¶ added in v1.10.6
func ReleaseCIDRIdentitiesByID(ctx context.Context, identities []identity.NumericIdentity)
ReleaseCIDRIdentitiesByID releases the specified identities. When the last use of the identity is released, the ipcache entry is deleted.
func RemoveLabelsExcluded ¶ added in v1.11.1
func RemoveLabelsExcluded( lbls labels.Labels, toExclude map[string]struct{}, src source.Source, updater identityUpdater, triggerer policyTriggerer, )
RemoveLabelsExcluded removes the given labels from all IPs inside the IDMD except for the IPs / prefixes inside the given excluded set. This may cause updates to the ipcache, as well as to the identity and policy logic via 'updater' and 'triggerer'.
func UpsertGeneratedIdentities ¶ added in v1.7.12
func UpsertIPToKVStore ¶
func UpsertIPToKVStore(ctx context.Context, IP, hostIP net.IP, ID identity.NumericIdentity, key uint8, metadata, k8sNamespace, k8sPodName string, npm policy.NamedPortMap) error
UpsertIPToKVStore updates / inserts the provided IP->Identity mapping into the kvstore, which will subsequently trigger an event in NewIPIdentityWatcher().
func UpsertMetadata ¶ added in v1.11.0
UpsertMetadata upserts a given IP and its corresponding labels associated with it into the identityMetadata map. The given labels are not modified nor is its reference saved, as they're copied when inserting into the map.
func WaitForKVStoreSync ¶
func WaitForKVStoreSync()
WaitForKVStoreSync waits until the ipcache has been synchronized from the kvstore
Types ¶
type CacheModification ¶
type CacheModification string
CacheModification represents the type of operation performed upon IPCache.
const ( // Upsert represents Upsertion into IPCache. Upsert CacheModification = "Upsert" // Delete represents deletion of an entry in IPCache. Delete CacheModification = "Delete" )
type ErrInvalidIP ¶
type ErrInvalidIP struct {
// contains filtered or unexported fields
}
ErrInvalidIP represents an error of an invalid IP.
func NewErrInvalidIP ¶
func NewErrInvalidIP(ip string) *ErrInvalidIP
NewErrInvalidIP returns a new ErrInvalidIP.
func (ErrInvalidIP) Error ¶
func (e ErrInvalidIP) Error() string
func (*ErrInvalidIP) Is ¶
func (e *ErrInvalidIP) Is(target error) bool
type ErrOverwrite ¶
ErrOverwrite represents an overwrite error where functions return the error to indicate the new source can't overwrite existing source.
func NewErrOverwrite ¶
func NewErrOverwrite(existing, new source.Source) *ErrOverwrite
NewErrOverwrite returns a new ErrOverwrite.
func (ErrOverwrite) Error ¶
func (e ErrOverwrite) Error() string
func (*ErrOverwrite) Is ¶
func (e *ErrOverwrite) Is(target error) bool
type IPCache ¶
type IPCache struct {
// contains filtered or unexported fields
}
IPCache is a collection of mappings:
- mapping of endpoint IP or CIDR to security identities of all endpoints which are part of the same cluster, and vice-versa
- mapping of endpoint IP or CIDR to host IP (maybe nil)
func NewIPCache ¶
func NewIPCache() *IPCache
NewIPCache returns a new IPCache with the mappings of endpoint IP to security identity (and vice-versa) initialized.
func (*IPCache) AddListener ¶
func (ipc *IPCache) AddListener(listener IPIdentityMappingListener)
AddListener adds a listener for this IPCache.
func (*IPCache) Delete ¶
Delete removes the provided IP-to-security-identity mapping from the IPCache.
func (*IPCache) DeleteOnMetadataMatch ¶
func (ipc *IPCache) DeleteOnMetadataMatch(IP string, source source.Source, namespace, name string) (namedPortsChanged bool)
DeleteOnMetadataMatch removes the provided IP to security identity mapping from the IPCache if the metadata cache holds the same "owner" metadata as the triggering pod event.
func (*IPCache) DumpToListenerLocked ¶
func (ipc *IPCache) DumpToListenerLocked(listener IPIdentityMappingListener)
DumpToListenerLocked dumps the entire contents of the IPCache by triggering the listener's "OnIPIdentityCacheChange" method for each entry in the cache.
func (*IPCache) GetK8sMetadata ¶
func (ipc *IPCache) GetK8sMetadata(ip string) *K8sMetadata
GetK8sMetadata returns Kubernetes metadata for the given IP address. The returned pointer should *never* be modified.
func (*IPCache) GetNamedPorts ¶
func (ipc *IPCache) GetNamedPorts() (npm policy.NamedPortMultiMap)
GetNamedPorts returns a copy of the named ports map. May return nil.
func (*IPCache) LookupByHostRLocked ¶
LookupByHostRLocked returns the list of IPs returns the set of IPs (endpoint or CIDR prefix) that have hostIPv4 or hostIPv6 associated as the host of the entry. Requires the caller to hold the RLock.
func (*IPCache) LookupByIP ¶
LookupByIP returns the corresponding security identity that endpoint IP maps to within the provided IPCache, as well as if the corresponding entry exists in the IPCache.
func (*IPCache) LookupByIPRLocked ¶
LookupByIPRLocked returns the corresponding security identity that endpoint IP maps to within the provided IPCache, as well as if the corresponding entry exists in the IPCache.
func (*IPCache) LookupByIdentity ¶
func (ipc *IPCache) LookupByIdentity(id identity.NumericIdentity) (ips []string)
LookupByIdentity returns the set of IPs (endpoint or CIDR prefix) that have security identity ID, or nil if the entry does not exist.
func (*IPCache) LookupByPrefix ¶
LookupByPrefix returns the corresponding security identity that endpoint IP maps to within the provided IPCache, as well as if the corresponding entry exists in the IPCache.
func (*IPCache) LookupByPrefixRLocked ¶
LookupByPrefixRLocked looks for either the specified CIDR prefix, or if the prefix is fully specified (ie, w.x.y.z/32 for IPv4), find the host for the identity in the provided IPCache, and returns the corresponding security identity as well as whether the entry exists in the IPCache.
func (*IPCache) RegisterK8sSyncedChecker ¶ added in v1.11.0
func (ipc *IPCache) RegisterK8sSyncedChecker(c k8sSyncedChecker)
RegisterK8sWaiter registers the object that checks for wehther the K8s cache has been fully synced.
func (*IPCache) SetListeners ¶
func (ipc *IPCache) SetListeners(listeners []IPIdentityMappingListener)
SetListeners sets the listeners for this IPCache.
func (*IPCache) TriggerLabelInjection ¶
func (ipc *IPCache) TriggerLabelInjection(src source.Source, sc identityUpdater, pt policyTriggerer)
TriggerLabelInjection triggers the label injection controller to iterate through the IDMD and potentially allocate new identities based on any label changes.
The following diagram describes the relationship between the label injector triggered here and the callers/callees.
+------------+ (1) (1) +-----------------------------+ | EP Watcher +-----+ +-----+ CN Watcher / Node Discovery | +-----+------+ W | | W +------+----------------------+ | | | | | v v | | +------+ | | | IDMD | | | +------+ | | ^ | | | | | (3) |R | | (2) +------+--------+ (2) | +------->|Label Injector |<------+ Trigger +-------+-------+ Trigger (4) |W | v +---+ |IPC| +---+ legend: * W means write * R means read
func (*IPCache) UpdateController ¶
func (ipc *IPCache) UpdateController(name string, params controller.ControllerParams)
Update a controller for this IPCache
func (*IPCache) Upsert ¶
func (ipc *IPCache) Upsert(ip string, hostIP net.IP, hostKey uint8, k8sMeta *K8sMetadata, newIdentity Identity) (namedPortsChanged bool, err error)
Upsert adds / updates the provided IP (endpoint or CIDR prefix) and identity into the IPCache.
Returns an error if the entry is not owned by the self declared source, i.e. returns error if the kubernetes layer is trying to upsert an entry now managed by the kvstore layer or if 'ip' is invalid. See source.AllowOverwrite() for rules on ownership. hostIP is the location of the given IP. It is optional (may be nil) and is propagated to the listeners. k8sMeta contains Kubernetes-specific metadata such as pod namespace and pod name belonging to the IP (may be nil).
type IPIdentityMappingListener ¶
type IPIdentityMappingListener interface { // OnIPIdentityCacheChange will be called whenever there the state of the // IPCache has changed. If an existing CIDR->ID mapping is updated, then // oldID is not nil; otherwise it is nil. // hostIP is the IP address of the location of the cidr. // hostIP is optional and may only be non-nil for an Upsert modification. // k8sMeta contains the Kubernetes pod namespace and name behind the IP // and may be nil. OnIPIdentityCacheChange(modType CacheModification, cidr net.IPNet, oldHostIP, newHostIP net.IP, oldID *Identity, newID Identity, encryptKey uint8, k8sMeta *K8sMetadata) // OnIPIdentityCacheGC will be called to sync other components which are // reliant upon the IPIdentityCache with the IPIdentityCache. OnIPIdentityCacheGC() }
IPIdentityMappingListener represents a component that is interested in learning about IP to Identity mapping events.
type IPIdentityWatcher ¶
type IPIdentityWatcher struct {
// contains filtered or unexported fields
}
IPIdentityWatcher is a watcher that will notify when IP<->identity mappings change in the kvstore
func NewIPIdentityWatcher ¶
func NewIPIdentityWatcher(backend kvstore.BackendOperations) *IPIdentityWatcher
NewIPIdentityWatcher creates a new IPIdentityWatcher using the specified kvstore backend
func (*IPIdentityWatcher) Close ¶ added in v1.5.0
func (iw *IPIdentityWatcher) Close()
Close stops the IPIdentityWatcher and causes Watch() to return
func (*IPIdentityWatcher) Watch ¶
func (iw *IPIdentityWatcher) Watch(ctx context.Context)
Watch starts the watcher and blocks waiting for events. When events are received from the kvstore, All IPIdentityMappingListener are notified. The function returns when IPIdentityWatcher.Close() is called. The watcher will automatically restart as required.
type Identity ¶
type Identity struct { // ID is the numeric identity ID identity.NumericIdentity // Source is the source of the identity in the cache Source source.Source // contains filtered or unexported fields }
Identity is the identity representation of an IP<->Identity cache.
type K8sMetadata ¶
type K8sMetadata struct { // Namespace is the Kubernetes namespace of the pod behind the IP Namespace string // PodName is the Kubernetes pod name behind the IP PodName string // NamedPorts is the set of named ports for the pod NamedPorts policy.NamedPortMap }
K8sMetadata contains Kubernetes pod information of the IP
func (*K8sMetadata) Equal ¶
func (m *K8sMetadata) Equal(o *K8sMetadata) bool
Equal returns true if two K8sMetadata pointers contain the same data or are both nil.