Metrics

Collect container metrics from Kubernetes with cased-agent

Cased Telemetry collects infrastructure metrics from your Kubernetes cluster using cased-agent, a lightweight DaemonSet that captures container CPU, memory, network, and events.

Features

Container Metrics - CPU, memory, network I/O for every container
Kubernetes Events - Pod restarts, OOM kills, scheduling events
Node Metrics - Host-level CPU and memory utilization
eBPF HTTP Tracing - Kernel-level HTTP request/response capture without application changes
Low Overhead - Minimal resource usage (10m CPU, 64Mi memory)

Prerequisites

Kubernetes 1.21+
kubectl configured with cluster access
Cased API key (from organization settings)

Installation

Helm (Recommended)

helm install cased-agent oci://ghcr.io/cased/charts/cased-agent \
  --namespace cased-system \
  --create-namespace \
  --set apiKey=YOUR_CASED_API_KEY \
  --set clusterId=prod

kubectl

For a simpler installation without Helm:

# Apply the manifest (creates namespace and RBAC)
kubectl apply -f https://raw.githubusercontent.com/cased/cased-agent/main/deploy/manifests/install.yaml

# Create the API key secret
kubectl -n cased-system create secret generic cased-agent \
  --from-literal=api-key="YOUR_CASED_API_KEY"

# Set your cluster ID
kubectl -n cased-system set env daemonset/cased-agent CASED_CLUSTER_ID=prod

3. Verify deployment

# Check DaemonSet status
kubectl -n cased-system get daemonset cased-agent

# View agent logs
kubectl -n cased-system logs -l app=cased-agent --tail=50

Configuration

Environment Variables

Variable	Required	Default	Description
`CASED_API_KEY`	Yes	-	Your organization API key
`CASED_API_ENDPOINT`	No	`https://app.cased.com`	Cased API endpoint
`CASED_CLUSTER_ID`	No	`default`	Identifier for this cluster
`CASED_ORG_ID`	No	-	Organization ID (auto-detected from API key)
`ENABLE_EBPF`	No	`true`*	Enable eBPF HTTP tracing (requires privileged mode)

*Default in provided manifest. Binary defaults to false if not set.

Command-line Arguments

Argument	Default	Description
`--interval`	`15s`	Metrics collection interval
`--batch-size`	`100`	Number of metrics per API request

Resource Limits

The default resource configuration is designed for minimal overhead:

resources:
  requests:
    cpu: 10m
    memory: 64Mi
  limits:
    cpu: 200m
    memory: 256Mi

Adjust based on cluster size. For large clusters (100+ nodes), consider:

resources:
  requests:
    cpu: 50m
    memory: 128Mi
  limits:
    cpu: 500m
    memory: 512Mi

Metrics Collected

Container Metrics

Metric	Type	Description
`cpu_usage_cores`	gauge	Current CPU usage in cores
`cpu_throttled_seconds`	counter	Time CPU was throttled
`memory_usage_bytes`	gauge	Current memory usage
`memory_limit_bytes`	gauge	Memory limit from cgroup
`network_rx_bytes`	counter	Network bytes received
`network_tx_bytes`	counter	Network bytes transmitted

Labels

Each metric includes labels for filtering:

cluster - Cluster ID from configuration
namespace - Kubernetes namespace
pod - Pod name
container - Container name
node - Node hostname

eBPF HTTP Tracing

The cased-agent uses eBPF (Extended Berkeley Packet Filter) to capture HTTP requests and responses at the kernel level. This provides:

Zero-instrumentation observability - No code changes or sidecars required
Complete visibility - Captures all HTTP traffic, including internal service-to-service calls
Low overhead - eBPF runs in kernel space with minimal performance impact
Cross-kernel portability - Uses CO:RE (Compile Once - Run Everywhere) for compatibility across kernel versions

How eBPF Works

eBPF programs attach to kernel syscalls (sendto, recvfrom) to intercept network data. The agent parses HTTP method, path, and status code from the raw bytes, then sends this data to Cased for correlation with errors and metrics.

┌─────────────────────────────────────────────────────────────┐
│  Kernel Space                                               │
│  ┌─────────────┐     ┌─────────────┐     ┌───────────────┐ │
│  │  sendto()   │────>│ eBPF probe  │────>│  Ring buffer  │ │
│  │  recvfrom() │     │ (http_trace)│     │               │ │
│  └─────────────┘     └─────────────┘     └───────┬───────┘ │
└─────────────────────────────────────────────────┬─────────┘
                                                  │
┌─────────────────────────────────────────────────▼─────────┐
│  User Space                                               │
│  ┌─────────────────────────────────────────────────────┐  │
│  │  cased-agent: parse HTTP, enrich with K8s labels,   │  │
│  │               send to Cased API                     │  │
│  └─────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────┘

Disabling eBPF

If you don’t need HTTP tracing or can’t run privileged containers, disable eBPF:

env:
  - name: ENABLE_EBPF
    value: "false"

With eBPF disabled, the agent still collects container metrics and Kubernetes events, but won’t capture HTTP traffic.

Security

The cased-agent requires elevated permissions to collect comprehensive telemetry. This section explains what’s required and why.

With eBPF Enabled (Default)

When eBPF HTTP tracing is enabled, the agent requires privileged mode:

securityContext:
  privileged: true
  capabilities:
    add:
      - SYS_PTRACE   # Read process info from /proc
      - SYS_ADMIN    # Load eBPF programs into kernel
      - NET_ADMIN    # Attach to network syscalls

Why privileged mode?

eBPF programs run in kernel space and require CAP_SYS_ADMIN to load. While Kubernetes supports granular capabilities, eBPF verifier and BTF (BPF Type Format) access typically require privileged mode for reliable operation across different kernel versions and cloud providers.

This is the same approach used by other eBPF-based observability tools like Groundcover, Cilium, and Pixie.

Additional mounts required:

/sys/kernel/debug (read-only) - Access BTF type information for CO:RE

With eBPF Disabled

When eBPF is disabled, the agent requires minimal permissions:

hostPID: true - Access to /proc for container metrics
SYS_PTRACE - Read process information from /proc
ClusterRole - Read-only access to pods, nodes, namespaces, events

RBAC Permissions

The agent’s ClusterRole has read-only access:

rules:
  - apiGroups: [""]
    resources: ["pods", "nodes", "namespaces", "events"]
    verbs: ["get", "list", "watch"]
  - apiGroups: ["metrics.k8s.io"]
    resources: ["pods", "nodes"]
    verbs: ["get", "list"]

Security Best Practices

Dedicated namespace - Deploy in cased-system to isolate from application workloads
Network policies - Restrict egress to only Cased API endpoints
Image scanning - The cased-agent image is regularly scanned for vulnerabilities
Audit logging - Enable Kubernetes audit logs to monitor privileged container activity
Pod Security Standards - If using PSS, you’ll need to exempt cased-system namespace from restricted policies

Troubleshooting

Agent not starting

Check pod status:

kubectl -n cased-system describe pod -l app=cased-agent

Common issues:

Missing secret: Create the cased-agent-config secret
Image pull error: Verify ECR access or use public image

No metrics appearing

Verify the agent is healthy:

kubectl -n cased-system logs -l app=cased-agent | grep -i error

Check API connectivity:

kubectl -n cased-system exec -it $(kubectl -n cased-system get pod -l app=cased-agent -o jsonpath='{.items[0].metadata.name}') -- wget -qO- https://app.cased.com/health

Verify API key is valid in Cased dashboard

High resource usage

If the agent uses more resources than expected:

Increase --interval to collect less frequently
Reduce --batch-size to send smaller payloads
Check for network issues causing retries

eBPF not loading

If you see “eBPF HTTP tracing disabled” in logs when it should be enabled:

Check privileged mode:

kubectl -n cased-system get pod -l app=cased-agent -o jsonpath='{.items[0].spec.containers[0].securityContext.privileged}'
# Should return: true

Verify kernel supports BTF:

kubectl -n cased-system exec -it $(kubectl -n cased-system get pod -l app=cased-agent -o jsonpath='{.items[0].metadata.name}') -- ls /sys/kernel/btf/vmlinux

Most modern kernels (5.4+) include BTF. If missing, the eBPF program can’t load with CO:RE.

Check debugfs is mounted:

kubectl -n cased-system exec -it $(kubectl -n cased-system get pod -l app=cased-agent -o jsonpath='{.items[0].metadata.name}') -- ls /sys/kernel/debug

Review agent logs for eBPF errors:

kubectl -n cased-system logs -l app=cased-agent | grep -i ebpf

eBPF permission denied

If you see “operation not permitted” errors:

Ensure privileged: true is set in the DaemonSet
Verify capabilities include SYS_ADMIN and NET_ADMIN
Check if Pod Security Policies/Standards are blocking privileged containers

To run without eBPF, set ENABLE_EBPF=false (metrics collection still works).

Uninstalling

kubectl delete -f install.yaml