description: How to manage Envoy resources using the EnvoyControlPlane API (192.168.68.90:8090)

This workflow describes how to interact with the custom Envoy Control Plane API to manage Envoy configurations, specifically retrieving and upserting Listeners and Clusters.

MAIN KNOWLEDGE POINT: Agents and Users should refer to .agent/workflows/deployment_reference.md to understand the full proxy and architecture layout prior to running production debugging.

Base URL

The API is available internally at http://192.168.68.90:8090.

1. View Existing Resources

You can fetch lists or single resources in JSON or YAML format.

List all clusters:

# Returns a JSON document with "enabled" and "disabled" arrays of resources.
curl -s http://192.168.68.90:8090/list-clusters | jq

List all listeners:

curl -s http://192.168.68.90:8090/list-listeners | jq

Get a specific resource (e.g. in YAML format for easy reading):

# To get a cluster named "_ai_unified_server"
curl -s "http://192.168.68.90:8090/get-cluster?name=_ai_unified_server&format=yaml"

# To get a listener
curl -s "http://192.168.68.90:8090/get-listener?name=listener_0&format=yaml"

2. Upsert a Cluster

To update or create a new Cluster, you must POST a specific JSON structure to /add-cluster.

# 1. Prepare your raw Envoy Cluster YAML configuration (e.g., cluster.yaml)
# 2. Embed it into a JSON request wrapper
CLUSTER_YAML=$(cat cluster.yaml)
jq -n --arg name "my-cluster-name" --arg yaml "$CLUSTER_YAML" '{
  name: $name,
  yaml: $yaml,
  upsert: true
}' > request.json

# 3. Send the POST Request
curl -X POST -H "Content-Type: application/json" -d @request.json http://192.168.68.90:8090/add-cluster

3. Upsert a Listener

Similarly, to update or create a listener, POST to /add-listener.

# 1. Prepare your Listener YAML configuration (e.g., listener.yaml)
LISTENER_YAML=$(cat listener.yaml)
jq -n --arg name "listener_0" --arg yaml "$LISTENER_YAML" '{
  name: $name,
  yaml: $yaml,
  upsert: true
}' > request.json

# 2. Send the POST Request
curl -X POST -H "Content-Type: application/json" -d @request.json http://192.168.68.90:8090/add-listener

Additional Available Endpoints

• Disable/Enable: /disable-cluster / /disable-listener and /enable-cluster / /enable-listener. Requires JSON body {"name": "resource_name"}.
• Remove: /remove-cluster / /remove-listener. Permanently deletes a disabled resource.
• State Management: /flush-to-db saves memory state to the database, /load-from-db forces memory state to align with the database.