OpenTelemetry Operator for Kubernetes

The OpenTelemetryCollector is a Custom Resource (CR) used to manage OpenTelemetry Collector instances within a Kubernetes cluster via the OpenTelemetry Operator. It allows you to define how collectors are deployed, how they are injected into workloads, and how they observe the cluster.

Key management capabilities include:

• Deployment modes: Choosing how the collector is deployed (e.g., as a sidecar or a standalone deployment).
• Sidecar injection: Automatically injecting collectors into application pods.
• Image pull secrets: Configuring credentials for pulling private collector images.
• Cluster Observability: Using the ClusterObservability controller to manage cluster-wide telemetry collection.

The OpenTelemetry Operator documentation provides comprehensive guides for managing OpenTelemetry in Kubernetes. Key areas include:

• Getting Started: Initial setup and quickstart guides.
• Core Concepts: Understanding the operator's mental model and abstractions.
• Component Guides: Detailed documentation for specific components:
  • Collector: Managing OpenTelemetry Collector instances.
  • Auto-instrumentation: Automatically injecting instrumentation into applications.
  • Target Allocator: Managing Prometheus target discovery.
  • OpAMP Bridge: Using the OpenTelemetry Agent Management Protocol.
• Reference & Troubleshooting: Technical references and guides for resolving common issues.

The OpenTelemetry Operator is a Kubernetes Operator designed to automate the management of observability components within a cluster. It primarily manages:

• OpenTelemetry Collector: Deployment and management of the OpenTelemetry Collector.
• Auto-instrumentation: Automatic injection of OpenTelemetry instrumentation libraries into workloads.

The OpenTelemetry Operator manages several Custom Resource Definitions (CRDs) to automate observability in Kubernetes. The primary resources you will interact with are:

• Instrumentation: Used to configure and inject OpenTelemetry instrumentation (like auto-instrumentation) into your applications.
• OpAMPBridge: Used to manage OpAMP (Open Agent Management Protocol) bridges.
• OpenTelemetryCollector: Used to manage the lifecycle and configuration of OpenTelemetry Collector instances.
• TargetAllocator: Used to manage Target Allocator resources, typically for Prometheus-style scraping configurations.

The OpAMP Bridge is an optional component of the OpenTelemetry Operator that implements the agent-side of the OpAMP protocol. It allows you to report and manage the state of OpenTelemetry Collectors in Kubernetes by communicating with an OpAMP server.

Key capabilities include:

• Reporting: Sends the status and effective configuration of OpenTelemetryCollector CRD instances to an OpAMP server.
• Management: Receives configurations from an OpAMP server and performs CRUD operations on the Kubernetes API server to modify OpenTelemetryCollector resources.
• Telemetry: Emits its own telemetry to an OTLP/HTTP endpoint.

Ephemeral volumes are handled by a cluster storage driver and are tied to the pod's lifecycle (created before the pod starts, deleted when the pod is removed). Use this when you need dynamic volume provisioning via a PersistentVolumeClaim (PVC).

To use this, you must provide a volumeClaimTemplate. The operator will create a stand-alone PVC that the pod owns. The PVC name will follow the pattern <pod name>-<volume name>.

Note: If a PVC with that name already exists but is not owned by the pod, the pod will be blocked from starting to prevent accidental volume attachment. You must update the existing PVC with an owner reference to the pod in such cases.

When defining command or args for an additional container in a TargetAllocator, you can use variable references in the format $(VAR_NAME). These references are expanded using the container's environment.

To escape the expansion syntax and use a literal $(VAR_NAME) string, use double dollar signs: $$. For example, "$$(VAR_NAME)" will result in the literal string "$(VAR_NAME)". Note that escaped references are never expanded, even if the variable exists in the environment.

The OpenTelemetry Operator is introducing the v1beta1 version of the Instrumentation Custom Resource Definition (CRD). This version is a breaking change from v1alpha1 and is designed to provide API stability and align with OpenTelemetry's declarative configuration initiative.

Key improvements in v1beta1 include:

• Support for strongly-typed spec.declarativeConfig alongside spec.envConfig.
• Explicit OTLP exporter protocol specification to resolve ambiguity between HTTP and gRPC.
• Normalized per-language resource fields and unified JSON tags.
• Consolidation of Resource and Defaults into a single top-level spec.resource field.
• Migration of injection control from annotations to labels to support webhook filtering via objectSelector.

The OpenTelemetryCollector.spec.targetAllocator.prometheusCR configuration uses label selectors to discover various resources. For all selector types (probes, scrape configs, namespaces, and service monitors), you can use two methods that are ANDed together:

1. matchLabels: A map of {key, value} pairs. This is a shorthand for an expression where the operator is In and the values array contains only that single value.
2. matchExpressions: A list of complex requirements allowing for more advanced logic.

Selector Behavior:

• An empty label selector matches all objects.
• A null label selector matches no objects.