菜单
文档breadcrumb arrow Beylabreadcrumb arrow 快速入门breadcrumb arrow Kubernetes 快速入门
Grafana Cloud

Beyla 和 Kubernetes 快速入门

Kubernetes 已完全集成到 Beyla 的运行模式中。

一方面,指标和追踪可以利用运行自动插桩服务的 Kubernetes 实体的元数据进行装饰。

另一方面,DaemonSet 已成为 Beyla 首选的部署模式:得益于新的服务选择器的多功能性,用户可以精确定义哪些服务需要插桩,哪些不需要。Beyla 的单个实例将能够插桩单个 Kubernetes 节点中选定的服务组。

Beyla 服务选择器

服务选择器是一组属性,允许 Beyla 查询哪些进程需要进行插桩。

当 Beyla 作为常规操作系统进程部署以插桩其他进程时,唯一的服务选择器是插桩进程应监听的网络端口(可以通过 `BEYLA_OPEN_PORT` 环境变量指定),或者是一个用于匹配要插桩进程的可执行文件名的正则表达式(`BEYLA_EXECUTABLE_NAME` 环境变量)。

要选择多个进程组,Beyla YAML 配置文件格式提供了 `discovery.services` 部分,该部分接受多个选择器组

yaml
discovery:
  services:
    # Instrument any process using the ports from 8080 to 8089
    - open_ports: 8080-8089
    # Instrument any process whose executable contains "http"
    - exe_path: "http"
    # Instrument any process with an executable containing "nginx"
    # and using the port 443 (both conditions must be fulfilled)
    - open_ports: 443
      exe_path: "nginx"

上述标准对于 Kubernetes Pod 不够充分,因为 Pod 中的端口是临时的且内部的。此外,Pod 是一个抽象层,应该隐藏其可执行文件名称等细节。因此,Beyla v1.2 引入了新的 Kubernetes 服务选择标准。它们都接受 Go RE2 语法正则表达式 作为值

  • k8s_namespace: 仅插桩命名空间与提供的正则表达式匹配的应用程序。
  • k8s_deployment_name: 仅插桩名称与提供的正则表达式匹配的 Deployment 中的 Pod。
  • k8s_replicaset_name: 仅插桩名称与提供的正则表达式匹配的 ReplicaSet 中的 Pod。
  • k8s_pod_name: 仅插桩名称与提供的正则表达式匹配的 Pod。

示例场景

1. 部署可插桩的测试服务

您可以插桩 Kubernetes 集群中的任何 HTTP 或 HTTPS 服务。如果愿意,可以先尝试插桩此示例中提供的虚拟服务。

以下 Kubernetes 示例文件包含两个 Apache HTTP 服务器:一个模拟公司**网站**,另一个模拟**文档**站点(`docs`)。请忽略这两个服务器在请求根目录时仅返回“It Works!”字符串,而在请求任何其他路径时返回 404 错误的事实。

将以下内容复制到文件(例如,`sampleapps.yml`)中,并使用命令 `kubectl apply -f sampleapps.yml` 进行部署。

yaml
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

要测试它们是否正在运行,请打开两个终端会话,并在不同的会话中运行以下命令中的一个:

# Redirect website to local port 8080
kubectl port-forward services/website 8080:80

# Redirect docs site to local port 8081
kubectl port-forward services/docs 8081:80

从您的计算机上,每个对 `https://:8080` 的请求将是针对公司网站的假设请求,而每个对 `https://:8081` 的请求将是针对文档网站的假设请求。

2. 创建 `beyla` 命名空间

在配置和部署 Beyla 之前,让我们创建一个 `beyla` 命名空间。我们将把所有与之相关的权限、配置和部署都集中到这里。

kubectl create namespace beyla

3. 获取 Grafana Cloud 凭据

Beyla 可以将指标和追踪导出到任何 OpenTelemetry 端点,也可以将指标作为 Prometheus 端点公开。但是,我们建议使用 Grafana Cloud 中的 OpenTelemetry 端点。您可以在 Grafana 网站上获取免费的 Grafana Cloud 账户

在 Grafana Cloud 门户中,找到**OpenTelemetry** 方框并单击**配置**。

OpenTelemetry Grafana Cloud portal

在**密码 / API 令牌**下单击**立即生成**,然后按照说明创建默认 API 令牌。

**环境变量**将填充一组标准的 OpenTelemetry 环境变量,这些变量将提供 Beyla 的连接端点和凭据信息。

OTLP connection headers

从**环境变量**部分,复制 OTEL_EXPORTER_OTLP_ENDPOINTOTEL_EXPORTER_OTLP_HEADERS 的值,并从中创建一个新的 Secret。例如,创建以下 Secret 文件并应用它

yaml
apiVersion: v1
kind: Secret
metadata:
  namespace: beyla
  name: grafana-credentials
type: Opaque
stringData:
  otlp-endpoint: "https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
  otlp-headers: "Authorization=Basic ...rest of the secret header value..."

4. 配置并运行 Beyla

接下来,您需要为 Beyla 提供权限,以观察和检查 Beyla 发现机制所需的各种 Kubernetes 资源的元数据。您必须创建以下 YAML 文件并应用它

yaml
apiVersion: v1
kind: ServiceAccount
metadata:
  namespace: beyla
  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: beyla
roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: beyla

现在,通过创建以下 Kubernetes 实体来部署 Beyla

  • 一个存储 beyla-config.yml Beyla 配置文件(定义服务发现标准)的 ConfigMap。为了验证 Beyla 即使在运行相同的镜像和可执行文件时也能按服务实例进行区分,Beyla 已配置为**仅**选择 docs Apache Web 服务器。
  • 一个提供 Beyla Pod 及其配置的 Beyla DaemonSet
    • 根据 BEYLA_CONFIG_PATH 环境变量的指定,从 ConfigMap 加载 beyla-config.yml 文件。
    • 引用 grafana-secrets 中用于端点和凭据的值。
    • 使用 beyla ServiceAccount 获取所有权限。

复制并部署以下 YAML 文件

yaml
apiVersion: v1
kind: ConfigMap
metadata:
  namespace: beyla
  name: beyla-config
data:
  beyla-config.yml: |
    # this is required to enable kubernetes discovery and metadata
    attributes:
      kubernetes:
        enable: true
    # this will provide automatic routes report while minimizing cardinality
    routes:
      unmatched: heuristic
    # let's instrument only the docs server
    discovery:
      services:
        - k8s_deployment_name: "^docs$"
        # uncomment the following line to also instrument the website server
        # - k8s_deployment_name: "^website$"
---
apiVersion: apps/v1
kind: DaemonSet
metadata:
  namespace: beyla
  name: beyla
spec:
  selector:
    matchLabels:
      instrumentation: beyla
  template:
    metadata:
      labels:
        instrumentation: beyla
    spec:
      serviceAccountName: beyla
      hostPID: true # mandatory!
      containers:
        - name: beyla
          image: grafana/beyla:latest
          imagePullPolicy: IfNotPresent
          securityContext:
            privileged: true # mandatory!
            readOnlyRootFilesystem: true
          volumeMounts:
            - mountPath: /config
              name: beyla-config
            - mountPath: /var/run/beyla
              name: var-run-beyla
          env:
            - name: BEYLA_CONFIG_PATH
              value: "/config/beyla-config.yml"
            - name: OTEL_EXPORTER_OTLP_ENDPOINT
              valueFrom:
                secretKeyRef:
                  name: grafana-credentials
                  key: otlp-endpoint
            - name: OTEL_EXPORTER_OTLP_HEADERS
              valueFrom:
                secretKeyRef:
                  name: grafana-credentials
                  key: otlp-headers
      volumes:
        - name: beyla-config
          configMap:
            name: beyla-config
        - name: var-run-beyla
          emptyDir: {}

另请注意

  • 要在 DaemonSet 模式下运行,Beyla 需要访问节点中的所有进程。因此,Beyla Pod 需要以 hostPID: true 运行。
  • Beyla 容器需要以 privileged: true 运行,因为它需要执行特权操作,例如加载 BPF 程序和创建 BPF 映射。要将 Beyla 作为 unprivileged 容器运行(即不带 privileged: true 选项),请访问部署非特权 Beyla 指南。

5. 测试您的插桩服务并在 Grafana 中查看结果

在前一步骤的 kubectl port-forward 命令仍在运行的情况下,测试两个 Web 服务器实例。例如

curl https://:8080
curl https://:8080/foo
curl https://:8081
curl https://:8081/foo

有些请求会返回 404 错误,但这没关系,因为它们也已被插桩。

现在,转到 Grafana Cloud 中的实例,并在左侧面板的**探索**部分,选择用于追踪的数据源(通常命名为 grafanacloud-<您的用户名>-traces)。

Select the traces data source

要搜索所有追踪,请在查询栏中选择**搜索**框,保持表单为空,然后单击**运行查询**

Searching for all the traces in the system

这将显示 docs 实例(端口 8081)的追踪。您可能会看到来自您自己服务的追踪,但不应看到来自 website 服务的追踪,因为它没有被 Beyla 插桩。

Grafana Cloud list of traces

在追踪详细信息中,追踪的资源属性通过运行插桩服务的 Kubernetes Pod 的元数据进行装饰

Details of the trace