You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit f475d8b
Browse filesBrowse the repository at this point in the historyBrowse files
docs: align control-plane docs with the current API and CLI (#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]>
Copy file name to clipboardExpand all lines: docs/api-style-guide.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -283,7 +283,7 @@ Rules:
283
283
- RPC name **must** begin with `Update` followed by the singular resource name.
284
284
- Response **must** be the resource itself — not an `UpdateActorResponse` wrapper.
285
285
-**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.
287
287
- 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`.
288
288
- The request **must** have no other fields, apart from its parent's `ObjectRef` for a subresource (see section #2.4).
289
289
- 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.
Copy file name to clipboardExpand all lines: docs/guides/authorization.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -183,7 +183,7 @@ viewer, and a global role holds the same role in every atespace. So
183
183
|`GetActorTemplate`|`can_get`, the template | Viewer of its atespace |
184
184
|`DeleteActorTemplate`|`can_delete`, the template | Editor of its atespace |
185
185
|`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`. |
187
187
|`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 |
188
188
|`GetActor`|`can_get`, the actor | Viewer of its atespace; `atenet-egress`; the objectstore control plugin |
189
189
|`DeleteActor`|`can_delete`, the actor | Editor of its atespace |
Copy file name to clipboardExpand all lines: docs/reference/api-guide.md
+6-6Lines changed: 6 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -467,7 +467,7 @@ a `Snapshot` with the following fields:
467
467
- `locality`: The node holding the snapshot's local files. For attachment rules,
468
468
see `ActorStatus.assigned_node` in the [API schema](../../api/ateapi/v1/ateapi.proto).
469
469
- `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
471
471
written and `COMPLETED` once it can be restored from. A synchronous suspend
472
472
uploads the copy before returning (`COMPLETED`); an asynchronous suspend
473
473
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
692
692
Registers a new logical actor in the system.
693
693
* **Request:** `CreateActorRequest`
694
694
* `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.
696
696
* `actor.worker_selector`: (Optional) Per-actor `WorkerSelector` merged with the template's `worker_selector` at resume time (actor keys override template keys).
697
697
* **Response:** the initialized `Actor`.
698
698
@@ -704,7 +704,7 @@ Replaces the mutable fields of an existing actor with the ones in the request (`
704
704
* `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`.
705
705
* 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`.
706
706
* **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).
708
708
709
709
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.
710
710
@@ -761,10 +761,10 @@ Query the state of logical actors.
761
761
* **GetActor:** Retrieves a single actor by ID.
762
762
* **ListActors:** Lists all actors currently tracked in the database.
* **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.
|`--token-file`|| Path to a bearer token for ate-api authentication, or `-` for stdin | Kubernetes ServiceAccount token |
61
61
|`--output`|`-o`| Output format (`table`, `json`, `yaml`) |`table`|
62
+
|`--preview`|| Allow the use of preview features enabled on the server |`false`|
62
63
|`--trace`|| Enable on-demand tracing for the request |`false`|
63
64
|`--verbose`|`-v`| Increase output verbosity; may be repeated or stacked (e.g., `-v`, `-vv`, `-vvvvv`) |`0`|
64
65
@@ -82,14 +83,19 @@ kubectl ate get actors -A
82
83
# Get a specific actor by name and output as raw YAML
83
84
kubectl ate get actor <actor-name> --atespace <atespace> -o yaml
84
85
85
-
# List all physical workers and see which actors are assigned to them
86
+
# List all physical workers or get specific workers by name
86
87
kubectl ate get workers
88
+
kubectl ate get worker <worker-name>
87
89
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`)
90
92
kubectl ate get workers -n <namespace>
91
93
kubectl ate get workers -a <atespace>
92
94
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
93
99
```
94
100
95
101
> **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>
104
110
|`NAME`| The actor's name. User-provided for application actors; UUID for the golden actor that each template materialises while building its golden tag. |
105
111
|`TEMPLATE`| The `ActorTemplate` the actor references, displayed as `<atespace>/<name>`. |
106
112
|`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. |
109
115
|`VERSION`| Monotonic integer that increments on every state transition (resume / suspend / checkpoint). Useful for distinguishing snapshots. |
110
116
|`AGE`| Time elapsed since the actor was created. |
111
117
112
118
#### `kubectl ate get worker` output columns
113
119
114
120
| Column | Meaning |
115
121
|---|---|
116
-
|`NAMESPACE`| The `WorkerPool` namespace. |
122
+
|`NAME`| The worker's name. The control plane assigns it. Treat it as opaque. |
117
123
|`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. |
121
130
122
131
### Atespaces
123
132
@@ -133,11 +142,11 @@ kubectl ate get atespaces
133
142
# Get an atespace
134
143
kubectl ate get atespace <atespace>
135
144
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)
137
146
kubectl ate delete atespace <atespace>
138
147
```
139
148
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).
141
150
142
151
#### `kubectl ate get atespace` output columns
143
152
@@ -242,7 +251,7 @@ kubectl ate get tags -A
242
251
kubectl ate get tag <tag-name> [<tag-name> ...] -a <atespace>
243
252
244
253
# 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.
246
255
kubectl ate create tag <tag-name> -a <atespace> --actor <actor-name> [--scope published]
247
256
kubectl ate update tag <tag-name> -a <atespace> --scope published
248
257
kubectl ate update tag <tag-name> -a <atespace> --scope atespace
0 commit comments