docs: Add mTLS client params to Spice.ai data connector

lukekim · lukekim · commit f4c9cbdebba4 · 2026-05-14T12:56:18.000+09:00
Documents the four new mTLS client identity parameters (`spiceai_tls_client_certificate_file`, `spiceai_tls_client_key_file`, `spiceai_tls_client_certificate`, `spiceai_tls_client_key`) added in spiceai/spiceai#10764 for spice-to-spice mTLS. Mirrors the FlightSQL connector docs update in #1720. - Adds the parameters to the connector reference table. - Adds the parameters to the deployment guide reference table. - Adds an "Mutual TLS (mTLS)" subsection with file-based and inline configuration examples to both pages.
diff --git a/website/docs/components/data-connectors/spiceai/deployment.md b/website/docs/components/data-connectors/spiceai/deployment.md
@@ -41,6 +41,10 @@ The connector authenticates to the upstream Spice runtime using `spiceai_api_key
 | `spiceai_endpoint`                | Override the Flight endpoint URL. Schemes: `http://`, `https://`, `grpc+tls://`.                                                                                   |
 | `spiceai_flight_endpoint`         | Legacy alias for `spiceai_endpoint`.                                                                                                                               |
 | `spiceai_tls_ca_certificate_file` | Path to a CA PEM file for verifying a self-hosted upstream that uses a private CA. Ignored for `http://` endpoints.                                                |
+| `spiceai_tls_client_certificate_file` | Path to a PEM client certificate chain for mutual TLS (mTLS). Must be set together with `spiceai_tls_client_key_file`. Mutually exclusive with `spiceai_tls_client_certificate`. |
+| `spiceai_tls_client_key_file`     | Path to the PEM private key matching `spiceai_tls_client_certificate_file`. Must be set together with `spiceai_tls_client_certificate_file`. Mutually exclusive with `spiceai_tls_client_key`. |
+| `spiceai_tls_client_certificate`  | Inline PEM client certificate chain for mutual TLS (mTLS). Resolve from a [secret store](../../secret-stores/) via `${secrets:...}`. Must be set together with `spiceai_tls_client_key`. Mutually exclusive with `spiceai_tls_client_certificate_file`. |
+| `spiceai_tls_client_key`          | Inline PEM private key for mutual TLS (mTLS). Resolve from a [secret store](../../secret-stores/) via `${secrets:...}`. Must be set together with `spiceai_tls_client_certificate`. Mutually exclusive with `spiceai_tls_client_key_file`. |
 
 Always source production keys from a managed secret store rather than from a checked-in `.env` file. API keys do not expire — rotate manually in the issuing system and update the secret store. Secret stores that support live reload (Kubernetes, Vault) pick up rotations without restarting the runtime.
 
@@ -68,6 +72,29 @@ params:
 
 The CA file is loaded once at startup; updates require a runtime restart. Mount it via Kubernetes ConfigMap or Secret in containerized deployments.
 
+### Mutual TLS (mTLS)
+
+When the upstream Spice runtime enforces mutual TLS (e.g. `runtime.tls.client_auth_mode: required`), the connector presents a client certificate during the handshake. Configure it as PEM files mounted into the pod, or as inline PEM material from a managed secret store:
+
+```yaml
+# File-based
+params:
+  spiceai_endpoint: grpc+tls://upstream.cluster.svc:50051
+  spiceai_tls_ca_certificate_file: /etc/spice/clients/server-ca.pem
+  spiceai_tls_client_certificate_file: /etc/spice/clients/client.pem
+  spiceai_tls_client_key_file: /etc/spice/clients/client.key
+```
+
+```yaml
+# Inline / secrets
+params:
+  spiceai_endpoint: grpc+tls://upstream.cluster.svc:50051
+  spiceai_tls_client_certificate: ${secrets:CLIENT_CERT_PEM}
+  spiceai_tls_client_key: ${secrets:CLIENT_KEY_PEM}
+```
+
+Certificate and key must be set as a pair within each form, and the file-based and inline forms are mutually exclusive. The cached Flight `Channel` is built once at dataset-load time, so cert rotation requires a runtime restart.
+
 ### Append Streams
 
 The connector supports long-lived append streams for real-time CDC. The upstream — whether Cloud or self-hosted — must expose a dataset with append-stream support. The sidecar subscribes over Flight `DoExchange` and receives each new batch as soon as it's emitted. Stream reconnection is automatic; persistent loss of connection causes the dataset to enter `Error` state if the lag exceeds the acceptable window. See [Data Refresh](../../../features/data-acceleration/data-refresh).
diff --git a/website/docs/components/data-connectors/spiceai/index.md b/website/docs/components/data-connectors/spiceai/index.md
@@ -69,6 +69,10 @@ Plain `grpc://` (without TLS) is rejected at startup. Use `http://` for unencryp
 | `spiceai_endpoint`                | Built from `spiceai_region` (Cloud)  | Override the Flight endpoint URL. Use for VPC / regional Cloud endpoints, or to point at a self-hosted Spice runtime. Schemes: `http://`, `https://`, `grpc+tls://`. |
 | `spiceai_flight_endpoint`         | None                                 | Legacy alias for `spiceai_endpoint`.                                                                                                                              |
 | `spiceai_tls_ca_certificate_file` | System cert store                    | Path to a CA certificate file (PEM) to verify a self-hosted upstream that uses a private CA. Ignored for `http://` endpoints.                                     |
+| `spiceai_tls_client_certificate_file` | None                            | Path to a PEM client certificate chain for mutual TLS (mTLS). Must be set together with `spiceai_tls_client_key_file`. Mutually exclusive with `spiceai_tls_client_certificate`. |
+| `spiceai_tls_client_key_file`     | None                                 | Path to the PEM private key matching `spiceai_tls_client_certificate_file`. Must be set together with `spiceai_tls_client_certificate_file`. Mutually exclusive with `spiceai_tls_client_key`. |
+| `spiceai_tls_client_certificate`  | None                                 | Inline PEM client certificate chain for mutual TLS (mTLS). Use the [secret replacement syntax](../secret-stores/) to load from a secret store, e.g. `${secrets:my_cert}`. Must be set together with `spiceai_tls_client_key`. Mutually exclusive with `spiceai_tls_client_certificate_file`. |
+| `spiceai_tls_client_key`          | None                                 | Inline PEM private key for mutual TLS (mTLS). Use the [secret replacement syntax](../secret-stores/) to load from a secret store, e.g. `${secrets:my_key}`. Must be set together with `spiceai_tls_client_certificate`. Mutually exclusive with `spiceai_tls_client_key_file`. |
 
 #### Endpoint resolution order
 
@@ -170,6 +174,33 @@ params:
 
 For local development and trusted internal networks, `http://` (no TLS) is also supported and avoids cert configuration entirely.
 
+### Mutual TLS (mTLS)
+
+When the upstream Spice runtime enforces mutual TLS (e.g. `runtime.tls.client_auth_mode: required`), the connector can present a client certificate during the handshake. Configure it in one of two mutually exclusive forms:
+
+**File-based** — point at PEM files on disk:
+
+```yaml
+params:
+  spiceai_endpoint: grpc+tls://upstream.cluster.svc:50051
+  spiceai_tls_ca_certificate_file: /etc/spice/clients/server-ca.pem
+  spiceai_tls_client_certificate_file: /etc/spice/clients/client.pem
+  spiceai_tls_client_key_file: /etc/spice/clients/client.key
+```
+
+**Inline** — supply PEM material directly, typically from a [secret store](../secret-stores/):
+
+```yaml
+params:
+  spiceai_endpoint: grpc+tls://upstream.cluster.svc:50051
+  spiceai_tls_client_certificate: ${secrets:CLIENT_CERT_PEM}
+  spiceai_tls_client_key: ${secrets:CLIENT_KEY_PEM}
+```
+
+Within each form, cert and key must be set together — setting only one is rejected at dataset-load time with a clear error naming both fields. The file-based and inline forms are mutually exclusive; mixing them is also rejected.
+
+The cached Flight `Channel` is built once at dataset-load time, so certificate rotation requires a runtime restart.
+
 ### Append streams (real-time CDC)
 
 The connector advertises [`supports_append_stream`](../../features/cdc/) — when the upstream Spice exposes a dataset with append-stream support, the sidecar can subscribe over Flight `DoExchange` and receive each new batch as soon as the upstream emits it. Enable on the sidecar via `refresh_mode: append` on an accelerated dataset:
