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:

config.yaml

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

AISIX verifies outbound connections 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

The outbound transport determines which deployment-wide upstream.tls fields it can apply:

Outbound transport	ca_file	Client certificate and key	verify: false
HTTP providers, HTTP guardrails, MCP and A2A upstreams, OIDC and JWKS requests, and OTLP, SLS, and Datadog exporters	Applies	Applies	Applies
Realtime WebSocket	Applies	Ignored	Applies
Amazon Bedrock models and guardrails	Applies	Ignored	Ignored; Bedrock always verifies the server certificate
Object-store exporters	Applies	Ignored	Applies

Per-provider-key tls settings have a narrower scope. They apply to HTTP provider dispatch, including compatible REST endpoints and passthrough requests, but not to Amazon Bedrock or the Realtime WebSocket. For Realtime, use the deployment-wide CA and verification settings. For Bedrock, only the deployment-wide ca_file setting applies.

Point upstream.tls.ca_file at the authority's certificate to fix this for the whole deployment:

config.yaml

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 HTTP upstreams require the caller to authenticate with a certificate as well. Set both fields together:

config.yaml

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.

Realtime, Bedrock, and object-store exporter connections do not present this client certificate. Do not use these fields as an mTLS control for those transports.

Trust a Different Authority per Endpoint

Add this provider key entry to trust a different certificate authority for one endpoint. The certificate stays with the resource rather than the gateway configuration:

resources.yaml (provider TLS)

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.

On supported HTTP paths, 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.

Bedrock and Realtime accept a provider key for credentials and endpoint selection, but their dispatch transports do not consume its tls block. Use the applicable deployment-wide setting from the table above instead.

Skip Verification in a Test Environment

Certificate verification can be turned off, deployment-wide or for one provider key:

config.yaml

upstream:
  tls:
    verify: false

danger

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.

upstream.tls.verify: false applies to HTTP request paths, the Realtime WebSocket, and object-store exporters, but not to Amazon Bedrock. The AWS SDK exposes additional trust roots but does not let AISIX disable certificate verification. Bedrock therefore continues to verify the server certificate, and the gateway logs a warning when it first builds the Bedrock client. The per-provider-key tls.verify field also does not apply to Bedrock or Realtime.

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." Use upstream.tls.ca_file for an explicit deployment-wide authority, or provider-key tls.ca_cert for one supported HTTP provider endpoint.

note

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:

config.yaml

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:

config.yaml

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:

config.yaml

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:

config.managed.yaml

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, for an HTTP provider endpoint, the provider key's own tls.ca_cert when only that 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.