pixie / docs
SOURCE GUIDE GitHub ↗
User guide

HTTPS, with client trust.

Enable server TLS, then optionally require a certificate from every client.

Enable HTTPS

Save this config and provide certificate files readable by the Pixie process:

addr: 0.0.0.0:8443
workers: 4
tls:
  cert_file: /etc/pixie/tls/server-chain.pem
  key_file: /etc/pixie/tls/server-key.pem

The chain file contains the server certificate first, followed by intermediates. The key is an unencrypted PEM private key supported by rustls. Use a certificate valid for the hostname clients use, protect the key with filesystem permissions, and restart after renewal.

curl --cacert server-ca.pem https://localhost:8443/

For a certificate trusted by your system, omit --cacert. Pixie does not obtain or renew certificates automatically. The configured listener serves HTTPS only; it does not also serve HTTP or redirect it.

Require client certificates

Add the trusted client CA bundle:

tls:
  cert_file: /etc/pixie/tls/server-chain.pem
  key_file: /etc/pixie/tls/server-key.pem
  client_ca_file: /etc/pixie/tls/client-ca.pem
curl --cacert server-ca.pem \
  --cert client.pem --key client-key.pem \
  https://localhost:8443/

Clients without a valid certificate trusted by the configured CA fail the handshake. This authenticates a client certificate; Pixie does not provide user accounts or per-route authorization.

Container and Kubernetes setup

Mount the config, server chain, key, and optional client CA as read-only files, and expose the configured TCP port. The supplied templates do not mount credentials automatically.

docker run --rm -p 8443:8443 \
  -v "$PWD/config-pixie.yml:/etc/pixie/config-pixie.yml:ro" \
  -v "$PWD/tls:/etc/pixie/tls:ro" \
  ghcr.io/laflut3/pixie:latest

The container runs as pixie; file permissions must allow that account to read the mounted credentials. For Kubernetes, mount a Secret and use a deployment configuration that points to its files. If TLS terminates at an Ingress instead, the connection from it to Pixie remains plain HTTP unless configured separately.

Experimental HTTP/3

HTTP/3 uses QUIC over UDP and is experimental. Enable http3.addr in Pixie configuration. In Helm, set tls.enabled=true, tls.secretName, and http3.enabled=true; expose the selected UDP port in the firewall and any external load balancer. The current chart mounts the Secret as /etc/pixie/tls.

When a connection fails

  • Startup error: check the config file syntax, certificate chain, key match, file paths, and permissions.
  • Client trust error: check the server hostname and the trusted server CA.
  • mTLS failure: check the client certificate, private key, expiry, and trusted client CA.
  • Connection refused: check the configured port, container mapping, service, and firewall.
Pixie documentation Built from the source. Updated with the features.