Monitoring Kubernetes in Instana by using OpenTelemetry Helm charts

Instana offers seamless integration with OpenTelemetry for comprehensive Kubernetes monitoring.

OpenTelemetry Kubernetes data ingestion to Instana backend

Instana supports comprehensive Kubernetes monitoring through OpenTelemetry integration. OpenTelemetry Kubernetes Data can be directly ingested to the Instana backend and shown in the Instana UI.

Setup process:

OpenTelemetry Kubernetes data ingestion through Instana agent

The Instana agent facilitates the ingestion of OpenTelemetry Kubernetes data to the Instana backend which displays the telemetry data in the Instana UI.

Setup process:

Configure the OpenTelemetry Collector

To configure the OpenTelemetry Collector for Kubernetes by using Helm Charts, you need two yaml file to seed the values.

Configure receivers to collect Kubernetes telemetry

  1. Create a DaemonSet values yaml file helmValuesDaemonset.yaml with the following content in a known location:

    helmValuesDaemonset.yaml

  2. Create another DeploymentSet values yaml helmValuesDeployment.yaml file with the following content in a known location:

    helmValuesDeployment.yaml

Configure resource attributes

Instana uses resource attributes set in the Helm charts to name and label the monitored Kubernetes cluster that is shown in the Instana UI. The following table shows the resource attributes used internally by Instana.

Resource attributes Description Sample value
k8s.cluster.name Name for the Kubernetes cluster otelClusterForDemo
k8s.cluster.distribution Name of the cluster distribution kubernetes
k8s.cluster.managedBy Name of the organization managing the cluster CNF
k8s.cluster.shortName Short name of the cluster oTelShortName
k8s.cluster.fullName Full name of the cluster Kubernetes
k8s.cluster.version Version of the cluster 1.27052025
k8s.namespace.name Namespace of the Kubernetes otel-test-cluster
service.instance.id Service instance ID for tracing otelk8sid
service.name Service name for use in tracing otelk8s
x-instana-key The Instana agent key to use only needed to send Telemetry data to Instana Backend agentkey
INSTANA_PLUGIN Mandatory constant for use internally by Instana k8s

The resource attributes can be set as part of the environment variables. The following sample code can be placed as part of extra env in the Helm charts:

extraEnvs:
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: 'k8s.cluster.name=otelClusterForDemo,k8s.cluster.distribution=kubernetes,k8s.cluster.managedBy=AWS,k8s.cluster.shortName=oTelShortName,k8s.cluster.fullName=Kubernetes,k8s.cluster.version=1.27052025,k8s.namespace.name=otel-test-cluster,service.instance.id=otelk8sid,service.name=otelk8s,x-instana-key=instanalocal,INSTANA_PLUGIN=k8s'

Configure to export the Telemetry data to Instana Agent

OpenTelemetry Collector can be configured to export telemetry Kubernetes data to the Instana agent by modifying the exporters.

exporters:
  otlp/ins:
    endpoint: 'http://9.43.49.227:4317' # Instana agent endpoint for OpenTelemetry. For example, "http://9.109.219.165:4317".
    tls:
      insecure: true

Also the exporter has to be added to the OpenTelemetry pipeline

service:
  pipelines:
    metrics:
      exporters: [otlp/ins]

Configure to export the Telemetry data to Instana Backend

OpenTelemetry Collector can be configured to export telemetry Kubernetes data to the Instana backend. An additional header in the otlp exporter must contain the agent key (typically agent download key) for authentication purposes. This can be achieved by modifying the exporters:

exporters:
  otlp/ins:
    endpoint: 'https://otlp-blue-saas.instana.io:4317' # Instana backend endpoint for OpenTelemetry. For example, "https://otlp-blue-saas.instana.io:4317".
    tls:
      insecure: true
    headers:
      x-instana-key: agentDownloadKey # The agent download key can be found in the agent page along with one-line installation of the agent in linux distributions.

service:
  pipelines:
    metrics:
      exporters: [otlp/ins]

Install the OpenTelemetry Collector by using Helm charts

To monitor Kubernetes with OpenTelemetry, install the OpenTelemetry Collector by using the Helm chart method as it offers simple configuration options to ease the process.

To collect Kubernetes signals, you require the following OpenTelemetry Collector installations:

The Helm chart for OpenTelemetry Collector requires to set a mode (daemonset or deployment). This mode determines the kind of installation to the Kubernetes environment.

To install OpenTelemetry Collector in a Kubernetes environment, complete the following steps.

  1. Add the OpenTelemetry Helm repository by running the following commands:

    helm repo add open-telemetry https://open-telemetry.github.io/opentelemetry-helm-charts

  2. Install the daemonset mode of OpenTelemetry Collector by completing the following steps:

    Run the following Helm command to install the daemonset mode of the collector:

     helm install otel-k8s open-telemetry/opentelemetry-collector --values <<values file>>

    Replace values file with the name of your values file.

    For example, if the values file is called helmValuesDaemonset.yaml, use the following command:

     helm install otel-k8s open-telemetry/opentelemetry-collector --values helmValuesDaemonset.yaml

  3. Install the deployment mode of OpenTelemetry Collector by completing the following steps: Run the following Helm command to install the deployment mode of collector:

    helm install otel-k8s-dep open-telemetry/opentelemetry-collector --values <<values file>>

    Replace values file with the name of your values file.

    For example, if the values file is called helmValuesDeployment.yaml, use the following command:

    helm install otel-k8s-dep open-telemetry/opentelemetry-collector --values helmValuesDeployment.yaml

  4. Verify the installation of OpenTelemetry Collector by running the following Kubernetes command:

    kubectl get pods -A

    The following image shows a typical output of the OpenTelemetry Collector installation:

    OpenTelemetry Kubernetes status
    Figure 1. OpenTelemetry Kubernetes status

Uninstalling the OpenTelemetry Collector

Uninstalling the OpenTelemetry Collector for Kubernetes is equivalent to uninstalling the Helm charts.

If you want to uninstall both the daemonset and deployment mode of OpenTelemetry Collector, run the following command:

helm uninstall otel-k8s-dep
helm uninstall otel-k8s

Viewing Kubernetes resources in Instana

After you install and configure the OpenTelemetry Collector, you can view Kubernetes resources in the Instana UI.

Troubleshooting

You might encounter the following issues while monitoring Kubernetes with the OpenTelemetry Collector.

CrashImageBackOff in Kubernetes

The OpenTelemetry Collector exits in few Kubernetes environment with CrashImageBackOff and fails to activate. To resolve this issue, update the default readiness or liveness port in the yaml file as shown in the following example:

config:
  extensions:
    health_check:
      endpoint: ${env:MY_POD_IP}:31000
livenessProbe:
  initialDelaySeconds: 60
  httpGet:
    path: /
    port: 31000
readinessProbe:
  initialDelaySeconds: 60
  httpGet:
    path: /
    port: 31000