TLS Certificate Management in APISIX#

APISIX manages SSL/TLS certificates as SSL objects stored in etcd and synchronized in real time to every data plane worker. Each SSL object carries the PEM certificate(s), encrypted private key(s), one or more SNI hostnames, and optional mTLS configuration. 1

SSL object key fields (schema):

Admin API is registered in apisix/admin/ssl.lua under the resource name ssls, exposing GET/POST/PUT/DELETE/PATCH /apisix/admin/ssls/{id}.

Key security behavior: private keys are AES-128-CBC encrypted before being written to etcd 2 and are stripped from GET responses 3.

Storage, Sync, and LRU Caching#

SSL objects are stored in etcd under the /ssls prefix. On worker startup, init_worker() registers an etcd watcher via core.config.new("/ssls", { automatic = true, ... }). Any change in etcd is automatically pushed to all data plane workers without a reload.

Hitless rotation is a direct consequence of this design: updating an SSL object via the Admin API propagates to workers asynchronously. The radix tree router is rebuilt lazily on the next TLS handshake when radixtree_router_ver no longer matches ssl_certificates.conf_version 4. In-flight connections are unaffected because NGINX handles each TLS handshake independently.

LRU caches in apisix/ssl.lua avoid re-parsing PEM on every handshake:

• cert_cache — parsed certificate objects, TTL 3600 s, max 1024 entries
• pkey_cache — parsed (and decrypted) private key objects, same limits

fetch_cert(sni, cert) and fetch_pkey(sni, pkey) are the cache-read entry points called during every TLS handshake.

SNI-Based Radix Tree Routing#

Certificate selection during a TLS handshake runs across two NGINX Lua phases:

ssl_client_hello_by_lua_block → ssl_certificate_by_lua_block

ClientHello phase (ssl_client_hello_phase()):

1. Extracts SNI from the TLS ClientHello packet using the ngx.ssl.clienthello API 5. If no SNI is present, falls back to apisix.ssl.fallback_sni from config.yaml.
2. Calls match_and_set(api_ctx, match_only=true, sni) — matches the SNI against the radix tree but does not yet load the cert, saving cryptographic work until the certificate phase.
3. Stores matched_ssl and client_hello_sni in ngx.ctx for the next phase 6.

Certificate phase (ssl_phase()):

1. Reads ngx.ctx.matched_ssl set by the ClientHello phase.
2. Calls _M.set(), which clears existing certs, fetches secrets if the cert/key are secret URIs, then calls set_cert_and_key() → ngx_ssl.set_cert() / ngx_ssl.set_priv_key().

Radix tree construction (create_router()):

• SNI strings are reversed before being inserted as paths (e.g. moc.elpmaxe.*), so wildcard prefix matching naturally handles *.example.com 7.
• The router is rebuilt in-place when conf_version changes; no worker restart needed.
• Only SSL objects with type == "server" and status == 1 (or nil) are inserted 8.

For mTLS, after setting the server cert, ngx_ssl.verify_client() is called with the parsed CA cert and depth from client.ca.

Deployment Architecture Patterns#

Gateway TLS Termination#

The default pattern. APISIX terminates TLS using a server-type SSL object and proxies requests to upstreams over HTTP or HTTPS. An SSL object with matching sni/snis is required for the client→APISIX segment. 1

Load Balancer Termination#

When a load balancer (e.g. AWS ALB, Nginx, HAProxy) sits in front of APISIX and terminates TLS, APISIX receives plain HTTP. No SSL object is required for the downstream segment. APISIX may still need SSL objects for APISIX→upstream mTLS.

mTLS (Bidirectional)#

• Client → APISIX: Add client.ca to the SSL object. APISIX verifies the client certificate during the TLS handshake via ngx_ssl.verify_client(). Use skip_mtls_uri_regex to exempt specific paths.
• APISIX → Upstream: Configure tls.client_cert / tls.client_key directly in the upstream object. For shared wildcard certs across multiple upstreams, create a type: "client" SSL object and reference it. 1

TLS Passthrough (L4 Stream)#

The stream subsystem enables SNI-based routing without terminating TLS. The NGINX template declares ssl_client_hello_by_lua_block in the stream context 9, which captures the SNI and stores it in ngx.ctx.client_hello_sni. The stream preread phase then uses the captured SNI for route matching via the ip_port router. The original encrypted connection is proxied to the upstream intact — APISIX never decrypts the payload.

Note: In the stream subsystem, ngx.ssl.server_name() returns the session hostname (not the original SNI) in the preread phase, so SNI must be captured in ssl_client_hello_phase() 10.

Key Files and Entry Points#

Related documentation: SSL Certificates key concept · Admin API - SSL Certificates · Configure HTTPS between Client and APISIX · Configure mTLS between Client and APISIX