agentscope-ai / agentscope-ai/AgentTeams

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

Offen
#924 0 Kommentare 0 Reaktionen 1 zugewiesene Person Beansprucht von @googs1025 Auf GitHub ansehen
area:container-k8s enhancement
Vorherrschende Sprache
Go
Sterne
5.6k
Forks
692
Ø Merge
5 T. 4 Std.
Gemergte PRs (30 T.)
23

Beschreibung

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

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.