Network and Security

Treat the proxy listener, admin listener, metrics/status listener, etcd, and managed 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
Admin listener	Admin API, admin health, OpenAPI, and playground	Loopback, private subnet, or admin-only network
Metrics/status listener	Prometheus metrics plus configuration and model status	Trusted monitoring network
Configuration store	Dynamic gateway resources in etcd for self-hosted deployments	AISIX and configuration-management systems only
Managed control-plane connection	mTLS-authenticated gateway communication with the AISIX managed control plane	Outbound mTLS path to the control plane

Expose only the proxy listener to callers. Keep admin, metrics/status, OpenAPI, playground, 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.

Choose a Privileged-Port Strategy

Use a privileged container port only when AISIX must bind directly to a port below 1024. Otherwise, keep the gateway listener on a non-privileged port and map the caller-facing port through a Service, ingress, or load balancer.

The published AISIX container image runs as a non-root user with UID 10001. Its gateway binary has the effective CAP_NET_BIND_SERVICE file capability, so the process can bind listener ports below 1024 without running as root. The default Docker and containerd capability sets include this capability, so a default deployment does not need an additional capability setting.

The container's capability and the way Kubernetes exposes a port are separate decisions. Choose the pattern that fits the cluster security policy.

Retain the Image Capability

Kubernetes spells the capability NET_BIND_SERVICE in a container securityContext. If the pod drops all capabilities, add this capability back for the published AISIX image, even when the configured listener uses a non-privileged port:

securityContext:
  capabilities:
    drop: ["ALL"]
    add: ["NET_BIND_SERVICE"]

The Kubernetes Restricted Pod Security Standard allows NET_BIND_SERVICE to be added back after dropping all capabilities. The rest of the pod specification must still meet the standard. Because the binary's file capability has the effective bit set, the container can fail during startup with exec: Operation not permitted if the runtime prevents that capability from being granted.

Expose a Service Port

AISIX does not need to bind a privileged container port for callers to use port 443. A Kubernetes Service can map its external service port to the proxy port configured for the gateway container:

# Service spec excerpt
ports:
  - name: https
    port: 443
    targetPort: 3000

In this example, targetPort: 3000 is the configured proxy listener rather than a fixed runtime port. The Service mapping avoids binding a privileged port inside the container, but it does not remove the published image's capability requirement described above. Terminate TLS on that AISIX listener or at the ingress or load balancer in front of the Service when callers use HTTPS.

Use hostNetwork or hostPort only when the gateway must bind directly on a node and the cluster policy explicitly allows it. The built-in Baseline and Restricted Pod Security Standards disallow host networking and nonzero host ports. These modes also introduce node-port conflicts and reduce network isolation, so they should not be presented as substitutes for a Service.

Credential Boundaries

Caller API keys 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
Provider key	Used to authenticate upstream provider requests	Configuration store, admin access, and backups
Observability exporter credential	Sent to or resolved for the configured telemetry destination	Dynamic resource store and observability configuration access
Managed certificate bundle	Authenticates a managed gateway to the control plane	Runtime state directory, trust root, and managed bootstrap process

In self-hosted deployments, provider credentials can live 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 etcd, backups, and the Admin API access path as secret-bearing surfaces. In managed deployments, the control plane handles provider keys and projects runtime configuration to the managed gateway.

AISIX authenticates callers with caller API keys and authenticates upstream requests with provider credentials. 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.
• The admin listener is private in self-hosted deployments.
• Metrics endpoints are private.
• etcd is private, persistent, backed up, and access-controlled in self-hosted deployments.
• Provider-key secrets and exporter credentials are treated as sensitive operational data.
• Listener TLS, etcd mTLS, or managed mTLS is configured where the deployment requires encrypted or mutually authenticated transport.
• Managed 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

You have now seen the network and credential boundaries to protect before exposing AISIX. Continue with TLS and mTLS for transport security.