Set up Beyla on Grafana Labs

Deploy Beyla in Kubernetes with Helm for Grafana Cloud

Fri, 03 Apr 2026 19:43:06 +0000

Deploy Beyla in Kubernetes with Helm for Grafana Cloud Knowledge Graph and Application Observability

This documentation section explains the best practices for deploying Beyla using the Helm chart, but specifically for Grafana Cloud Knowledge Graph and Application Observability.

Knowledge Graph and Application Observability in Grafana Cloud rely on OpenTelemetry span and service graph metrics, which are typically produced from traces. Beyla can directly generate span and service graph metrics, without having to generate traces, which means that we can configure head sampling for OpenTelemetry traces, or disable trace generation completely, and still generate correct Request-Error-Duration(RED) metrics.

If you are familiar with the Grafana Cloud Application Observability configuration for the Tempo span metric generator, this component is not needed, nor needs to be configured/enabled for Beyla span and service graph metrics generation.

Note
For more details about the diverse Helm configuration options, check out the Beyla Helm chart options document.

Contents:

Deploy Beyla with Helm for Grafana Cloud

First, you need to add the Grafana helm repository to Helm:

helm repo add grafana https://grafana.github.io/helm-charts

If you have previously added the Grafana Helm repository, run the update command to refresh the helm repository information:

helm repo update

The following command deploys a Beyla DaemonSet with a default configuration for Grafana Cloud in the beyla namespace:

helm upgrade --install --atomic --timeout 300s beyla grafana/beyla --namespace "beyla" --create-namespace --values - <<EOF
config:
  data:
    discovery:
      instrument:
        - k8s_namespace: "*"
    otel_metrics_export:
      endpoint: <Your Grafana Cloud tenant Mimir endpoint> e.g. "https://otlp-gateway-ops-eu-south-0.grafana-ops.net/otlp/v1/metrics"
      features:
        - application_span
        - application_service_graph
        - application_host
    otel_traces_export:
      endpoint: <Your Grafana Cloud tenant Tempo endpoint> e.g. "https://otlp-gateway-ops-eu-south-0.grafana-ops.net/otlp/v1/traces"
env:
  OTEL_EXPORTER_OTLP_METRICS_HEADERS: "Authorization=Basic <Your Grafana Cloud Mimir auth token>"
  OTEL_EXPORTER_OTLP_TRACES_HEADERS: "Authorization=Basic <Your Grafana Cloud Tempo auth token>"
EOF

The Beyla configuration above:

exports metrics and traces in a format that can be consumed by Grafana Cloud Knowledge Graph and Application Observability.
exports host information metrics application_host which are needed for the host based pricing model of the Grafana Cloud products.
tries to instrument all the applications in your cluster.
only provides application-level metrics (span and service graph) and excludes network-level metrics by default
configures Beyla to decorate the metrics with Kubernetes metadata labels, for example k8s.namespace.name or k8s.pod.name

Configure Beyla

You might want to override the default configuration of Beyla. For example, to export the metrics using the OpenTelemetry semantic conventions instead of span metrics, or to restrict the number of services to instrument.

You can override the default Beyla configuration options with your own values.

For example, create a helm-beyla.yml file with a custom configuration:

config:
  data:
    # Contents of the actual Beyla configuration file,
    # specifying only two Kubernetes namespaces to be instrumented.
    discovery:
      instrument:
        - k8s_namespace: demo
        - k8s_namespace: blog
    metrics:
      features:
        - application_span
        - application_service_graph
        - application_host
    otel_metrics_export:
      endpoint: <Your Grafana Cloud tenant Mimir endpoint> e.g. "https://otlp-gateway-ops-eu-south-0.grafana-ops.net/otlp/v1/metrics"
    otel_traces_export:
      endpoint: <Your Grafana Cloud tenant Tempo endpoint> e.g. "https://otlp-gateway-ops-eu-south-0.grafana-ops.net/otlp/v1/traces"
    routes:
      unmatched: heuristic
env:
  OTEL_EXPORTER_OTLP_METRICS_HEADERS: "Authorization=Basic <Your Grafana Cloud Mimir auth token>"
  OTEL_EXPORTER_OTLP_TRACES_HEADERS: "Authorization=Basic <Your Grafana Cloud Tempo auth token>"

The config.data section contains a Beyla configuration file, documented in the Beyla configuration options documentation.

Then pass the overridden configuration to the helm command with the -f flag. For example:

helm install beyla grafana/beyla -f helm-beyla.yml

or, if the Beyla chart was previously deployed:

helm upgrade beyla grafana/beyla -f helm-beyla.yml

Configure Beyla metadata

If Beyla exports the data using the Prometheus exporter, you can expose its metrics by creating a Kubernetes Service and configuring a ServiceMonitor, allowing your Prometheus scraper to discover it. To enable this feature, edit your helm-beyla.yml file to include the following configuration:

service:
  enabled: true

serviceMonitor:
  enabled: true

Note
Configure your Prometheus scraper with honor_labels: true to preserve the per-process instance identifiers set by Beyla.

Analogously, the Helm chart allows overriding names, labels, and annotations for multiple resources involved in the deployment of Beyla, such as service accounts, cluster roles, security contexts, etc. The Beyla Helm chart documentation describes the diverse configuration options.

Provide secrets to the Helm configuration

If you are submitting directly the metrics and traces to Grafana Cloud via the OpenTelemetry Endpoint, you need to provide the credentials via the OTEL_EXPORTER_OTLP_HEADERS environment variable.

The recommended way is to store such value in a Kubernetes Secret and then specify the environment variable referring to it from the Helm configuration.

For example, deploy the following secret:

apiVersion: v1
kind: Secret
metadata:
  name: grafana-secret
type: Opaque
stringData:
  otlp-headers: "Authorization=Basic ...."

Then refer to it from the helm-config.yml file via the envValueFrom section:

env:
  OTEL_EXPORTER_OTLP_ENDPOINT: "<...your Grafana Cloud OTLP endpoint URL...>"
envValueFrom:
  OTEL_EXPORTER_OTLP_HEADERS:
    secretKeyRef:
      key: otlp-headers
      name: grafana-secret

Deploy Beyla with the Kubernetes Monitoring Helm Chart

Fri, 03 Apr 2026 19:43:06 +0000

Deploy Beyla with the Kubernetes Monitoring Helm Chart

This documentation section explains the best practices for deploying Beyla using the Kubernetes Monitoring Helm chart, but specifically for Grafana Cloud Knowledge Graph and Application Observability. For documentation on how to deploy Beyla using the Beyla standalone Helm chart, refer to the Deploy Beyla in Kubernetes with Helm for Grafana Cloud Application Observability documentation section.

Contents:

Deploy Beyla

The easiest way to get started with deploying Beyla with the Kubernetes Monitoring Helm chart is to visit your cloud Kubernetes Monitoring configuration page. For example:

https://<my grafana slug>.grafana.net/a/grafana-k8s-app/configuration?from=now-1h&to=now

In the Containerized application monitoring section, enable Auto Instrumentation -> Metrics of inbound and outbound calls. If you also want to generate OpenTelemetry traces from Beyla directly, you can choose to also enable Forward traces to application receivers.

After choosing your other desired options, the Grafana Cloud Kubernetes Monitoring UI generates a Helm deployment script for you, which contains all the necessary settings for you to get started. The Beyla instrumentation section can be found under the section autoInstrumentation:.

For example:

helm repo add grafana https://grafana.github.io/helm-charts &&
  helm repo update &&
  helm upgrade --install --atomic --timeout 300s grafana-k8s-monitoring grafana/k8s-monitoring \
    --namespace "default" --create-namespace --values - <<'EOF'
cluster:
  name: my-cluster
destinations:
...
autoInstrumentation:
  enabled: true
  beyla:
    deliverTracesToApplicationObservability: false
...
EOF

The Beyla configuration above:

exports metrics in a format that can be consumed by Grafana Cloud Knowledge Graph and Application Observability.
does not export Beyla traces.
tries to instrument all the applications in your cluster.

Configure Beyla

You might want to override the default configuration of Beyla. For example, to choose a subset of your cluster namespaces to instrument or to override the Beyla image used to a newer version.

You can override the default Beyla configuration options with your own values.

For example, we can modify the autoinstrumentation: configuration section generated by the Kubernetes Monitoring Helm chart to pick and choose what to instrument:

helm repo add grafana https://grafana.github.io/helm-charts &&
  helm repo update &&
  helm upgrade --install --atomic --timeout 300s grafana-k8s-monitoring grafana/k8s-monitoring \
    --namespace "default" --create-namespace --values - <<'EOF'
cluster:
  name: my-cluster
destinations:
...
autoInstrumentation:
  enabled: true
  beyla:
    deliverTracesToApplicationObservability: true
    image: 
      tag: main
    pullPolicy: always
    config:
      data:
        discovery:
          services:
            - k8s_namespace: alpha
            - k8s_namespace: bravo
            - k8s_namespace: delta    
...
EOF

The autoInstrumentation.beyla.config.data section contains a Beyla configuration file, documented in the Beyla configuration options documentation.

In the example above the configuration is modified to:

Enable Beyla traces generation.
We only instrument three namespaces in the cluster: alpha, bravo and delta.
We have chosen to pull the latest main Beyla image.

Run Beyla as a Docker container

Fri, 03 Apr 2026 19:43:06 +0000

Run Beyla as a Docker container

Beyla can run a standalone Docker container that can instrument a process running in another container.

Find the latest image of Beyla on Docker Hub with the following name:

grafana/beyla:latest

The Beyla container must be configured in following way:

run as a privileged container, or with the required Linux capabilities. Refer to Security, permissions and capabilities for the list of capabilities required for your use case
share the PID space with the container that is being instrumented

Docker CLI example

For this example you need a container running an HTTP/S or GRPC service. If you don’t have one, you can use this simple blog engine service written in Go:

docker run -p 18443:8443 --name goblog mariomac/goblog:dev

The above command runs a simple HTTPS application. The process opens the container’s internal port 8443, which is then exposed at the host level as the port 18443.

Set environment variables to configure Beyla to print to stdout and listen to a port (container) to inspect the executable:

export BEYLA_TRACE_PRINTER=text
export BEYLA_OPEN_PORT=8443

Beyla needs to be run with the following settings:

in --privileged mode, or with the required Linux capabilities. Refer to Security, permissions and capabilities for the list of capabilities required for your use case
a container PID namespace, with the option --pid="container:goblog".

docker run --rm \
  -e BEYLA_OPEN_PORT=8443 \
  -e BEYLA_TRACE_PRINTER=text \
  --pid="container:goblog" \
  --privileged \
  grafana/beyla:latest

After Beyla is running, open https://localhost:18443 in your browser, use the app to generate test data, and verify that Beyla prints trace requests to stdout similar to:

time=2023-05-22T14:03:42.402Z level=INFO msg="creating instrumentation pipeline"
time=2023-05-22T14:03:42.526Z level=INFO msg="Starting main node"
2023-05-22 14:03:53.5222353 (19.066625ms[942.583µs]) 200 GET / [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (355.792µs[321.75µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:03:53.5222353 (170.958µs[142.916µs]) 200 GET /static/img.png [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (7.243667ms[295.292µs]) 200 GET /entry/201710281345_instructions.md [172.17.0.1]->[localhost:18443] size:0B
2023-05-22 14:13:47.52221347 (115µs[75.625µs]) 200 GET /static/style.css [172.17.0.1]->[localhost:18443] size:0B

Now that Beyla is tracing the target HTTP service, configure it to send metrics and traces to an OpenTelemetry endpoint, or have metrics scraped by Prometheus.

For information on how to export traces and metrics, refer to the configuration options documentation.

Docker Compose example

The following Docker compose file replicates the same functionality of the Docker CLI example:

version: "3.8"

services:
  # Service to instrument. Change it to any
  # other container that you want to instrument.
  goblog:
    image: mariomac/goblog:dev
    ports:
      # Exposes port 18843, forwarding it to container port 8443
      - "18443:8443"

  autoinstrumenter:
    image: grafana/beyla:latest
    pid: "service:goblog"
    privileged: true
    environment:
      BEYLA_TRACE_PRINTER: text
      BEYLA_OPEN_PORT: 8443

Run the Docker compose file with the following command and use the app to generate traces:

docker compose -f compose-example.yml up

Deploy Beyla in Kubernetes

Fri, 03 Apr 2026 19:43:06 +0000

Deploy Beyla in Kubernetes

Note
This document explains how to manually deploy Beyla in Kubernetes, setting up all the required entities by yourself.

You might prefer to follow the Deploy Beyla in Kubernetes with Helm documentation instead.

Contents:

Deploy Beyla in Kubernetes

Configuring Kubernetes metadata decoration

Beyla can decorate your traces with the following Kubernetes labels:

k8s.namespace.name
k8s.deployment.name
k8s.statefulset.name
k8s.replicaset.name
k8s.daemonset.name
k8s.node.name
k8s.pod.name
k8s.container.name
k8s.pod.uid
k8s.pod.start_time
k8s.cluster.name

To enable metadata decoration, you need to:

Create a ServiceAccount and bind a ClusterRole granting list and watch permissions for both Pods and ReplicaSets. You can do it by deploying this example file:

apiVersion: v1
kind: ServiceAccount
metadata:
  name: beyla
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: beyla
rules:
  - apiGroups: [ "apps" ]
    resources: [ "replicasets" ]
    verbs: [ "list", "watch" ]
  - apiGroups: [ "" ]
    resources: [ "pods", "services", "nodes" ]
    verbs: [ "list", "watch" ]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
  name: beyla
subjects:
  - kind: ServiceAccount
    name: beyla
    namespace: default
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: beyla

(You need to change the namespace: default value if you are deploying Beyla in another namespace).

Configure Beyla with the BEYLA_KUBE_METADATA_ENABLE=true environment variable, or the attributes.kubernetes.enable: true YAML configuration.
Don’t forget to specify the serviceAccountName: beyla property in your Beyla Pod (as shown in the later deployment examples).

Optionally, select which Kubernetes services to instrument in the discovery -> instrument section of the YAML configuration file. For more information, refer to the Service discovery section in the Configuration document, as well as the Providing an external configuration file section of this page.

Deploying Beyla

You can deploy Beyla in Kubernetes in two different ways:

As a sidecar container
As a DaemonSet

Deploy Beyla as a sidecar container

This is the way you can deploy Beyla if you want to monitor a given service that might not be deployed in all the hosts, so you only have to deploy one Beyla instance per each service instance.

Deploying Beyla as a sidecar container has the following configuration requirements:

The process namespace must be shared between all containers in the Pod (shareProcessNamespace: true pod variable)
The auto-instrument container must run in privileged mode (securityContext.privileged: true property of the container configuration), or with the required Linux capabilities. Refer to Security, permissions and capabilities for the list of capabilities required for your use case, or check the Deploy Beyla unprivileged section below.

The following example instruments the goblog pod by attaching Beyla as a container (image available at grafana/beyla:latest). The auto-instrumentation tool is configured to forward metrics and traces to Grafana Alloy, which is accessible behind the grafana-alloy service in the same namespace:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: goblog
  labels:
    app: goblog
spec:
  replicas: 2
  selector:
    matchLabels:
      app: goblog
  template:
    metadata:
      labels:
        app: goblog
    spec:
      # Required so the sidecar instrument tool can access the service process
      shareProcessNamespace: true
      serviceAccountName: beyla # required if you want kubernetes metadata decoration
      containers:
        # Container for the instrumented service
        - name: goblog
          image: mariomac/goblog:dev
          imagePullPolicy: IfNotPresent
          command: ["/goblog"]
          ports:
            - containerPort: 8443
              name: https
        # Sidecar container with Beyla - the eBPF auto-instrumentation tool
        - name: beyla
          image: grafana/beyla:latest
          securityContext: # Privileges are required to install the eBPF probes
            privileged: true
          env:
            # The internal port of the goblog application container
            - name: BEYLA_OPEN_PORT
              value: "8443"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://grafana-alloy:4318"
              # required if you want kubernetes metadata decoration
            - name: BEYLA_KUBE_METADATA_ENABLE
              value: "true"

For more information about the different configuration options, check the Configuration section of this documentation site.

Deploy Beyla as a Daemonset

You can also deploy Beyla as a Daemonset. This is the preferred way if:

You want to instrument a Daemonset
You want to instrument multiple processes from a single Beyla instance, or even all of the processes in your cluster.

Using the previous example (the goblog pod), we cannot select the process to instrument by using its open port, because the port is internal to the Pod. At the same time multiple instances of the service would have different open ports. In this case, we will need to instrument by using the application service executable name (see later example).

In addition to the privilege requirements of the sidecar scenario, you will need to configure the auto-instrument pod template with the hostPID: true option enabled, so that it can access all the processes running on the same host.

---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: beyla
  labels:
    app: beyla
spec:
  selector:
    matchLabels:
      app: beyla
  template:
    metadata:
      labels:
        app: beyla
    spec:
      hostPID: true # Required to access the processes on the host
      serviceAccountName: beyla # required if you want kubernetes metadata decoration
      containers:
        - name: autoinstrument
          image: grafana/beyla:latest
          securityContext:
            privileged: true
          env:
            # Select the executable by its name instead of BEYLA_OPEN_PORT
            - name: BEYLA_AUTO_TARGET_EXE
              value: "*/goblog"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              value: "http://grafana-alloy:4318"
              # required if you want kubernetes metadata decoration
            - name: BEYLA_KUBE_METADATA_ENABLE
              value: "true"

Deploy Beyla unprivileged

In all of the examples so far, privileged:true or the SYS_ADMIN Linux capability was used in the Beyla deployment’s securityContext section. While this works in all circumstances, there are ways to deploy Beyla in Kubernetes with reduced privileges if your security configuration requires you to do so. Whether this is possible depends on the Kubernetes version you have and the underlying container runtime used (e.g. Containerd, CRI-O or Docker).

The following guide is based on tests performed mainly by running containerd with GKE, kubeadm, k3s, microk8s and kind.

To run Beyla unprivileged, you need to replace the privileged:true setting with a set of Linux capabilities. A comprehensive list of capabilities required by Beyla can be found in Security, permissions and capabilities.

Note Loading BPF programs requires that Beyla is able to read the Linux performance events, or at least be able to execute the Linux Kernel API perf_event_open().

This permission is granted by CAP_PERFMON or more liberally through CAP_SYS_ADMIN. Since both CAP_PERFMON and CAP_SYS_ADMIN grant Beyla the permission to read performance events, you should use CAP_PERFMON because it grants lesser permissions. However, at system level, the access to the performance events is controlled through the setting kernel.perf_event_paranoid, which you can read or write by using sysctl or by modifying the file /proc/sys/kernel/perf_event_paranoid. The default setting for kernel.perf_event_paranoid is typically 2, which is documented under the perf_event_paranoid section in the kernel documentation. Some Linux distributions define higher levels for kernel.perf_event_paranoid, for example Debian based distributions also use kernel.perf_event_paranoid=3, which disallows access to perf_event_open() without CAP_SYS_ADMIN. If you are running on a distribution with kernel.perf_event_paranoid setting higher than 2, you can either modify your configuration to lower it to 2 or use CAP_SYS_ADMIN instead of CAP_PERFMON.

An example of a Beyla unprivileged container configuration can be found below, or you can download the full example deployment file:

...
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: beyla
  namespace: beyla-demo
  labels:
    k8s-app: beyla
spec:
  selector:
    matchLabels:
      k8s-app: beyla
  template:
    metadata:
      labels:
        k8s-app: beyla
    spec:
      serviceAccount: beyla
      hostPID: true           # <-- Important. Required in Daemonset mode so Beyla can discover all monitored processes
      containers:
      - name: beyla
        terminationMessagePolicy: FallbackToLogsOnError
        image: grafana/beyla:latest
        env:
          - name: BEYLA_TRACE_PRINTER
            value: "text"
          - name: BEYLA_KUBE_METADATA_ENABLE
            value: "autodetect"
          - name: KUBE_NAMESPACE
            valueFrom:
              fieldRef:
                fieldPath: metadata.namespace
          ...
        securityContext:
          runAsUser: 0
          readOnlyRootFilesystem: true
          capabilities:
            add:
              - BPF                 # <-- Important. Required for most eBPF probes to function correctly.
              - SYS_PTRACE          # <-- Important. Allows Beyla to access the container namespaces and inspect executables.
              - NET_RAW             # <-- Important. Allows Beyla to use socket filters for http requests.
              - CHECKPOINT_RESTORE  # <-- Important. Allows Beyla to open ELF files.
              - DAC_READ_SEARCH     # <-- Important. Allows Beyla to open ELF files.
              - PERFMON             # <-- Important. Allows Beyla to load BPF programs.
              #- SYS_RESOURCE       # <-- pre 5.11 only. Allows Beyla to increase the amount of locked memory.
              #- SYS_ADMIN          # <-- Required for Go application trace context propagation, or if kernel.perf_event_paranoid >= 3 on Debian distributions.
            drop:
              - ALL
        volumeMounts:
        - name: var-run-beyla
          mountPath: /var/run/beyla
        - name: cgroup
          mountPath: /sys/fs/cgroup
      tolerations:
      - effect: NoSchedule
        operator: Exists
      - effect: NoExecute
        operator: Exists
      volumes:
      - name: var-run-beyla
        emptyDir: {}
      - name: cgroup
        hostPath:
          path: /sys/fs/cgroup
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: some-service
  namespace: beyla-demo
  ...
---

Providing an external configuration file

In the previous examples, Beyla was configured via environment variables. However, you can also configure it via an external YAML file (as documented in the Configuration section of this site).

To provide the configuration as a file, the recommended way is to deploy a ConfigMap with the intended configuration, then mount it into the Beyla Pod, and refer to it with the BEYLA_CONFIG_PATH environment variable.

Example of ConfigMap with the Beyla YAML documentation:

apiVersion: v1
kind: ConfigMap
metadata:
  name: beyla-config
data:
  beyla-config.yml: |
    trace_printer: text
    grafana:
      otlp:
        submit: ["metrics","traces"]
    otel_traces_export:
      sampler:
        name: parentbased_traceidratio
        arg: "0.01"
    routes:
      patterns:
        - /factorial/{num}

Example of Beyla DaemonSet configuration, mounting and accessing to the previous ConfigMap:

apiVersion: apps/v1
kind: DaemonSet
metadata:
  name: beyla
spec:
  selector:
    matchLabels:
      instrumentation: beyla
  template:
    metadata:
      labels:
        instrumentation: beyla
    spec:
      serviceAccountName: beyla
      hostPID: true #important!
      containers:
        - name: beyla
          image: grafana/beyla:latest
          imagePullPolicy: IfNotPresent
          securityContext:
            privileged: true
            readOnlyRootFilesystem: true
          # mount the previous ConfigMap as a folder
          volumeMounts:
            - mountPath: /config
              name: beyla-config
            - mountPath: /var/run/beyla
              name: var-run-beyla
          env:
            # tell beyla where to find the configuration file
            - name: BEYLA_CONFIG_PATH
              value: "/config/beyla-config.yml"
      volumes:
        - name: beyla-config
          configMap:
            name: beyla-config
        - name: var-run-beyla
          emptyDir: {}

Providing secret configuration

The previous example is valid for regular configuration but should not be used to pass secret information like passwords or API keys.

To provide secret information, the recommended way is to deploy a Kubernetes Secret. For example, this secret contains some fictional Grafana Cloud credentials:

apiVersion: v1
kind: Secret
metadata:
  name: grafana-secret
type: Opaque
stringData:
  grafana-user: "123456"
  grafana-api-key: "xxxxxxxxxxxxxxx"

Then you can access the secret values as environment variables. Following the previous DaemonSet example, this would be achieved by adding the following env section to the Beyla container:

env:
  - name: GRAFANA_CLOUD_ZONE
    value: prod-eu-west-0
  - name: GRAFANA_CLOUD_INSTANCE_ID
    valueFrom:
      secretKeyRef:
        key: grafana-user
        name: grafana-secret
  - name: GRAFANA_CLOUD_API_KEY
    valueFrom:
      secretKeyRef:
        key: grafana-api-key
        name: grafana-secret

Deploy Beyla in Kubernetes with Helm

Fri, 03 Apr 2026 19:43:06 +0000

Deploy Beyla in Kubernetes with Helm

Note
For more details about the diverse Helm configuration options, check out the Beyla Helm chart options document.

Contents:

Deploy Beyla with helm

First, you need to add the Grafana helm repository to Helm:

helm repo add grafana https://grafana.github.io/helm-charts

The following command deploys a Beyla DaemonSet with a default configuration in the beyla namespace:

helm install beyla -n beyla --create-namespace  grafana/beyla

The default Beyla configuration:

exports the metrics as Prometheus metrics in the Pod HTTP port 9090, /metrics path.
tries to instrument all the applications in your cluster.
only provides application-level metrics and excludes network-level metrics by default
configures Beyla to decorate the metrics with Kubernetes metadata labels, for example k8s.namespace.name or k8s.pod.name

Configure Beyla

You might want to override the default configuration of Beyla. For example, to export the metrics and/or spans as OpenTelemetry instead of Prometheus, or to restrict the number of services to instrument.

You can override the default Beyla configuration options with your own values.

For example, create a helm-beyla.yml file with a custom configuration:

config:
  data:
    # Contents of the actual Beyla configuration file
    discovery:
      instrument:
        - k8s_namespace: demo
        - k8s_namespace: blog
    routes:
      unmatched: heuristic

The config.data section contains a Beyla configuration file, documented in the Beyla configuration options documentation.

Then pass the overridden configuration to the helm command with the -f flag. For example:

helm install beyla grafana/beyla -f helm-beyla.yml

or, if the Beyla chart was previously deployed:

helm upgrade beyla grafana/beyla -f helm-beyla.yml

Configure Beyla metadata

service:
  enabled: true

serviceMonitor:
  enabled: true

Note
Configure your Prometheus scraper with honor_labels: true to preserve the per-process instance identifiers set by Beyla.

Provide secrets to the Helm configuration

If you are submitting directly the metrics and traces to Grafana Cloud via the OpenTelemetry Endpoint, you need to provide the credentials via the OTEL_EXPORTER_OTLP_HEADERS environment variable.

The recommended way is to store such value in a Kubernetes Secret and then specify the environment variable referring to it from the Helm configuration.

For example, deploy the following secret:

apiVersion: v1
kind: Secret
metadata:
  name: grafana-secret
type: Opaque
stringData:
  otlp-headers: "Authorization=Basic ...."

Then refer to it from the helm-config.yml file via the envValueFrom section:

env:
  OTEL_EXPORTER_OTLP_ENDPOINT: "<...your Grafana Cloud OTLP endpoint URL...>"
envValueFrom:
  OTEL_EXPORTER_OTLP_HEADERS:
    secretKeyRef:
      key: otlp-headers
      name: grafana-secret

Run Beyla in Kubernetes using Grafana Alloy Helm's chart

Fri, 03 Apr 2026 19:43:06 +0000

Run Beyla in Kubernetes using Grafana Alloy Helm’s chart

Grafana Alloy is a vendor-neutral distribution of the OpenTelemetry Collector. Alloy offers native pipelines for OpenTelemetry, Prometheus, and other telemetry signals.

Grafana Alloy bundles Beyla allowing you to instrument your applications at the same time you instrument your infrastructure. It also provides a Helm chart to deploy Alloy in Kubernetes.

In this tutorial, you learn how to deploy Beyla in Kubernetes using Grafana Alloy Helm’s chart.

Prerequisites

A Kubernetes cluster, you can use kind to create a local cluster
kubectl installed and configured for your cluster
Helm installed
A Grafana Cloud account or a compatible Prometheus and/or OpenTelemetry backend to receive the data

1. Prepare the Alloy environment in Kubernetes

You need to install the Helm chart for Grafana Alloy in your Kubernetes cluster.

helm install --namespace alloy alloy grafana/alloy

This command installs the Grafana Alloy Helm chart in the alloy namespace.

2. Deploy services

You can instrument any HTTP or HTTPS service in your Kubernetes cluster.

Copy the following contents into a file, for example sampleapps.yml, and deploy it with the command kubectl apply -f sampleapps.yml.

kind: Deployment
apiVersion: apps/v1
metadata:
  name: docs
spec:
  replicas: 2
  selector:
    matchLabels:
      app: docs
  template:
    metadata:
      labels:
        app: docs
    spec:
      containers:
        - name: docs-server
          image: httpd:latest
          ports:
            - containerPort: 80
              protocol: TCP
              name: http
---
apiVersion: v1
kind: Service
metadata:
  name: docs
spec:
  selector:
    app: docs
  ports:
    - protocol: TCP
      port: 80
---
kind: Deployment
apiVersion: apps/v1
metadata:
  name: website
spec:
  replicas: 2
  selector:
    matchLabels:
      app: website
  template:
    metadata:
      labels:
        app: website
    spec:
      containers:
        - name: website-server
          image: httpd:latest
          ports:
            - containerPort: 80
              protocol: TCP
              name: http
---
apiVersion: v1
kind: Service
metadata:
  name: website
spec:
  selector:
    app: website
  ports:
    - protocol: TCP
      port: 80

3. Configure credentials

Alloy can export metrics and traces to any OpenTelemetry endpoint, as well as exposing metrics as a Prometheus endpoint. However, it’s recommend using the Prometheus and Tempo remote write endpoints in Grafana Cloud. You can get a free Grafana Cloud Account.

From the Grafana Cloud Portal, look for the Prometheus box and click Send Metrics. For the Tempo box, click Send Traces.

Create a secrets.yml file with your Grafana Cloud credentials for Prometheus and Tempo remote write. Deploy it with the command kubectl apply -f secrets.yml.

apiVersion: v1
kind: Secret
metadata:
  namespace: alloy
  name: grafana-credentials
type: Opaque
stringData:
  prometheus-rw-user: "prom-user"
  prometheus-rw-pwd: "prom-pwd"
  tempo-rw-user: "tempo-user"
  tempo-rw-pwd: "tempo-pwd"

3. Create a ConfigMap with Alloy configuration

Create a ConfigMap with the Alloy configuration. Copy the following contents into a file, for example config.alloy:

beyla.ebpf "default" {
	attributes {
		kubernetes {
			enable = "true"
		}
	}

	discovery {
		services {
      kubernetes {
				namespace = "default"
				deployment_name = "."
      }
		}
	}

	metrics {
		features = [
			"application",
		]
	}

	output {
		traces = [otelcol.exporter.otlp.grafana_cloud_tempo.input]
	}
}

prometheus.scrape "beyla" {
	targets      = beyla.ebpf.default.targets
	honor_labels = true
	forward_to   = [prometheus.remote_write.rw.receiver]
}

prometheus.remote_write "rw" {
	endpoint {
		url = "https://prometheus-us-central1.grafana.net/api/prom/push"

		basic_auth {
			username = env("PROMETHEUS_REMOTE_WRITE_USERNAME")
			password = env("PROMETHEUS_REMOTE_WRITE_PASSWORD")
		}
	}
}

otelcol.exporter.otlp "grafana_cloud_tempo" {
	client {
		endpoint = "tempo-us-central1.grafana.net:443"
		auth     = otelcol.auth.basic.grafana_cloud_tempo.handler
	}
}

otelcol.auth.basic "grafana_cloud_tempo" {
	username = env("TEMPO_REMOTE_WRITE_USERNAME")
	password = env("TEMPO_REMOTE_WRITE_PASSWORD")
}

Deploy the configuration with the command:

kubectl create configmap --namespace alloy alloy-config "--from-file=config.alloy=./config.alloy"

With this configuration Beyla instruments the services running in the Kubernetes cluster and send traces to Grafana Cloud Tempo and metrics to Prometheus.

The attributes > kubernetes > enable enables Kubernetes decoration for metrics and traces, which adds the metadata of the Kubernetes entities running the automatically instrumented services.

The argument discovery > services > kubernetes specifies the selection of services based on Kubernetes metadata. In this example, Beyla instruments all deployments in namespace “default”.

The prometheus.scrape section configures Prometheus scrape to collect metrics from Beyla. The honor_labels = true setting preserves the per-process instance identifiers set by Beyla. The prometheus.remote_write section sends the metrics to Grafana Cloud Prometheus.

The output section configures that Beyla component sends traces to otelcol.exporter.otlp component. The otelcol.exporter.otlp section configures the OTLP exporter to send the traces to Grafana Cloud Tempo.

For further details on the configuration options, refer to the documentation of the Grafana Alloy Beyla component

4. Deploy Alloy with Helm

Create a values.yaml with the configuration for the Alloy Helm chart. Copy the following contents into a file, for example values.yaml.

# -- Overrides the chart's name. Used to change the infix in the resource names.
nameOverride: null

# -- Overrides the chart's computed fullname. Used to change the full prefix of
# resource names.
fullnameOverride: null

## Global properties for image pulling override the values defined under `image.registry` and `configReloader.image.registry`.
## If you want to override only one image registry, use the specific fields but if you want to override them all, use `global.image.registry`
global:
  image:
    # -- Global image registry to use if it needs to be overridden for some specific use cases (e.g local registries, custom images, ...)
    registry: ""

    # -- Optional set of global image pull secrets.
    pullSecrets: []

  # -- Security context to apply to the Grafana Alloy pod.
  podSecurityContext: {}

crds:
  # -- Whether to install CRDs for monitoring.
  create: true

## Various Alloy settings. For backwards compatibility with the grafana-agent
## chart, this field may also be called "agent". Naming this field "agent" is
## deprecated and will be removed in a future release.
alloy:
  configMap:
    # -- Create a new ConfigMap for the config file.
    create: false
    # -- Name of existing ConfigMap to use. Used when create is false.
    name: alloy-config
    # -- Key in ConfigMap to get config from.
    key: config.alloy

  clustering:
    # -- Deploy Alloy in a cluster to allow for load distribution.
    enabled: false

  # -- Minimum stability level of components and behavior to enable. Must be
  # one of "experimental", "public-preview", or "generally-available".
  stabilityLevel: "public-preview"

  # -- Path to where Grafana Alloy stores data (for example, the Write-Ahead Log).
  # By default, data is lost between reboots.
  storagePath: /tmp/alloy

  # -- Address to listen for traffic on. 0.0.0.0 exposes the UI to other
  # containers.
  listenAddr: 0.0.0.0

  # -- Port to listen for traffic on.
  listenPort: 12345

  # -- Scheme is needed for readiness probes. If enabling tls in your configs, set to "HTTPS"
  listenScheme: HTTP

  # --  Base path where the UI is exposed.
  uiPathPrefix: /

  # -- Enables sending Grafana Labs anonymous usage stats to help improve Grafana
  # Alloy.
  enableReporting: true

  # -- Extra environment variables to pass to the Alloy container.
  extraEnv:
  - name: PROMETHEUS_REMOTE_WRITE_USERNAME
    valueFrom:
      secretKeyRef:
        name: grafana-credentials
        key: prometheus-rw-user
  - name: PROMETHEUS_REMOTE_WRITE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: grafana-credentials
        key: prometheus-rw-pwd
  - name: TEMPO_REMOTE_WRITE_USERNAME
    valueFrom:
      secretKeyRef:
        name: grafana-credentials
        key: tempo-rw-user
  - name: TEMPO_REMOTE_WRITE_PASSWORD
    valueFrom:
      secretKeyRef:
        name: grafana-credentials
        key: tempo-rw-pwd

  # -- Maps all the keys on a ConfigMap or Secret as environment variables. https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#envfromsource-v1-core
  envFrom: []

  # -- Extra args to pass to `alloy run`: https://grafana.com/docs/alloy/latest/reference/cli/run/
  extraArgs: []

  # -- Extra ports to expose on the Alloy container.
  extraPorts: []
  # - name: "faro"
  #   port: 12347
  #   targetPort: 12347
  #   protocol: "TCP"

  mounts:
    # -- Mount /var/log from the host into the container for log collection.
    varlog: false
    # -- Mount /var/lib/docker/containers from the host into the container for log
    # collection.
    dockercontainers: false

    # -- Extra volume mounts to add into the Grafana Alloy container. Does not
    # affect the watch container.
    extra: []

  # -- Security context to apply to the Grafana Alloy container.
  securityContext:
    privileged: true # important!

  # -- Resource requests and limits to apply to the Grafana Alloy container.
  resources: {}

image:
  # -- Grafana Alloy image registry (defaults to docker.io)
  registry: "docker.io"
  # -- Grafana Alloy image repository.
  repository: grafana/alloy
  # -- (string) Grafana Alloy image tag. When empty, the Chart's appVersion is
  # used.
  tag: null
  # -- Grafana Alloy image's SHA256 digest (either in format "sha256:XYZ" or "XYZ"). When set, will override `image.tag`.
  digest: null
  # -- Grafana Alloy image pull policy.
  pullPolicy: IfNotPresent
  # -- Optional set of image pull secrets.
  pullSecrets: []

rbac:
  # -- Whether to create RBAC resources for Alloy.
  create: true

serviceAccount:
  # -- Whether to create a service account for the Grafana Alloy deployment.
  create: true
  # -- Additional labels to add to the created service account.
  additionalLabels: {}
  # -- Annotations to add to the created service account.
  annotations: {}
  # -- The name of the existing service account to use when
  # serviceAccount.create is false.
  name: null

# Options for the extra controller used for config reloading.
configReloader:
  # -- Enables automatically reloading when the Alloy config changes.
  enabled: true
  image:
    # -- Config reloader image registry (defaults to docker.io)
    registry: "ghcr.io"
    # -- Repository to get config reloader image from.
    repository: jimmidyson/configmap-reload
    # -- Tag of image to use for config reloading.
    tag: v0.12.0
    # -- SHA256 digest of image to use for config reloading (either in format "sha256:XYZ" or "XYZ"). When set, will override `configReloader.image.tag`
    digest: ""
  # -- Override the args passed to the container.
  customArgs: []
  # -- Resource requests and limits to apply to the config reloader container.
  resources:
    requests:
      cpu: "1m"
      memory: "5Mi"
  # -- Security context to apply to the Grafana configReloader container.
  securityContext: {}

controller:
  # -- Type of controller to use for deploying Grafana Alloy in the cluster.
  # Must be one of 'daemonset', 'deployment', or 'statefulset'.
  type: 'daemonset'

  # -- Number of pods to deploy. Ignored when controller.type is 'daemonset'.
  replicas: 1

  # -- Annotations to add to controller.
  extraAnnotations: {}

  # -- Whether to deploy pods in parallel. Only used when controller.type is
  # 'statefulset'.
  parallelRollout: true

  # -- Configures Pods to use the host network. When set to true, the ports that will be used must be specified.
  hostNetwork: false

  # -- Configures Pods to use the host PID namespace.
  hostPID: true # important!

  # -- Configures the DNS policy for the pod. https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/#pod-s-dns-policy
  dnsPolicy: ClusterFirst

  # -- Update strategy for updating deployed Pods.
  updateStrategy: {}

  # -- nodeSelector to apply to Grafana Alloy pods.
  nodeSelector: {}

  # -- Tolerations to apply to Grafana Alloy pods.
  tolerations: []

  # -- Topology Spread Constraints to apply to Grafana Alloy pods.
  topologySpreadConstraints: []

  # -- priorityClassName to apply to Grafana Alloy pods.
  priorityClassName: ''

  # -- Extra pod annotations to add.
  podAnnotations: {}

  # -- Extra pod labels to add.
  podLabels: {}

  # -- Whether to enable automatic deletion of stale PVCs due to a scale down operation, when controller.type is 'statefulset'.
  enableStatefulSetAutoDeletePVC: false

  autoscaling:
    # -- Creates a HorizontalPodAutoscaler for controller type deployment.
    enabled: false
    # -- The lower limit for the number of replicas to which the autoscaler can scale down.
    minReplicas: 1
    # -- The upper limit for the number of replicas to which the autoscaler can scale up.
    maxReplicas: 5
    # -- Average CPU utilization across all relevant pods, a percentage of the requested value of the resource for the pods. Setting `targetCPUUtilizationPercentage` to 0 will disable CPU scaling.
    targetCPUUtilizationPercentage: 0
    # -- Average Memory utilization across all relevant pods, a percentage of the requested value of the resource for the pods. Setting `targetMemoryUtilizationPercentage` to 0 will disable Memory scaling.
    targetMemoryUtilizationPercentage: 80

    scaleDown:
      # -- List of policies to determine the scale-down behavior.
      policies: []
        # - type: Pods
        #   value: 4
        #   periodSeconds: 60
      # -- Determines which of the provided scaling-down policies to apply if multiple are specified.
      selectPolicy: Max
      # -- The duration that the autoscaling mechanism should look back on to make decisions about scaling down.
      stabilizationWindowSeconds: 300

    scaleUp:
      # -- List of policies to determine the scale-up behavior.
      policies: []
        # - type: Pods
        #   value: 4
        #   periodSeconds: 60
      # -- Determines which of the provided scaling-up policies to apply if multiple are specified.
      selectPolicy: Max
      # -- The duration that the autoscaling mechanism should look back on to make decisions about scaling up.
      stabilizationWindowSeconds: 0

  # -- Affinity configuration for pods.
  affinity: {}

  volumes:
    # -- Extra volumes to add to the Grafana Alloy pod.
    extra: []

  # -- volumeClaimTemplates to add when controller.type is 'statefulset'.
  volumeClaimTemplates: []

  ## -- Additional init containers to run.
  ## ref: https://kubernetes.io/docs/concepts/workloads/pods/init-containers/
  ##
  initContainers: []

  # -- Additional containers to run alongside the Alloy container and initContainers.
  extraContainers: []

service:
  # -- Creates a Service for the controller's pods.
  enabled: true
  # -- Service type
  type: ClusterIP
  # -- NodePort port. Only takes effect when `service.type: NodePort`
  nodePort: 31128
  # -- Cluster IP, can be set to None, empty "" or an IP address
  clusterIP: ''
  # -- Value for internal traffic policy. 'Cluster' or 'Local'
  internalTrafficPolicy: Cluster
  annotations: {}
    # cloud.google.com/load-balancer-type: Internal

serviceMonitor:
  enabled: false
  # -- Additional labels for the service monitor.
  additionalLabels: {}
  # -- Scrape interval. If not set, the Prometheus default scrape interval is used.
  interval: ""
  # -- MetricRelabelConfigs to apply to samples after scraping, but before ingestion.
  # ref: https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#relabelconfig
  metricRelabelings: []
  # - action: keep
  #   regex: 'kube_(daemonset|deployment|pod|namespace|node|statefulset).+'
  #   sourceLabels: [__name__]

  # -- Customize tls parameters for the service monitor
  tlsConfig: {}

  # -- RelabelConfigs to apply to samples before scraping
  # ref: https://github.com/prometheus-operator/prometheus-operator/blob/main/Documentation/api.md#relabelconfig
  relabelings: []
  # - sourceLabels: [__meta_kubernetes_pod_node_name]
  #   separator: ;
  #   regex: ^(.*)$
  #   targetLabel: nodename
  #   replacement: $1
  #   action: replace
ingress:
  # -- Enables ingress for Alloy (Faro port)
  enabled: false
  # For Kubernetes >= 1.18 you should specify the ingress-controller via the field ingressClassName
  # See https://kubernetes.io/blog/2020/04/02/improvements-to-the-ingress-api-in-kubernetes-1.18/#specifying-the-class-of-an-ingress
  # ingressClassName: nginx
  # Values can be templated
  annotations:
    {}
    # kubernetes.io/ingress.class: nginx
    # kubernetes.io/tls-acme: "true"
  labels: {}
  path: /
  faroPort: 12347

  # pathType is only for k8s >= 1.1=
  pathType: Prefix

  hosts:
    - chart-example.local
  ## Extra paths to prepend to every host configuration. This is useful when working with annotation based services.
  extraPaths: []
  # - path: /*
  #   backend:
  #     serviceName: ssl-redirect
  #     servicePort: use-annotation
  ## Or for k8s > 1.19
  # - path: /*
  #   pathType: Prefix
  #   backend:
  #     service:
  #       name: ssl-redirect
  #       port:
  #         name: use-annotation

  tls: []
  #  - secretName: chart-example-tls
  #    hosts:
  #      - chart-example.local

Deploy the configuration with the command:

helm upgrade --namespace alloy alloy grafana/alloy -f values.yaml

To run in DaemonSet mode, Beyla requires to have access to all the processes in the node. Therefore set hostPID: true the controller section.
The Beyla container needs to run with privileges as it requires to perform privileged actions such as loading BPF programs and creating BPF maps. Therefore set privileged: true in securityContext section. For running Beyla as unprivileged container, that’s without the privileged: true option, visit the Deploy Beyla unprivileged guide.
The extraEnv section sets the environment variables for the Prometheus and Tempo remote write credentials.

5. Test the setup

With the kubectl port-forward commands from the first step still running, test both web server instances. For example:

curl http://localhost:8080
curl http://localhost:8080/foo
curl http://localhost:8081
curl http://localhost:8081/foo

Navigate to the instance in Grafana Cloud, and from the Explore section in the left panel, select the data source for the traces, named grafanacloud-<your user name>-traces.

To search for all the traces, select the Search box in the Query bar, leave the form empty, and click Run query:

This shows the traces for the docs instance on port 8081. You might see traces from your own services, but you shouldn’t see traces from the website service, as it Beyla isn’t instrumenting it.

In the trace details, the resource attributes of the traces have metadata of the Kubernetes Pod running the instrumented service: