kube

package
v0.138.0 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2025 License: Apache-2.0 Imports: 28 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// From historical reasons some of workloads are using `*.labels.*` and `*.annotations.*` instead of
	// `*.label.*` and `*.annotation.*`
	// Sematic conventions define `*.label.*` and `*.annotation.*`
	// More information - https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/37957
	K8sPodLabelsKey            = "k8s.pod.labels.%s"
	K8sPodLabelKey             = "k8s.pod.label.%s"
	K8sPodAnnotationsKey       = "k8s.pod.annotations.%s"
	K8sPodAnnotationKey        = "k8s.pod.annotation.%s"
	K8sNodeLabelsKey           = "k8s.node.labels.%s"
	K8sNodeLabelKey            = "k8s.node.label.%s"
	K8sNodeAnnotationsKey      = "k8s.node.annotations.%s"
	K8sNodeAnnotationKey       = "k8s.node.annotation.%s"
	K8sNamespaceLabelsKey      = "k8s.namespace.labels.%s"
	K8sNamespaceLabelKey       = "k8s.namespace.label.%s"
	K8sNamespaceAnnotationsKey = "k8s.namespace.annotations.%s"
	K8sNamespaceAnnotationKey  = "k8s.namespace.annotation.%s"
	// Semconv attributes https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/k8s.md#deployment
	K8sDeploymentLabel      = "k8s.deployment.label.%s"
	K8sDeploymentAnnotation = "k8s.deployment.annotation.%s"
	// Semconv attributes https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/k8s.md#statefulset
	K8sStatefulSetLabel      = "k8s.statefulset.label.%s"
	K8sStatefulSetAnnotation = "k8s.statefulset.annotation.%s"
	// Semconv attributes https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/k8s.md#daemonset
	K8sDaemonSetLabel      = "k8s.daemonset.label.%s"
	K8sDaemonSetAnnotation = "k8s.daemonset.annotation.%s"
	// Semconv attributes https://github.com/open-telemetry/semantic-conventions/blob/main/docs/resource/k8s.md#job
	K8sJobLabel      = "k8s.job.label.%s"
	K8sJobAnnotation = "k8s.job.annotation.%s"
)
View Source
const (

	// MetadataFromPod is used to specify to extract metadata/labels/annotations from pod
	MetadataFromPod = "pod"
	// MetadataFromNamespace is used to specify to extract metadata/labels/annotations from namespace
	MetadataFromNamespace = "namespace"
	// MetadataFromNode is used to specify to extract metadata/labels/annotations from node
	MetadataFromNode = "node"
	// MetadataFromDeployment is used to specify to extract metadata/labels/annotations from deployment
	MetadataFromDeployment = "deployment"
	// MetadataFromStatefulSet is used to specify to extract metadata/labels/annotations from statefulset
	MetadataFromStatefulSet = "statefulset"
	// MetadataFromDaemonSet  is used to specify to extract metadata/labels/annotations from daemonset
	MetadataFromDaemonSet = "daemonset"
	// MetadataFromJob  is used to specify to extract metadata/labels/annotations from job
	MetadataFromJob        = "job"
	PodIdentifierMaxLength = 4

	ResourceSource   = "resource_attribute"
	ConnectionSource = "connection"
	K8sIPLabelName   = "k8s.pod.ip"
)

Variables

This section is empty.

Functions

func NewFakeInformer

func NewFakeInformer(
	_ kubernetes.Interface,
	namespace string,
	labelSelector labels.Selector,
	fieldSelector fields.Selector,
) cache.SharedInformer

func NewFakeNamespaceInformer

func NewFakeNamespaceInformer(
	_ kubernetes.Interface,
) cache.SharedInformer

func NewFakeReplicaSetInformer added in v0.78.0

func NewFakeReplicaSetInformer(
	_ kubernetes.Interface,
	_ string,
) cache.SharedInformer

func NewNoOpInformer

func NewNoOpInformer(
	_ kubernetes.Interface,
) cache.SharedInformer

func NewNoOpWorkloadInformer added in v0.128.0

func NewNoOpWorkloadInformer(
	_ kubernetes.Interface,
	_ string,
) cache.SharedInformer

Types

type APIClientsetProvider

type APIClientsetProvider func(config k8sconfig.APIConfig) (kubernetes.Interface, error)

APIClientsetProvider defines a func type that initializes and return a new kubernetes Clientset object.

type Association

type Association struct {
	Name    string
	Sources []AssociationSource
}

Association represents one association rule

type AssociationSource added in v0.55.0

type AssociationSource struct {
	From string
	Name string
}

type Associations

type Associations struct {
	Associations []Association
}

Associations represent a list of rules for Pod metadata associations with resources

type Client

type Client interface {
	GetPod(PodIdentifier) (*Pod, bool)
	GetNamespace(string) (*Namespace, bool)
	GetNode(string) (*Node, bool)
	GetDeployment(string) (*Deployment, bool)
	GetStatefulSet(string) (*StatefulSet, bool)
	GetDaemonSet(string) (*DaemonSet, bool)
	GetJob(string) (*Job, bool)
	Start() error
	Stop()
}

Client defines the main interface that allows querying pods by metadata.

func New

func New(
	set component.TelemetrySettings,
	apiCfg k8sconfig.APIConfig,
	rules ExtractionRules,
	filters Filters,
	associations []Association,
	exclude Excludes,
	newClientSet APIClientsetProvider,
	informersFactory InformersFactoryList,
	waitForMetadata bool,
	waitForMetadataTimeout time.Duration,
) (Client, error)

New initializes a new k8s Client.

type ClientProvider

ClientProvider defines a func type that returns a new Client.

type Container

type Container struct {
	Name              string
	ImageName         string
	ImageTag          string
	ServiceInstanceID string
	ServiceVersion    string

	// Statuses is a map of container k8s.container.restart_count attribute to ContainerStatus struct.
	Statuses map[int]ContainerStatus
}

Container stores resource attributes for a specific container defined by k8s pod spec.

type ContainerStatus

type ContainerStatus struct {
	ContainerID     string
	ImageRepoDigest string
}

ContainerStatus stores resource attributes for a particular container run defined by k8s pod status.

type CronJob added in v0.136.0

type CronJob struct {
	Name       string
	UID        string
	Attributes map[string]string
}

CronJob represents a kubernetes cronjob.

type DaemonSet added in v0.135.0

type DaemonSet struct {
	Name       string
	UID        string
	Attributes map[string]string
}

DaemonSet represents a kubernetes daemonset.

type Deployment added in v0.78.0

type Deployment struct {
	Name       string
	UID        string
	Attributes map[string]string
}

Deployment represents a kubernetes deployment.

type ExcludePods

type ExcludePods struct {
	Name *regexp.Regexp
}

ExcludePods represent a Pod name to ignore

type Excludes

type Excludes struct {
	Pods []ExcludePods
}

Excludes represent a list of Pods to ignore

type ExtractionRules

type ExtractionRules struct {
	CronJobName               bool
	CronJobUID                bool
	DeploymentName            bool
	DeploymentUID             bool
	DaemonSetUID              bool
	DaemonSetName             bool
	JobUID                    bool
	JobName                   bool
	Namespace                 bool
	PodName                   bool
	PodUID                    bool
	PodHostName               bool
	PodIP                     bool
	ReplicaSetID              bool
	ReplicaSetName            bool
	StatefulSetUID            bool
	StatefulSetName           bool
	Node                      bool
	NodeUID                   bool
	StartTime                 bool
	ContainerName             bool
	ContainerID               bool
	ContainerImageName        bool
	ContainerImageRepoDigests bool
	ContainerImageTag         bool
	ClusterUID                bool
	ServiceNamespace          bool
	ServiceName               bool
	ServiceVersion            bool
	ServiceInstanceID         bool

	Annotations []FieldExtractionRule
	Labels      []FieldExtractionRule
}

ExtractionRules is used to specify the information that needs to be extracted from pods and added to the spans as tags.

func (*ExtractionRules) IncludesOwnerMetadata added in v0.80.0

func (rules *ExtractionRules) IncludesOwnerMetadata() bool

IncludesOwnerMetadata determines whether the ExtractionRules include metadata about Pod Owners

type FakeController

type FakeController struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func (*FakeController) HasStopped

func (c *FakeController) HasStopped() bool

func (*FakeController) HasSynced

func (*FakeController) HasSynced() bool

func (*FakeController) LastSyncResourceVersion

func (*FakeController) LastSyncResourceVersion() string

func (*FakeController) Run

func (c *FakeController) Run(stopCh <-chan struct{})

type FakeInformer

type FakeInformer struct {
	*FakeController
	// contains filtered or unexported fields
}

func (*FakeInformer) AddEventHandler

func (*FakeInformer) AddEventHandlerWithResyncPeriod

func (*FakeInformer) GetController

func (f *FakeInformer) GetController() cache.Controller

func (*FakeInformer) GetStore

func (*FakeInformer) GetStore() cache.Store

func (*FakeInformer) IsStopped added in v0.68.0

func (*FakeInformer) IsStopped() bool

func (*FakeInformer) RemoveEventHandler added in v0.68.0

func (*FakeInformer) SetTransform added in v0.51.0

func (*FakeInformer) SetTransform(cache.TransformFunc) error

func (*FakeInformer) SetWatchErrorHandler

func (*FakeInformer) SetWatchErrorHandler(cache.WatchErrorHandler) error

type FakeNamespaceInformer

type FakeNamespaceInformer struct {
	*FakeController
}

func (*FakeNamespaceInformer) AddEventHandler

func (*FakeNamespaceInformer) AddEventHandlerWithResyncPeriod

func (*FakeNamespaceInformer) AddEventHandlerWithResyncPeriod(cache.ResourceEventHandler, time.Duration)

func (*FakeNamespaceInformer) GetController

func (f *FakeNamespaceInformer) GetController() cache.Controller

func (*FakeNamespaceInformer) GetStore

func (*FakeNamespaceInformer) GetStore() cache.Store

type FakeReplicaSetInformer added in v0.78.0

type FakeReplicaSetInformer struct {
	*FakeController
}

func (*FakeReplicaSetInformer) AddEventHandler added in v0.78.0

func (*FakeReplicaSetInformer) AddEventHandlerWithResyncPeriod added in v0.78.0

func (*FakeReplicaSetInformer) AddEventHandlerWithResyncPeriod(cache.ResourceEventHandler, time.Duration)

func (*FakeReplicaSetInformer) GetController added in v0.78.0

func (f *FakeReplicaSetInformer) GetController() cache.Controller

func (*FakeReplicaSetInformer) GetStore added in v0.78.0

func (*FakeReplicaSetInformer) GetStore() cache.Store

func (*FakeReplicaSetInformer) SetTransform added in v0.78.0

type FieldExtractionRule

type FieldExtractionRule struct {
	// Name is used to as the Span tag name.
	Name string
	// Key is used to lookup k8s pod fields.
	Key string
	// KeyRegex is a regular expression(full length match) used to extract a Key that matches the regex.
	KeyRegex             *regexp.Regexp
	HasKeyRegexReference bool
	// Regex is a regular expression used to extract a sub-part of a field value.
	// Full value is extracted when no regexp is provided.
	Regex *regexp.Regexp
	// From determines the kubernetes object the field should be retrieved from.
	// Currently only three values are supported,
	//  - pod
	//  - namespace
	//  - node
	//  - deployment
	//  - statefulset
	//  - daemonset
	//  - job
	From string
}

FieldExtractionRule is used to specify which fields to extract from pod fields and inject into spans as attributes.

func OtelAnnotations added in v0.127.0

func OtelAnnotations() FieldExtractionRule

type FieldFilter

type FieldFilter struct {
	// Key matches the field name.
	Key string
	// Value matches the field value.
	Value string
	// Op determines the matching operation.
	// Currently only two operations are supported,
	//  - Equals
	//  - NotEquals
	Op selection.Operator
}

FieldFilter represents exactly one filter by field rule.

type Filters

type Filters struct {
	Node      string
	Namespace string
	Fields    []FieldFilter
	Labels    []LabelFilter
}

Filters is used to instruct the client on how to filter out k8s pods. Right now only filters supported are the ones supported by k8s API itself for performance reasons. We can support adding additional custom filters in future if there is a real need.

type InformerProvider

type InformerProvider func(
	client kubernetes.Interface,
	namespace string,
	labelSelector labels.Selector,
	fieldSelector fields.Selector,
) cache.SharedInformer

InformerProvider defines a function type that returns a new SharedInformer. It is used to allow passing custom shared informers to the watch client.

type InformerProviderNamespace

type InformerProviderNamespace func(
	client kubernetes.Interface,
) cache.SharedInformer

InformerProviderNamespace defines a function type that returns a new SharedInformer. It is used to allow passing custom shared informers to the watch client for fetching namespace objects.

type InformerProviderNode added in v0.89.0

type InformerProviderNode func(
	client kubernetes.Interface,
) cache.SharedInformer

InformerProviderNode defines a function type that returns a new SharedInformer. It is used to allow passing custom shared informers to the watch client for fetching node objects.

type InformerProviderWorkload added in v0.128.0

type InformerProviderWorkload func(
	client kubernetes.Interface,
	namespace string,
) cache.SharedInformer

InformerProviderWorkload defines a function type that returns a new SharedInformer. It is used to allow passing custom shared informers to the watch client. It's used for high-level workloads such as ReplicaSets, Deployments, DaemonSets, StatefulSets or Jobs

type InformersFactoryList added in v0.128.0

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

type Job added in v0.135.0

type Job struct {
	Name       string
	UID        string
	Attributes map[string]string
	CronJob    CronJob
}

Job represents a kubernetes job.

type LabelFilter added in v0.120.0

type LabelFilter struct {
	// Key matches the label name.
	Key string
	// Value matches the label value.
	Value string
	// Op determines the matching operation.
	// The following operations are supported,
	//	- Exists
	// 	- DoesNotExist
	//	- Equals
	//	- DoubleEquals
	//	- NotEquals
	//	- GreaterThan
	//	- LessThan
	Op selection.Operator
}

LabelFilter represents exactly one filter by label rule.

type Namespace

type Namespace struct {
	Name         string
	NamespaceUID string
	Attributes   map[string]string
	StartTime    metav1.Time
	DeletedAt    time.Time
}

Namespace represents a kubernetes namespace.

type NoOpController

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

func (*NoOpController) HasSynced

func (*NoOpController) HasSynced() bool

func (*NoOpController) IsStopped added in v0.68.0

func (c *NoOpController) IsStopped() bool

func (*NoOpController) LastSyncResourceVersion

func (*NoOpController) LastSyncResourceVersion() string

func (*NoOpController) Run

func (c *NoOpController) Run(stopCh <-chan struct{})

func (*NoOpController) SetWatchErrorHandler

func (*NoOpController) SetWatchErrorHandler(cache.WatchErrorHandler) error

type NoOpInformer

type NoOpInformer struct {
	*NoOpController
}

func (*NoOpInformer) AddEventHandler

func (*NoOpInformer) GetController

func (f *NoOpInformer) GetController() cache.Controller

func (*NoOpInformer) GetStore

func (*NoOpInformer) GetStore() cache.Store

func (*NoOpInformer) RemoveEventHandler added in v0.68.0

func (*NoOpInformer) SetTransform added in v0.51.0

func (*NoOpInformer) SetTransform(cache.TransformFunc) error

type Node added in v0.89.0

type Node struct {
	Name       string
	NodeUID    string
	Attributes map[string]string
}

Node represents a kubernetes node.

type Pod

type Pod struct {
	Name           string
	Address        string
	PodUID         string
	Attributes     map[string]string
	StartTime      *metav1.Time
	Ignore         bool
	Namespace      string
	NodeName       string
	DeploymentUID  string
	StatefulSetUID string
	DaemonSetUID   string
	JobUID         string
	HostNetwork    bool

	// Containers specifies all containers in this pod.
	Containers PodContainers

	DeletedAt time.Time
}

Pod represents a kubernetes pod.

type PodContainers added in v0.76.1

type PodContainers struct {
	// ByID specifies all containers in a pod by container ID.
	ByID map[string]*Container
	// ByName specifies all containers in a pod by container name (k8s.container.name).
	ByName map[string]*Container
}

PodContainers specifies a list of pod containers. It is not safe for concurrent use.

type PodIdentifier

PodIdentifier is a custom type to represent Pod identification

func (*PodIdentifier) IsNotEmpty added in v0.55.0

func (p *PodIdentifier) IsNotEmpty() bool

IsNotEmpty checks if PodIdentifier is empty or not

type PodIdentifierAttribute added in v0.55.0

type PodIdentifierAttribute struct {
	Source AssociationSource
	Value  string
}

PodIdentifierAttribute represents AssociationSource with matching value for pod

func PodIdentifierAttributeFromConnection added in v0.55.0

func PodIdentifierAttributeFromConnection(value string) PodIdentifierAttribute

PodIdentifierAttributeFromSource builds PodIdentifierAttribute for connection with given value

func PodIdentifierAttributeFromResourceAttribute added in v0.55.0

func PodIdentifierAttributeFromResourceAttribute(key, value string) PodIdentifierAttribute

PodIdentifierAttributeFromSource builds PodIdentifierAttribute for given resource_attribute name and value

func PodIdentifierAttributeFromSource added in v0.55.0

func PodIdentifierAttributeFromSource(source AssociationSource, value string) PodIdentifierAttribute

PodIdentifierAttributeFromSource builds PodIdentifierAttribute using AssociationSource and value

type ReplicaSet added in v0.78.0

type ReplicaSet struct {
	Name       string
	Namespace  string
	UID        string
	Deployment Deployment
}

ReplicaSet represents a kubernetes replicaset.

type StatefulSet added in v0.131.0

type StatefulSet struct {
	Name       string
	UID        string
	Attributes map[string]string
}

StatefulSet represents a kubernetes statefulset.

type WatchClient

type WatchClient struct {

	// A map containing Pod related data, used to associate them with resources.
	// Key can be either an IP address or Pod UID
	Pods         map[PodIdentifier]*Pod
	Rules        ExtractionRules
	Filters      Filters
	Associations []Association
	Exclude      Excludes

	// A map containing Namespace related data, used to associate them with resources.
	// Key is namespace name
	Namespaces map[string]*Namespace

	// A map containing Node related data, used to associate them with resources.
	// Key is node name
	Nodes map[string]*Node

	// A map containing Deployment related data, used to associate them with resources.
	// Key is deployment uid
	Deployments map[string]*Deployment

	// A map containing StatefulSet related data, used to associate them with resources.
	// Key is statefulset uid
	StatefulSets map[string]*StatefulSet

	// A map containing DaemonSet related data, used to associate them with resources.
	// Key is daemonset uid
	DaemonSets map[string]*DaemonSet

	// A map containing job related data, used to associate them with resources.
	// Key is job uid
	Jobs map[string]*Job

	// A map containing ReplicaSets related data, used to associate them with resources.
	// Key is replicaset uid
	ReplicaSets map[string]*ReplicaSet
	// contains filtered or unexported fields
}

WatchClient is the main interface provided by this package to a kubernetes cluster.

func (*WatchClient) GetDaemonSet added in v0.135.0

func (c *WatchClient) GetDaemonSet(daemonSetUID string) (*DaemonSet, bool)

func (*WatchClient) GetDeployment added in v0.128.0

func (c *WatchClient) GetDeployment(deploymentUID string) (*Deployment, bool)

func (*WatchClient) GetJob added in v0.135.0

func (c *WatchClient) GetJob(jobUID string) (*Job, bool)

func (*WatchClient) GetNamespace

func (c *WatchClient) GetNamespace(namespace string) (*Namespace, bool)

GetNamespace takes a namespace and returns the namespace object the namespace is associated with.

func (*WatchClient) GetNode added in v0.89.0

func (c *WatchClient) GetNode(nodeName string) (*Node, bool)

GetNode takes a node name and returns the node object the node name is associated with.

func (*WatchClient) GetPod

func (c *WatchClient) GetPod(identifier PodIdentifier) (*Pod, bool)

GetPod takes an IP address or Pod UID and returns the pod the identifier is associated with.

func (*WatchClient) GetReplicaSet added in v0.136.0

func (c *WatchClient) GetReplicaSet(uid string) (*ReplicaSet, bool)

func (*WatchClient) GetStatefulSet added in v0.131.0

func (c *WatchClient) GetStatefulSet(statefulSetUID string) (*StatefulSet, bool)

func (*WatchClient) Start

func (c *WatchClient) Start() error

Start registers pod event handlers and starts watching the kubernetes cluster for pod changes.

func (*WatchClient) Stop

func (c *WatchClient) Stop()

Stop signals the k8s watcher/informer to stop watching for new events.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL