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 gateway identity, materialized mTLS files, and the configuration snapshot cache. AISIX stores these under /var/lib/aisix by default.

For a container or Kubernetes deployment, mount /var/lib/aisix as persistent storage when a recreated gateway must reuse its identity and latest accepted configuration without first reconnecting to the control plane. Give each gateway instance its own writable volume.

Issue a Gateway Certificate

1. In the AISIX Cloud dashboard, select the environment the gateway should serve.
2. Open Data planes.
3. Select the certificate validity period and optionally enter a hostname.
4. Select Issue certificate.
5. Copy the generated install snippet for the target deployment.

caution

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), Kubernetes (YAML), and systemd installation tabs. The systemd tab generates the service and credential configuration, but it does not install the executable.

Deploy on Kubernetes

Use the Kubernetes (Helm) tab to install the api7/aisix chart, or use the Kubernetes (YAML) tab to generate a Namespace, Secret, Deployment, and Service that you apply with kubectl.

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, confirm that a compatible aisix-dp executable is installed at /usr/local/bin/aisix-dp, as expected by the generated unit.

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. Mounting only /var/lib/aisix/mtls does not preserve the gateway identity file and snapshot cache.

Verify the Connection

Verify the initial connection before configuring traffic:

1. Confirm that the process starts without certificate, trust-chain, or configuration-store connection errors.
2. In the environment's Data planes view, confirm that the gateway appears with a recent heartbeat.
3. 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 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, /var/lib/aisix/dp_id, and /var/lib/aisix/config_cache.json. A single per-instance mount at /var/lib/aisix covers all three.

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.