{"id":13490404,"url":"https://github.com/open-telemetry/opentelemetry-operator","last_synced_at":"2025-05-13T18:12:22.899Z","repository":{"id":37602662,"uuid":"228925870","full_name":"open-telemetry/opentelemetry-operator","owner":"open-telemetry","description":"Kubernetes Operator for OpenTelemetry Collector","archived":false,"fork":false,"pushed_at":"2025-05-12T15:10:59.000Z","size":9710,"stargazers_count":1393,"open_issues_count":319,"forks_count":511,"subscribers_count":29,"default_branch":"main","last_synced_at":"2025-05-12T16:28:59.938Z","etag":null,"topics":["hacktoberfest","kubernetes-operator","opentelemetry","opentelemetry-collector"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/open-telemetry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2019-12-18T21:39:22.000Z","updated_at":"2025-05-12T15:23:46.000Z","dependencies_parsed_at":"2023-10-14T14:25:13.317Z","dependency_job_id":"0d5eaf8c-63e6-4a6b-ad1e-c3569983752f","html_url":"https://github.com/open-telemetry/opentelemetry-operator","commit_stats":{"total_commits":1646,"total_committers":203,"mean_commits":8.108374384236454,"dds":0.764277035236938,"last_synced_commit":"f81ef338f0cad8d2d00dffa49fbb3b72d1157a6d"},"previous_names":[],"tags_count":123,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-operator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-operator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-operator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/open-telemetry%2Fopentelemetry-operator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/open-telemetry","download_url":"https://codeload.github.com/open-telemetry/opentelemetry-operator/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254000857,"owners_count":21997442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","kubernetes-operator","opentelemetry","opentelemetry-collector"],"created_at":"2024-07-31T19:00:46.189Z","updated_at":"2025-05-13T18:12:22.874Z","avatar_url":"https://github.com/open-telemetry.png","language":"Go","readme":"[![Continuous Integration][github-workflow-img]][github-workflow] [![Go Report Card][goreport-img]][goreport] [![GoDoc][godoc-img]][godoc]\n\n# OpenTelemetry Operator for Kubernetes\n\nThe OpenTelemetry Operator is an implementation of a [Kubernetes Operator](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/).\n\nThe operator manages:\n\n- [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector)\n- [auto-instrumentation](https://opentelemetry.io/docs/concepts/instrumentation/automatic/) of the workloads using OpenTelemetry instrumentation libraries\n\n## Documentation\n\n- [Compatibility \u0026 Support docs](./docs/compatibility.md)\n- [API docs](./docs/api/README.md)\n- [Official OpenTelemetry Operator page](https://opentelemetry.io/docs/kubernetes/operator/)\n\n## Helm Charts\n\nYou can install OpenTelemetry Operator via [Helm Chart](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator) from the opentelemetry-helm-charts repository. More information is available in [here](https://github.com/open-telemetry/opentelemetry-helm-charts/tree/main/charts/opentelemetry-operator).\n\n## Getting started\n\nTo install the operator in an existing cluster, make sure you have [`cert-manager` installed](https://cert-manager.io/docs/installation/) and run:\n\n```bash\nkubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml\n```\n\nOnce the `opentelemetry-operator` deployment is ready, create an OpenTelemetry Collector (otelcol) instance, like:\n\n```yaml\nkubectl apply -f - \u003c\u003cEOF\napiVersion: opentelemetry.io/v1beta1\nkind: OpenTelemetryCollector\nmetadata:\n  name: simplest\nspec:\n  config:\n    receivers:\n      otlp:\n        protocols:\n          grpc:\n            endpoint: 0.0.0.0:4317\n          http:\n            endpoint: 0.0.0.0:4318\n    processors:\n      memory_limiter:\n        check_interval: 1s\n        limit_percentage: 75\n        spike_limit_percentage: 15\n      batch:\n        send_batch_size: 10000\n        timeout: 10s\n\n    exporters:\n      debug: {}\n\n    service:\n      pipelines:\n        traces:\n          receivers: [otlp]\n          processors: [memory_limiter, batch]\n          exporters: [debug]\nEOF\n```\n\n**_WARNING:_** Until the OpenTelemetry Collector format is stable, changes may be required in the above example to remain\ncompatible with the latest version of the OpenTelemetry Collector image being referenced.\n\nThis will create an OpenTelemetry Collector instance named `simplest`, exposing a `jaeger-grpc` port to consume spans from your instrumented applications and exporting those spans via `debug`, which writes the spans to the console (`stdout`) of the OpenTelemetry Collector instance that receives the span.\n\nThe `config` node holds the `YAML` that should be passed down as-is to the underlying OpenTelemetry Collector instances. Refer to the [OpenTelemetry Collector](https://github.com/open-telemetry/opentelemetry-collector) documentation for a reference of the possible entries.\n\n\u003e 🚨 **NOTE:** At this point, the Operator does _not_ validate the whole contents of the configuration file: if the configuration is invalid, the instance might still be created but the underlying OpenTelemetry Collector might crash.\n\n\u003e 🚨 **Note:** For private GKE clusters, you will need to either add a firewall rule that allows master nodes access to port `9443/tcp` on worker nodes, or change the existing rule that allows access to port `80/tcp`, `443/tcp` and `10254/tcp` to also allow access to port `9443/tcp`. More information can be found in the [Official GCP Documentation](https://cloud.google.com/load-balancing/docs/tcp/setting-up-tcp#config-hc-firewall). See the [GKE documentation](https://cloud.google.com/kubernetes-engine/docs/how-to/private-clusters#add_firewall_rules) on adding rules and the [Kubernetes issue](https://github.com/kubernetes/kubernetes/issues/79739) for more detail.\n\nThe Operator does examine the configuration file for a few purposes:\n\n- To discover configured receivers and their ports. If it finds receivers with ports, it creates a pair of kubernetes services, one headless, exposing those ports within the cluster. If the port is using environment variable expansion or cannot be parsed, an error will be returned. The headless service contains a `service.beta.openshift.io/serving-cert-secret-name` annotation that will cause OpenShift to create a secret containing a certificate and key. This secret can be mounted as a volume and the certificate and key used in those receivers' TLS configurations.\n\n- To check if Collector observability is enabled (controlled by `spec.observability.metrics.enableMetrics`). In this case, a Service and ServiceMonitor/PodMonitor are created for the Collector instance. As a consequence, if the metrics service address contains an invalid port or uses environment variable expansion for the port, an error will be returned. A workaround for the environment variable case is to set `enableMetrics` to `false` and manually create the previously mentioned objects with the correct port if you need them.\n \n### Upgrades\n\nAs noted above, the OpenTelemetry Collector format is continuing to evolve. However, a best-effort attempt is made to upgrade all managed `OpenTelemetryCollector` resources.\n\nIn certain scenarios, it may be desirable to prevent the operator from upgrading certain `OpenTelemetryCollector` resources. For example, when a resource is configured with a custom `.Spec.Image`, end users may wish to manage configuration themselves as opposed to having the operator upgrade it. This can be configured on a resource by resource basis with the exposed property `.Spec.UpgradeStrategy`.\n\nBy configuring a resource's `.Spec.UpgradeStrategy` to `none`, the operator will skip the given instance during the upgrade routine.\n\nThe default and only other acceptable value for `.Spec.UpgradeStrategy` is `automatic`.\n\n### Deployment modes\n\nThe `CustomResource` for the `OpenTelemetryCollector` exposes a property named `.Spec.Mode`, which can be used to specify whether the Collector should run as a [`DaemonSet`](https://kubernetes.io/docs/concepts/workloads/controllers/daemonset/), [`Sidecar`](https://kubernetes.io/docs/concepts/workloads/pods/#workload-resources-for-managing-pods), [`StatefulSet`](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/) or [`Deployment`](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) (default).\n\nSee below for examples of each deployment mode:\n\n- [`Deployment`](https://github.com/open-telemetry/opentelemetry-operator/blob/main/tests/e2e/ingress/00-install.yaml)\n- [`DaemonSet`](https://github.com/open-telemetry/opentelemetry-operator/blob/main/tests/e2e/daemonset-features/01-install.yaml)\n- [`StatefulSet`](https://github.com/open-telemetry/opentelemetry-operator/blob/main/tests/e2e/smoke-statefulset/00-install.yaml)\n- [`Sidecar`](https://github.com/open-telemetry/opentelemetry-operator/blob/main/tests/e2e/smoke-sidecar/00-install.yaml)\n\n#### Sidecar injection\n\nA sidecar with the OpenTelemetry Collector can be injected into pod-based workloads by setting the pod annotation `sidecar.opentelemetry.io/inject` to either `\"true\"`, or to the name of a concrete `OpenTelemetryCollector`, like in the following example:\n\n```yaml\nkubectl apply -f - \u003c\u003cEOF\napiVersion: opentelemetry.io/v1beta1\nkind: OpenTelemetryCollector\nmetadata:\n  name: sidecar-for-my-app\nspec:\n  mode: sidecar\n  config:\n    receivers:\n      jaeger:\n        protocols:\n          thrift_compact: {}\n    processors:\n\n    exporters:\n      debug: {}\n\n    service:\n      pipelines:\n        traces:\n          receivers: [jaeger]\n          exporters: [debug]\nEOF\n\nkubectl apply -f - \u003c\u003cEOF\napiVersion: v1\nkind: Pod\nmetadata:\n  name: myapp\n  annotations:\n    sidecar.opentelemetry.io/inject: \"true\"\nspec:\n  containers:\n  - name: myapp\n    image: jaegertracing/vertx-create-span:operator-e2e-tests\n    ports:\n      - containerPort: 8080\n        protocol: TCP\nEOF\n```\n\nWhen there are multiple `OpenTelemetryCollector` resources with a mode set to `Sidecar` in the same namespace, a concrete name should be used. When there's only one `Sidecar` instance in the same namespace, this instance is used when the annotation is set to `\"true\"`.\n\nThe annotation value can come either from the namespace, or from the pod. The most specific annotation wins, in this order:\n\n- the pod annotation is used when it's set to a concrete instance name or to `\"false\"`\n- namespace annotation is used when the pod annotation is either absent or set to `\"true\"`, and the namespace is set to a concrete instance or to `\"false\"`\n\nThe possible values for the annotation can be:\n\n- \"true\" - inject `OpenTelemetryCollector` resource from the namespace.\n- \"sidecar-for-my-app\" - name of `OpenTelemetryCollector` CR instance in the current namespace.\n- \"my-other-namespace/my-instrumentation\" - name and namespace of `OpenTelemetryCollector` CR instance in another namespace.\n- \"false\" - do not inject\n\nWhen using a pod-based workload, such as `Deployment` or `StatefulSet`, make sure to add the annotation to the `PodTemplate` part. Like:\n\n```yaml\nkubectl apply -f - \u003c\u003cEOF\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-app\n  labels:\n    app: my-app\n  annotations:\n    sidecar.opentelemetry.io/inject: \"true\" # WRONG\nspec:\n  selector:\n    matchLabels:\n      app: my-app\n  replicas: 1\n  template:\n    metadata:\n      labels:\n        app: my-app\n      annotations:\n        sidecar.opentelemetry.io/inject: \"true\" # CORRECT\n    spec:\n      containers:\n      - name: myapp\n        image: jaegertracing/vertx-create-span:operator-e2e-tests\n        ports:\n          - containerPort: 8080\n            protocol: TCP\nEOF\n```\n\nWhen using sidecar mode the OpenTelemetry collector container will have the environment variable `OTEL_RESOURCE_ATTRIBUTES`set with Kubernetes resource attributes, ready to be consumed by the [resourcedetection](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor) processor.\n\n### Using imagePullSecrets\n\nThe OpenTelemetry Collector defines a ServiceAccount field which could be set to run collector instances with a specific Service and their properties (e.g. imagePullSecrets). Therefore, if you have a constraint to run your collector with a private container registry, you should follow the procedure below:\n\n- Create Service Account.\n\n```bash\nkubectl create serviceaccount \u003cservice-account-name\u003e\n```\n\n- Create an imagePullSecret.\n\n```bash\nkubectl create secret docker-registry \u003csecret-name\u003e --docker-server=\u003cregistry name\u003e \\\n        --docker-username=DUMMY_USERNAME --docker-password=DUMMY_DOCKER_PASSWORD \\\n        --docker-email=DUMMY_DOCKER_EMAIL\n```\n\n- Add image pull secret to service account\n\n```bash\nkubectl patch serviceaccount \u003cservice-account-name\u003e -p '{\"imagePullSecrets\": [{\"name\": \"\u003csecret-name\u003e\"}]}'\n```\n\n### OpenTelemetry auto-instrumentation injection\n\nThe operator can inject and configure OpenTelemetry auto-instrumentation libraries. Currently, Apache HTTPD, DotNet, Go, Java, Nginx, NodeJS and Python are supported.\n\nTo use auto-instrumentation, configure an `Instrumentation` resource with the configuration for the SDK and instrumentation.\n\n```yaml\nkubectl apply -f - \u003c\u003cEOF\napiVersion: opentelemetry.io/v1alpha1\nkind: Instrumentation\nmetadata:\n  name: my-instrumentation\nspec:\n  exporter:\n    endpoint: http://otel-collector:4317\n  propagators:\n    - tracecontext\n    - baggage\n    - b3\n  sampler:\n    type: parentbased_traceidratio\n    argument: \"0.25\"\n  python:\n    env:\n      # Required if endpoint is set to 4317.\n      # Python autoinstrumentation uses http/proto by default\n      # so data must be sent to 4318 instead of 4317.\n      - name: OTEL_EXPORTER_OTLP_ENDPOINT\n        value: http://otel-collector:4318\n  dotnet:\n    env:\n      # Required if endpoint is set to 4317.\n      # Dotnet autoinstrumentation uses http/proto by default\n      # See https://github.com/open-telemetry/opentelemetry-dotnet-instrumentation/blob/888e2cd216c77d12e56b54ee91dafbc4e7452a52/docs/config.md#otlp\n      - name: OTEL_EXPORTER_OTLP_ENDPOINT\n        value: http://otel-collector:4318\n  go:\n    env:\n      # Required if endpoint is set to 4317.\n      # Go autoinstrumentation uses http/proto by default\n      # so data must be sent to 4318 instead of 4317.\n      - name: OTEL_EXPORTER_OTLP_ENDPOINT\n        value: http://otel-collector:4318\nEOF\n```\n\nThe values for `propagators` are added to the `OTEL_PROPAGATORS` environment variable.\nValid values for `propagators` are defined by the [OpenTelemetry Specification for OTEL_PROPAGATORS](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_propagators).\n\nThe value for `sampler.type` is added to the `OTEL_TRACES_SAMPLER` environment variable.\nValid values for `sampler.type` are defined by the [OpenTelemetry Specification for OTEL_TRACES_SAMPLER](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_traces_sampler).\nThe value for `sampler.argument` is added to the `OTEL_TRACES_SAMPLER_ARG` environment variable. Valid values for `sampler.argument` will depend on the chosen sampler. See the [OpenTelemetry Specification for OTEL_TRACES_SAMPLER_ARG](https://opentelemetry.io/docs/concepts/sdk-configuration/general-sdk-configuration/#otel_traces_sampler_arg) for more details.\n\nThe instrumentation will automatically inject `OTEL_NODE_IP` and `OTEL_POD_IP` environment variables should you need to reference either value in an endpoint.\n\nThe above CR can be queried by `kubectl get otelinst`.\n\nThen add an annotation to a pod to enable injection. The annotation can be added to a namespace, so that all pods within\nthat namespace will get instrumentation, or by adding the annotation to individual PodSpec objects, available as part of\nDeployment, StatefulSet, and other resources.\n\nJava:\n\n```bash\ninstrumentation.opentelemetry.io/inject-java: \"true\"\n```\n\nNodeJS:\n\n```bash\ninstrumentation.opentelemetry.io/inject-nodejs: \"true\"\n```\n\nPython:\nPython auto-instrumentation also honors an annotation that will permit it to run it on images with a different C library than glibc.\n\n```bash\ninstrumentation.opentelemetry.io/inject-python: \"true\"\ninstrumentation.opentelemetry.io/otel-python-platform: \"glibc\" # for Linux glibc based images, this is the default value and can be omitted\ninstrumentation.opentelemetry.io/otel-python-platform: \"musl\" # for Linux musl based images\n```\n\n.NET:\n.NET auto-instrumentation also honors an annotation that will be used to set the .NET [Runtime Identifiers](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog)(RIDs).\nCurrently, only two RIDs are supported: `linux-x64` and `linux-musl-x64`.\nBy default `linux-x64` is used.\n\n```bash\ninstrumentation.opentelemetry.io/inject-dotnet: \"true\"\ninstrumentation.opentelemetry.io/otel-dotnet-auto-runtime: \"linux-x64\" # for Linux glibc based images, this is default value and can be omitted\ninstrumentation.opentelemetry.io/otel-dotnet-auto-runtime: \"linux-musl-x64\"  # for Linux musl based images\n```\n\nGo:\n\nGo auto-instrumentation also honors an annotation that will be used to set the [OTEL_GO_AUTO_TARGET_EXE env var](https://github.com/open-telemetry/opentelemetry-go-instrumentation/blob/main/docs/how-it-works.md).\nThis env var can also be set via the Instrumentation resource, with the annotation taking precedence.\nSince Go auto-instrumentation requires `OTEL_GO_AUTO_TARGET_EXE` to be set, you must supply a valid\nexecutable path via the annotation or the Instrumentation resource. Failure to set this value causes instrumentation injection to abort, leaving the original pod unchanged.\n\n```bash\ninstrumentation.opentelemetry.io/inject-go: \"true\"\ninstrumentation.opentelemetry.io/otel-go-auto-target-exe: \"/path/to/container/executable\"\n```\n\nGo auto-instrumentation also requires elevated permissions. The below permissions are set automatically and are required.\n\n```yaml\nsecurityContext:\n  privileged: true\n  runAsUser: 0\n```\n\nApache HTTPD:\n\n```bash\ninstrumentation.opentelemetry.io/inject-apache-httpd: \"true\"\n```\n\nNginx:\n\n```bash\ninstrumentation.opentelemetry.io/inject-nginx: \"true\"\n```\n\nOpenTelemetry SDK environment variables only:\n\n```bash\ninstrumentation.opentelemetry.io/inject-sdk: \"true\"\n```\n\nThe possible values for the annotation can be\n\n- `\"true\"` - inject and `Instrumentation` resource from the namespace.\n- `\"my-instrumentation\"` - name of `Instrumentation` CR instance in the current namespace.\n- `\"my-other-namespace/my-instrumentation\"` - name and namespace of `Instrumentation` CR instance in another namespace.\n- `\"false\"` - do not inject\n\n\u003e **Note:** For `DotNet` auto-instrumentation, by default, operator sets the `OTEL_DOTNET_AUTO_TRACES_ENABLED_INSTRUMENTATIONS` environment variable which specifies the list of traces source instrumentations you want to enable. The value that is set by default by the operator is all available instrumentations supported by the `openTelemery-dotnet-instrumentation` release consumed in the image, i.e. `AspNet,HttpClient,SqlClient`. This value can be overridden by configuring the environment variable explicitly.\n\n#### Multi-container pods with single instrumentation\n\nIf nothing else is specified, instrumentation is performed on the first container available in the pod spec.\nIn some cases (for example in the case of the injection of an Istio sidecar) it becomes necessary to specify on which container(s) this injection must be performed.\n\nFor this, it is possible to fine-tune the pod(s) on which the injection will be carried out.\n\nFor this, we will use the `instrumentation.opentelemetry.io/container-names` annotation for which we will indicate one or more container names (`.spec.containers.name`) on which the injection must be made:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-deployment-with-multiple-containers\nspec:\n  selector:\n    matchLabels:\n      app: my-pod-with-multiple-containers\n  replicas: 1\n  template:\n    metadata:\n      labels:\n        app: my-pod-with-multiple-containers\n      annotations:\n        instrumentation.opentelemetry.io/inject-java: \"true\"\n        instrumentation.opentelemetry.io/container-names: \"myapp,myapp2\"\n    spec:\n      containers:\n        - name: myapp\n          image: myImage1\n        - name: myapp2\n          image: myImage2\n        - name: myapp3\n          image: myImage3\n```\n\nIn the above case, `myapp` and `myapp2` containers will be instrumented, `myapp3` will not.\n\n\u003e 🚨 **NOTE**: Go auto-instrumentation **does not** support multicontainer pods. When injecting Go auto-instrumentation the first pod should be the only pod you want instrumented.\n\n#### Multi-container pods with multiple instrumentations\n\nWorks only when `enable-multi-instrumentation` flag is `true`.\n\nAnnotations defining which language instrumentation will be injected are required. When feature is enabled, specific for Instrumentation language containers annotations are used:\n\nJava:\n\n```bash\ninstrumentation.opentelemetry.io/java-container-names: \"java1,java2\"\n```\n\nNodeJS:\n\n```bash\ninstrumentation.opentelemetry.io/nodejs-container-names: \"nodejs1,nodejs2\"\n```\n\nPython:\n\n```bash\ninstrumentation.opentelemetry.io/python-container-names: \"python1,python3\"\n```\n\nDotNet:\n\n```bash\ninstrumentation.opentelemetry.io/dotnet-container-names: \"dotnet1,dotnet2\"\n```\n\nGo:\n\n```bash\ninstrumentation.opentelemetry.io/go-container-names: \"go1\"\n```\n\nApacheHttpD:\n\n```bash\ninstrumentation.opentelemetry.io/apache-httpd-container-names: \"apache1,apache2\"\n```\n\nNGINX:\n\n```bash\ninstrumentation.opentelemetry.io/inject-nginx-container-names: \"nginx1,nginx2\"\n```\n\nSDK:\n\n```bash\ninstrumentation.opentelemetry.io/sdk-container-names: \"app1,app2\"\n```\n\nIf language instrumentation specific container names are not specified, instrumentation is performed on the first container available in the pod spec (only if single instrumentation injection is configured).\n\nIn some cases containers in the pod are using different technologies. It becomes necessary to specify language instrumentation for container(s) on which this injection must be performed.\n\nFor this, we will use language instrumentation specific container names annotation for which we will indicate one or more container names (`.spec.containers.name`) on which the injection must be made:\n\n```yaml\napiVersion: apps/v1\nkind: Deployment\nmetadata:\n  name: my-deployment-with-multi-containers-multi-instrumentations\nspec:\n  selector:\n    matchLabels:\n      app: my-pod-with-multi-containers-multi-instrumentations\n  replicas: 1\n  template:\n    metadata:\n      labels:\n        app: my-pod-with-multi-containers-multi-instrumentations\n      annotations:\n        instrumentation.opentelemetry.io/inject-java: \"true\"\n        instrumentation.opentelemetry.io/java-container-names: \"myapp,myapp2\"\n        instrumentation.opentelemetry.io/inject-python: \"true\"\n        instrumentation.opentelemetry.io/python-container-names: \"myapp3\"\n    spec:\n      containers:\n        - name: myapp\n          image: myImage1\n        - name: myapp2\n          image: myImage2\n        - name: myapp3\n          image: myImage3\n```\n\nIn the above case, `myapp` and `myapp2` containers will be instrumented using Java and `myapp3` using Python instrumentation.\n\n**NOTE**: Go auto-instrumentation **does not** support multicontainer pods. When injecting Go auto-instrumentation the first container should be the only you want to instrument.\n\n**NOTE**: This type of instrumentation **does not** allow to instrument a container with multiple language instrumentations.\n\n**NOTE**: `instrumentation.opentelemetry.io/container-names` annotation is not used for this feature.\n\n#### Use customized or vendor instrumentation\n\nBy default, the operator uses upstream auto-instrumentation libraries. Custom auto-instrumentation can be configured by\noverriding the `image` fields in a CR.\n\n```yaml\napiVersion: opentelemetry.io/v1alpha1\nkind: Instrumentation\nmetadata:\n  name: my-instrumentation\nspec:\n  java:\n    image: your-customized-auto-instrumentation-image:java\n  nodejs:\n    image: your-customized-auto-instrumentation-image:nodejs\n  python:\n    image: your-customized-auto-instrumentation-image:python\n  dotnet:\n    image: your-customized-auto-instrumentation-image:dotnet\n  go:\n    image: your-customized-auto-instrumentation-image:go\n  apacheHttpd:\n    image: your-customized-auto-instrumentation-image:apache-httpd\n  nginx:\n    image: your-customized-auto-instrumentation-image:nginx\n```\n\nThe Dockerfiles for auto-instrumentation can be found in [autoinstrumentation directory](./autoinstrumentation).\nFollow the instructions in the Dockerfiles on how to build a custom container image.\n\n#### Using Apache HTTPD autoinstrumentation\n\nFor `Apache HTTPD` autoinstrumentation, by default, instrumentation assumes httpd version 2.4 and httpd configuration directory `/usr/local/apache2/conf` as it is in the official `Apache HTTPD` image (f.e. docker.io/httpd:latest). If you need to use version 2.2, or your HTTPD configuration directory is different, and or you need to adjust agent attributes, customize the instrumentation specification per following example:\n\n```yaml\napiVersion: opentelemetry.io/v1alpha1\nkind: Instrumentation\nmetadata:\n  name: my-instrumentation\nspec:\n  apacheHttpd:\n    image: your-customized-auto-instrumentation-image:apache-httpd\n    version: \"2.2\"\n    configPath: /your-custom-config-path\n    attrs:\n      - name: ApacheModuleOtelMaxQueueSize\n        value: \"4096\"\n      - name: ...\n        value: ...\n```\n\nList of all available attributes can be found at [otel-webserver-module](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/otel-webserver-module)\n\n#### Using Nginx autoinstrumentation\n\nFor `Nginx` autoinstrumentation, Nginx versions 1.22.0, 1.23.0, and 1.23.1 are supported at this time. The Nginx configuration file is expected to be `/etc/nginx/nginx.conf` by default, if it's different, see following example on how to change it. Instrumentation at this time also expects, that `conf.d` directory is present in the directory, where configuration file resides and that there is a `include \u003cconfig-file-dir-path\u003e/conf.d/*.conf;` directive in the `http { ... }` section of Nginx configuration file (like it is in the default configuration file of Nginx). You can also adjust OpenTelemetry SDK attributes. Example:\n\n```yaml\napiVersion: opentelemetry.io/v1alpha1\nkind: Instrumentation\nmetadata:\n  name: my-instrumentation\nspec:\n  nginx:\n    image: your-customized-auto-instrumentation-image:nginx # if custom instrumentation image is needed\n    configFile: /my/custom-dir/custom-nginx.conf\n    attrs:\n      - name: NginxModuleOtelMaxQueueSize\n        value: \"4096\"\n      - name: ...\n        value: ...\n```\n\nList of all available attributes can be found at [otel-webserver-module](https://github.com/open-telemetry/opentelemetry-cpp-contrib/tree/main/instrumentation/otel-webserver-module)\n\n#### Inject OpenTelemetry SDK environment variables only\n\nYou can configure the OpenTelemetry SDK for applications which can't currently be autoinstrumented by using `inject-sdk` in place of `inject-python` or `inject-java`, for example. This will inject environment variables like `OTEL_RESOURCE_ATTRIBUTES`, `OTEL_TRACES_SAMPLER`, and `OTEL_EXPORTER_OTLP_ENDPOINT`, that you can configure in the `Instrumentation`, but will not actually provide the SDK.\n\n```bash\ninstrumentation.opentelemetry.io/inject-sdk: \"true\"\n```\n\n#### Controlling Instrumentation Capabilities\n\nThe operator allows specifying, via the flags, which languages the Instrumentation resource may instrument.\nIf a language is enabled by default its gate only needs to be supplied when disabling the gate.\nLanguage support can be disabled by passing the flag with a value of `false`.\n\n| Language    | Gate                                  | Default Value |\n| ----------- | ------------------------------------- | ------------- |\n| Java        | `enable-java-instrumentation`         | `true`        |\n| NodeJS      | `enable-nodejs-instrumentation`       | `true`        |\n| Python      | `enable-python-instrumentation`       | `true`        |\n| DotNet      | `enable-dotnet-instrumentation`       | `true`        |\n| ApacheHttpD | `enable-apache-httpd-instrumentation` | `true`        |\n| Go          | `enable-go-instrumentation`           | `false`       |\n| Nginx       | `enable-nginx-instrumentation`        | `false`       |\n\n\nOpenTelemetry Operator allows to instrument multiple containers using multiple language specific instrumentations.\nThese features can be enabled using the `enable-multi-instrumentation` flag. By default flag is `false`.\n\nFor more information about multi-instrumentation feature capabilities please see [Multi-container pods with multiple instrumentations](#Multi-container-pods-with-multiple-instrumentations).\n\n### Target Allocator\n\nThe OpenTelemetry Operator comes with an optional component, the [Target Allocator](/cmd/otel-allocator/README.md) (TA). When creating an OpenTelemetryCollector Custom Resource (CR) and setting the TA as enabled, the Operator will create a new deployment and service to serve specific `http_sd_config` directives for each Collector pod as part of that CR. It will also rewrite the Prometheus receiver configuration in the CR, so that it uses the deployed target allocator. The following example shows how to get started with the Target Allocator:\n\n```yaml\nkubectl apply -f - \u003c\u003cEOF\napiVersion: opentelemetry.io/v1beta1\nkind: OpenTelemetryCollector\nmetadata:\n  name: collector-with-ta\nspec:\n  mode: statefulset\n  targetAllocator:\n    enabled: true\n  config:\n    receivers:\n      prometheus:\n        config:\n          scrape_configs:\n          - job_name: 'otel-collector'\n            scrape_interval: 10s\n            static_configs:\n            - targets: [ '0.0.0.0:8888' ]\n            metric_relabel_configs:\n            - action: labeldrop\n              regex: (id|name)\n            - action: labelmap\n              regex: label_(.+)\n              replacement: $$1\n\n    exporters:\n      debug: {}\n\n    service:\n      pipelines:\n        metrics:\n          receivers: [prometheus]\n          exporters: [debug]\nEOF\n```\n\nThe usage of `$$` in the replacement keys in the example above is based on the information provided in the Prometheus receiver [README](https://github.com/open-telemetry/opentelemetry-collector-contrib/blob/main/receiver/prometheusreceiver/README.md) documentation, which states:\n`Note: Since the collector configuration supports env variable substitution $ characters in your prometheus configuration are interpreted as environment variables. If you want to use $ characters in your prometheus configuration, you must escape them using $$.`\n\nBehind the scenes, the OpenTelemetry Operator will convert the Collector’s configuration after the reconciliation into the following:\n\n```yaml\nreceivers:\n  prometheus:\n    target_allocator:\n      endpoint: http://collector-with-ta-targetallocator:80\n      interval: 30s\n      collector_id: $POD_NAME\n\nexporters:\n  debug:\n\nservice:\n  pipelines:\n    metrics:\n      receivers: [prometheus]\n      exporters: [debug]\n```\n\nThe OpenTelemetry Operator will also convert the Target Allocator's Prometheus configuration after the reconciliation into the following:\n\n```yaml\nconfig:\n  scrape_configs:\n    - job_name: otel-collector\n      scrape_interval: 10s\n      static_configs:\n        - targets: [\"0.0.0.0:8888\"]\n      metric_relabel_configs:\n        - action: labeldrop\n          regex: (id|name)\n        - action: labelmap\n          regex: label_(.+)\n          replacement: $1\n```\n\nNote that in this case, the Operator replaces \"$$\" with a single \"$\" in the replacement keys. This is because the collector supports environment variable substitution, whereas the TA (Target Allocator) does not. Therefore, to ensure compatibility, the TA configuration should only contain a single \"$\" symbol.\n\nMore info on the TargetAllocator can be found [here](cmd/otel-allocator/README.md).\n\n#### Using Prometheus Custom Resources for service discovery\n\nThe target allocator can use Custom Resources from the prometheus-operator ecosystem, like ServiceMonitors and PodMonitors, for service discovery, performing\na function analogous to that of prometheus-operator itself. This is enabled via the `prometheusCR` section in the Collector CR.\n\nSee below for a minimal example:\n\n```yaml\nkubectl apply -f - \u003c\u003cEOF\napiVersion: opentelemetry.io/v1beta1\nkind: OpenTelemetryCollector\nmetadata:\n  name: collector-with-ta-prometheus-cr\nspec:\n  mode: statefulset\n  targetAllocator:\n    enabled: true\n    serviceAccount: everything-prometheus-operator-needs\n    prometheusCR:\n      enabled: true\n      serviceMonitorSelector: {}\n      podMonitorSelector: {}\n  config:\n    receivers:\n      prometheus:\n        config: {}\n\n    exporters:\n      debug: {}\n\n    service:\n      pipelines:\n        metrics:\n          receivers: [prometheus]\n          exporters: [debug]\nEOF\n```\n\n## Configure resource attributes\n\nThe OpenTelemetry Operator can automatically set resource attributes as defined in the \n[OpenTelemetry Semantic Conventions](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/non-normative/k8s-attributes.md).\n\n### Configure resource attributes with annotations\n\nThis example shows a pod configuration with OpenTelemetry annotations using the `resource.opentelemetry.io/` prefix. \nThese annotations can be used to add resource attributes to data produced by OpenTelemetry instrumentation.\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: example-pod\n  annotations:\n    # this is just an example, you can create any resource attributes you need\n    resource.opentelemetry.io/service.name: \"my-service\"\n    resource.opentelemetry.io/service.version: \"1.0.0\"\n    resource.opentelemetry.io/deployment.environment.name: \"production\"\nspec:\n  containers:\n  - name: main-container\n    image: your-image:tag\n```\n\n### Configure resource attributes with labels\n\nYou can also use common labels to set resource attributes (first entry wins).\n\nThe following labels are supported:\n- `app.kubernetes.io/instance` becomes `service.name`\n- `app.kubernetes.io/name` becomes `service.name`\n- `app.kubernetes.io/version` becomes `service.version`\n\n```yaml\napiVersion: v1\nkind: Pod\nmetadata:\n  name: example-pod\n  labels:\n    app.kubernetes.io/name: \"my-service\"\n    app.kubernetes.io/version: \"1.0.0\"\n    app.kubernetes.io/part-of: \"shop\"\nspec:\n  containers:\n  - name: main-container\n    image: your-image:tag\n```\n\nThis requires an explicit opt-in as follows:\n\n```yaml\napiVersion: opentelemetry.io/v1alpha1\nkind: Instrumentation\nmetadata:\n  name: my-instrumentation\nspec:\n  defaults:\n    useLabelsForResourceAttributes: true\n```\n\n### Priority for setting resource attributes\n\nThe priority for setting resource attributes is as follows (first found wins):\n\n1. Resource attributes set via `OTEL_RESOURCE_ATTRIBUTES` and `OTEL_SERVICE_NAME` environment variables\n2. Resource attributes set via annotations (with the `resource.opentelemetry.io/` prefix)\n3. Resource attributes set via labels (e.g. `app.kubernetes.io/name`)\n   if the `Instrumentation` CR has defaults.useLabelsForResourceAttributes=true (see above)\n4. Resource attributes calculated from the pod's metadata (e.g. `k8s.pod.name`)\n5. Resource attributes set via the `Instrumentation` CR (in the `spec.resource.resourceAttributes` section)\n\nThis priority is applied for each resource attribute separately, so it is possible to set some attributes via\nannotations and others via labels.\n\n### How resource attributes are calculated from the pod's metadata\n\nThe following resource attributes are calculated from the pod's metadata.\n\n#### How `service.name` is calculated\n\nChoose the first value found: \n\n- `pod.annotation[resource.opentelemetry.io/service.name]`\n- `if (config[useLabelsForResourceAttributes]) pod.label[app.kubernetes.io/name]`\n- `k8s.deployment.name`\n- `k8s.replicaset.name`\n- `k8s.statefulset.name`\n- `k8s.daemonset.name`\n- `k8s.cronjob.name`\n- `k8s.job.name`\n- `k8s.pod.name`\n- `k8s.container.name`\n\n#### How `service.version` is calculated\n\nChoose the first value found:\n\n- `pod.annotation[resource.opentelemetry.io/service.version]`\n- `if (cfg[useLabelsForResourceAttributes]) pod.label[app.kubernetes.io/version]`\n- `if (contains(container docker image tag, '/') == false) container docker image tag`\n\n#### How `service.instance.id` is calculated\n\nChoose the first value found:\n\n- `pod.annotation[resource.opentelemetry.io/service.instance.id]`\n- `concat([k8s.namespace.name, k8s.pod.name, k8s.container.name], '.')`\n\n#### How `service.namespace` is calculated\n\nChoose the first value found:\n\n- `pod.annotation[resource.opentelemetry.io/service.namespace]`\n- `k8s.namespace.name`\n\n## Contributing and Developing\n\nPlease see [CONTRIBUTING.md](CONTRIBUTING.md).\n\nIn addition to the [core responsibilities](https://github.com/open-telemetry/community/blob/main/community-membership.md) the operator project requires approvers and maintainers to be responsible for releasing the project. See [RELEASE.md](./RELEASE.md) for more information and release schedule.\n\nTriagers ([@open-telemetry/operator-triagers](https://github.com/orgs/open-telemetry/teams/operator-triagers)):\n\n- [Antoine Toulme](https://github.com/atoulme), Splunk\n\nApprovers ([@open-telemetry/operator-approvers](https://github.com/orgs/open-telemetry/teams/operator-approvers)):\n\n- [Tyler Helmuth](https://github.com/TylerHelmuth), Honeycomb\n- [Yuri Oliveira Sa](https://github.com/yuriolisa), OllyGarden\n- [Israel Blancas](https://github.com/iblancasa), Coralogix\n\nEmeritus Approvers:\n\n- [Anthony Mirabella](https://github.com/Aneurysm9), AWS\n- [Dmitrii Anoshin](https://github.com/dmitryax), Splunk\n- [Jay Camp](https://github.com/jrcamp), Splunk\n- [James Bebbington](https://github.com/james-bebbington), Google\n- [Owais Lone](https://github.com/owais), Splunk\n- [Pablo Baeyens](https://github.com/mx-psi), DataDog\n\nMaintainers ([@open-telemetry/operator-maintainers](https://github.com/orgs/open-telemetry/teams/operator-maintainers)):\n\n- [Benedikt Bongartz](https://github.com/frzifus), Red Hat\n- [Jacob Aronoff](https://github.com/jaronoff97), Omlet\n- [Mikołaj Świątek](https://github.com/swiatekm), Elastic\n- [Pavol Loffay](https://github.com/pavolloffay), Red Hat\n\nEmeritus Maintainers\n\n- [Alex Boten](https://github.com/codeboten), Lightstep\n- [Bogdan Drutu](https://github.com/BogdanDrutu), Splunk\n- [Juraci Paixão Kröhling](https://github.com/jpkrohling), Grafana Labs\n- [Tigran Najaryan](https://github.com/tigrannajaryan), Splunk\n- [Vineeth Pothulapati](https://github.com/VineethReddy02), Timescale\n\nLearn more about roles in the [community repository](https://github.com/open-telemetry/community/blob/main/community-membership.md).\n\nThanks to all the people who already contributed!\n\n[![Contributors][contributors-img]][contributors]\n\n## License\n\n[Apache 2.0 License](./LICENSE).\n\n[github-workflow]: https://github.com/open-telemetry/opentelemetry-operator/actions\n[github-workflow-img]: https://github.com/open-telemetry/opentelemetry-operator/workflows/Continuous%20Integration/badge.svg\n[goreport-img]: https://goreportcard.com/badge/github.com/open-telemetry/opentelemetry-operator\n[goreport]: https://goreportcard.com/report/github.com/open-telemetry/opentelemetry-operator\n[godoc-img]: https://godoc.org/github.com/open-telemetry/opentelemetry-operator?status.svg\n[godoc]: https://godoc.org/github.com/open-telemetry/opentelemetry-operator/pkg/apis/opentelemetry/v1alpha1#OpenTelemetryCollector\n[contributors]: https://github.com/open-telemetry/opentelemetry-operator/graphs/contributors\n[contributors-img]: https://contributors-img.web.app/image?repo=open-telemetry/opentelemetry-operator\n","funding_links":[],"categories":["Go","OpenTelemetry Instrumentation 🎺"],"sub_categories":["Supported Databases"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-telemetry%2Fopentelemetry-operator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopen-telemetry%2Fopentelemetry-operator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopen-telemetry%2Fopentelemetry-operator/lists"}