Skip to main content
Version: Next

TLS: Transport Layer Security

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.

Pre-requisites​

A valid TLS certificate and private key in PEM format are required. To generate certificates for testing, follow the TLS Cookbook.

Enable TLS via command line arguments​

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.

# Provide the TLS certicate and key PEM files to the Spice runtime
spiced --tls-enabled true --tls-certificate-file /path/to/cert.pem --tls-key-file /path/to/key.pem

Alternatively, to pass PEM-encoded certificate and private key strings directly, use the --tls-certificate and --tls-key arguments.

# Provide the TLS certicate and key using PEM-encoded strings to the Spice runtime
export TLS_CERT=$(cat /path/to/cert.pem)
export TLS_KEY=$(cat /path/to/key.pem)
spiced --tls-enabled true --tls-certificate "$TLS_CERT" --tls-key "$TLS_KEY"

When using the Spice CLI, arguments, including the TLS arguments, are passed to spice run automatically.

# Run Spice using the CLI and provide the TLS certicate and key as PEM files
spice run -- --tls-enabled true --tls-certificate-file /path/to/cert.pem --tls-key-file /path/to/key.pem

Note that -- is used to separate the spice run arguments from the Spice runtime arguments.

Enable TLS via spicepod.yaml​

Use the tls section as a child to runtime to provide the certificate and key files/strings.

runtime:
tls:
enabled: true
# Using filesystem paths
certificate_file: /path/to/cert.pem
key_file: /path/to/key.pem
runtime:
tls:
enabled: true
# Specify the certificate and key directly
certificate: |
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
key: |
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
runtime:
tls:
enabled: true
# Provide the certificate and key using secrets
certificate: ${secrets:tls_cert}
key: ${secrets:tls_key}

To learn more about secrets, see Secret Stores.

Certificate Hot-Reload​

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.

  • In-flight TLS connections are unaffected — only new handshakes use the rotated certificate.
  • If a rotated file contains invalid PEM data, the runtime logs the error and continues serving with the previous certificate.
  • If a rotated certificate does not match the private key, for example when only one of the two files has been replaced, the runtime logs a warning naming both files and continues serving with the previous pair. Writing the matching file triggers another reload that picks up the new pair. At startup, a certificate that does not match its key fails with TLS certificate <cert> does not match private key <key>.
  • A reload that reads the certificate and key already being served, such as the second of the two reloads that a rotation of both files triggers, is skipped and not counted.
  • File changes are detected via polling (every 2 seconds). Atomic file renames are handled correctly.

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:

LabelValues
scopepublic, cluster
resultok, io_error, parse_error, key_mismatch
info

When using inline certificates or secrets (certificate / key), changes are not applied at runtime and will only take effect on restart.

Handshake Timeout​

The HTTP, Arrow Flight, and metrics listeners, and the cluster gRPC listeners in distributed query, close a connection that does not complete its TLS handshake within 10 seconds. A client that opens a connection and sends nothing cannot keep it open indefinitely, so idle or stalled connections do not stop the listener from accepting new clients. The timeout is fixed and not configurable. A client on a slow or high-latency network that cannot finish the handshake in time sees its connection closed and must reconnect. The deadline applies only to the handshake: a connection that has completed it is not affected.

In v2.4.2 and earlier, only the Arrow Flight and cluster gRPC listeners had this deadline. An HTTP or metrics client that connected and never completed the handshake kept its connection open, and a graceful shutdown waited for the full shutdown_timeout.

Output​

When TLS is enabled, the runtime output will print the TLS certificate details.

INFO runtime: All endpoints secured with TLS using certificate: CN=spiced.localhost, OU=IT, O=Widgets, Inc., L=Seattle, S=Washington, C=US

Using the Spice CLI​

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.

spice sql --tls-root-certificate-file /path/to/root.pem

Mutual TLS (mTLS)​

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.

Enable mTLS via spicepod.yaml​

Set client_auth_mode to request or required and provide a CA bundle to verify client certificates:

runtime:
tls:
enabled: true
certificate_file: /path/to/server.crt
key_file: /path/to/server.key
client_auth_mode: required
client_auth_ca_file: /path/to/client-ca.pem

Enable mTLS via command line​

spiced --tls-enabled true \
--tls-certificate-file /path/to/server.crt \
--tls-key-file /path/to/server.key \
--tls-client-auth-mode required \
--tls-client-auth-ca-file /path/to/client-ca.pem

Client auth modes​

ModeBehavior
none (default)Standard one-way TLS. No client certificate is requested.
requestThe server requests a client certificate but accepts connections without one. Presented certificates are verified against the CA. Useful for migration or audit-only deployments.
requiredA 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.

Connecting with a client certificate​

Use cURL with a client certificate:

curl --cacert ca.pem --cert client.crt --key client.key \
https://localhost:8090/v1/sql -d 'SELECT 1'

Use the Spice CLI with a client certificate:

spice sql --tls-root-certificate-file ./ca.pem \
--client-tls-certificate-file ./client.crt \
--client-tls-key-file ./client.key

Probe and metrics access​

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.

Client CA hot-reload​

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.