> ## Documentation Index
> Fetch the complete documentation index at: https://docs.traversal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Traversal Processor

> Deploy the Traversal Processor to Kubernetes via Helm or to any container runtime via environment variables.

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.

<Note>
  If your environment restricts outbound traffic, see [Network allowlisting](/responsible-use/security#traversal-processor) for the IPs to allow before deploying.
</Note>

## Deployment

<Tabs>
  <Tab title="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.

    <CardGroup cols={3}>
      <Card title="Container image" icon="cube" href="#container-image">
        Public, built and published by Traversal.
      </Card>

      <Card title="Helm chart" icon="helmet-safety" href="#helm-chart">
        Public OCI artifact. Generic across all deployments.
      </Card>

      <Card title="Values file" icon="file-lock" href="#values-file">
        Per-deployment. Pulled with a Traversal-issued token.
      </Card>
    </CardGroup>

    ## Container image

    Traversal builds and publishes the Traversal Processor image to the [traversalext/traversal-processor repository on Docker Hub](https://hub.docker.com/r/traversalext/traversal-processor). The image is private, so you will have to authenticate with Docker Hub.

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

    If your security policy requires it, you can mirror the published image into an internal registry — override `image.repository` (and `image.pullSecrets`, if your registry requires authentication) in your values when installing the chart.

    ## 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:

    ```bash theme={null}
    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.

    ### Required values

    The chart and Traversal Processor together require the following fields. 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                                                                                             |
    | :----------------------------------------- | :----------------------------------------------------------------------------------------------------- |
    | `traversalProcessor.account.id`            | Your account UUID, used to associate ingested logs with your account.                                  |
    | `traversalProcessor.traversalApi.endpoint` | The Traversal API endpoint to which the processor sends processed logs.                                |
    | `traversalProcessor.mtls.certBase64`       | Base64-encoded PEM client certificate the processor presents when authenticating to the Traversal API. |
    | `traversalProcessor.mtls.keyBase64`        | Base64-encoded PEM private key for the client certificate above.                                       |

    All other fields — field extraction, redaction, replica count, resource requests, observability, scheduling — are optional and have sensible defaults.

    ## 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.

    <Steps>
      <Step title="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.
      </Step>

      <Step title="Install the ORAS CLI">
        The values file is published as an OCI artifact, which Helm doesn't natively pull. Install the [ORAS CLI](https://oras.land):

        ```bash theme={null}
        brew install oras
        ```

        See the [ORAS installation guide](https://oras.land/docs/installation) for non-macOS platforms.
      </Step>

      <Step title="Pull the values file">
        Set the values shared by Traversal, then pull the artifact:

        ```bash theme={null}
        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.
      </Step>
    </Steps>

    ## 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:

    ```bash theme={null}
    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 port 3000; 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:

    ```yaml theme={null}
    # 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](/setup/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):

    ```yaml theme={null}
    traversalProcessor:
      tls:
        enabled: true
        certFile: "/etc/tls/tls.crt"
        keyFile: "/etc/tls/tls.key"
    ```

    **Inline base64** — provide base64-encoded PEM content directly, decoded by the processor at startup (no volume mounts needed):

    ```yaml theme={null}
    traversalProcessor:
      tls:
        enabled: true
        certB64: "<base64-encoded-cert>"
        keyB64: "<base64-encoded-key>"
    ```

    Under the hood the chart sets environment variables consumed by the processor binary:

    | Environment variable      | Description                                              |
    | :------------------------ | :------------------------------------------------------- |
    | `PROCESSOR_TLS_CERT_FILE` | Path to the PEM certificate file.                        |
    | `PROCESSOR_TLS_KEY_FILE`  | Path to the PEM private key file.                        |
    | `PROCESSOR_TLS_CERT_B64`  | Base64-encoded PEM certificate (inline, no file needed). |
    | `PROCESSOR_TLS_KEY_B64`   | Base64-encoded PEM private key (inline, no file needed). |

    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.

    When TLS is enabled, the chart automatically switches the Kubernetes liveness and readiness probes to use `HTTPS`.
  </Tab>
</Tabs>

## Want to learn more?

<CardGroup cols={2}>
  <Card title="Redaction" icon="eraser" href="/setup/redaction">
    Rules file format, field filtering, caching behaviour, and mount examples.
  </Card>

  <Card title="ORAS CLI" icon="terminal" href="https://oras.land/docs/installation">
    Pull OCI artifacts from any registry.
  </Card>

  <Card title="Helm OCI registries" icon="box-archive" href="https://helm.sh/docs/topics/registries/">
    Helm's native OCI support for chart distribution.
  </Card>
</CardGroup>