Skip to main content
API7.ai Logo

Managed Gateway

A managed gateway serves live AI traffic in your runtime environment while connecting to the AISIX managed control plane for configuration, telemetry, certificate rotation, and managed 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.

Managed Gateway Connection​

A managed 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 managed 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. A managed gateway also needs outbound network access to the control plane and a writable state directory.

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

The state directory is also part of the managed 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 managed 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 managed 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 managed 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 managed gateway.
  • A live request through the managed 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.

Managed 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 managed configuration derives the managed 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 managed gateway traffic path.