--- title: "Deploy Beyla with the Beyla Helm chart | Grafana Beyla documentation" description: "Install Grafana Beyla in Kubernetes with the Beyla Helm chart, customize its configuration, reduce its privileges, scrape its metrics with the Prometheus Operator, and pass OTLP credentials from a Secret." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # Deploy Beyla with the Beyla Helm chart The Beyla Helm chart deploys Grafana Beyla as a DaemonSet, which runs a Beyla Pod on your cluster nodes and instruments the applications on each node. To configure the chart for Grafana Cloud Application Observability and Knowledge Graph, refer to [Deploy Beyla in Kubernetes with Helm for Grafana Cloud](https://grafana.com/docs/beyla/next/setup/kubernetes-helm-appolly/). ## Before you begin Before you install the chart, make sure you have the following: - A Kubernetes cluster whose nodes meet the [Beyla requirements and limitations](https://grafana.com/docs/beyla/next/introduction/requirements/) - Helm and `kubectl`, configured for the cluster - Permission to create cluster-scoped resources and privileged Pods - The Prometheus Operator, if you want the chart to create a ServiceMonitor ## Review the chart defaults With the default values, Beyla does the following: - Instruments applications in every namespace, except Kubernetes system namespaces and other namespaces that Beyla [excludes by default](https://grafana.com/docs/beyla/next/configure/service-discovery/#default-exclude-services-from-instrumentation) - Collects application-level metrics, not [network-level metrics](https://grafana.com/docs/beyla/next/network/) - Adds Kubernetes metadata labels to metrics, for example `k8s_namespace_name` and `k8s_pod_name` - Exports metrics in Prometheus format on port `9090` of each node, at the `/metrics` path The following chart values control what Beyla collects, where it runs, and what access its Pods get on each node: Expand table | Chart value | Default | Effect | |------------------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------| | `preset` | `application` | Instruments all namespaces and runs Beyla in the host process ID (PID) namespace. Set `network` to collect network metrics instead. | | `privileged` | `true` | Runs Beyla as a privileged container. | | `contextPropagation.enabled` | `true` | Gives the Pod host network access, the host `/sys/fs/cgroup` and `/sys/kernel/tracing` directories, and, when unprivileged, `NET_ADMIN`. | | `tolerations` | `[]` | Skips nodes with taints that the DaemonSet doesn’t tolerate, such as control-plane nodes. | The `contextPropagation.enabled` value grants the access that [network-level context propagation](https://grafana.com/docs/beyla/next/traces/#context-propagation-at-network-level) needs, but doesn’t turn it on in Beyla. If another process on the node uses port `9090`, change `config.data.prometheus_export.port`. To change these defaults, refer to [Customize the Beyla configuration](https://grafana.com/docs/beyla/next/setup/kubernetes-helm/#customize-the-beyla-configuration) and [Reduce Beyla privileges](https://grafana.com/docs/beyla/next/setup/kubernetes-helm/#reduce-beyla-privileges). ## Install the chart To install the chart with its default values, complete the following steps: 1. Add the Grafana Helm repository and update your local chart index: sh ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```sh helm repo add grafana https://grafana.github.io/helm-charts helm repo update ``` 2. Install the chart in the `beyla` namespace: sh ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```sh helm upgrade --install beyla grafana/beyla --namespace beyla --create-namespace ``` 3. Check that the Beyla Pods are running: sh ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```sh kubectl get pods --namespace beyla ``` ## Customize the Beyla configuration To change what Beyla instruments or where it sends data, override the chart values in a values file. Your values file has two kinds of settings: - Top-level chart values, such as `privileged` and `tolerations`, control the Kubernetes resources that the chart creates - Values under `config.data` form the Beyla configuration file, which the chart renders into a ConfigMap The `preset` chart value changes both the Kubernetes resources and the Beyla configuration. For the Beyla configuration options, refer to [Configure Beyla](https://grafana.com/docs/beyla/next/configure/). The chart also has values for resource names, Pod labels and annotations, the service account, RBAC rules, security contexts, scheduling, and resource limits. For the full list, refer to the [Beyla Helm chart README](https://github.com/grafana/beyla/blob/main/charts/beyla/README.md). Helm merges the values you supply with the chart defaults. It merges maps key by key and replaces lists. To remove a chart default, set it to `null`. For example, create a `helm-beyla.yml` file that instruments only the `demo` and `blog` namespaces and uses the `heuristic` [routes decorator](https://grafana.com/docs/beyla/next/configure/routes-decorator/): YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```yaml config: data: # Contents of the actual Beyla configuration file discovery: instrument: - k8s_namespace: demo - k8s_namespace: blog routes: unmatched: heuristic ``` If you set any `discovery` option, the chart doesn’t add its default `instrument` selector. Include an `instrument` selector, or Beyla exits at startup with a `missing application discovery section` error. Install or upgrade the release with the file: sh ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```sh helm upgrade --install beyla grafana/beyla --namespace beyla --create-namespace -f helm-beyla.yml ``` ## Reduce Beyla privileges To reduce the access that Beyla gets on each node, add one or both of the following chart values to your `helm-beyla.yml` file: YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```yaml privileged: false contextPropagation: enabled: false ``` The `privileged: false` value runs Beyla with a list of Linux capabilities instead of a privileged container. For the capabilities, refer to [Beyla security, permissions, and capabilities](https://grafana.com/docs/beyla/next/setup/security/). The chart still runs Beyla in the host PID namespace. The `contextPropagation.enabled: false` value removes the access that network-level context propagation needs. If you set `ebpf.context_propagation` under `config.data`, keep `contextPropagation.enabled: true`. The `network` preset still runs Beyla in the host network namespace. Apply the updated `helm-beyla.yml` file with the same `helm upgrade --install` command. ## Scrape metrics with the Prometheus Operator If you run the Prometheus Operator, the chart can create a Service and a ServiceMonitor for Beyla. The ServiceMonitor points Prometheus at the metrics endpoint that Beyla opens when `config.data.prometheus_export` is set. The default chart values set this section to port `9090` and path `/metrics`. If you remove the section, for example with `prometheus_export: null` under `config.data`, Beyla has no Prometheus endpoint and the chart doesn’t create a ServiceMonitor. Add the following to your `helm-beyla.yml` file: YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```yaml service: enabled: true serviceMonitor: enabled: true endpoint: honorLabels: true ``` The `honorLabels` setting keeps the `instance` and `job` labels that Beyla sets for each instrumented process. For more information, refer to [Prometheus exporter component](https://grafana.com/docs/beyla/next/configure/export-data/#prometheus-exporter-component). If your Prometheus selects ServiceMonitors by label, add that label with the chart value `serviceMonitor.additionalLabels`. Apply the updated `helm-beyla.yml` file with the same `helm upgrade --install` command. ## Pass OTLP credentials from a Kubernetes Secret Some OTLP endpoints, such as Grafana Cloud, require an authentication header. Pass it to Beyla in the `OTEL_EXPORTER_OTLP_HEADERS` environment variable. Store the header in a Kubernetes Secret, and reference the Secret from your Helm values. The `OTEL_EXPORTER_OTLP_ENDPOINT` variable sends both metrics and traces to the endpoint. Create a Secret in the namespace where Beyla runs: YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```yaml apiVersion: v1 kind: Secret metadata: name: grafana-secret namespace: beyla type: Opaque stringData: otlp-headers: "Authorization=Basic " ``` Add the endpoint to `env`, and reference the Secret from `envValueFrom` in your `helm-beyla.yml` file: YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```yaml env: OTEL_EXPORTER_OTLP_ENDPOINT: "" envValueFrom: OTEL_EXPORTER_OTLP_HEADERS: secretKeyRef: key: otlp-headers name: grafana-secret ``` Replace the following: - *``* : The Base64-encoded credentials for your OTLP endpoint. For Grafana Cloud, generate them from the **OpenTelemetry** tile of your stack. For the steps, refer to [Send data to the Grafana Cloud OTLP endpoint](https://grafana.com/docs/grafana-cloud/send-data/otlp/send-data-otlp/#manual-opentelemetry-setup-for-advanced-users). - *``* : The base URL of your OTLP endpoint. Beyla still exports Prometheus metrics after you add the OTLP endpoint. To export only through OTLP, set `prometheus_export: null` under `config.data`. Apply the updated `helm-beyla.yml` file with the same `helm upgrade --install` command. ## Use your own ConfigMap To manage the Beyla configuration file outside the chart, store it in a ConfigMap in the Beyla namespace. If you haven’t installed the chart yet, create the namespace first with `kubectl create namespace beyla`. Use the `beyla-config.yml` key, because Beyla reads its configuration from `/etc/beyla/config/beyla-config.yml`: sh ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```sh kubectl create configmap beyla-config --namespace beyla --from-file=beyla-config.yml= ``` Replace *``* with the path to your Beyla configuration file. Then set the chart value `config.name` to the ConfigMap name in your `helm-beyla.yml` file: YAML ![Copy code to clipboard](https://grafana.com/media/images/icons/icon-copy-small-2.svg) Copy ```yaml config: name: beyla-config ``` With `config.name` set, the chart doesn’t create its own ConfigMap or render `config.data` into one. The chart still reads `config.data.prometheus_export` to set the container port, the Service, and the ServiceMonitor. Keep that value consistent with the `prometheus_export` section of your file. The `preset` value doesn’t add its defaults to your file, so include a `discovery` or `network` section. The chart doesn’t restart the Beyla Pods when your ConfigMap changes. To restart them on the next upgrade, set the chart value `config.checksum` to a value that changes with your ConfigMap. ## Next steps - [Beyla Helm chart README](https://github.com/grafana/beyla/blob/main/charts/beyla/README.md) - [Configure Beyla](https://grafana.com/docs/beyla/next/configure/) - [Deploy Beyla in Kubernetes with Helm for Grafana Cloud](https://grafana.com/docs/beyla/next/setup/kubernetes-helm-appolly/)