Network and Security
Treat the proxy listener, metrics/status listener, etcd, and AISIX Cloud control-plane connection as separate trust zones.
Network Surfaces
Use this map to decide what can be reachable from each network:
| Surface | What it carries | Exposure |
|---|---|---|
| Proxy listener | Caller-facing AI traffic, such as /v1/chat/completions | Intended callers or the ingress tier |
| Metrics/status listener | Prometheus metrics plus configuration and model status | Trusted monitoring network |
| Configuration store | Dynamic resources for open-source AISIX gateways configured through etcd | AISIX and configuration-management systems only |
| AISIX Cloud control-plane connection | mTLS-authenticated gateway communication with the AISIX Cloud control plane | Outbound mTLS path to the control plane |
Expose only the proxy listener to callers. Keep metrics/status and etcd on private networks. The metrics path and /status/* routes are unauthenticated and served on the dedicated metrics/status listener. Model status includes model IDs and display names, so do not expose this listener publicly.
Use TLS or mTLS where network placement requires encrypted or mutually authenticated transport. When etcd mTLS is enabled, the startup configuration must point to the CA, client certificate, and client key files that the gateway process can read.
Expose the Proxy Listener
Keep the gateway on a non-privileged container port unless it must bind directly below 1024. Publish the caller-facing port through a load balancer, ingress, or service instead of widening access to the other listeners.
The published AISIX image runs as non-root UID 10001. Its gateway binary carries the effective CAP_NET_BIND_SERVICE file capability, so it can bind ports such as 80 and 443 without running as root. A runtime policy that prevents the capability from being granted can make the container fail at startup with exec: Operation not permitted.
Terminate TLS either on the AISIX proxy listener or at the trusted ingress tier in front of it. When another proxy terminates or forwards traffic, configure real-client-IP resolution only for the exact trusted proxy ranges and forwarded header.
For AISIX gateways that run on Kubernetes and connect to AISIX Cloud, see Deploy AISIX Gateways on Kubernetes for Service exposure, container capabilities, autoscaling, and disruption handling.
Credential Boundaries
Caller credentials and upstream provider credentials have different storage and forwarding rules:
| Credential or Secret | How AISIX Uses It | Protect |
|---|---|---|
| Caller API key | Stored as a hash; plaintext is held by the calling application | Application secret storage and API key rotation workflow |
| OIDC-issued JWT | Signature and claims are verified, then the identity maps to a caller API key | Application token storage, OIDC trust-provider policy, and identity-provider availability |
| Provider key | Used to authenticate upstream provider requests | Resources file or configuration store, environment variables, and backups |
| Observability exporter credential | Sent to or resolved for the configured telemetry destination | Dynamic resource store and observability configuration access |
| AISIX Cloud certificate bundle | Authenticates an AISIX gateway to the control plane | Runtime state directory, trust root, and control-plane bootstrap process |
For open-source AISIX gateways, provider credentials can be referenced from environment variables in a resources file or stored in the configuration store. OTLP HTTP exporter headers can be stored in dynamic configuration. Object-storage, Aliyun SLS, and Datadog exporters use credential references that the gateway resolves locally.
Treat resources files, etcd, environment variables, and backups as secret-bearing surfaces. In AISIX Cloud deployments, the control plane handles provider keys and projects runtime configuration to the AISIX gateway.
AISIX authenticates each caller with a caller API key or an OIDC-issued JWT and authenticates upstream requests with provider credentials. A verified JWT maps to a caller API key before AISIX applies access and traffic controls. Passthrough strips sensitive inbound headers by default. Provider-key strip settings can affect what is forwarded, so keep credential-bearing headers such as authorization, cookie, and x-api-key stripped unless a specific upstream integration requires otherwise.
Security Baseline
Confirm these controls before routing production traffic:
- The proxy listener is reachable only from intended callers or ingress.
- Metrics endpoints are private.
- etcd is private, persistent, backed up, and access-controlled when it stores open-source AISIX gateway resources.
- Provider-key secrets and exporter credentials are treated as sensitive operational data.
- OIDC trust providers pin the expected issuer and audiences, and their discovery and JWKS endpoints are reviewed as outbound trust destinations.
- Listener TLS, etcd mTLS, or AISIX Cloud mTLS is configured where the deployment requires encrypted or mutually authenticated transport.
- For gateways connected to AISIX Cloud, gateway identity is validated through the certificate-based bootstrap path.
- Backups and observability pipelines do not expose dynamic resource payloads or provider credentials.
Next Steps
Continue with TLS and mTLS to configure transport security for each connection in your deployment.