How to Set Up TLS Encryption for the Switchyard Server

To enable TLS encryption for the Switchyard server, provide the --tls-cert and --tls-key flags pointing to PEM-encoded certificate files when starting the server, which activates the built-in axum-server TLS backend.

The NVIDIA-NeMo/Switchyard repository provides a high-performance routing layer for AI model inference, and securing client-to-server communication is critical for production deployments. Setting up TLS encryption for the Switchyard server requires only two additional CLI arguments, but understanding the underlying implementation in crates/switchyard-server/src/lib.rs ensures proper certificate management and troubleshooting.

How TLS Works in Switchyard

Switchyard's TLS support is implemented directly in the switchyard-server binary using the axum-server crate with the tls-rustls feature enabled. When TLS options are supplied, the server constructs a RustlsConfig using RustlsConfig::from_pem_file and wraps the TCP listener with axum_server::from_tcp_rustls to serve HTTPS traffic.

The core logic resides in crates/switchyard-server/src/lib.rs within the serve_tls function (lines 302-391). Here, the server checks for the ServerRunOptions.tls field, which contains a TlsOptions struct holding the certificate and key paths. If TLS configuration is present, the server invokes the asynchronous serve_tls function; otherwise, it falls back to plain HTTP via the standard serve function.

Prerequisites for TLS Encryption

Before configuring the server, you must obtain or generate a PEM-encoded certificate and private key pair. Switchyard requires:

• A PEM-encoded X.509 certificate (commonly cert.pem or server.crt)
• A PEM-encoded private key (commonly key.pem or server.key)
• Both files must be readable by the user running the switchyard-server process

For development environments, you can generate a self-signed certificate. Production deployments should use certificates issued by a trusted Certificate Authority (CA).

Step-by-Step TLS Configuration

Generate a Self-Signed Certificate

For testing purposes, use OpenSSL to create a 2048-bit RSA key pair valid for 365 days:

openssl req -newkey rsa:2048 -nodes -keyout key.pem \
    -x509 -days 365 -out cert.pem \
    -subj "/CN=my-switchyard"

Move these files to a secure directory with restricted permissions:

sudo mkdir -p /etc/switchyard
sudo cp cert.pem /etc/switchyard/cert.pem
sudo cp key.pem /etc/switchyard/key.pem
sudo chmod 600 /etc/switchyard/key.pem

Launch the Server with TLS Flags

The command-line interface defined in crates/switchyard-server/src/cli.rs exposes two mutually required flags: --tls-cert and --tls-key. You must provide both arguments simultaneously; the parser enforces this dependency via requires = "tls_key" and requires = "tls_cert" constraints.

Start the server with TLS enabled on port 443:

switchyard-server \
    --addr 0.0.0.0:443 \
    --tls-cert /etc/switchyard/cert.pem \
    --tls-key /etc/switchyard/key.pem \
    --config /etc/switchyard/config.toml

The server initializes the TLS context by calling RustlsConfig::from_pem_file with the provided paths, then binds the Axum router to the encrypted listener.

Systemd Deployment with TLS

The repository includes a sample systemd unit file at dev-server/switchyard.service that demonstrates production deployment with TLS enabled. The file already includes placeholder flags for certificate paths (lines 5-6).

Copy and customize the service file:

sudo cp dev-server/switchyard.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now switchyard.service

Ensure the ExecStart line in your service file includes the full paths to your certificate and key:

ExecStart=/usr/local/bin/switchyard-server \
    --addr 0.0.0.0:443 \
    --tls-cert /etc/switchyard/cert.pem \
    --tls-key /etc/switchyard/key.pem \
    --config /etc/switchyard/config.toml

Summary

• Switchyard implements TLS via the axum-server crate with Rustls, requiring only --tls-cert and --tls-key flags to enable HTTPS.
• The TLS logic lives in crates/switchyard-server/src/lib.rs, specifically within the serve_tls function and TlsOptions struct.
• Certificate and key files must be in PEM format and readable by the server process.
• The CLI enforces mutual dependency between --tls-cert and --tls-key to prevent partial TLS configuration.
• Production deployments can use the sample systemd unit at dev-server/switchyard.service for persistent encrypted service.

Frequently Asked Questions

What certificate formats does Switchyard support?

Switchyard accepts standard PEM-encoded X.509 certificates and PKCS#8 or RSA private keys. The server uses RustlsConfig::from_pem_file internally, which parses the certificate chain and key files according to Rustls specifications. Ensure your certificate file includes the full chain if using an intermediate CA.

What happens if I provide only one TLS flag?

The command-line parser will exit with an error before the server starts. Because the flags are configured with mutual requirements in crates/switchyard-server/src/cli.rs, providing only --tls-cert without --tls-key (or vice versa) triggers a Clap validation error indicating that the missing argument is required.

Can I use Let's Encrypt certificates with Switchyard?

Yes. Switchyard accepts any PEM-encoded certificate, including those from Let's Encrypt. Ensure your certificate file contains the full chain (certificate plus intermediate) and the key file contains the unencrypted private key. Reference these files using the --tls-cert and --tls-key flags when starting the server.

Where are the TLS CLI flags defined?

The --tls-cert and --tls-key arguments are defined in crates/switchyard-server/src/cli.rs. They are marked as mutually required using Clap's requires attribute, ensuring the parser rejects invocations that specify only one flag.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}