agentscope-ai / agentscope-ai/AgentTeams

feat(crd): add status.conditions for reconcile observability

未關閉
#924 0 則留言 0 個 reaction 已指派 1 人 已被 @googs1025 認領 在 GitHub 檢視
area:container-k8s enhancement
主要語言
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 還沒有評估資料。

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。