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.