Skip to Content
TutorialsFirst Cluster

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.yaml

The 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.

Last updated on