Skip to main content
API7.ai Logo

Connect an AISIX Gateway

An AISIX gateway serves live AI traffic in your runtime environment while connecting to the AISIX Cloud control plane for configuration, telemetry, certificate rotation, and budget checks.

The connection uses a certificate bundle issued by the control plane. The bundle identifies the gateway and its environment, then lets the gateway authenticate with mutual TLS.

Connect the Gateway​

An AISIX gateway starts with a certificate bundle and control-plane URL. The gateway serves proxy traffic locally while the control plane projects resource configuration to it.

Use the certificate bundle issued for the same environment the AISIX gateway should serve. The bundle includes a client certificate, private key, and CA bundle. Provide all three values together, either as inline PEM values or as file paths.

Get Connection Values​

From the environment's Data planes view, issue the control-plane URL, gateway certificate, private key, and CA bundle. The same view generates install snippets for common deployment targets. An AISIX gateway also needs outbound network access to the control plane and a writable state directory.

Hybrid Cloud supplies the API7-hosted control-plane endpoint. On-Premises uses the data-plane manager endpoint configured for that installation.

The state directory is also part of the control-plane connection. The gateway stores its mTLS files, gateway identity, and local configuration snapshot there. Restarts can then reuse the same identity and recover from temporary control-plane connectivity loss.

Start the Gateway​

In the target environment, open Data planes, issue a gateway certificate, choose the deployment target, and copy the generated install snippet.

Treat the generated snippet as sensitive because it includes one-time certificate material for the AISIX gateway. Store it in your deployment secret system and avoid committing or sharing it.

If you use inline PEM values instead of files, provide the certificate, key, and CA PEM variables together. Do not mix inline PEM and file-path values for the same certificate role.

The AISIX Cloud configuration binds the proxy listener to port 3000 and the dedicated metrics listener to port 9090 by default. It does not bind the local admin listener.

If you run the binary directly, use the equivalent --config flag or AISIX_CONFIG environment variable:

aisix --config /path/to/config.managed.yaml

Make the state directory writable by the same user that runs the gateway. Mounting only the certificate subdirectory is not enough because the process also writes gateway identity and snapshot files under the state directory.

Connectivity Signals​

After the gateway starts, verify the control-plane connection in order:

  • The process starts without certificate or trust-chain errors.
  • The control plane shows a healthy registered data plane with a recent heartbeat for the expected environment.
  • Projected resources reach the AISIX gateway.
  • A live request through the AISIX gateway endpoint succeeds.
  • Usage or telemetry for that request appears in the control plane.

If heartbeat fails, check the control plane URL, certificate bundle, trust root, file permissions, state directory, and outbound network access. If heartbeat is healthy but resources or live traffic do not behave as expected, continue with Resource Projection.

AISIX Cloud Connection Configuration​

Use file-path variables when certificates are mounted as files. Use inline PEM variables when the control plane or your deployment system injects the bundle directly into the process environment.

ConfigureUse
Control-plane URLAISIX_MANAGED__CP_BASE_URL
Certificate fileAISIX_MANAGED__CP_CERT_FILE
Private key fileAISIX_MANAGED__CP_KEY_FILE
CA bundle fileAISIX_MANAGED__CP_CA_FILE
Inline certificateAISIX_MANAGED__CP_CERT_PEM
Inline private keyAISIX_MANAGED__CP_KEY_PEM
Inline CA bundleAISIX_MANAGED__CP_CA_PEM

The gateway derives the control-plane etcd endpoint from the control-plane URL unless your deployment supplies a separate endpoint. Use AISIX_MANAGED__CP_ETCD_ENDPOINT only when the control plane provides a distinct etcd endpoint for the environment.

Next Steps​

Continue with High Availability to design a redundant AISIX gateway traffic path.