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

> Set up the Traversal Connector in the Traversal web app, then deploy it with Helm on Kubernetes or run the container image with Docker.

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](https://docs.traversal.com/architecture/connector.md).

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](https://helm.sh/docs/intro/install/), 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](https://docs.traversal.com/responsible-use/security.md#traversal-connector) 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:

```bash theme={null}
openssl ecparam -name prime256v1 -genkey -noout -out traversal-connector-<id>.key

openssl req -new -key traversal-connector-<id>.key -out traversal-connector-<id>.csr \
  -subj "/" \
  -addext "subjectAltName=URI:spiffe://traversal.com/tenant/<org_id>/<org_name>"
```

The Subject Alternative Name (SAN) is a [SPIFFE URI](https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/#spiffe-id) 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:

```bash theme={null}
openssl req -in traversal-connector-<id>.csr -noout -text | grep -A1 "Subject Alternative Name"
```

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](#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**.

> [!NOTE]
>
> 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](https://github.com/InteractionLabs/traversal-connector), and Traversal publishes the image to the [traversalext/traversal-connector repository on Docker Hub](https://hub.docker.com/r/traversalext/traversal-connector). The image is public, so your cluster or runtime pulls it directly from Docker Hub by default.

> [!NOTE]
>
> 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:

```bash theme={null}
helm pull oci://registry-1.docker.io/traversalext/traversal-connector-charts \
  --version <version> --untar
```

In the commands below, use the version the app shows. No Docker Hub token or values file is needed.

> [tab] Helm (Kubernetes)
>
> Run the command the app generates. It has this form:
>
> ```bash theme={null}
> helm upgrade --install connector-<id> \
>   oci://registry-1.docker.io/traversalext/traversal-connector-charts \
>   --version <version> \
>   --namespace traversal --create-namespace \
>   --set-file controllerTLS.certPEM=./client.crt \
>   --set-file controllerTLS.keyPEM=./traversal-connector-<id>.key \
>   --set-string connectorID=<id> \
>   --set-string envName=<name> \
>   --set-string controllerURL=https://edge.<base-domain> \
>   --set-string pipes.trustedRoots.current=<value-from-the-app> \
>   --set-string pipes.capabilityIssuer=<value-from-the-app> \
>   --set-string otel.metricsEndpoint=https://telemetry.<base-domain>:4317 \
>   --set-string otel.tracesEndpoint=https://telemetry.<base-domain>:4317 \
>   --set-string otel.logsEndpoint=https://telemetry.<base-domain>:4317
> ```
>
> 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.
>
> 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.

> [tab] Docker
>
> Run the command the app generates. It has this form:
>
> ```bash theme={null}
> docker run --rm \
>   -e ENV_NAME=<name> \
>   -e TRAVERSAL_CONTROLLER_URL=https://edge.<base-domain> \
>   -e TRAVERSAL_CONNECTOR_ID=<id> \
>   -e OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
>   -e OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://telemetry.<base-domain>:4317 \
>   -e OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://telemetry.<base-domain>:4317 \
>   -e OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://telemetry.<base-domain>:4317 \
>   -e TLS_CERT_BASE64="$(base64 < ./client.crt)" \
>   -e TLS_KEY_BASE64="$(base64 < ./traversal-connector-<id>.key)" \
>   -e TRAVERSAL_CAPABILITY_ROOTS=<value-from-the-app> \
>   -e TRAVERSAL_CAPABILITY_ISSUER=<value-from-the-app> \
>   -p 8080:8080 \
>   traversalext/traversal-connector:v<version>
> ```
>
> Version 0.10 and later also requires the `TRAVERSAL_CAPABILITY_*` variables. The app's command includes them. If you write the command yourself, copy these values from the app's command.
>
> The connector serves `/healthz` and `/readyz` on `HTTP_PORT` (default `8080`). Wire these into your runtime's health checks so traffic is gated on the connection being 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

| Helm value | Environment variable | Description |
| :- | :- | :- |
| `envName` | `ENV_NAME` | A short label for your deployment environment (for example, `acme-prod`). Tags the connector's metrics, logs, and traces. |
| `connectorID` | `TRAVERSAL_CONNECTOR_ID` | The connector's ID from the app. Must be a lower-case UUID, or the connector fails to install or start. The connector sends it on every request to the control plane (the `X-Traversal-Connector-ID` header). |
| `controllerURL` | `TRAVERSAL_CONTROLLER_URL` | The edge controller URL, `https://edge.<base-domain>`, with no extra path. |
| `controllerTLS.certPEM` and `controllerTLS.keyPEM` | `TLS_CERT_BASE64` and `TLS_KEY_BASE64` | The client certificate and private key. The chart takes PEM strings. The variables take base64-encoded PEM. In the certificate, put the leaf first, followed by any intermediates. |
| `controllerTLS.existingSecret` | n/a | Alternative to the inline PEM values: a Secret you manage, with keys `tls.crt`, `tls.key`, and optionally `ca.crt`. The chart fails to render if you set neither form. |
| `pipes.trustedRoots.current` (or `pipes.capabilityKeys`), and `pipes.capabilityIssuer` | `TRAVERSAL_CAPABILITY_ROOTS` (or `TRAVERSAL_CAPABILITY_KEYS`), and `TRAVERSAL_CAPABILITY_ISSUER` | Capability trust values. Required for chart and image 0.10 and later. Copy them from the app's command. |
| `otel.metricsEndpoint`, `otel.tracesEndpoint`, `otel.logsEndpoint` | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`, `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`, `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | OTLP endpoints for the connector's own telemetry. Required unless you [disable telemetry](#disable-telemetry). See [Telemetry](#telemetry). |

### Optional settings

| Helm value | Environment variable | Default | Description |
| :- | :- | :- | :- |
| `replicaCount` | n/a | `5` | Number of connector replicas. |
| n/a | `ENV_LEVEL` | `production` | `production` or `development`. Switches the log format (text or JSON) and development or release mode. In `development`, the telemetry and `https://` requirements are relaxed. It does not change log verbosity. |
| `proxyURL` | `EGRESS_PROXY_URL` | none | HTTP forward proxy for outbound traffic to the control plane. Must start with `http://`. The proxy must not intercept TLS, because the connector opens its tunnels with `CONNECT`. |
| `controllerTLS.caPEM` | `TLS_CA_BASE64` | system trust | CA certificate used to verify the control plane. Needed only if the control plane uses a private CA. |
| n/a | `HTTP_PORT` | `8080` | Port for health checks. |
| n/a | `REQUEST_TIMEOUT` | `60s` | Per-request timeout. |
| `maxRequestBodySizeMB` | `MAX_REQUEST_BODY_SIZE_MB` | `32` | Maximum size, in MB, of a request body the connector sends upstream. |
| `maxResponseBodySizeMB` | `MAX_RESPONSE_BODY_SIZE_MB` | `32` | Maximum size, in MB, of an upstream response. Applies only to responses from hosts covered by a [redaction rule](https://docs.traversal.com/setup/redaction.md), because the connector buffers those. |
| `maxDecodedResponseBodySizeMB` | `MAX_DECODED_RESPONSE_BODY_SIZE_MB` | `256` | Maximum size, in MB, of a response after decompression. Same scope as above. |

The connector refuses a covered response that exceeds a limit instead of forwarding it. See [Troubleshooting](https://docs.traversal.com/setup/connector-troubleshooting.md).

> [!NOTE]
>
> 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.

| Helm value | Environment variable | Default | Description |
| :- | :- | :- | :- |
| `upstreamTLS.caPEM` | `UPSTREAM_TLS_CA_BASE64` | system trust | PEM CA certificate (base64-encoded for the variable) for upstream services that use a private CA. |
| `upstreamTLS.existingSecret` | n/a | none | A Secret you manage that holds the CA under the key `ca.crt`. |
| `upstreamTLS.caFile` | `UPSTREAM_TLS_CA_FILE` | none | Path to a CA file inside the container. Mutually exclusive with the base64 variable. |
| n/a | `UPSTREAM_TLS_VERIFY` | `true` | Whether to verify upstream TLS certificates. |

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

| Environment variable | Default | Description |
| :- | :- | :- |
| `OTEL_SERVICE_NAME` | `traversal-connector` | Service name reported on all signals. |
| `OTEL_EXPORTER_OTLP_PROTOCOL` | empty (chart default `grpc`) | `grpc` or `http/protobuf` selects gRPC. `http/json` or empty selects HTTP. For gRPC, endpoints take the form `https://host:port`. For HTTP, the path names the signal (`https://host/v1/metrics`). |

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

| Helm value | Default | Description |
| :- | :- | :- |
| `otel.sidecar.enabled` | `true` | Runs the forwarder. Set to `false` to export directly from the connector. |
| `otel.sidecar.image` | `traversalext/alloy` | Forwarder image. Override `repository` to pull from an internal mirror. |
| `otel.sidecar.resources` | 50m CPU, 128–256Mi memory | Resource requests and limits for the forwarder. |

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

> [!WARNING]
>
> 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](https://docs.traversal.com/setup/redaction.md).

> [tab] Helm (Kubernetes)
>
> Set `redaction.enabled` and provide the rules file in exactly one of three ways.
>
> Inline rules. The chart creates and manages the ConfigMap:
>
> ```yaml theme={null}
> 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}'
>     hosts   = ['api\.example\.com']
> ```
>
> A ConfigMap you manage:
>
> ```yaml theme={null}
> redaction:
>   enabled: true
>   existingConfigMap: my-redaction-rules
> ```
>
> A Secret you manage (chart 0.9 and later):
>
> ```yaml theme={null}
> redaction:
>   enabled: true
>   existingSecret: my-redaction-rules
> ```
>
> 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.

> [tab] Docker
>
> Set `REDACTION_RULES_FILE` to the in-container path of your rules file and mount the file into the container:
>
> ```bash theme={null}
> docker run --rm \
>   -e REDACTION_RULES_FILE=/etc/traversal/redaction-rules.toml \
>   -v /path/to/your/rules.toml:/etc/traversal/redaction-rules.toml:ro \
>   traversalext/traversal-connector:v<version>
> ```
>
> Add these to the command from [Install the connector](#install-the-connector). Set `REDACTION_RELOAD_INTERVAL` to change how often the connector checks the file for changes (default `10s`).

## Network controls

To restrict the connector's egress to approved destinations, enforce it with your environment's network controls. See [Destination control](https://docs.traversal.com/architecture/connector.md#destination-control) for the network model.

* **Kubernetes:** use a [`NetworkPolicy`](https://kubernetes.io/docs/concepts/services-networking/network-policies/) 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](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-IMDS-new-instances.html) 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](https://docs.sigstore.dev/cosign/system_config/installation/). Each release also includes inspectable build metadata and a checksum for its Helm chart.

> [accordion] Verify the image signature
>
> Verify the release you plan to deploy. You can find the digest on [Docker Hub](https://hub.docker.com/r/traversalext/traversal-connector/tags) or inspect the version tag with Docker Buildx.
>
> **1. Resolve the release digest**
>
> Set the release version, then inspect its multi-platform image:
>
> ```bash theme={null}
> IMAGE=docker.io/traversalext/traversal-connector
> VERSION=v<version>
>
> docker buildx imagetools inspect "${IMAGE}:${VERSION}"
> ```
>
> Copy the `sha256:...` digest from the output.
>
> **2. Download the release public key**
>
> Install [Cosign](https://docs.sigstore.dev/cosign/system_config/installation/), then download the public key from the matching source tag:
>
> ```bash theme={null}
> curl -fsSLo cosign.pub \
>   "https://raw.githubusercontent.com/InteractionLabs/traversal-connector/${VERSION}/cosign.pub"
> ```
>
> **3. Verify the signed digest**
>
> Replace the placeholder with the digest from the first step:
>
> ```bash theme={null}
> DIGEST=sha256:<release-digest>
> cosign verify --key cosign.pub "${IMAGE}@${DIGEST}"
> ```
>
> A successful command confirms that Traversal signed the image at that digest.

> [accordion] Verify the Helm chart checksum
>
> Each [GitHub release](https://github.com/InteractionLabs/traversal-connector/releases) includes a Helm chart archive and its SHA-256 checksum file.
>
> ```bash theme={null}
> VERSION=v<version>
> CHART="traversal-connector-charts-${VERSION#v}.tgz"
> RELEASE_URL="https://github.com/InteractionLabs/traversal-connector/releases/download/${VERSION}"
>
> curl -fLO "${RELEASE_URL}/${CHART}"
> curl -fLO "${RELEASE_URL}/${CHART}.sha256"
> sha256sum --check "${CHART}.sha256"
> ```
>
> On macOS, use `shasum -a 256 --check "${CHART}.sha256"` instead.

> [accordion] Inspect the SBOM and provenance
>
> Release images include a platform-specific SPDX SBOM and build provenance. Set the platform you plan to run, then inspect both attestations:
>
> ```bash theme={null}
> IMAGE=docker.io/traversalext/traversal-connector
> DIGEST=sha256:<release-digest>
> PLATFORM=linux/amd64
> RELEASE_IMAGE="${IMAGE}@${DIGEST}"
>
> docker buildx imagetools inspect "$RELEASE_IMAGE" --format '{{ json .SBOM }}' \
>   | jq --arg platform "$PLATFORM" '.[$platform]'
> docker buildx imagetools inspect "$RELEASE_IMAGE" --format '{{ json .Provenance }}' \
>   | jq --arg platform "$PLATFORM" '.[$platform]'
> ```

## Want to learn more?

> [card] [Redaction](https://docs.traversal.com/setup/redaction.md)
>
> Rules file format, host and field filtering, and reload behavior.

> [card] [Troubleshooting](https://docs.traversal.com/setup/connector-troubleshooting.md)
>
> Diagnose connection, startup, and redaction problems.

> [card] [Connector architecture](https://docs.traversal.com/architecture/connector.md)
>
> How the connection works, what data flows where, and why no inbound network access is required.

> [card] [Source on GitHub](https://github.com/InteractionLabs/traversal-connector)
>
> Inspect the connector source code or build your own image.

> [card] [Image on Docker Hub](https://hub.docker.com/r/traversalext/traversal-connector)
>
> The published multi-platform connector image.

> [card] [Helm OCI registries](https://helm.sh/docs/topics/registries/)
>
> Helm's native OCI support for chart distribution.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.