Transport Layer Security (TLS) is a cryptographic protocol that secures communication over a network. TLS is the successor to deprecated Secure-Sockets-Layer (SSL). Learn how to configure Spice to use TLS for encryption in transit.
A valid TLS certificate and private key in PEM format are required. To generate certificates for testing, follow the TLS Cookbook.
Use --tls-enabled true to enable TLS from the command line. The arguments --tls-certificate-file and --tls-key-file specify the paths to the certificate and private key files.
Alternatively, to pass PEM-encoded certificate and private key strings directly, use the --tls-certificate and --tls-key arguments.
When using the Spice CLI, arguments, including the TLS arguments, are passed to spice run automatically.
Note that -- is used to separate the spice run arguments from the Spice runtime arguments.
Use the tls section as a child to runtime to provide the certificate and key files/strings.
To learn more about secrets, see Secret Stores.
When TLS is configured using file paths (certificate_file / key_file or --tls-certificate-file / --tls-key-file), the runtime automatically watches the certificate and key files for changes and reloads them without restarting. This is useful when certificates are rotated by external tools such as SPIRE, cert-manager, or kubelet.
When TLS is configured using inline values (certificate / key, including ${secrets:…} references), certificates are loaded once at startup and are not automatically reloaded.
The runtime_tls_reload_total OTel counter tracks reload attempts:
| Label | Values |
|---|---|
scope | public, cluster |
result | ok, io_error, parse_error |
:::info
When using inline certificates or secrets (certificate / key), changes are not applied at runtime and will only take effect on restart.
:::
When TLS is enabled, the runtime output will print the TLS certificate details.
When TLS is enabled in the runtime, the Spice CLI can be configured to connect to the runtime using TLS by specifying the --tls-root-certificate-file argument, providing the path to the root certificate file.
:::info Enterprise Feature mTLS (client certificate authentication) is included in the Enterprise distribution of Spice.ai. Learn more. :::
mTLS extends standard TLS by requiring the client to also present a certificate during the TLS handshake. This provides cryptographic authentication of both the server and the client.
Set client_auth_mode to request or required and provide a CA bundle to verify client certificates:
| Mode | Behavior |
|---|---|
none (default) | Standard one-way TLS. No client certificate is requested. |
request | The server requests a client certificate but accepts connections without one. Presented certificates are verified against the CA. Useful for migration or audit-only deployments. |
required | A valid client certificate is required. The Flight listener rejects no-cert connections at the TLS handshake. The HTTP listener admits no-cert connections so /health and /v1/ready remain accessible for Kubernetes probes, but all other HTTP endpoints return 401 without a verified client certificate. |
Use cURL with a client certificate:
Use the Spice CLI with a client certificate:
Kubernetes liveness/readiness probes (/health, /v1/ready) and the metrics endpoint (/metrics) are always accessible without a client certificate, even under client_auth_mode: required.
When client_auth_ca_file is used, the CA bundle is watched for changes and reloaded atomically alongside the server certificate and key. When client_auth_ca (inline) is used, the CA is loaded once at startup.
For a complete walkthrough, see the mTLS Cookbook recipe.
