How to setup Astra Traffic Collector in Kubernetes

Last updated: August 18, 2025

Overview

The Astra Traffic Collector (ATC) is a containerized service that uses the OpenTelemetry (OTel) collector to capture and forward network traffic traces emitted by integrated sensors. This document explains how to install, configure, customize, upgrade, and troubleshoot the ATC in Kubernetes environments such as Amazon EKS, Google GKE, or Azure AKE.

Prerequisites

Before proceeding, ensure the following:

kubectl is installed and configured to communicate with your Kubernetes cluster.
Helm (v3 or higher) is installed.
Astra Traffic Collector is available and reachable.
📄 How to Create Collector Integration for API Observability

Quick Installation

Step 1 — Create a Working Directory

mkdir -p /opt/astra-traffic-collector && cd /opt/astra-traffic-collector

Step 2 — Create the Namespace

Create astra-collector namespace for traffic collector installation by running

kubectl create ns astra-collector

Step 3 — Add the Astra Helm Repository

Add astra traffic collector helm repository

helm repo add getastra https://raw.githubusercontent.com/getastra/obs-deployments/gh-pages/
helm repo update

Step 4 — Create `values.yaml`

This file contains your ATC configuration and authentication credentials.

Replace the following values in the values.yaml

Variable	Description	Example Value
`collectorId`	Collector ID aka integration ID generated when you create ATC in Astra Dashboard	`12345678-1234-4abc-9def-987654321000`
`clientId`	Secret displayed at the end of creation of ATC integration	`12345678-1234-4abc-9def-987654321000`
`clientSecret`	Secret displayed at the end of creation of ATC integration	`12345678-1234-4abc-9def-987654321000`

secret:
      name: astra-collector-secrets
      collectorId: 12345678-1234-4abc-9def-987654321000
      clientId: 12345678-1234-4abc-9def-987654321000
      clientSecret: 12345678-1234-4abc-9def-987654321000
      tokenUrl: https://auth.getastra.com/realms/astra_api_scanner/protocol/openid-connect/token
      remoteAddrIdentifierHeader: x-forwarded-for

volumes:
  - configMap:
      defaultMode: 444
      name: astra-collector-custom-config
    name: custom-config
  
volumeMounts:
  - name: collector-message
    mountPath: /var/lib/otelcol/file_storage
  - name: custom-config
    mountPath: /etc/otelcol-contrib/config_custom.yaml
    subPath: config_custom.yaml

Step 5 — Create `config_custom.yaml`

Create a file called as config_custom.yaml and paste the following content. This is the default template for custom configuration which is useful for customized redaction, templatizing and filtering

processors:

  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/filterprocessor
  filter/custom:
      error_mode: ignore
      traces:
        span:
          ## allowing traces based on hostname regex pattern. Following will drop all traces originated from host other than: localhost*
          #- IsMatch(attributes["url.host"], "localhost*") == false
          ## excluding traces based on hostname regex pattern. Following will drop all traces originated from host: localhost*
          #- IsMatch(attributes["url.host"], "localhost*")
          ## excluding traces based on template regex pattern. Following will drop all traces having url_template: _wdt*
          #- IsMatch(attributes["url.template"], "_wdt*")
           - ConvertCase(attributes["http.method"], "upper") == "OPTIONS"
  
  # https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/transformprocessor
  transform/custom:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          ## Templatize url path regex pattern by keyword: "slug". Following will templatize the url Path: /api/v1/products/details/prod-12r4ty   ->  /api/v1/products/details/{{product_id}}
          #- replace_pattern(attributes["url.template"], "prod-*", "{{product_id}}")
          ## Redact MasterCard credit card number
          - replace_all_patterns(attributes, "value", "^5[1-5][0-9]{14}$", "{{CreditCard}}")

service:
    pipelines:
      traces:
        exporters: [debug, otlp]

Step 6 — Create ConfigMap from `config_custom.yaml`

kubectl create configmap astra-collector-custom-config --from-file=./config_custom.yaml -n astra-collector

Step 7 — Install the Helm Chart

helm upgrade --install traffic-collector getastra/traffic-collector-chart --namespace astra-collector --debug --values values.yaml

Step 8 — Verify Deployment

kubectl get pods -n astra-collector

You should see a running pod named astra-traffic-collector-0.

Customizing the behavior of Astra Traffic Collector

Step 1 — Edit Custom Configuration

Modify /opt/astra-traffic-collector/config_custom.yaml to add filtering, redaction, or URL templating.

📄 How to customize the Astra Traffic collector

Step 2 - Apply Updated ConfigMap

kubectl create configmap astra-collector-custom-config --from-file=/opt/astra-traffic-collector/config_custom.yaml -n astra-collector --dry-run=client -o yaml | kubectl apply -f -
kubectl delete po astra-traffic-collector -n astra-collector

Upgrade

Step 1 — Update the Helm repository:

helm repo update

Step 2 — Upgrade to the latest chart:

helm upgrade --install traffic-collector getastra/traffic-collector-chart --namespace astra-collector --debug --values values.yaml

Troubleshooting

Issue 1 — Unable to Send Traces

Symptoms

No new entries in the inventory.
Logs show authentication errors:
📄 Verifying Traces in Astra Traffic Collector

error	exporterhelper/queue_sender.go:92	Exporting failed... rpc error: code = Unauthenticated ...

Cause
Invalid clientId or clientSecret in values.yaml.

Solution

Update values.yaml with correct credentials.
Redeploy:

helm upgrade --install traffic-collector getastra/traffic-collector-chart --namespace astra-collector --debug --values values.yaml

Issue 2 — No Inventory Updates but No Errors