Skip to main content
The Traversal Connector is a lightweight service that opens an outbound, mTLS-encrypted connection to the Traversal control plane. Traversal uses that connection to reach your private data sources without any inbound network access. For an architectural overview, see Traversal Connector. You create the connector and its certificate in the Traversal web app, then deploy the container image with the install command the app generates. You can deploy with a Helm chart on Kubernetes (the recommended path) or run the image on any container runtime, such as Docker on EC2, systemd-managed containers, or Nomad.

Prerequisites

  • Organization admin access in the Traversal web app.
  • A Kubernetes cluster with Helm, or a host that runs Docker or another container runtime.
  • openssl 1.1.1 or newer (for -addext support) on the machine where you generate the key.
  • Outbound access from the connector to the Traversal edge controller on port 443, and to the telemetry endpoint on port 4317. If your environment restricts outbound traffic, see Network allowlisting for the IPs to allow.
The Helm command creates the traversal namespace for you.

Set up in the Traversal web app

In the left navigation, open Integrations → Connectors and add a connector. The setup has three steps: Details, Certificate, and Deploy.
1

Enter the details

Enter a name and description for the connector. The app creates the connector and assigns it an ID (a UUID). You use this ID in the file names and install command below, shown as <id>.
2

Generate the key and certificate

The connector authenticates to the Traversal control plane with a client certificate. You generate the private key and a Certificate Signing Request (CSR) on your own machine, so the private key never leaves your environment.The app shows these commands with your values filled in:
The Subject Alternative Name (SAN) is a SPIFFE URI that identifies your organization. The control plane uses it to identify the sender of every request.To check that the SAN is encoded correctly, run:
You should see your spiffe://... URI on the next line.Upload the .csr file in the app. The app signs it immediately and returns your certificate (client.crt) and the CA chain. Do not upload or share the .key file.The app rejects a CSR unless it meets all of these requirements:
  • PEM format, 64 KiB or smaller.
  • A NIST P-256 (prime256v1) EC key. RSA keys are rejected.
  • A SHA-256, SHA-384, or SHA-512 signature.
  • An empty subject (-subj "/").
  • Exactly one extension: a single SAN URI that matches the one the app shows.
Certificates are valid for one year. A connector can have up to two active certificates at a time.
3

Deploy the connector

Download client.crt. The app generates the install command for your connector, with the chart or image version pinned. Run it as described in Install the connector.The app then shows the connector’s status: Waiting for connection, Offline, or Online. The connector is ready once it shows Online.
If Traversal gave you a pre-built values file instead, follow the instructions that came with it.

Install the connector

The connector is open source. The source lives in the traversal-connector repository on GitHub, and Traversal publishes the image to the traversalext/traversal-connector repository on Docker Hub. The image is public, so your cluster or runtime pulls it directly from Docker Hub by default.
The connector image is multi-platform and supports both x86 and ARM (linux/amd64 and linux/arm64).
You can also build the image yourself from the public source or mirror it into an internal registry. With Helm, override image.repository (and image.pullSecrets, if your registry requires authentication) when you install the chart. The Helm chart is a public OCI artifact at oci://registry-1.docker.io/traversalext/traversal-connector-charts. It contains no customer-specific configuration, so you can inspect or vendor it with standard Helm tooling. The pulled chart includes a values.yaml that documents every supported field:
In the commands below, use the version the app shows. No Docker Hub token or values file is needed.
Run the command the app generates. It has this form:
Chart 0.10 and later requires the pipes.* trust values. The app’s command includes them. If you write the command yourself, copy these values from the app’s command.Chart 0.10.3 and later mounts the certificate and key into the pod as files from a Kubernetes Secret, so the private key isn’t in the pod’s environment. This chart needs connector image 0.10.3 or later. If you override image.tag, set it to the version the app shows: the chart fails to render with an older release. The mounted files are readable through the pod’s group, so keep podSecurityContext.fsGroup set (the chart default is 65532).You can also install through a GitOps pipeline (Argo CD, Flux) that references the OCI chart, or through an internal Helm registry mirror.The pod connects to the Traversal control plane within a few seconds of starting. Its readiness probe gates traffic until the connection is live.

Configuration reference

The tables list the Helm value and the environment variable for each setting. A dash means the setting has no equivalent listed here. Run helm show values on the chart to see every supported value.

Required settings

Optional settings

The connector refuses a covered response that exceeds a limit instead of forwarding it. See Troubleshooting.
Since 0.10.0, MAX_TUNNELS_ALLOWED, MAX_CONCURRENT_REQUESTS, RECONNECT_INTERVAL, MAX_BACKOFF_DELAY, and TLS_SERVER_NAME no longer have any effect. Connection capacity uses the environment variables TRAVERSAL_TUNNELS_COUNT (default 2, maximum 8), TRAVERSAL_PIPES_MAX (default 200), and TRAVERSAL_PIPES_MAX_STREAMS (default 100).

Upstream TLS

These settings control how the connector verifies TLS for the upstream services it queries for Traversal. The CA you provide is added to the system trust roots.

Telemetry

The connector reports its own operational telemetry (metrics, traces, and logs) to Traversal over OTLP. This is how Traversal supports your deployment. Logs also always go to stdout. Endpoints must be https:// URLs that name a host. Plain http:// is accepted only for a loopback address, which is how the Helm forwarder is wired. The connector exits at startup if an endpoint is unset or invalid, unless telemetry is disabled or ENV_LEVEL=development.

Helm forwarder

By default, the chart adds a second container to the connector pod. It buffers telemetry and retries delivery, so a brief interruption doesn’t lose data. It authenticates with the connector’s controllerTLS identity and needs no credentials of its own. There is no forwarder outside Kubernetes, so a Docker connector exports directly.

Disable telemetry

Set disableTelemetry: true (Helm) or TRAVERSAL_DISABLE_TELEMETRY=true (environment variable, default false) to stop all telemetry export. This drops the endpoints and removes the Helm forwarder.
Disabling telemetry is highly discouraged. Telemetry is Traversal’s only view into a connector running in your network, so without it Traversal can provide only limited support.

Redaction

The connector can rewrite sensitive text in upstream responses before they leave your environment. Rules live in a TOML file. For the file format, host and field filtering, and how reloads behave, see Redaction.
Set redaction.enabled and provide the rules file in exactly one of three ways.Inline rules. The chart creates and manages the ConfigMap:
A ConfigMap you manage:
A Secret you manage (chart 0.9 and later):
With existingConfigMap or existingSecret, the key inside the resource must be redaction-rules.toml. The chart mounts the file at /etc/traversal/redaction-rules.toml.The connector checks the file for changes every redaction.reloadInterval (default 10s). A changed ConfigMap or Secret reaches the pod after the kubelet’s sync delay.

Network controls

To restrict the connector’s egress to approved destinations, enforce it with your environment’s network controls. See Destination control for the network model.
  • Kubernetes: use a NetworkPolicy for pod, namespace, or IP-CIDR rules if your cluster’s network plugin enforces it. For hostname-based rules, use your network plugin’s policy or firewall rules.
  • AWS EC2 with the Instance Metadata Service enabled: require IMDSv2 and set the response hop limit to 1. The connector doesn’t depend on AWS or IMDS.

Verify a release

Traversal signs connector images with Cosign. Each release also includes inspectable build metadata and a checksum for its Helm chart.
Verify the release you plan to deploy. You can find the digest on Docker Hub or inspect the version tag with Docker Buildx.
1

Resolve the release digest

Set the release version, then inspect its multi-platform image:
Copy the sha256:... digest from the output.
2

Download the release public key

Install Cosign, then download the public key from the matching source tag:
3

Verify the signed digest

Replace the placeholder with the digest from the first step:
A successful command confirms that Traversal signed the image at that digest.
Each GitHub release includes a Helm chart archive and its SHA-256 checksum file.
On macOS, use shasum -a 256 --check "${CHART}.sha256" instead.
Release images include a platform-specific SPDX SBOM and build provenance. Set the platform you plan to run, then inspect both attestations:

Want to learn more?

Redaction

Rules file format, host and field filtering, and reload behavior.

Troubleshooting

Diagnose connection, startup, and redaction problems.

Connector architecture

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

Source on GitHub

Inspect the connector source code or build your own image.

Image on Docker Hub

The published multi-platform connector image.

Helm OCI registries

Helm’s native OCI support for chart distribution.