---
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:**
```bash
# 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:**
```bash
curl -s http://192.168.68.90:8090/list-listeners | jq
```

**Get a specific resource (e.g. in YAML format for easy reading):**
```bash
# 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`.

```bash
# 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`.

```bash
# 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.
