First Cluster
Soha supports two cluster connection modes: direct_kubeconfig and agent. Use direct mode for a local or trusted cluster where the control plane can read kubeconfig material. Use agent mode for a private cluster whose Agent initiates a long-lived connection to the Soha access address.
Prerequisites
- A running Soha control plane from First Deploy.
- An access token with cluster-management permissions.
- A kubeconfig path or permission to deploy the generated Agent manifest.
Direct Kubeconfig Registration
Register a direct cluster through the cluster API. Replace the kubeconfig path and metadata before running this against a real environment.
export SOHA_SERVER=http://localhost:8080
export SOHA_TOKEN=replace-with-access-token
curl -sS -X POST "$SOHA_SERVER/api/v1/clusters" \
-H "Authorization: Bearer $SOHA_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"id": "local",
"name": "Local",
"connectionMode": "direct_kubeconfig",
"kubeconfig": "/Users/example/.kube/config",
"context": "local"
}'The API reference name is POST /api/v1/clusters.
Agent Installation
Set the Soha access address in Runtime Configuration, create an Agent connection on the cluster page, and run its short-lived installation command:
kubectl apply -f https://soha.example.com/api/v1/kubernetes/agent-installations/<install-ticket>/manifest.yamlThe cluster-side Agent connects outward to Soha and reconnects automatically. Do not expose an inbound Agent NodePort. See Kubernetes Workbench for capability, Prometheus, and production checks.
Verify Cluster Reads
List registered clusters:
curl -sS "$SOHA_SERVER/api/v1/clusters" \
-H "Authorization: Bearer $SOHA_TOKEN"The API reference name is GET /api/v1/clusters.
Read namespaces from the registered cluster:
curl -sS "$SOHA_SERVER/api/v1/clusters/local/namespaces" \
-H "Authorization: Bearer $SOHA_TOKEN"The API reference name is GET /api/v1/clusters/:clusterID/namespaces.
Expected Output Shape
The concrete cluster metadata depends on your kubeconfig or agent endpoint. Successful responses should include stable identity and list wrappers:
Fixture artifact: first-cluster.expected.txt
POST "$SOHA_SERVER/api/v1/clusters"
GET "$SOHA_SERVER/api/v1/clusters"
GET "$SOHA_SERVER/api/v1/clusters/local/namespaces"{"item": {"id": "local", "name": "Local", "connectionMode": "direct_kubeconfig"}}
{"items": [{"id": "local", "connectionMode": "direct_kubeconfig"}]}
{"items": [{"name": "default", "status": "Active"}]}Exit Criteria
- The cluster appears in the cluster list.
- Namespace reads return data or a clear runtime error.
- Direct clusters report kubeconfig validation errors before registration when credentials are invalid.
- Agent clusters fail with an explicit connectivity or authorization state rather than a silent empty resource list.
Known Limits
Use the live capability matrix instead of assuming Direct and Agent parity. Agent metrics remain partial when the Soha control plane cannot reach the configured Prometheus endpoint, and custom-resource access depends on explicit Kubernetes RBAC for each API group and resource.