Connect a Managed Gateway

In this guide, you will connect a managed gateway to AISIX Cloud with an AISIX Cloud-issued certificate bundle.

The certificate bundle identifies the gateway and the environment it belongs to. After the gateway starts, it uses mutual TLS to report health and telemetry, receive projected configuration, rotate certificates, and check managed budgets.

Managed Gateway Connection

A managed gateway starts with a certificate bundle and a Cloud manager URL. The gateway serves proxy traffic locally, while AISIX Cloud manages the resource configuration projected into that gateway.

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.

Before You Start

Prepare the values issued by AISIX Cloud for the target environment:

• The Cloud manager URL.
• The gateway certificate, private key, and CA bundle.
• A writable state directory for the gateway.
• Outbound network access from the gateway to AISIX Cloud.

The Cloud manager URL must point to the endpoint that accepts managed gateway mTLS traffic. Do not use the AISIX Cloud web console URL or a general control-plane API URL.

The state directory is also part of the managed connection. The gateway writes its persisted mTLS files, gateway identity, and local configuration snapshot under this directory so restarts can reuse the same identity and recover from temporary Cloud connectivity loss.

Start the Managed Gateway

A managed gateway usually starts from the published container image with the managed configuration file selected and the certificate bundle supplied by mounted files.

Start the container with the managed configuration and certificate bundle:

docker run --rm \
  -e AISIX_CONFIG_PATH=/etc/aisix/config.managed.yaml \
  -e AISIX_MANAGED__CP_BASE_URL="https://dpm.example.com:7944" \
  -e AISIX_MANAGED__CP_CERT_FILE="/etc/aisix/mtls/client.crt" \
  -e AISIX_MANAGED__CP_KEY_FILE="/etc/aisix/mtls/client.key" \
  -e AISIX_MANAGED__CP_CA_FILE="/etc/aisix/mtls/ca.crt" \
  -v "$PWD/mtls:/etc/aisix/mtls:ro" \
  -v aisix-state:/var/lib/aisix \
  ghcr.io/api7/ai-gateway:dev

Replace the example URL, certificate paths, and image tag with the values issued for your environment.

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.

Verify Managed Connectivity

After the gateway starts, verify the managed connection in order:

• The process starts without certificate or trust-chain errors.
• AISIX Cloud shows 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 AISIX Cloud.

If heartbeat fails, check the Cloud manager 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 AISIX Cloud or your deployment system injects the bundle directly into the process environment.

Configure	Use
Cloud manager URL	AISIX_MANAGED__CP_BASE_URL
Certificate file	AISIX_MANAGED__CP_CERT_FILE
Private key file	AISIX_MANAGED__CP_KEY_FILE
CA bundle file	AISIX_MANAGED__CP_CA_FILE
Inline certificate	AISIX_MANAGED__CP_CERT_PEM
Inline private key	AISIX_MANAGED__CP_KEY_PEM
Inline CA bundle	AISIX_MANAGED__CP_CA_PEM

The managed configuration derives the Cloud etcd endpoint from the Cloud manager URL unless your deployment supplies a separate etcd endpoint. Use AISIX_MANAGED__CP_ETCD_ENDPOINT only when AISIX Cloud gives you a distinct etcd endpoint for the environment.

Next Steps

You have now seen how a managed gateway connects to AISIX Cloud with certificate-based mTLS. Continue with Resource Projection for how Cloud resources reach the gateway.