Skip to main content
API7.ai Logo

Production Deployment

Before sending production traffic through AISIX, confirm its management model, runtime dependencies, network exposure, health checks, and shutdown behavior. These checks turn a working development gateway into a controlled production traffic path.

Choose the Deployment Mode​

Choose an operating model before planning the rest of the deployment. Deployment Options compares the open-source self-hosted gateway, AISIX Cloud, and AISIX Cloud On-Premises.

For a self-hosted gateway, plan a private Admin API path and a reachable etcd configuration store. You manage provider keys, model aliases, caller API keys, and policy resources through that local path.

For AISIX Cloud or AISIX Cloud On-Premises, plan the managed mTLS connection, certificate bundle, and control-plane reachability. The control plane projects resources to the gateway; the local admin listener and local playground are not exposed.

Use the selected option consistently throughout the remaining production checks. Do not mix a managed configuration path with self-hosted Admin API assumptions.

Prepare the Runtime Dependencies​

In self-hosted deployments, run etcd outside the gateway process and keep it private to AISIX and the systems that manage gateway configuration.

Plan persistence, backups, and access control before accepting production traffic. Etcd stores dynamic resources, including sensitive provider credentials and policy configuration.

Start with memory-backed cache policies unless multiple gateway instances must share cached responses. When a cache policy selects Redis, configure cache.redis for the selected single, cluster, or Sentinel topology; the policy does not silently fall back to memory when Redis is unavailable.

Rate-limit counters use local process memory by default. For multi-instance deployments where request, token, or concurrency caps must apply across the whole gateway group, configure ratelimit.backend: redis and point every instance at the same Redis backend.

Keep process-level settings in startup configuration. Load dynamic resources such as provider keys, model aliases, caller API keys, guardrails, cache policies, and observability exporters from the configuration store.

Set the Listener Baseline​

Expose the proxy listener only to intended callers or the ingress tier that fronts them.

In self-hosted deployments, bind the admin listener to loopback, a private subnet, or an admin-only network. Do not expose admin or OpenAPI endpoints publicly.

Prometheus metrics and operational /status/* routes are unauthenticated and served on a dedicated metrics/status listener. Keep that listener private and allow access only from trusted monitoring infrastructure. Verify the address and metrics path set by your startup configuration.

Enable listener TLS when proxy or admin traffic leaves a trusted local boundary. Configure etcd mTLS when the configuration store requires an encrypted, mutually authenticated connection.

In managed deployments, verify the certificate bundle and control-plane URL before troubleshooting higher-level configuration projection.

Verify before Routing Traffic​

Liveness proves that the process is running, not that it can serve an authorized model request. Verify the listeners first, then exercise the complete caller-to-provider path.

Set the proxy URL and, for a self-hosted gateway, the admin URL and key:

PROXY_URL="https://gateway.example.com"
ADMIN_URL="https://admin.internal.example.com"
AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"

Check proxy liveness on the proxy listener:

curl -i "${PROXY_URL}/livez"

For self-hosted deployments, also check admin liveness on the private admin listener:

curl -i "${ADMIN_URL}/livez"

For a self-hosted gateway, inspect model health and configuration freshness through the Admin API:

curl -sS "${ADMIN_URL}/admin/v1/health" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}"

After the listeners respond, verify behavior that liveness cannot prove:

  • Call GET /v1/models with the same caller API key the application will use.
  • Send one provider-backed request for every endpoint family you plan to expose.
  • Find the smoke-test request in logs, metrics, headers, usage events, or exporter output.
  • Send an invalid or unauthorized caller API key and confirm that access control rejects it.

Shutdown Behavior​

AISIX handles graceful shutdown on SIGINT and SIGTERM. During shutdown, the server stops accepting new work, coordinates listener shutdown with background tasks, and marks liveness as failing.

During an intentional drain, AISIX marks /livez as failed so load balancers or orchestration probes can remove the instance from service. GET /livez is a liveness signal, not a full readiness or traffic-drain contract.

Before Widening Traffic​

Before exposing production traffic broadly, confirm these conditions:

  • The startup config matches the intended deployment mode.
  • The proxy listener is reachable only through the intended network path.
  • The admin listener is private in self-hosted deployments.
  • The configuration store is private and reachable from the gateway.
  • TLS, mTLS, and certificate file paths are valid for the transports that use them.
  • At least one provider key, model alias, and caller API key have been created.
  • The model alias appears through the caller-facing proxy path.
  • A real provider-backed request succeeds through the gateway.
  • Operational signals show the smoke-test request.

If the process is live but a real request fails, troubleshoot the request path. Check model visibility, configuration propagation, caller API key access, provider credentials, and upstream connectivity before widening traffic.

Next Steps​

Continue with Network and Security for listener and secret handling, TLS and mTLS for transport security, and Health Checks for process, traffic, model, and configuration health.