Skip to content

Commit f475d8b

Browse files
authored
docs: align control-plane docs with the current API and CLI (agent-substrate#3404)
Several control-plane docs and the `kubectl-ate` reference still described earlier field names (`durableSnapshot.status`, `source_snapshot_tag`), empty-atespace rules, and older CLI columns and flags. Updates them to match the current implementation: - `docs/reference/glossary.md`: lists `Tag` under control-plane records, and notes that deleting an atespace requires its actors, actor templates, and tags to be gone. - `docs/reference/api-guide.md`: fixes `durableSnapshot.state`, documents deletion checks on `CreateActor` and `UpdateActor`, and adds `GetWorker` and `ListWorkerActorAssignments`. - `docs/api-style-guide.md`: renames `source_snapshot_tag` to `source_tag`. - `docs/guides/authorization.md`: `CreateActor` skips `can_use_tag` when `sourceTag` is omitted. - `docs/reference/kubectl-ate.md`: documents `--preview`, `--sandbox-class`, `top workers`, the current `get worker` and `get actor` columns, template removal before `delete atespace`, and automatic snapshot upload on `create tag`. AI use: AI-assisted to audit control-plane docs against the codebase and draft the documentation updates. I reviewed and verified the changes. - [x] Tests pass - [x] Docs updated Signed-off-by: Haiyan Meng <[email protected]>
1 parent 5e22427 commit f475d8b

5 files changed

Lines changed: 38 additions & 23 deletions

File tree

‎docs/api-style-guide.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -283,7 +283,7 @@ Rules:
283283
- RPC name **must** begin with `Update` followed by the singular resource name.
284284
- Response **must** be the resource itself — not an `UpdateActorResponse` wrapper.
285285
- **Output-only** fields — server-managed, never set by the client (`uid`, `version`, `create_time`, `update_time`, `delete_time`, and the whole `status` submessage). Whatever the request carries in them is ignored and the server's own values are kept.
286-
- **Immutable** fields — caller-set at creation but fixed thereafter (`atespace`, `name`, and resource-specific ones such as an actor's `source_snapshot_tag`). A request that changes one - including by omitting it, which would clear it - **must** return `INVALID_ARGUMENT` naming the field.
286+
- **Immutable** fields (`atespace`, `name`, and resource-specific ones such as an actor's `source_tag`) are caller-set at creation and fixed thereafter. A request that changes one, including by omitting it, **must** return `INVALID_ARGUMENT` naming the field.
287287
- The embedded resource field **must** be named after the resource's own snake_case type name (e.g. `actor` for `Actor`), not a generic name like `resource` or `body`.
288288
- The request **must** have no other fields, apart from its parent's `ObjectRef` for a subresource (see section #2.4).
289289
- A request carrying a field the server does not know, at any level of nesting, **must** return `INVALID_ARGUMENT` naming the field, as for every RPC. Fields only the client does not know are a different case: a client that modifies the resource it read sends them back unchanged, so an update from an older client does not clear fields a newer server set.

‎docs/guides/authorization.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -183,7 +183,7 @@ viewer, and a global role holds the same role in every atespace. So
183183
| `GetActorTemplate` | `can_get`, the template | Viewer of its atespace |
184184
| `DeleteActorTemplate` | `can_delete`, the template | Editor of its atespace |
185185
| `ListActorTemplates` | `can_list_actor_templates`, the atespace, or global if none is given | Atespace viewer; global viewer for all atespaces |
186-
| `CreateActor` | 1. `can_create_actor`, the actor's atespace<br>2. `can_use_template`, the actor template<br>3. `can_use_tag`, the `sourceTag`, if one is given | 1. Atespace editor<br>2. Viewer of the template's atespace, which may be another one<br>3. Editor of the tag's atespace. Golden tags skip this check: the handler only accepts one built from the actor's own template. |
186+
| `CreateActor` | 1. `can_create_actor`, the actor's atespace<br>2. `can_use_template`, the actor template<br>3. `can_use_tag`, the `sourceTag`, if one is given | 1. Atespace editor<br>2. Viewer of the template's atespace, which may be another one<br>3. Editor of the tag's atespace. When `sourceTag` is omitted, the handler resolves the template's golden tag without checking `can_use_tag`. |
187187
| `UpdateActor` | 1. `can_update`, the actor<br>2. `can_use_template`, the template in the request | 1. Editor of its atespace<br>2. Viewer of the template's atespace, so an actor can't be switched to a template its editor can't use |
188188
| `GetActor` | `can_get`, the actor | Viewer of its atespace; `atenet-egress`; the objectstore control plugin |
189189
| `DeleteActor` | `can_delete`, the actor | Editor of its atespace |

‎docs/reference/api-guide.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -467,7 +467,7 @@ a `Snapshot` with the following fields:
467467
- `locality`: The node holding the snapshot's local files. For attachment rules,
468468
see `ActorStatus.assigned_node` in the [API schema](../../api/ateapi/v1/ateapi.proto).
469469
- `durableSnapshot`: The copy in object storage, with its URI in
470-
`object.snapshotUri` and a `status` that is `PENDING` while the copy is being
470+
`object.snapshotUri` and a `state` that is `PENDING` while the copy is being
471471
written and `COMPLETED` once it can be restored from. A synchronous suspend
472472
uploads the copy before returning (`COMPLETED`); an asynchronous suspend
473473
records the copy as `PENDING`, and atelet uploads it in the background. A
@@ -692,7 +692,7 @@ The Substrate Control Plane (`ate-api-server`) exposes a gRPC interface for mana
692692
Registers a new logical actor in the system.
693693
* **Request:** `CreateActorRequest`
694694
* `actor`: `Actor` — the actor to create. Its `metadata` carries the atespace and name (name must be a DNS-1123 label); the `actor_template` ref (atespace + name) selects the `ActorTemplate`.
695-
* `actor.source_tag`: (Optional) `ObjectRef` of a `Tag` to seed the actor from. The tag must be taken under the same `ActorTemplate`, and either in the actor's own atespace or `PUBLISHED`. Nothing is copied: the new actor's `status.snapshots` points at the tag's snapshot, under the tag's prefix, until its own first suspend.
695+
* `actor.source_tag`: (Optional) `ObjectRef` of a `Tag` to seed the actor from. The tag must be taken under the same `ActorTemplate`, must not be marked for deletion, and must be either in the actor's own atespace or `PUBLISHED`. Nothing is copied: the new actor's `status.snapshots` points at the tag's snapshot, under the tag's prefix, until its own first suspend.
696696
* `actor.worker_selector`: (Optional) Per-actor `WorkerSelector` merged with the template's `worker_selector` at resume time (actor keys override template keys).
697697
* **Response:** the initialized `Actor`.
698698

@@ -704,7 +704,7 @@ Replaces the mutable fields of an existing actor with the ones in the request (`
704704
* `worker_selector` may be updated or cleared (`nil`) in any state, but not while another operation is changing the actor. The updated selector takes effect on the next `ResumeActor`.
705705
* A suspended actor with a local snapshot is initially pinned to its node (see `locality` in [Snapshot Storage Layout](#snapshot-storage-layout)). `ResumeActor` first looks for a worker there matching the template and actor selectors. If none is available but a worker satisfies the remaining constraints without node or runtime restrictions, resume detaches the checkpoint and retries placement. If no eligible worker has room, it returns `RESOURCE_EXHAUSTED`.
706706
* **Response:** the updated `Actor`.
707-
* **Errors:** `INVALID_ARGUMENT` if `uid` or `version` is unset, or if the request changes an immutable field — including by leaving one unset; `FAILED_PRECONDITION` if a change to `actor_template` breaks one of the rules above; `ABORTED` if either guard no longer matches the stored resource, or while another operation is changing the actor (retry the same request).
707+
* **Errors:** `INVALID_ARGUMENT` if `uid` or `version` is unset, or if the request changes an immutable field (including by leaving one unset). `FAILED_PRECONDITION` if the actor is marked for deletion or if a change to `actor_template` breaks one of the rules above. `ABORTED` if either guard no longer matches the stored resource, or while another operation is changing the actor (retry the same request).
708708

709709
Because the guards are required and only a read supplies them, an update is always a read-modify-write. To Update an `Actor`, you must first `GetActor`/`CreateActor`, instead of building a new one — see [§7.2 of the API style guide](../api-style-guide.md#72-using-version-and-uid-to-guard-writes) for why reconstructing the message can silently drop data.
710710

@@ -761,10 +761,10 @@ Query the state of logical actors.
761761
* **GetActor:** Retrieves a single actor by ID.
762762
* **ListActors:** Lists all actors currently tracked in the database.
763763

764-
#### `ListWorkers`
764+
#### `GetWorker` / `ListWorkers` / `ListWorkerActorAssignments`
765765
Query the physical resource pool.
766-
* **Request:** `ListWorkersRequest`
767-
* **Response:** `ListWorkersResponse` containing a list of `Worker` objects (Pods) and their current assignment status.
766+
* **GetWorker / ListWorkers:** Retrieve one or more `Worker` records, including each worker's `status.state`, `status.capacity`, `status.allocated`, and `status.sandbox_classes`.
767+
* **ListWorkerActorAssignments:** Lists the `ActorAssignment` subresources for the actors currently hosted on a worker.
768768

769769
---
770770

‎docs/reference/glossary.md‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,18 +58,24 @@ for etcd.
5858
- **Atespace**: the isolation boundary an Actor belongs to, and the first half
5959
of its identity: an Actor is addressed by `(atespace, name)`, so the same
6060
name can exist in two atespaces. Atespaces are global-scoped, not Kubernetes
61-
namespaces — an `ActorTemplate` also lives in an atespace, while
61+
namespaces. `ActorTemplate`s and `Tag`s also live in an atespace, while
6262
`WorkerPool`s live in Kubernetes namespaces. One must exist before any
63-
Actor can be created in it, and it can only be deleted once empty.
63+
resource can be created in it, and it can only be deleted once its actors,
64+
actor templates, and tags are gone.
6465

6566
- **Actor**: a single instance derived from an `ActorTemplate`, identified by a
6667
DNS-1123 name. It is the unit that is suspended and resumed, and it moves
6768
between workers over its lifetime. An Actor record tracks its lifecycle
6869
status and snapshot references.
6970

71+
- **Tag**: a durable, atespace-scoped snapshot record created from a suspended
72+
Actor (or by `ate-api-server` for a template's golden snapshot). Each Tag
73+
holds its own copy of the snapshot in object storage and can be scoped to its
74+
own atespace or published across atespaces.
75+
7076
- **Worker**: a record representing one worker pod in a `WorkerPool`. A Worker
7177
hosts several Actors at once, each in its own sandbox, up to its actor limit
72-
and its compute capacity; many more are multiplexed across a pool over time.
78+
and its compute capacity. Many more are multiplexed across a pool over time.
7379

7480
## Components
7581

‎docs/reference/kubectl-ate.md‎

Lines changed: 21 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,7 @@ These flags can be appended to any command:
5959
| `--endpoint` | | Manual gRPC endpoint override (e.g., `localhost:8080`) | |
6060
| `--token-file` | | Path to a bearer token for ate-api authentication, or `-` for stdin | Kubernetes ServiceAccount token |
6161
| `--output` | `-o` | Output format (`table`, `json`, `yaml`) | `table` |
62+
| `--preview` | | Allow the use of preview features enabled on the server | `false` |
6263
| `--trace` | | Enable on-demand tracing for the request | `false` |
6364
| `--verbose` | `-v` | Increase output verbosity; may be repeated or stacked (e.g., `-v`, `-vv`, `-vvvvv`) | `0` |
6465

@@ -82,14 +83,19 @@ kubectl ate get actors -A
8283
# Get a specific actor by name and output as raw YAML
8384
kubectl ate get actor <actor-name> --atespace <atespace> -o yaml
8485

85-
# List all physical workers and see which actors are assigned to them
86+
# List all physical workers or get specific workers by name
8687
kubectl ate get workers
88+
kubectl ate get worker <worker-name>
8789

88-
# Filter workers by Kubernetes namespace, assigned-actor atespace, or
89-
# worker pool labels (same flags as `top workers`)
90+
# Filter workers by Kubernetes namespace, assigned-actor atespace,
91+
# worker pool labels, or sandbox class (same flags as `top workers`)
9092
kubectl ate get workers -n <namespace>
9193
kubectl ate get workers -a <atespace>
9294
kubectl ate get workers -l <label-selector>
95+
kubectl ate get workers --sandbox-class <gvisor|microvm>
96+
97+
# Show live CPU and memory usage of worker pods
98+
kubectl ate top workers
9399
```
94100

95101
> **Note:** `get actors` requires either `--atespace <name>` / `-a <name>` (one atespace) or `-A`/`--all-atespaces` (all atespaces) — there is no default atespace. Getting a single actor always requires `--atespace`/`-a`, since an actor is addressed by `(atespace, name)`. `-a` (lower-case) scopes to one atespace; `-A` (upper-case) spans all.
@@ -104,20 +110,23 @@ kubectl ate get workers -l <label-selector>
104110
| `NAME` | The actor's name. User-provided for application actors; UUID for the golden actor that each template materialises while building its golden tag. |
105111
| `TEMPLATE` | The `ActorTemplate` the actor references, displayed as `<atespace>/<name>`. |
106112
| `STATE` | Current lifecycle state (`ACTOR_STATE_RESUMING`, `ACTOR_STATE_RUNNING`, `ACTOR_STATE_SUSPENDING`, `ACTOR_STATE_SUSPENDED`, `ACTOR_STATE_CRASHED`, `ACTOR_STATE_DELETING`, `ACTOR_STATE_REVERTING`). |
107-
| `WORKER POD` | The worker pod (namespace/name) currently hosting the actor. Empty while suspended. |
108-
| `WORKER IP` | The pod IP of that worker. Empty while suspended. |
113+
| `WORKER POD` | The worker pod (`<namespace>/<name>`) currently hosting the actor, or `<none>` while suspended. |
114+
| `WORKER IPS` | Comma-separated pod IPs of that worker. Empty while suspended. |
109115
| `VERSION` | Monotonic integer that increments on every state transition (resume / suspend / checkpoint). Useful for distinguishing snapshots. |
110116
| `AGE` | Time elapsed since the actor was created. |
111117

112118
#### `kubectl ate get worker` output columns
113119

114120
| Column | Meaning |
115121
|---|---|
116-
| `NAMESPACE` | The `WorkerPool` namespace. |
122+
| `NAME` | The worker's name. The control plane assigns it. Treat it as opaque. |
117123
| `POOL` | The `WorkerPool` name. |
118-
| `POD` | The worker pod name. |
119-
| `STATUS` | `FREE` (idle, ready to receive an actor) or `ASSIGNED` (currently hosting an actor). |
120-
| `ASSIGNED ACTOR` | If `STATUS=ASSIGNED`, the actor reference `<namespace>/<template>/<actor-name>`. |
124+
| `STATE` | Current worker state. `WORKER_STATE_ACTIVE` when schedulable. `WORKER_STATE_UNAVAILABLE` while the worker is not ready or is restarting. `WORKER_STATE_DRAINING` once the pod is terminating. |
125+
| `ACTORS` | Actors assigned to the worker vs. the worker's actor limit (`<allocated>/<capacity>`). |
126+
| `CPU(MILLICORES)` | Allocated vs. capacity CPU in millicores (`<allocated>/<capacity>`). Allocated includes each runtime's per-actor overhead. `-` if the worker reports no CPU capacity. |
127+
| `MEMORY` | Allocated vs. capacity memory with binary suffixes, such as `0/960Mi`. Allocated includes each runtime's per-actor overhead. `-` if the worker reports no memory capacity. |
128+
| `POD` | The worker pod (`<namespace>/<name>`). |
129+
| `AGE` | Time elapsed since `ate-controller` created the Worker for its pod. |
121130

122131
### Atespaces
123132

@@ -133,11 +142,11 @@ kubectl ate get atespaces
133142
# Get an atespace
134143
kubectl ate get atespace <atespace>
135144

136-
# Delete an atespace (must be empty — fails if any actors remain)
145+
# Delete an atespace (must be empty: fails if any actors, templates, or tags remain)
137146
kubectl ate delete atespace <atespace>
138147
```
139148

140-
> **Note:** `create actor … -a <atespace>` requires the atespace to already exist, otherwise it fails with `FailedPrecondition`. `delete atespace` only removes an **empty** atespace; delete its actors and tags first (cascade delete is not yet supported).
149+
> **Note:** `create actor … -a <atespace>` requires the atespace to already exist, otherwise it fails with `FailedPrecondition`. `delete atespace` only removes an **empty** atespace. Delete its actors, actor templates, and tags first (cascade delete is not yet supported).
141150
142151
#### `kubectl ate get atespace` output columns
143152

@@ -242,7 +251,7 @@ kubectl ate get tags -A
242251
kubectl ate get tag <tag-name> [<tag-name> ...] -a <atespace>
243252

244253
# Tag the snapshot a suspended actor holds, then publish or unpublish the tag.
245-
# Tagging fails until the snapshot is in storage: suspend with --mode=sync to tag right away.
254+
# After an asynchronous suspend, create tag uploads the local snapshot first if needed.
246255
kubectl ate create tag <tag-name> -a <atespace> --actor <actor-name> [--scope published]
247256
kubectl ate update tag <tag-name> -a <atespace> --scope published
248257
kubectl ate update tag <tag-name> -a <atespace> --scope atespace

0 commit comments

Comments
 (0)