APM Agent Setup with Kubernetes

Visual Guide

Prerequisites

• Kubernetes 1.18 or later
• Helm 3.x installed and configured against your cluster
• A Kloudfuse API key with trace ingestion scope (see Administration → API Keys)
• Outbound HTTPS access from the cluster to the Kloudfuse platform
• At least one application instrumented with an OpenTelemetry SDK (see Java, Python, or Go)

Supported Environments

kf-agent runs on any conformant Kubernetes distribution:

Step 1: Install kf-agent

Add the Helm Repository

helm repo add kloudfuse https://helm.kloudfuse.com
helm repo update

Deploy the Agent

Install kf-agent into a dedicated namespace. Replace <your-kloudfuse-api-key> with your API key and <my-cluster> with a name that identifies this cluster in the Kloudfuse UI:

helm install kf-agent kloudfuse/kf-agent \
  --namespace kloudfuse \
  --create-namespace \
  --set clusterName=my-cluster \
  --set apiKey=<your-kloudfuse-api-key>

To avoid embedding the API key in shell history or CI logs, pass it from a Kubernetes Secret:

kubectl create secret generic kloudfuse-api-key \
  --namespace kloudfuse \
  --from-literal=value=<your-kloudfuse-api-key>

helm install kf-agent kloudfuse/kf-agent \
  --namespace kloudfuse \
  --create-namespace \
  --set clusterName=my-cluster \
  --set apiKeySecretName=kloudfuse-api-key

Verify the Agent is Running

kubectl get pods -n kloudfuse -l app=kf-agent
kubectl logs -n kloudfuse -l app=kf-agent --tail=50

The agent is ready when the pod is in Running state and logs show Listening on :4317 (gRPC) and Listening on :4318 (HTTP).

Key Helm Values

Network Requirements

Application pods must be able to reach kf-agent on two ports:

If your cluster enforces NetworkPolicy, add an egress rule allowing application pods to reach kf-agent on both ports:

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: allow-kf-agent-egress
  namespace: <app-namespace>
spec:
  podSelector: {}
  policyTypes:
    - Egress
  egress:
    - to:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: kloudfuse
      ports:
        - port: 4317
          protocol: TCP
        - port: 4318
          protocol: TCP

Step 2: Instrument Your Applications

Set these two environment variables on every application pod to point it at kf-agent:

OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://kf-agent:4317

Java

Use JAVA_TOOL_OPTIONS to attach the OpenTelemetry Java agent without modifying the container entrypoint:

env:
  - name: JAVA_TOOL_OPTIONS
    value: "-javaagent:/agent/opentelemetry-javaagent.jar"
  - name: OTEL_SERVICE_NAME
    value: my-java-service
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://kf-agent:4317
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: service.namespace=payments,deployment.environment.name=production

Python

Run your application through the opentelemetry-instrument wrapper and set the endpoint via environment variable:

opentelemetry-instrument \
  --traces_exporter otlp \
  --exporter_otlp_endpoint http://kf-agent:4317 \
  --service_name my-python-service \
  python app.py

Or configure entirely via environment variables in the pod spec:

env:
  - name: OTEL_SERVICE_NAME
    value: my-python-service
  - name: OTEL_EXPORTER_OTLP_ENDPOINT
    value: http://kf-agent:4317
  - name: OTEL_TRACES_EXPORTER
    value: otlp

Go

Configure the otlptracegrpc exporter to point at kf-agent on port 4317:

import "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"

exporter, err := otlptracegrpc.New(ctx,
    otlptracegrpc.WithEndpoint("kf-agent:4317"),
    otlptracegrpc.WithInsecure(),
)

Or read the endpoint from an environment variable so it can be set in the pod spec without changing code:

# Pod spec env
OTEL_SERVICE_NAME=my-go-service
OTEL_EXPORTER_OTLP_ENDPOINT=http://kf-agent:4317

// Use otlptracegrpc.WithEndpointURL to read OTEL_EXPORTER_OTLP_ENDPOINT automatically
exporter, err := otlptracegrpc.New(ctx)

Step 3: Verify Trace Collection

1. Open Kloudfuse UI → APM → Trace Explorer
2. In the search bar, filter by service.name = <your-service-name>
3. Send a test request to your application — a trace should appear within a few seconds
4. Click the trace to verify span names, attributes, and parent-child relationships
5. Open APM → Service Map to confirm inter-service dependencies are visible

If traces do not appear, see Common Setup Issues for diagnostic steps.