Connect an AISIX Gateway
In an AISIX Cloud deployment, the AISIX gateway runs as the data plane in your infrastructure. Add a gateway to an environment so it can receive configuration, report heartbeats and telemetry, and request budget decisions. Live AI requests go directly to the gateway and do not pass through the control plane.
The gateway initiates outbound management connections authenticated with a certificate bundle issued for one AISIX Cloud environment.
How the Connection Works
The certificate bundle contains a client certificate, private key, and CA certificate. The client certificate identifies the gateway and the environment it serves.
AISIX uses the same certificate identity for the configuration watch and the gateway management APIs. The configured management endpoint is also the base for heartbeat, telemetry, and budget-check requests. The gateway derives the configuration-store endpoint from that URL unless the deployment supplies a separate endpoint.
Prerequisites
Before connecting the gateway, prepare:
- An AISIX Cloud environment for the gateway.
- Outbound network access from the gateway host or cluster to the gateway management endpoint.
- A secret store for the client certificate and private key.
- Writable local storage for the gateway identity and materialized mTLS files. AISIX stores these under
/var/lib/aisixby default.
The state directory must be writable so the gateway can materialize its certificate bundle and identity. The generated container and Kubernetes instructions provide the bundle again at each start, so those files do not require persistent storage. To recover a successfully persisted configuration snapshot without first reconnecting to the control plane, enable the snapshot cache and mount its state directory on persistent storage. A persistent volume alone does not enable the cache. For this recovery, give each gateway instance its own volume and follow Restart from Cached Configuration.
Issue a Gateway Certificate
- In the AISIX Cloud dashboard, select the environment the gateway should serve.
- Open Data planes.
- Select the certificate validity period and optionally enter a hostname.
- Select Issue certificate.
- Copy the generated install snippet for the target deployment.
The private key appears only in the certificate-issuance response. Copy the bundle immediately, store it in your deployment secret system, and do not commit or share the generated snippet.
The dashboard provides Docker, Docker Compose, Kubernetes (Helm), and systemd installation tabs. The systemd tab generates the service and credential configuration, but it does not install the executable or the managed startup configuration.
Deploy on Kubernetes
Use the Kubernetes (Helm) tab to install the api7/aisix chart. The chart is the only Kubernetes path the dashboard generates, because it carries the settings a gateway needs to stop without dropping traffic — a preStop pause and a termination grace period sized to cover the drain — which a hand-written manifest leaves at the Kubernetes defaults.
For a chart-managed production deployment with autoscaling, disruption budgets, and Prometheus integration, follow Deploy AISIX Gateways on Kubernetes.
Start the Gateway
Run the generated instructions in the target runtime environment. Before using the systemd instructions:
- Install a compatible
aisix-dpexecutable at/usr/local/bin/aisix-dp. - Copy
config.managed.yamlto/etc/aisix/config.managed.yaml. - In the generated unit, remove the
AISIX_CONFIG_PATHenvironment assignment and append--config /etc/aisix/config.managed.yamltoExecStart.AISIX_CONFIG_PATHbelongs to the container entrypoint and is not a binary option.
The generated configuration binds the proxy listener to port 3000 and the metrics and status listener to port 9090 by default. See the Port Reference for listener exposure and outbound control-plane connectivity.
Make /var/lib/aisix writable by the same user that runs the gateway. A mount limited to /var/lib/aisix/mtls leaves the gateway identity file and, when enabled, the snapshot cache outside that mount.
Verify the Connection
Verify the initial connection before configuring traffic:
- Confirm that the process starts without certificate, trust-chain, or configuration-store connection errors.
- In the environment's Data planes view, confirm that the gateway appears with a recent heartbeat.
- Confirm that the reported hostname and certificate ID identify the intended deployment and environment.
After configuring a provider, model alias, and caller API key, verify the end-to-end data path. Confirm that projected resources reach the gateway, a live request succeeds, and its usage or telemetry appears in the control plane.
If the gateway does not appear, check the management endpoint, certificate bundle, trust root, file permissions, state directory, and outbound network access. A healthy heartbeat confirms the management API path, but it does not prove that a resource change has reached every gateway instance. Use Resource Projection after saving the first provider key, model, and caller API key.
AISIX Cloud Connection Configuration
Provide the certificate, key, and CA together. Use file-path variables when the bundle is mounted as files, or inline variables when the deployment system injects PEM content. Do not configure both forms for the same certificate role.
| Configure | Use |
|---|---|
| Gateway management base URL | AISIX_MANAGED__CP_BASE_URL |
| Separate configuration-store endpoint | AISIX_MANAGED__CP_ETCD_ENDPOINT |
| Certificate file | AISIX_MANAGED__CP_CERT_FILE |
| Private key file | AISIX_MANAGED__CP_KEY_FILE |
| CA certificate file | AISIX_MANAGED__CP_CA_FILE |
| Inline certificate | AISIX_MANAGED__CP_CERT_PEM |
| Inline private key | AISIX_MANAGED__CP_KEY_PEM |
| Inline CA certificate | AISIX_MANAGED__CP_CA_PEM |
| Materialized mTLS directory | AISIX_MANAGED__MTLS_DIR |
| Gateway identity file | AISIX_MANAGED__DP_ID_FILE |
| Snapshot cache switch | AISIX_MANAGED__SNAPSHOT_CACHE_ENABLED |
| Snapshot cache file | AISIX_MANAGED__SNAPSHOT_CACHE_PATH |
Set AISIX_MANAGED__CP_ETCD_ENDPOINT only when the control plane provides a configuration-store endpoint that differs from the gateway management base URL. Specify this endpoint as host:port without a URL scheme.
The default state paths are /var/lib/aisix/mtls and /var/lib/aisix/dp_id. The optional snapshot cache uses /var/lib/aisix/config_cache.json only when AISIX_MANAGED__SNAPSHOT_CACHE_ENABLED=true; it is disabled by default. A per-instance volume at /var/lib/aisix covers these paths.
Next Steps
Continue with Choose a Provider Upstream. Each provider guide creates a provider key, model alias, and caller API key, then verifies the configuration with a live request through the connected gateway.
If a saved resource does not affect live traffic as expected, use Resource Projection to trace how environment configuration reaches the gateway.