Traversal Processor

The Traversal Processor is a high-performance telemetry ingestion and processing service that receives telemetry data from your infrastructure, and extracts and indexes structured data into the Traversal platform. Today, the Traversal Processor accepts logs data only, via HTTP endpoints and OpenTelemetry Protocol (OTLP) over both gRPC and HTTP. The Traversal Processor ships as a single container image can be deployed via a Helm chart and a Values file provided by Traversal. The Traversal Processor is designed to operate as a horizontally scalable service, and does not require coordination across instances.

If your environment restricts outbound traffic, see Network allowlisting for the IPs to allow before deploying.

Deployment

Use Helm on K8s

A Helm-based Kubernetes deployment is composed of three artifacts. While the chart is published openly, the image requires authentication. The values file also requires authentication, since it carries credentials issued for your deployment.

Container image

Public, built and published by Traversal.

Helm chart

Public OCI artifact. Generic across all deployments.

Values file

Per-deployment. Pulled with a Traversal-issued token.

Container image

Traversal builds and publishes the Traversal Processor image to the traversalext/traversal-processor repository on Docker Hub. The image is private, so you will have to authenticate with Docker Hub.

The processor image is a multi-platform image with support for both x86 and ARM (linux/amd64 and linux/arm64).

If your security policy requires it, you can mirror the published image into an internal registry and point the chart at it by overriding image.repository in your values. If the mirror requires authentication, attach the pull credentials to the deployment’s service account (imagePullSecrets) in your cluster.

Helm chart

The Helm chart is published as a public OCI artifact at oci://registry-1.docker.io/traversalext/traversal-processor-charts. The chart is generic across all deployments — it contains no customer-specific configuration — so you can inspect or vendor it freely with standard Helm tooling:

helm pull oci://registry-1.docker.io/traversalext/traversal-processor-charts \
  --version <version> --untar

The pulled chart includes a values.yaml template that documents every supported field and indicates which ones are required.See the chart changelog for what’s new in each version and any upgrade notes.

Required values

The chart and Traversal Processor together require the following fields, all under the traversalProcessor key. Traversal pre-populates all of them in the values file it builds for you, so you don’t typically need to set them manually:

Field	What it is
`account.id`	Your account UUID, used to associate ingested logs with your account.
`traversalIngestion.endpoint`	The Traversal ingest endpoint the processor streams processed log clusters to.
`mtls.certBase64`	Base64-encoded PEM client certificate the processor presents when authenticating to Traversal.
`mtls.keyBase64`	Base64-encoded PEM private key for the client certificate above.

The mTLS material can be supplied three ways — provide exactly one:

Inline base64: mtls.certBase64 and mtls.keyBase64 (the chart renders a Kubernetes Secret).
Existing Secret: mtls.existingSecret, the name of a Secret you manage with keys cert.pem and key.pem (for example, one produced by cert-manager).
Files: mtls.certFile and mtls.keyFile, PEM paths already present in the container (mounted via extraVolumes/extraVolumeMounts, a CSI driver, an init container, etc.).

The telemetry forwarder reuses this identity, whichever form you choose.

All other fields — sizing, field extraction, redaction, replica count, TLS, scheduling — are optional and have sensible defaults.

Sizing and throughput

A single value, traversalProcessor.size, selects a validated resource-and-tuning preset — pick the tier that matches your log volume and the chart configures CPU, memory, and internal ingest tuning for you.

Size	Resources (per pod)	Recommended node	Guideline throughput (per pod)
`normal`	~3 vCPU / 4 GiB	AWS `c8g.xlarge`	~40,000 records/s · ~150 MB/s
`large`	~7 vCPU / 8 GiB	AWS `c8g.2xlarge`	~80,000 records/s · ~300 MB/s

Scale up by moving normal → large; scale out by raising replicaCount (the processor is horizontally scalable with no cross-instance coordination). If your cluster mixes node families, pin pods to the recommended instance type with nodeSelector.

Throughput figures are guidance, not guarantees. They were measured with roughly 4 KB average log records, ~40% cluster compression, and redaction disabled. Actual throughput depends on record size, field cardinality, redaction, and downstream latency — size for headroom and validate against your own traffic.

Telemetry forwarding

The processor reports its own operational telemetry — metrics, traces, and logs — to Traversal over OTLP. It is how Traversal supports your deployment, and is separate from the log data you send the processor to ingest.By default the chart adds a second container to the processor pod: a forwarder that buffers this telemetry and retries delivery, so a brief interruption reaching Traversal does not lose it. It authenticates with the processor’s mtls identity and needs no credentials of its own.

Field	Default	What it is
`observability.otel.sidecar.enabled`	`true`	Runs the forwarder. Set to `false` to export directly from the processor, leaving one container in the pod.
`observability.otel.sidecar.image`	`traversalext/alloy`	Forwarder image. Override `repository` to pull from an internal mirror.
`observability.otel.sidecar.resources`	50m CPU, 128–256Mi memory	Resource requests and limits for the forwarder container.
`observability.otel.forwardProxy`	none	Forward proxy for telemetry egress. Set this where your network reaches Traversal only through a proxy.

The observability.otel endpoints default to Traversal’s telemetry ingest. Override all three to send to a collector you operate instead.

Disabling telemetry

Setting observability.otel.enabled: false stops all telemetry export and removes the forwarder.

Disabling telemetry is highly discouraged. Telemetry is Traversal’s only view into a processor running in your network, so without it Traversal can provide only limited support.

Values file

The values file holds your deployment-specific configuration: your account details, Traversal API endpoint, mTLS material, and any deployment-specific tuning or telemetry destinations.Because it may embed private key material, the values file is not published publicly. Instead, Traversal builds it for you and packages it as an OCI artifact in a private Docker Hub namespace, alongside the chart.

Receive credentials from Traversal

Through a secure channel, Traversal shares with you a Docker Hub access token, scoped read-only to your deployment’s namespace, and the artifact reference for your values file (for example, registry-1.docker.io/traversalext/traversal-processor-charts-<your-deployment>:<version>).The Docker Hub username is always traversalext. Only the token is per-customer.

Install the ORAS CLI

The values file is published as an OCI artifact, which Helm doesn’t natively pull. Install the ORAS CLI:

brew install oras

See the ORAS installation guide for non-macOS platforms.

Pull the values file

Set the values shared by Traversal, then pull the artifact:

export DOCKERHUB_REPO_NAME="<repo>"   # provided by Traversal
export DOCKERHUB_REPO_TOKEN="<token>" # provided by Traversal
export VALUES_FILE_VERSION="v0.1.0"

oras pull \
  --username traversalext --password "$DOCKERHUB_REPO_TOKEN" \
  "registry-1.docker.io/traversalext/$DOCKERHUB_REPO_NAME:$VALUES_FILE_VERSION"

This writes the values file into your current directory. Pass -o <path> to ORAS to place it elsewhere.

Installing

With the chart and values file in hand, install in whatever way fits your environment — helm install directly, a GitOps pipeline (ArgoCD, Flux) referencing the OCI chart, or an internal Helm registry mirror. As a minimal end-to-end example using Helm directly:

helm install traversal-processor \
  oci://registry-1.docker.io/traversalext/traversal-processor-charts \
  --version <version> \
  -f <your-deployment>-values.yaml

The pod exposes a health endpoint at /health on its dedicated probe port (healthPort, default 3001); its readiness probe gates traffic until the service is ready.

Redaction

The processor supports a regex-based redaction pipeline that rewrites sensitive text in log fields before data is sent to Traversal. Redaction is opt-in, disabled by default.Set redaction.enabled in your Helm values and provide a rules file using one of two options:

# Option A: inline rules — the chart creates and manages the ConfigMap
redaction:
  enabled: true
  rulesContent: |
    [[rules]]
    name    = "email"
    type    = "regex-structured-data"
    pattern = '[a-zA-Z0-9._%+\-]+@[a-zA-Z0-9.\-]+\.[a-zA-Z]{2,6}'

# Option B: reference a ConfigMap you manage externally
redaction:
  enabled: true
  existingConfigMap: my-redaction-rules

When using existingConfigMap, the key inside that resource must be named redaction-rules.toml.See Redaction for the rules file format and field filtering options.

TLS for the ingestion endpoint

By default the processor serves plain HTTP on port 3000. If your environment requires end-to-end encryption — for example when a load balancer or service mesh terminates TLS and re-encrypts to the backend — you can enable TLS so the processor serves HTTPS directly.TLS is configured through the tls block in your Helm values. Provide exactly one of two credential sources:PEM files — provide paths to certificate and key files already mounted in the container (for example via a Kubernetes Secret volume):

traversalProcessor:
  tls:
    enabled: true
    certFile: "/etc/tls/tls.crt"
    keyFile: "/etc/tls/tls.key"

Inline base64 — provide base64-encoded PEM content directly; the chart creates a Kubernetes Secret from it and mounts it read-only into the container, so you don’t manage any files yourself:

traversalProcessor:
  tls:
    enabled: true
    certB64: "<base64-encoded-cert>"
    keyB64: "<base64-encoded-key>"

The chart validates that exactly one credential source is provided — setting both file-based and inline values, or only one half of a pair, will produce a clear error at install time.Enabling TLS affects only the main ingest port. Health and metrics stay on the separate probe port (healthPort), which always serves plain HTTP on its own runtime — so the Kubernetes liveness and readiness probes keep working unchanged whether or not ingest TLS is enabled.

Want to learn more?

Redaction

Rules file format, field filtering, caching behaviour, and mount examples.

ORAS CLI

Pull OCI artifacts from any registry.

Helm OCI registries

Helm’s native OCI support for chart distribution.

Get Started

Architecture

Set up

Using Traversal

API

Security & Trust

Changelog

Traversal Processor

Deployment

Container image

Helm chart

Values file

Container image

Helm chart

Required values

Sizing and throughput

Telemetry forwarding

Disabling telemetry

Values file

Installing

Redaction

TLS for the ingestion endpoint

Want to learn more?

Redaction

ORAS CLI

Helm OCI registries

​Deployment

Container image

Helm chart

Values file

​Container image

​Helm chart

​Required values

​Sizing and throughput

​Telemetry forwarding

​Disabling telemetry

​Values file

​Installing

​Redaction

​TLS for the ingestion endpoint

​Want to learn more?

Redaction

ORAS CLI

Helm OCI registries

Deployment

Container image

Helm chart

Required values

Sizing and throughput

Telemetry forwarding

Disabling telemetry

Values file

Installing

Redaction

TLS for the ingestion endpoint

Want to learn more?