TLS and mTLS
AISIX AI Gateway uses TLS in four different places. Configure each area that applies to the connections in your deployment.
| Connection | Configuration Area | Purpose |
|---|---|---|
| Caller to AISIX | proxy.tls | Terminates HTTPS on the proxy listener |
| AISIX to an upstream | upstream.tls, provider_key.tls | Decides which certificates AISIX trusts when it calls out |
| AISIX to etcd | etcd.tls | Verifies the etcd server and presents the AISIX client identity |
| AISIX gateway to control plane | managed.* certificate bundle fields | Authenticates the AISIX gateway to the AISIX Cloud control plane |
These settings are independent. Enabling HTTPS on the proxy listener does not configure etcd mTLS, trusting a private certificate authority for an upstream does not affect etcd, and the AISIX Cloud certificate bundle does not replace listener TLS.
Configure Listener TLS
Use listener TLS when AISIX should terminate HTTPS directly on the proxy listener.
Configure TLS on the proxy listener:
proxy:
addr: "0.0.0.0:3000"
tls:
cert_file: "/etc/aisix/tls/proxy.crt"
key_file: "/etc/aisix/tls/proxy.key"
Listener TLS protects inbound traffic to that listener. It does not prove that AISIX can connect to etcd, reach the AISIX Cloud control plane, or authenticate to an upstream provider.
Trust an Upstream Behind a Private Certificate Authority
Every connection AISIX opens on a request path — model endpoints, guardrail services, MCP and A2A upstreams, OIDC discovery and JWKS fetches, the Realtime WebSocket, Amazon Bedrock, and log-export object stores — is verified against the platform's certificate authorities. A self-hosted endpoint whose certificate is signed by your own authority is not among them, so requests to it fail:
transport error: error sending request for url (https://internal-llm.example:8443/v1/chat/completions):
client error (Connect): invalid peer certificate: UnknownIssuer
Point upstream.tls.ca_file at the authority's certificate to fix this for the whole deployment:
upstream:
tls:
ca_file: "/etc/aisix/tls/private-ca.pem"
The file is PEM-encoded and may contain several certificates, so a full chain in one bundle works. These certificates are trusted in addition to the platform's own, so adding a private authority never makes a public provider unreachable.
If AISIX cannot read the file, or the file contains no certificate, startup fails with the path in the message rather than the connection failing later on every request.
Present a Client Certificate
Some upstreams require the caller to authenticate with a certificate as well. Set both fields together:
upstream:
tls:
ca_file: "/etc/aisix/tls/private-ca.pem"
client_cert_file: "/etc/aisix/tls/client.crt"
client_key_file: "/etc/aisix/tls/client.key"
Setting only one of the two is rejected at startup.
Trust a Different Authority per Endpoint
A deployment facing more than one private authority declares trust on the provider key that carries the endpoint, rather than deployment-wide. The certificate is supplied inline, because the endpoint is declared on the resource rather than in the gateway's configuration file:
provider_keys:
- display_name: internal-llm
provider: openai
api_key: "sk-..."
api_base: "https://internal-llm.example:8443/v1"
tls:
ca_cert: |
-----BEGIN CERTIFICATE-----
MIIB...
-----END CERTIFICATE-----
In AISIX Cloud, the same settings are on the provider key's Endpoint TLS section in the dashboard.
A certificate configured on one provider key applies only to that key's endpoint. Keys are not pooled into one trust store, so two endpoints signed by two different authorities each need their own.
Skip Verification in a Test Environment
Certificate verification can be turned off, deployment-wide or for one provider key:
upstream:
tls:
verify: false
This accepts any certificate for the affected connections, including an expired one, one issued for a different host, and one presented by an interceptor. Anyone able to intercept the connection can read and rewrite every prompt, response, and upstream API key that crosses it. Use ca_file or ca_cert in any environment where that matters.
Amazon Bedrock does not honour this setting. The HTTP stack in the AWS SDK exposes trust roots only, so Bedrock certificates are still verified whatever verify says, and a client certificate cannot be presented either. The gateway logs a warning at startup when the setting is present, rather than letting it look applied. ca_file does apply to Bedrock.
Use the Environment Instead
SSL_CERT_FILE and SSL_CERT_DIR are honoured, and are additive to the platform's certificate authorities. They remain a valid way to trust a private authority without changing the configuration file.
They apply to the whole process, so they cannot express "this one endpoint, this one authority." That is what upstream.tls.ca_file and provider_key.tls are for.
Installing the certificate into the container's system trust store with update-ca-certificates does not work. The image runs as the unprivileged aisix user, so the command fails with a permission error, leaves the bundle unchanged, and the gateway still rejects the certificate — while looking as though the authority was installed.
Configure a Redis Backend
The shared cache and rate-limit backend keeps its own trust settings, because it usually sits inside your deployment and is issued by a different authority than the model endpoints. The fields match upstream.tls, and apply only to a rediss:// URL:
ratelimit:
backend: redis
redis:
mode: single
url: "rediss://redis.internal:6379"
tls:
ca_file: "/etc/aisix/tls/redis-ca.pem"
In Sentinel mode, ca_file does not apply. The client library accepts no custom trust roots for the master it discovers, so put the certificate in the system trust store or point SSL_CERT_FILE at it instead. The gateway logs a warning at startup when ca_file is set in this mode. verify does apply in Sentinel mode.
Configure etcd mTLS
Use etcd.tls when the configuration store requires mTLS. AISIX expects the CA certificate, client certificate, and client key together.
Configure etcd trust and client identity:
etcd:
endpoints:
- "https://etcd.internal.example.com:2379"
prefix: "/aisix"
tls:
ca_cert_file: "/etc/aisix/etcd/ca.crt"
client_cert_file: "/etc/aisix/etcd/client.crt"
client_key_file: "/etc/aisix/etcd/client.key"
AISIX uses the CA file to verify the etcd server certificate and presents the client certificate and key to etcd. All three files must be readable by the AISIX process at startup.
When the etcd certificate uses a server name that differs from the endpoint hostname, set domain_name explicitly:
etcd:
endpoints:
- "https://10.0.0.10:2379"
tls:
ca_cert_file: "/etc/aisix/etcd/ca.crt"
client_cert_file: "/etc/aisix/etcd/client.crt"
client_key_file: "/etc/aisix/etcd/client.key"
domain_name: "etcd.internal.example.com"
If domain_name is omitted, AISIX derives it from the first etcd endpoint.
Configure AISIX Cloud mTLS
AISIX gateways authenticate to the control plane with a certificate bundle. This is separate from listener TLS and etcd mTLS for an open-source AISIX gateway.
Set managed.enabled to true, provide the control-plane connection settings, and supply the certificate bundle:
managed:
enabled: true
cp_base_url: "https://dpm.example.com:7944"
mtls_dir: "/var/lib/aisix/mtls"
dp_id_file: "/var/lib/aisix/dp_id"
cp_cert_file: "/etc/aisix/mtls/client.crt"
cp_key_file: "/etc/aisix/mtls/client.key"
cp_ca_file: "/etc/aisix/mtls/ca.crt"
The AISIX Cloud certificate bundle must include a certificate, private key, and CA bundle. The example uses file paths; AISIX also accepts inline PEM values. Provide all three values through the same style, and do not set both the inline and file-path variant for the same certificate, key, or CA role.
Most AISIX gateways derive the control-plane etcd endpoint from cp_base_url. Set cp_etcd_endpoint only when the control-plane deployment exposes a separate, known etcd endpoint.
AISIX materializes the certificate bundle into mtls_dir and reuses the persisted bundle on restart. The runtime state directory must be writable by the gateway process.
For the full AISIX Cloud connection flow, see Connect an AISIX Gateway.
Check the Right Connection
Start with the failing connection and check the matching configuration area.
If HTTPS caller traffic fails while the process is running, check proxy.tls, certificate and key readability, and the client-facing hostname.
If startup fails while connecting to etcd, check etcd.tls, etcd network reachability, and certificate trust. If expected configuration changes stop applying after startup, keep the focus on the etcd connection and configuration watch health.
If a request to a provider fails with invalid peer certificate: UnknownIssuer, the endpoint's certificate is signed by an authority AISIX does not trust — check upstream.tls.ca_file, or the provider key's own tls.ca_cert when only one endpoint is affected.
If AISIX Cloud heartbeat, telemetry, budget checks, or certificate rotation fail, check the certificate bundle, trust root, runtime state directory, and managed.cp_base_url.
Each TLS area uses its own certificate context. Listener certificates, upstream trust settings, etcd client certificates, and AISIX Cloud control-plane certificates are configured and validated separately.
Next Steps
Continue with Configuration Propagation to understand how validated updates become active gateway snapshots.