agentscope-ai / agentscope-ai/AgentTeams
feat(crd): add status.conditions for reconcile observability
- 主要語言
- Go
- 星號
- 5.6k
- 分支
- 692
- 平均合併
- 5 天 4 小時
- 30 天內合併 PR
- 23
描述
## Summary
Add standard `status.conditions` to HiClaw CRDs (`Manager`, `Worker`, `Team`, and `Human`) so operators, CLIs, and future monitoring UIs can understand where reconciliation is blocked.
Related: #209, #555, #503
## Current behavior
Current status fields are useful but coarse:
- `ManagerStatus` has `phase`, `message`, `matrixUserID`, `roomID`, `containerState`, etc.
- `WorkerStatus` has `phase`, `message`, `matrixUserID`, `roomID`, `containerState`, `exposedPorts`, etc.
- `TeamStatus` has `phase`, `message`, room IDs, readiness counts, and member status.
- `HumanStatus` has `phase`, `message`, `matrixUserID`, `rooms`, etc.
The missing piece is a structured, Kubernetes-native way to answer:
- Did Matrix provisioning succeed?
- Is the room ready?
- Is gateway auth ready?
- Is object-storage/config sync complete?
- Is the Pod/container running?
- Which step failed most recently, and when?
This directly supports the observability request in #209 and helps make partial reconcile failures in #555/#503 visible.
## Proposed API
Add a `conditions` field to each CRD status using Kubernetes condition semantics, preferably `[]metav1.Condition`:
```yaml
status:
conditions:
- type: InfrastructureReady
status: "True"
reason: Provisioned
message: Matrix user, room, gateway consumer, and storage credentials are ready.
observedGeneration: 3
lastTransitionTime: "2026-06-10T10:00:00Z"
- type: ConfigSynced
status: "True"
reason: Synced
message: Workspace config and skills are synced to object storage.
observedGeneration: 3
lastTransitionTime: "2026-06-10T10:00:05Z"
- type: PodReady
status: "False"
reason: ImagePullBackOff
message: Worker Pod failed to pull image.
observedGeneration: 3
lastTransitionTime: "2026-06-10T10:00:30Z"
```
## Suggested condition types
For `Manager` and `Worker`:
- `InfrastructureReady` - Matrix account/room, gateway consumer/key, storage credentials.
- `ServiceAccountReady` - Kubernetes ServiceAccount exists and token projection can be used.
- `ConfigSynced` - package, inline config, mcporter, skills pushed to storage.
- `PodReady` or `ContainerReady` - backend Pod/container is present and healthy enough.
- `ExposedPortsReady` - only when `spec.expose` is used.
- `Ready` - aggregate condition for user-facing readiness.
For `Team`:
- `TeamRoomsReady` - Team Room and Leader DM exist.
- `TeamStorageReady` - shared team storage initialized.
- `MembersReady` - all desired members reconciled.
- `Ready` - aggregate condition.
For `Human`:
- `MatrixUserReady` - human Matrix account exists and display name is synced.
- `RoomAccessReady` - desired room membership/invites are reconciled.
- `Ready` - aggregate condition.
## Why this is needed
This would improve several user/operator workflows:
- `kubectl wait --for=condition=Ready worker/alice`
- CLI and UI can show the exact blocked phase instead of only `phase/message`.
- GitOps tools can evaluate health more reliably.
- Partial failures during Matrix/Higress/storage/Pod creation become visible.
- Team member readiness can be summarized without parsing logs.
## Implementation notes
Suggested implementation shape:
1. Add `Conditions []metav1.Condition` to all status structs.
2. Add helper functions for setting/updating conditions consistently.
3. Update conditions at the end of each reconcile phase:
- infra
- service account
- config deploy
- container/pod
- expose
- room membership
4. Keep existing `phase` and `message` fields for backward compatibility.
5. Add printer columns later if useful, but avoid bloating default `kubectl get` output initially.
6. Add unit tests for condition transitions on success, partial failure, and recovery.
## Acceptance criteria
- `Manager`, `Worker`, `Team`, and `Human` CRDs expose `status.conditions`.
- Conditions include `type`, `status`, `reason`, `message`, `observedGeneration`, and `lastTransitionTime`.
- At least one aggregate `Ready` condition exists for each resource type.
- Failed reconcile steps update a relevant condition with actionable reason/message.
- Existing `phase` and status fields remain compatible.
- Docs and examples mention how to inspect and wait on conditions.
貢獻指南
這個儲存庫沒有索引到貢獻指南
評估
這個 Issue 還沒有評估資料。