TLS and mTLS

AISIX AI Gateway uses TLS in three different places. Configure the one that matches the connection you want to protect.

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 etcd and optionally presents a client certificate
Managed gateway to AISIX Cloud	managed.* certificate bundle fields	Authenticates the managed gateway to AISIX Cloud

These settings are independent. Enabling HTTPS on the proxy listener does not configure etcd TLS, 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 AISIX Cloud, or authenticate to an upstream provider.

Configure etcd TLS

Use etcd.tls when the configuration store requires TLS or mTLS.

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 uses the client certificate and key when etcd requires client authentication. The 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 AISIX Cloud with a certificate bundle. This is separate from listener TLS and etcd TLS in a self-hosted deployment.

Select managed mode, provide the Cloud 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 AISIX Cloud gives you a separate etcd endpoint to use during managed bootstrap.

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 Setup.

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 configuration freshness stalls 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 Cloud 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.