TLS and mTLS

AISIX AI Gateway uses TLS in three different places. Configure each area that applies to the connections in your deployment.

Connection	Configuration Area	Purpose
Caller or admin client to AISIX	proxy.tls or admin.tls	Terminates HTTPS on the proxy or admin listener
AISIX to etcd	etcd.tls	Verifies the etcd server and presents the AISIX client identity
Managed gateway to control plane	managed.* certificate bundle fields	Authenticates the managed gateway to the AISIX managed control plane

These settings are independent. Enabling HTTPS on the proxy listener does not configure etcd mTLS, and the managed certificate bundle does not replace listener TLS.

Configure Listener TLS

Use listener TLS when AISIX should terminate HTTPS directly on the proxy or admin 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"

Configure TLS on the self-hosted admin listener separately:

config.yaml

admin:
  addr: "127.0.0.1:3001"
  admin_keys:
    - "YOUR_ADMIN_KEY"
  tls:
    cert_file: "/etc/aisix/tls/admin.crt"
    key_file: "/etc/aisix/tls/admin.key"

Listener TLS protects inbound traffic to that listener. It does not prove that AISIX can connect to etcd, reach the managed control plane, or authenticate to an upstream provider.

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 Managed mTLS

Managed gateways authenticate to the control plane with a certificate bundle. This is separate from listener TLS and etcd mTLS in a self-hosted deployment.

Select managed mode, 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 managed 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 managed gateways derive the managed 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 managed 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 managed bootstrap flow, see Managed 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 HTTPS admin traffic fails in self-hosted mode, check admin.tls, admin listener binding, and the private admin 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 managed heartbeat, telemetry, budget checks, or certificate rotation fail, check the managed certificate bundle, trust root, runtime state directory, and managed.cp_base_url.

Each TLS area uses its own certificate context. Listener certificates, etcd client certificates, and managed control-plane certificates are configured and validated separately.

Next Steps

You have now seen where to configure each TLS and mTLS connection. Continue with Health Checks to verify process and configuration health.