Agent Protocol
Goal
The soha agent protocol gives the platform a stable way to talk to remote clusters when direct kubeconfig connectivity is not desired or is not possible.
The backend stores agent connection metadata in PostgreSQL, then the Gin API calls the agent over HTTP for summary, resource list, and controlled execution requests.
Registration Model
Platform registration payload:
{
"id": "edge-prod-01",
"name": "Edge Production 01",
"region": "cn-shanghai",
"environment": "production",
"connectionMode": "agent",
"agentEndpoint": "https://agent.example.internal",
"agentToken": "optional-bearer-token"
}Persisted storage:
clusters.connection_mode = agentcluster_credentials_meta.credential_type = bearercluster_credentials_meta.source_type = agentcluster_credentials_meta.metadata.endpointcluster_credentials_meta.metadata.token
Required Agent Endpoints
Summary
GET /api/v1/platform/summary
Response:
{
"data": {
"id": "edge-prod-01",
"name": "Edge Production 01",
"region": "cn-shanghai",
"environment": "production",
"labels": { "provider": "agent" },
"connectionMode": "agent",
"version": "v1.31.2",
"capabilities": ["apps", "batch", "networking.k8s.io"],
"health": {
"status": "healthy",
"message": "ok",
"lastChecked": "2026-03-22T10:00:00Z"
}
}
}Namespaces
GET /api/v1/platform/namespaces
Response:
{
"items": [
{
"name": "default",
"status": "Active",
"labels": {},
"ageSeconds": 3600,
"allowedActions": ["view", "list"]
}
]
}Pods
GET /api/v1/platform/workloads/pods?namespace=default
Deployments
GET /api/v1/platform/workloads/deployments?namespace=default
Controlled Action Endpoints
Restart Deployment
POST /api/v1/platform/actions/deployments/restart
Request:
{
"namespace": "default",
"name": "api"
}Scale Deployment
POST /api/v1/platform/actions/deployments/scale
Request:
{
"namespace": "default",
"name": "api",
"replicas": 3
}Authentication
When agentToken is configured, soha sends:
Authorization: Bearer <token>Recommended agent behavior:
- verify bearer token before any platform call
- separate read endpoints from execution endpoints
- keep execution endpoints explicitly allow-listed
Error Contract
Agent errors should return normal HTTP error codes. soha maps downstream connection or execution failures into cluster_unavailable when the remote agent cannot be reached or rejects the operation.
Authorization Boundary
The platform remains the primary authorization decision point.
That means:
- RBAC + ABAC is evaluated in soha before the agent call
- the agent should still validate its own bearer token
- the agent should not assume the caller is trusted just because the request comes from soha
- high-risk actions should stay narrow and explicit
Current Platform Usage
Current backend usage of the agent protocol:
- cluster health snapshot sync via summary endpoint
- resource list reads for namespaces, pods, deployments
- workload actions including deployment restart and scale
- bounded container logs and supported streaming interfaces
- YAML fetch
- events
- exec
- rollout history
Agent mode provides these capabilities through a reverse connection initiated by the in-cluster Agent. Availability depends on the running Agent version, installation preset, security.allowed_actions, and Kubernetes RBAC; an implemented action is not automatically authorized in every installation.
Use the platform capability matrix and Kubernetes Workbench as the operational references. The authenticated GET /api/v1/diagnostics/actions endpoint helps inspect implemented actions, configured allowlists, and authorization readiness; diagnostic reads do not authorize mutations.