Quarkus与OpenTelemetry本地Agent在Kubernetes中的配置方法

要让Quarkus应用和以DaemonSet部署在本地节点的OpenTelemetry Collector（Agent）配合工作，核心是让Quarkus Pod能访问到同一节点上的Agent实例，以下是具体配置步骤：

1. 确认OpenTelemetry Collector Agent的部署配置 #

首先要保证DaemonSet的Agent能被同节点的Quarkus Pod访问，常用两种方式：

• 启用HostNetwork：让Agent直接使用节点的网络命名空间，监听节点的默认端口（gRPC端口4317、HTTP端口4318）。DaemonSet配置示例：

  apiVersion: apps/v1
  kind: DaemonSet
  metadata:
    name: otel-agent
  spec:
    selector:
      matchLabels:
        app: otel-agent
    template:
      metadata:
        labels:
          app: otel-agent
      spec:
        hostNetwork: true
        containers:
        - name: otel-agent
          image: otel/opentelemetry-collector-contrib:latest
          args:
          - --config=/etc/otel-agent-config.yaml
          ports:
          - containerPort: 4317 # gRPC OTLP端口
          - containerPort: 4318 # HTTP OTLP端口
          volumeMounts:
          - name: config
            mountPath: /etc/otel-agent-config.yaml
            subPath: otel-agent-config.yaml
        volumes:
        - name: config
          configMap:
            name: otel-agent-config
  

• 使用HostPort：如果不想让Agent占用节点网络命名空间，可以给Agent容器配置hostPort，将容器端口映射到节点端口：

  containers:
  - name: otel-agent
    # ... 其他配置
    ports:
    - name: otlp-grpc
      containerPort: 4317
      hostPort: 4317
      protocol: TCP
    - name: otlp-http
      containerPort: 4318
      hostPort: 4318
      protocol: TCP
  

2. 配置Quarkus访问本地节点的Agent #

Quarkus需要知道当前节点的IP，才能指向同节点的Agent，这里用Kubernetes的Downward API注入节点IP到环境变量，再用这个变量配置OTLP端点：

步骤2.1：在Quarkus Deployment中注入节点IP #

在Quarkus的Deployment配置里添加环境变量，通过fieldRef获取当前节点的IP：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: quarkus-app
spec:
  # ... 其他配置
  template:
    spec:
      containers:
      - name: quarkus-app
        image: your-quarkus-image:latest
        env:
        - name: NODE_IP
          valueFrom:
            fieldRef:
              fieldPath: status.hostIP
        # ... 其他容器配置

步骤2.2：设置Quarkus的OTLP端点 #

有两种方式配置Quarkus的OTLP端点，选一种即可：

方式A：通过应用配置文件

在Quarkus的application.properties或application.yaml中引用注入的环境变量：

• properties格式：

  # 若使用gRPC协议（默认）
  quarkus.opentelemetry.tracer.exporter.otlp.endpoint=http://${NODE_IP}:4317
  # 若使用HTTP/protobuf协议
  quarkus.opentelemetry.tracer.exporter.otlp.endpoint=http://${NODE_IP}:4318/v1/traces
  quarkus.opentelemetry.tracer.exporter.otlp.protocol=http/protobuf
  

• yaml格式：

  quarkus:
    opentelemetry:
      tracer:
        exporter:
          otlp:
            # gRPC协议（默认）
            endpoint: "http://${NODE_IP}:4317"
            # HTTP/protobuf协议的配置（注释掉上面的gRPC配置后启用）
            # endpoint: "http://${NODE_IP}:4318/v1/traces"
            # protocol: "http/protobuf"
  

方式B：通过环境变量直接覆盖（推荐）

Quarkus支持将大写+下划线命名的环境变量映射到配置属性，直接在Deployment的环境变量中设置，无需修改应用配置文件：

env:
# ... 其他环境变量
- name: QUARKUS_OPENTELEMETRY_TRACER_EXPORTER_OTLP_ENDPOINT
  value: "http://$(NODE_IP):4317"
# 如果用HTTP协议，加上下面的配置
# - name: QUARKUS_OPENTELEMETRY_TRACER_EXPORTER_OTLP_PROTOCOL
#   value: "http/protobuf"
# - name: QUARKUS_OPENTELEMETRY_TRACER_EXPORTER_OTLP_ENDPOINT
#   value: "http://$(NODE_IP):4318/v1/traces"

3. 验证配置 #

部署完成后，进入Quarkus Pod，检查环境变量和连接性：

# 进入Pod
kubectl exec -it <quarkus-pod-name> -- sh
# 查看NODE_IP变量是否正确注入
echo $NODE_IP
# 检查与Agent端口的连通性（以gRPC端口为例）
curl -v http://$NODE_IP:4317

内容的提问来源于stack exchange，提问作者Željko Trogrlić