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

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

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](/architecture/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.

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

## 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](https://spiffe.io/docs/latest/spiffe-about/spiffe-concepts/#spiffe-id):

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

<Steps>
  <Step title="Generate a private key">
    Generate a private key locally and store it in a secure location. The key never leaves your environment.

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

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

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

    ```bash theme={null}
    openssl req -in client.csr -noout -text | grep -A1 "Subject Alternative Name"
    ```

    You should see your `spiffe://...` URI on the next line.
  </Step>

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

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

<Note>
  Where these files go depends on your deployment path:

  * **Helm:** `client.crt` and `client.key` populate `controllerTLS.certPEM` and `controllerTLS.keyPEM`. See [Required values](#required-values).
  * **Other:** the same two files populate `TLS_CERT_BASE64` and `TLS_KEY_BASE64` (each base64-encoded). See [Required](#required).
</Note>

## Deployment

<Tabs>
  <Tab title="Use Helm on K8s">
    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.

    <CardGroup cols={3}>
      <Card title="Container image" icon="cube" href="#container-image">
        Public, built from the open-source connector repo.
      </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

    The connector is open source. The source lives in the [traversal-connector repository on GitHub](https://github.com/InteractionLabs/traversal-connector), and Traversal builds and 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 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:

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

    <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-connector-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=...    # 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.
      </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-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:

    ```yaml theme={null}
    # 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
    ```

    <Note>
      When using `existingConfigMap`, the key inside that resource must be named `redaction-rules.toml`.
    </Note>

    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](/setup/redaction) for the rules file format and field filtering options.
  </Tab>

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

    The connector is open source. The source lives in the [traversal-connector repository on GitHub](https://github.com/InteractionLabs/traversal-connector), and Traversal builds and 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 runtime can pull it directly from Docker Hub. You can also build it yourself from the public source or mirror it into an internal registry.

    ## 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                                                                                                                        |
    | :---------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
    | <code style={{whiteSpace: "nowrap"}}>ENV\_NAME</code>                               | A short label identifying your deployment environment (for example, `acme-prod`). Tags the connector's metrics, logs, and traces. |
    | <code style={{whiteSpace: "nowrap"}}>TRAVERSAL\_CONTROLLER\_URL</code>              | The URL of the Traversal control plane this connector reaches.                                                                    |
    | <code style={{whiteSpace: "nowrap"}}>TLS\_CERT\_BASE64</code>                       | Base64-encoded PEM client certificate the connector presents when authenticating to the control plane.                            |
    | <code style={{whiteSpace: "nowrap"}}>TLS\_KEY\_BASE64</code>                        | Base64-encoded PEM private key for the client certificate above.                                                                  |
    | <code style={{whiteSpace: "nowrap"}}>OTEL\_EXPORTER\_OTLP\_METRICS\_ENDPOINT</code> | OTLP endpoint to which the connector exports its operational metrics.                                                             |
    | <code style={{whiteSpace: "nowrap"}}>OTEL\_EXPORTER\_OTLP\_TRACES\_ENDPOINT</code>  | OTLP endpoint to which the connector exports its operational traces.                                                              |
    | <code style={{whiteSpace: "nowrap"}}>OTEL\_EXPORTER\_OTLP\_LOGS\_ENDPOINT</code>    | OTLP endpoint to which the connector exports its operational logs.                                                                |

    ### Connection tuning

    | Variable                                                                 | Default      | What it is                                                               |
    | :----------------------------------------------------------------------- | :----------- | :----------------------------------------------------------------------- |
    | <code style={{whiteSpace: "nowrap"}}>ENV\_LEVEL</code>                   | `production` | Environment level: `production` or `development`. Affects log verbosity. |
    | <code style={{whiteSpace: "nowrap"}}>PROXY\_URL</code>                   | *none*       | HTTP forward proxy for outbound traffic to the control plane.            |
    | <code style={{whiteSpace: "nowrap"}}>HTTP\_PORT</code>                   | `8080`       | Port the connector listens on for health checks.                         |
    | <code style={{whiteSpace: "nowrap"}}>MAX\_TUNNELS\_ALLOWED</code>        | `2`          | Maximum number of concurrent connections to the control plane.           |
    | <code style={{whiteSpace: "nowrap"}}>MAX\_CONCURRENT\_REQUESTS</code>    | `10`         | Maximum number of in-flight requests across all connections.             |
    | <code style={{whiteSpace: "nowrap"}}>RECONNECT\_INTERVAL</code>          | `5s`         | Initial reconnect interval after a connection drop.                      |
    | <code style={{whiteSpace: "nowrap"}}>MAX\_BACKOFF\_DELAY</code>          | `60s`        | Maximum exponential backoff delay between reconnect attempts.            |
    | <code style={{whiteSpace: "nowrap"}}>REQUEST\_TIMEOUT</code>             | `60s`        | Per-request timeout.                                                     |
    | <code style={{whiteSpace: "nowrap"}}>MAX\_REQUEST\_BODY\_SIZE\_MB</code> | `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                                                                                                                                       |
    | :------------------------------------------------------------ | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |
    | <code style={{whiteSpace: "nowrap"}}>TLS\_CA\_BASE64</code>   | *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. |
    | <code style={{whiteSpace: "nowrap"}}>TLS\_SERVER\_NAME</code> | *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                                                                           |
    | :-------------------------------------------------------------------- | :------------- | :----------------------------------------------------------------------------------- |
    | <code style={{whiteSpace: "nowrap"}}>UPSTREAM\_TLS\_VERIFY</code>     | `true`         | Whether to verify TLS certificates of upstream services.                             |
    | <code style={{whiteSpace: "nowrap"}}>UPSTREAM\_TLS\_CA\_BASE64</code> | *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                                                                         |
    | :----------------------------------------------------------------- | :------ | :--------------------------------------------------------------------------------- |
    | <code style={{whiteSpace: "nowrap"}}>REDACTION\_RULES\_FILE</code> | *none*  | Path inside the container to a TOML rules file. See [Redaction](/setup/redaction). |

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

    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](/setup/redaction) for the full rules file format.

    ## Running the connector

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

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

## Want to learn more?

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

  <Card title="Connector architecture" icon="sitemap" href="/architecture/connector">
    How the connection works, what data flows where, and why no inbound network access is required.
  </Card>

  <Card title="Source on GitHub" icon="github" href="https://github.com/InteractionLabs/traversal-connector">
    Traversal Connector source code — inspect it, or build your own image.
  </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>