Skip to Content
入门教程第一次接入集群

第一次接入集群

Soha 支持两种集群连接模式:direct_kubeconfig 和 agent。本地或可信集群可以使用 direct 模式,让控制平面读取 kubeconfig。内网集群可以使用 agent 模式,由集群内 Agent 主动与 Soha 访问地址建立长连接。

前置条件

  • 已按 第一次部署 启动 Soha 控制平面。
  • 有一个具备 cluster-management 权限的 access token。
  • 有 kubeconfig 路径,或有权限部署生成的 Agent Manifest。

注册 Direct Kubeconfig 集群

通过 cluster API 注册 direct 集群。真实环境执行前请替换 kubeconfig 路径和元数据。

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" }'

API reference 名称是 POST /api/v1/clusters。

安装 Agent

在运行时配置中设置 Soha 访问地址,在集群页面创建 Agent 连接,然后执行短有效期的安装命令:

kubectl apply -f https://soha.example.com/api/v1/kubernetes/agent-installations/<install-ticket>/manifest.yaml

集群内 Agent 主动连接 Soha,并在断开后自动重连。不要暴露入站 Agent NodePort。能力、Prometheus 和生产验收要求见 Kubernetes 工作台。

验证集群读取

列出已注册集群:

curl -sS "$SOHA_SERVER/api/v1/clusters" \ -H "Authorization: Bearer $SOHA_TOKEN"

API reference 名称是 GET /api/v1/clusters。

读取注册集群中的 namespace:

curl -sS "$SOHA_SERVER/api/v1/clusters/local/namespaces" \ -H "Authorization: Bearer $SOHA_TOKEN"

API reference 名称是 GET /api/v1/clusters/:clusterID/namespaces。

预期输出形状

具体集群 metadata 取决于 kubeconfig 或 agent endpoint。成功响应应该包含稳定身份和 list wrapper:

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"}]}

验收标准

  • cluster 出现在集群列表中。
  • Namespace 读取返回数据,或返回清晰的 runtime error。
  • Direct 集群在 credential 无效时,应在注册前报告 kubeconfig validation error。
  • Agent 集群在不可达或未授权时,应返回明确的 connectivity 或 authorization 状态,而不是静默空列表。

已知限制

应使用实时能力矩阵,而不是假设 Direct 与 Agent 完全对等。Soha 控制平面无法访问配置的 Prometheus 时,Agent 指标能力仍为 partial;自定义资源访问则依赖针对每个 API Group 和 Resource 的明确 Kubernetes RBAC。

Last updated on