Traversal Connector

The Traversal Connector is a lightweight service that establishes an outbound, mTLS-encrypted connection to the Traversal control plane, allowing Traversal to access your private data sources without any inbound network access. For an architectural overview, see Traversal Connector. The connector ships as a single container image and supports two deployment paths: a Helm chart for Kubernetes (the recommended path), or running the image directly on any container runtime — Docker on EC2, systemd-managed containers, Nomad, etc. — configured through environment variables.

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

Client certificate

The connector authenticates to the Traversal control plane over mTLS. The recommended way to provision the client certificate is to generate the private key in your own environment and send Traversal a Certificate Signing Request (CSR) — the private key never leaves your environment, and Traversal countersigns the CSR with its certificate authority. Before you start, you’ll need:

openssl (1.1.1 or newer, for -addext support), or any tool that can produce a PKCS#10 CSR with a SAN URI extension.
Your tenant UUID and tenant name, both provided by Traversal.

The CSR’s Subject Alternative Name encodes your tenant identity using a SPIFFE URI:

spiffe://traversal.com/tenant/<tenant-uuid>/<tenant-name>

Traversal’s control plane uses this SPIFFE ID to identify the sender of every request, so both fields must exactly match the values Traversal shared with you.

Generate a private key

Generate a private key locally and store it in a secure location. The key never leaves your environment.

openssl ecparam -name prime256v1 -genkey -noout -out client.key

P-256 is the SPIFFE-recommended algorithm. RSA 2048+ also works if your platform requires it (openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out client.key).

Create the CSR

Generate a CSR that embeds the SPIFFE URI as a SAN. Substitute <tenant-uuid> and <tenant-name> with the values Traversal shared with you.

openssl req -new -key client.key -out client.csr \
  -subj "/CN=<tenant-name>" \
  -addext "subjectAltName=URI:spiffe://traversal.com/tenant/<tenant-uuid>/<tenant-name>"

Verify the SAN URI is encoded correctly before sending:

openssl req -in client.csr -noout -text | grep -A1 "Subject Alternative Name"

You should see your spiffe://... URI on the next line.

Send the CSR to Traversal

Share client.csr with Traversal through the secure channel agreed upon during onboarding.Do not share client.key — keeping the private key in your environment is the whole point of this flow.

Receive your signed certificate

Traversal signs the CSR with its certificate authority and returns your signed client certificate:

client.crt — valid for the lifetime issued by Traversal.

Together with the client.key you generated in Step 1, these are the two files you’ll plug into the deployment configuration below.

Where these files go depends on your deployment path:

Helm: client.crt and client.key populate controllerTLS.certPEM and controllerTLS.keyPEM. See Required values.
Other: the same two files populate TLS_CERT_BASE64 and TLS_KEY_BASE64 (each base64-encoded). See Required.

Deployment

Use Helm on K8s
Other

A Helm-based Kubernetes deployment is composed of three artifacts. The image and chart are published openly; only the values file requires authentication, since it may carry credentials issued for your deployment.

Container image

Public, built from the open-source connector repo.

Helm chart

Public OCI artifact. Generic across all deployments.

Values file

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

Container image

The connector is open source. The source lives in the traversal-connector repository on GitHub, and Traversal builds and publishes the image to the traversalext/traversal-connector repository on Docker Hub. The image is public, so by default your cluster pulls it directly from Docker Hub.If your security policy requires it, you can also build the image yourself from the public source or 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-connector-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-connector-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 connector together require four fields. Traversal pre-populates all four in the values file it builds for you, so you don’t typically need to set them manually:

Field	What it is
`envName`	A short label identifying your deployment environment (for example, `acme-prod`). Tags the connector’s metrics, logs, and traces, and identifies your deployment on the control plane side.
`controllerURL`	The URL of the Traversal control plane this connector reaches.
`controllerTLS`	The mTLS material the connector presents when authenticating to the control plane: a client certificate and its private key. Supplied inline as PEM strings (the chart renders a Kubernetes Secret) or by referencing the name of an existing Secret you manage. A custom CA certificate (`controllerTLS.caPEM`) is supported but optional — if not set, the system trust store is used.
`otel`	OTLP telemetry endpoints: `otel.metricsEndpoint`, `otel.tracesEndpoint`, and `otel.logsEndpoint`. The connector exports its operational metrics, traces, and logs to these endpoints.

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

Values file

The values file holds your deployment-specific configuration: your envName and controllerURL, your connector’s 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-connector-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=...    # provided by Traversal
export DOCKERHUB_REPO_TOKEN=...   # provided by Traversal
export VALUES_FILE_VERSION=v0.4.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-connector \
  oci://registry-1.docker.io/traversalext/traversal-connector-charts \
  --version v0.4.0 \
  -f YOUR_VALUES_FILE

The pod establishes its connection to the Traversal control plane within a few seconds of starting; its readiness probe gates traffic until the connection is live.

Redaction

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: |
    version = "v1"
    [[rules]]
    name    = "email"
    type    = "regex"
    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.

The connector watches the rules file and hot-reloads it whenever the content changes. No restart is required. If the file is missing, unreadable, or contains an invalid pattern when hot-reloaded, the connector exits rather than using the new, invalid, redaction configuration.See Redaction for the rules file format and field filtering options.

For environments without Kubernetes, run the same connector image directly on any container runtime — Docker, podman, systemd, Nomad, ECS, and so on. The image is identical to the one used in the Kubernetes path; the only difference is that you supply configuration through environment variables instead of a Helm values file.

Container image

Configuration via environment variables

Every connector setting is exposed as an environment variable. The required variables are listed first; the remaining sections are optional with sensible defaults.

Required

Variable	What it is
`ENV_NAME`	A short label identifying your deployment environment (for example, `acme-prod`). Tags the connector’s metrics, logs, and traces.
`TRAVERSAL_CONTROLLER_URL`	The URL of the Traversal control plane this connector reaches.
`TLS_CERT_BASE64`	Base64-encoded PEM client certificate the connector presents when authenticating to the control plane.
`TLS_KEY_BASE64`	Base64-encoded PEM private key for the client certificate above.
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	OTLP endpoint to which the connector exports its operational metrics.
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	OTLP endpoint to which the connector exports its operational traces.
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	OTLP endpoint to which the connector exports its operational logs.

Connection tuning

Variable	Default	What it is
`ENV_LEVEL`	`production`	Environment level: `production` or `development`. Affects log verbosity.
`PROXY_URL`	none	HTTP forward proxy for outbound traffic to the control plane.
`HTTP_PORT`	`8080`	Port the connector listens on for health checks.
`MAX_TUNNELS_ALLOWED`	`2`	Maximum number of concurrent connections to the control plane.
`MAX_CONCURRENT_REQUESTS`	`10`	Maximum number of in-flight requests across all connections.
`RECONNECT_INTERVAL`	`5s`	Initial reconnect interval after a connection drop.
`MAX_BACKOFF_DELAY`	`60s`	Maximum exponential backoff delay between reconnect attempts.
`REQUEST_TIMEOUT`	`60s`	Per-request timeout.
`MAX_REQUEST_BODY_SIZE_MB`	`32`	Maximum HTTP request body size, in MB.

Control plane TLS

Optional overrides for the TLS handshake to the control plane. Set these only when the control plane uses a private CA or requires a non-default SNI.

Variable	Default	What it is
`TLS_CA_BASE64`	system trust	Base64-encoded PEM CA certificate used to verify the control plane’s identity. Required only if the control plane uses a private/self-signed CA.
`TLS_SERVER_NAME`	from URL	Override SNI server name for the control plane TLS handshake.

Upstream TLS

Controls how the connector verifies TLS for the upstream services it queries on Traversal’s behalf.

Variable	Default	What it is
`UPSTREAM_TLS_VERIFY`	`true`	Whether to verify TLS certificates of upstream services.
`UPSTREAM_TLS_CA_BASE64`	system trust	Base64-encoded PEM CA certificate used to verify upstream services with private CAs.

Redaction

The connector supports a regex-based redaction pipeline that rewrites sensitive text in upstream responses before they leave your environment. Set REDACTION_RULES_FILE to the in-container path of your rules file and mount it into the container:

Variable	Default	What it is
`REDACTION_RULES_FILE`	none	Path inside the container to a TOML rules file. See Redaction.

docker run --rm \
  -e REDACTION_RULES_FILE=/etc/traversal/rules.toml \
  -v /path/to/your/rules.toml:/etc/traversal/rules.toml:ro \
  traversalext/traversal-connector:<version>

Running the connector

Once you have the required values from Traversal, start the connector with any container runtime. As a minimal example with Docker:

docker run --rm \
  -e ENV_NAME=acme-prod \
  -e TRAVERSAL_CONTROLLER_URL=https://controller.example.com \
  -e TLS_CERT_BASE64="$(base64 < client.crt)" \
  -e TLS_KEY_BASE64="$(base64 < client.key)" \
  -p 8080:8080 \
  traversalext/traversal-connector:<version>

The connector exposes /healthz and /readyz on HTTP_PORT (default 8080) for health and readiness checks. Wire these into your runtime’s health checks so traffic is gated on the connection being live.

Want to learn more?

Redaction

Rules file format, field filtering, mount examples, and hot-reload behaviour.

Connector architecture

How the connection works, what data flows where, and why no inbound network access is required.

Source on GitHub

Traversal Connector source code — inspect it, or build your own image.

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

Traversal Connector

Client certificate

Deployment

Container image

Helm chart

Values file

Container image

Helm chart

Required values

Values file

Installing

Redaction

Container image

Configuration via environment variables

Required

Connection tuning

Control plane TLS

Upstream TLS

Redaction

Running the connector

Want to learn more?

Redaction

Connector architecture

Source on GitHub

ORAS CLI

Helm OCI registries

Get Started

Architecture

Set up

Using Traversal

API

Security & Trust

Documentation Index

​Client certificate

​Deployment

Container image

Helm chart

Values file

​Container image

​Helm chart

​Required values

​Values file

​Installing

​Redaction

​Container image

​Configuration via environment variables

​Required

​Connection tuning

​Control plane TLS

​Upstream TLS

​Redaction

​Running the connector

​Want to learn more?

Redaction

Connector architecture

Source on GitHub

ORAS CLI

Helm OCI registries

Client certificate

Deployment

Container image

Helm chart

Required values

Values file

Installing

Redaction

Container image

Configuration via environment variables

Required

Connection tuning

Control plane TLS

Upstream TLS

Redaction

Running the connector

Want to learn more?