How Apache APISIX manages TLS certificates and SNI for many domains
When one gateway fronts many hostnames, each with its own certificate and renewal cycle, the design question is how the gateway selects the right certificate for each incoming connection. In Apache APISIX, certificates are stored as SSL objects, and the gateway chooses among them by matching the server name the client sends during the TLS handshake, which is Server Name Indication (SNI). A team needs this design when a shared gateway serves several domains, partner hostnames or tenants whose certificates are issued, rotated and revoked on different schedules.
APISIX is released under the Apache License 2.0 (SPDX: Apache-2.0) and is built on NGINX and etcd, with configuration held in etcd and hot-loaded into the data plane. Each SSL object carries the certificate and private key for one or more server names, and the same object can hold settings for OCSP stapling, which is provided through the ocsp-stapling general plugin. Client certificate verification is configured on the SSL object through the client.ca and client.depth fields, which matters when the gateway must verify client certificates for specific hostnames. Before you rely on any of these settings, confirm the field names, defaults and supported certificate formats against the version you will deploy, because the schema has changed between releases.
Plan the inventory before you touch the gateway. List every hostname, the certificate authority that issues it, the key type, the expiry date, the owner who approves renewal, and whether the name needs client verification or OCSP stapling. Overlapping names, such as a wildcard and a specific host that both match one request, need an explicit rule about which SSL object wins, and you should test that rule with the exact handshake your clients use. Ask your implementation partner or APISIX team to show how the chosen version handles this case on a staging gateway before production rollout.
Certificate configuration options and when each fits
This table compares the main ways to supply certificates and client CA settings to an APISIX SSL object, along with OCSP stapling. Read each row against your rotation cadence, how many hostnames one key should cover, and which team owns the private key.
| Option | Trade-off | When it fits |
|---|---|---|
| SSL object with inline PEM | Simple to create through the Admin API, but the private key sits in the configuration store, so rotation means rewriting the object and re-encrypting stored fields. | Small estates with few certificates and a team that already manages key material and the configuration store carefully. |
| SSL object with environment variable secret references | Keys stay out of the configuration store, but rotation depends on how the environment is redeployed, which can widen the blast radius if many gateway nodes share one variable set. | Containerized deployments where the platform team already injects secrets at startup and rotates through deployment pipelines. |
| SSL object referencing HashiCorp Vault, AWS Secrets Manager or GCP Secret Manager | Centralizes rotation and access policy in a secret manager you may already operate, but adds a runtime dependency and requires confirming the exact reference syntax for your APISIX version. | Organizations that already run a secret manager with audit logging and want one owner for certificate lifecycle across services. |
| Wildcard certificate for one zone | One certificate and key cover every hostname under the zone, so rotation is simple, but compromise of the key affects all names in that zone and wildcard scope must match your naming. | Many internal or tenant subdomains under one domain that one team controls end to end. |
| Separate certificate per hostname | Each name has its own key, so compromise or a failed renewal stays contained, but issuance, SNI objects and renewal jobs grow with the number of hostnames. | Public APIs, partner-facing hostnames or regulated services where containment and per-owner renewal matter more than volume. |
| Client CA verification with client.ca and client.depth | Enforces client certificate trust per SSL object, so a wrong CA or depth setting can reject legitimate clients or accept unintended chains. Trust bundles need an owner and a review cycle. | APIs that authenticate machines or partners with certificates and need a defined trust chain per hostname. |
| OCSP stapling through the ocsp-stapling plugin | Reduces client revocation lookups, but depends on the CA's responder being reachable from the gateway and needs monitoring for stale or failed staples. | Public-facing hostnames where clients benefit from stapled revocation status and the responder is reliably reachable. |
| Validity fields in the SSL schema | Fields named exptime, validity_start and validity_end were removed from the SSL schema in APISIX 3.7.0, so expiry must be tracked outside those fields, for example by your monitoring or renewal tooling. | Any upgrade across 3.7.0 or any script that reads or writes these fields. |
Setting up SNI-based certificates in your environment
This sequence takes a gateway from confirmed version and deployment mode to a set of SSL objects that serve each hostname with its own certificate, checked hostname by hostname with a TLS client. It is written for the platform team that will run the certificates after go-live.
Confirm the APISIX version and deployment mode
The platform lead records the exact APISIX version in use and whether the gateway runs in traditional, decoupled or standalone mode. Field names, Admin API paths and certificate handling differ between releases, so the version decides which documentation the team follows. Traditional mode serves client traffic on port 9080 and the Admin API on port 9180 by default, and the team should confirm those ports in its own configuration. Done means a written record of version, mode and the node or nodes that will hold the SSL objects. Check the version on the APISIX downloads page and the deployment modes documentation before writing any SSL object.
Decide where private keys live
The security owner and platform team agree where each private key is stored before any certificate is loaded. Options include keys written directly into the SSL object, environment variables, HashiCorp Vault, AWS Secrets Manager or GCP Secret Manager, which APISIX can reference from SSL certificates. Keys held in a secret manager keep plaintext out of configuration files and version control, but add a dependency that must be reachable when the gateway loads certificates. Done means a decision record naming the key store, who can read it and how renewals will update it. Confirm with the team that owns the secret manager how access is granted to the gateway.
Create SSL objects with snis lists
The platform engineer creates one SSL object per certificate, with an snis list naming every hostname that certificate should answer for. Wildcard certificates cover a single label under a domain, so a wildcard entry only serves hostnames that match it. Hostnames without a matching SSL object fall through to a default or fail the handshake, depending on configuration, so the team should list every public name explicitly. Done means the Admin API or the configuration file returns each SSL object with its snis list and no hostname appears under two objects. Verify by reading the stored objects back and comparing them with the hostname inventory.
Enable client certificate verification where needed
For endpoints that require mutual TLS, the security engineer sets client.ca and client.depth on the relevant SSL object, so only clients whose certificates chain to the approved CA are accepted. Apply this only to hostnames that need it, because mutual TLS changes what every caller must present. Done means a client without a valid certificate is refused on that hostname and a client with one reaches the route. The APISIX mTLS documentation covers the full set of fields and is the natural next read before changing production objects.
Enable OCSP stapling on the gateway
The platform engineer enables the ocsp-stapling general plugin so the gateway can present a signed revocation status with the certificate during the handshake. The team should confirm that the certificate authority issues OCSP responses for the chain in use and that the gateway can reach the responder from its network. Done means a handshake against a hostname returns a stapled response when the test client requests one. If no response appears, check responder reachability and the chain order before changing the plugin settings.
Test each hostname with a TLS client
The QA or security engineer connects to every hostname in the inventory with a TLS client, such as openssl s_client, and checks the presented certificate subject, the issuer, the validity dates and the chain. Wildcard and mutual TLS hostnames are tested separately, using a client with and without a valid certificate. Done means a signed table lists each hostname, the certificate it received, and whether it passed. Any hostname that returns the wrong certificate points to a missing or overlapping snis entry, so the team fixes that object before sign-off. Keep the table with the change record as evidence of the configuration.
Keeping private keys out of etcd and renewing certificates automatically
The main control is to keep private keys out of etcd by letting an SSL object hold a secret reference in place of the PEM key material. APISIX can resolve references from environment variables, HashiCorp Vault, AWS Secrets Manager and GCP Secret Manager, and the same mechanism covers plugin and consumer configuration. Each backend needs its own setup before any SSL object points at it. For environment variables, confirm how the variable reaches the gateway process and what a change requires. For Vault, create a read-only policy for the path and an auth method the gateway nodes can use. For AWS and GCP, grant the gateway's identity read access to the specific secret only. Confirm the exact reference format and resolution behavior in the APISIX secret documentation before you write any automation against it.
Renewal jobs then need to do two things in a fixed order: write the new certificate and key to the secret store, then update the SSL object so it resolves to the new material. In traditional mode, the job calls the Admin API, which listens on port 9180, so the caller and its network path must be locked down first. In standalone mode, the job rewrites conf/apisix.yaml or conf/apisix.json, and APISIX checks those files every second and hot-reloads them. Note that APISIX 3.7.0 removed the exptime, validity_start and validity_end fields from the SSL schema, so the gateway no longer reports expiry on the object. Expiry tracking must come from the certificate itself or from the secret store. Encrypting the secret material already in etcd is covered in the sibling topic on that subject and is not repeated here.
Two decisions remain open and should be settled before the job is built. The first is who owns the issuance process: a public CA, an internal CA, or an ACME client running on your side, and who approves a new certificate for each domain. The second is how renewal failures are detected and escalated. A failed issuance, a failed secret write, a rejected Admin API call and a certificate nearing expiry each need a signal that reaches an on-call owner, and each needs a documented rollback to the previous certificate. Ask your team to name these owners in writing, and make it a scope item in any implementation agreement.
Questions teams ask before running APISIX certificates in production
How much effort does a multi-domain APISIX certificate setup take?
Effort depends mainly on how many domains, how many environments and how many certificate sources you have, not on the APISIX configuration itself. Each domain needs an SSL object with its certificate, private key and SNI names, and each one must be tested against the right route. The work grows when domains share wildcard coverage, when certificates come from several authorities, or when private keys must stay in a secret backend. Ask for a quote that counts domains, environments, certificate sources and the number of renewal paths, since those are the inputs that move the estimate. The engagement does not change how APISIX itself handles SNI matching.
Can our team manage APISIX certificates on its own?
Many teams can, provided they already run TLS and can read the APISIX SSL object schema. The parts that usually need outside help are the first pass across an existing estate, the secret backend wiring and the renewal automation that must survive a failed renewal at 2 a.m. Your team keeps ownership of the certificate authority, DNS and the decisions about which names belong on which certificate. A fixed-scope engagement can cover one part, such as the inventory and migration of existing certificates, and leave the rest with your staff. Decide which of these tasks you will own before you ask for a quote.
What do we need to provide before a certificate rollout starts?
Before work starts, you should have a certificate inventory listing every domain, its issuer, expiry date, key location and the routes that use it. You also need DNS access for validation records, the name of your secret backend, and either access to your internal CA or a documented process for issuing certificates. Teams commonly supply a test gateway where SNI changes can be checked before production. Confirm these items with your security and platform owners at the start, because missing access is the most common cause of a delayed schedule. The written scope should list each dependency and who provides it.
How long does a rollout take across domains and environments?
Duration is set by the number of domains, the number of environments and how many certificate sources must be reconciled. A small set of domains on one gateway is a different job from dozens of domains across development, staging and production with separate secret stores. Testing SNI matching and renewal in each environment usually takes longer than the initial configuration. No duration applies to every estate, so ask the provider for a timeline in the written scope, with milestones for inventory, pilot domains, production cutover and renewal testing. Ask what happens if a dependency, such as DNS access, is late.
Do existing SSL objects need changes when we upgrade across APISIX 3.7?
Yes, check them before the upgrade. APISIX 3.7.0 removed the exptime, validity_start and validity_end fields from the SSL schema, according to the project changelog. If your SSL objects or automation still set or read those fields, the configuration will need to be changed to remove them. Certificate validity is still visible from the certificate itself, so monitoring should read expiry from the certificate rather than from those fields. Export your current SSL objects, search for the removed fields in your repositories and scripts, and test the change in a non-production gateway before upgrading production.
How should APISIX use secrets for certificate private keys?
APISIX can reference secrets from environment variables, HashiCorp Vault, AWS Secrets Manager and GCP Secret Manager in SSL certificates, according to the project's secret documentation. Storing key material in a secret backend keeps private keys out of plain configuration and out of your Git history. The trade-offs are the added dependency on the secret backend during gateway startup and renewal, and the access policies you must define for each gateway node. Confirm which backend your organization already operates and whose team owns it before choosing this path.
What does a fixed-scope certificate engagement cover?
A fixed-scope engagement covers the agreed deliverables in writing before work starts, such as the certificate inventory, the SSL object design, the SNI and wildcard plan, the secret backend integration, the renewal automation and the runbook for your team. It does not include certificate issuance by an independent authority, and DeployOpen does not issue audit reports or certifications. Ongoing renewal monitoring and upgrades can be handled under a retainer. Ask the provider to list which domains, environments and systems are in scope, and what is excluded, so the boundary is clear before the quote is accepted.
Security and operational risks in certificate management
Certificates on a shared gateway fail in two directions: attackers gain private keys or change routing, or valid traffic breaks because a certificate expired, matched the wrong name or stopped stapling. The cards below pair each risk with the control to plan before the first domain goes live.
Private key exposure in etcd or logs
An SSL object holds the private key for every domain it serves, so anyone who can read the configuration store or a debug log can impersonate those domains. Confirm that sensitive fields are encrypted in etcd on your APISIX version, and that key material is never echoed in CLI output, CI logs or ticket attachments. Where possible, reference the key from a secret manager instead of pasting it into the object. Use private keys should never leave the secret store in plain text as the working rule for the build.
Admin API changing certificates
Anyone who can call the Admin API can create, replace or delete an SSL object, which redirects a hostname to a certificate and key they control. Plan who may manage certificates, how the Admin API is reached, and whether changes go through reviewed configuration files rather than manual calls. Record every certificate change with the requester, the approver and the domains affected, so a bad change can be traced and reversed.
Expired certificates causing outages
A certificate that expires on a gateway fails every client of every domain bound to it at the same moment, which makes one missed renewal a broad outage. Inventory each SSL object with its domains and expiry date, and alert well before expiry. Because APISIX 3.7.0 removed the exptime, validity_start and validity_end fields from the SSL schema, expiry tracking must come from your own inventory or from the certificate itself, not from fields you may have copied from older examples.
Wildcard scope creep
A wildcard certificate for *.example.com is convenient, but it lets any service that holds the key present a valid certificate for every subdomain, including ones that no longer exist. Decide which hostnames need wildcard coverage and which need a single-name certificate. Review wildcard keys as high-value assets, restrict which teams can attach them to routes, and remove bindings when a service is retired.
Weak client CA trust
When client.ca on an SSL object trusts a CA that issues more certificates than intended, any holder of a valid client certificate from that CA can reach protected routes. Confirm which issuing CA signs each client population, limit trust to the narrowest CA that fits, and set client.depth deliberately so intermediate chains are verified as you expect. Revisit the trusted CA list whenever a partner, device fleet or internal PKI changes.
Stapling failures that stay silent
The ocsp-stapling plugin can fail to staple a response without any visible error for clients, so the gateway appears healthy while browsers and clients lose the revocation check they expect. Test stapling from outside your network after each certificate change, and monitor the responder and the gateway logs for fetch errors. Treat a stapling check as part of the renewal runbook, not a one-time setup step.
How we scope certificate and SNI work with your team
Scoping starts with an inventory, because the number and type of certificates decide most of the design. Before work begins, we ask for the full list of domains and subdomains the gateway will serve, which of them need wildcard coverage, which sit behind a different certificate authority, and which must present a client CA for mutual TLS. We also need the current renewal method for each certificate, whether that is a manual process, a script, a load balancer or a certificate manager, and who owns each step today. The domain inventory is the input that most changes the plan. Each entry becomes a candidate for an SSL object with its own snis list, so unclear ownership at this stage usually turns into unclear ownership of certificates later.
The second group of inputs covers where key material lives and how traffic reaches the gateway. We ask which secret stores are approved for private keys, such as HashiCorp Vault, AWS Secrets Manager or GCP Secret Manager, and whether APISIX can reach them from the gateway network. We also need the network paths between clients, any upstream load balancer, the gateway nodes and the etcd cluster, along with the ports and firewall rules that apply. Confirm the APISIX version you run or plan to run. Schema details differ across releases, so a field removed in one version can break an automation script written for another.
Scope and deliverables are agreed in writing before any configuration changes are made, and the written scope names the environments, domains, renewal workflow and handover items included. The output is configuration for your environment, runbooks for issuance and renewal, and verification evidence such as test results, certificate chain checks and SNI routing tests. Those artifacts help your own assessors and auditors, but DeployOpen does not issue audit reports, attestations or certifications. Ask your compliance lead early which evidence their assessor expects, so the verification steps are designed to produce it.
How DeployOpen delivers APISIX certificate management
DeployOpen plans the certificate layout for your APISIX gateway before any SSL object is created, then builds, tests and documents it inside your own infrastructure. Engagements are fixed-scope, with the domains, certificate sources, renewal method and deliverables agreed in writing before work starts.
How we scope
- We inventory every domain, subdomain and wildcard your gateway must serve, and which ones need client certificate verification.
- We confirm your APISIX version, deployment mode and whether certificates will be stored in etcd or referenced from a secret manager.
- The written scope names the certificate sources, SNI mapping approach, renewal method, test cases and handover documents before any quote is final.
How we build
- We create SSL objects, SNI bindings and any client CA settings in a staging gateway first, then promote them through your change process.
- We wire certificate and key references to your chosen secret store and confirm that no private key is written in plain configuration.
- We test handshakes for each hostname, OCSP stapling behavior and renewal, and record the results against the agreed test list.
How we hand over
- You receive the certificate inventory, SSL object mapping, secret references and renewal runbook, written for the team that will operate them.
- We walk your engineers through how to add a domain, rotate a certificate and check expiry, and confirm they can do it without us.
- Documentation records the APISIX version and any schema changes, so future upgrades start from an accurate baseline.
How we support
- Ongoing support, upgrades and continuous testing are available as a retainer, covering certificate changes and version upgrades.
- A retainer can include periodic expiry review and re-testing of SNI routing after new domains or upgrades are added.
- Ask for the support scope, response arrangements and upgrade handling in writing as part of any quote.
