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.
• 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:

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.

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