From 46d2331fd9f267b58bfb8ae0ebca3bb5d9d048e5 Mon Sep 17 00:00:00 2001 From: botengyao Date: Sat, 8 Aug 2026 16:22:01 -0400 Subject: [PATCH] docs: fix and fill gaps in the kubectl-ate CLI reference MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two more documented commands fail the way #561 fixed: the `--trace` example in the CLI README and `get actors` in the parking demo both omit `-a/--atespace`, which those commands require. Also in the CLI README: - The actor STATUS column listed 4 of the 8 states the API defines, missing PAUSING, PAUSED, CRASHED, and DELETING. - `pause actor` was undocumented, even though pause vs suspend (node-local vs uploaded snapshot) is the distinction users most need spelled out. - `top` was undocumented, while the `get workers` section already referred to "the same flags as `top workers`" — a dangling reference. Plus a typo in hack/update/proto-fmt.sh. --- cmd/kubectl-ate/README.md | 44 +++++++++++++++++++++++++++++++++++++-- demos/parking/README.md | 4 ++-- hack/update/proto-fmt.sh | 2 +- 3 files changed, 45 insertions(+), 5 deletions(-) diff --git a/cmd/kubectl-ate/README.md b/cmd/kubectl-ate/README.md index 1e2842428..fa73cce1b 100644 --- a/cmd/kubectl-ate/README.md +++ b/cmd/kubectl-ate/README.md @@ -54,7 +54,7 @@ The kind overlay installed by `hack/install-ate-kind.sh --deploy-ate-system` alr Port-forward the Jaeger UI and invoke any command with `--trace`: ```bash kubectl port-forward -n otel-system svc/jaeger 16686:16686 & -kubectl ate get actor my-counter-1 --trace +kubectl ate get actor my-counter-1 -a demo --trace # open http://localhost:16686 and search for the most recent trace ``` @@ -108,7 +108,7 @@ kubectl ate get workers -l | `ATESPACE` | The atespace the actor belongs to. Part of the actor's identity; folded into the storage key as `actor::`. | | `NAME` | The actor's name. User-provided for application actors; UUID for the golden actor that each template materialises during `ResumeGoldenActor`. | | `TEMPLATE` | The `ActorTemplate` the actor was created from, as `/` (the template namespace is distinct from `ATESPACE`). | -| `STATUS` | One of `STATUS_RESUMING`, `STATUS_RUNNING`, `STATUS_SUSPENDING`, `STATUS_SUSPENDED`. | +| `STATUS` | One of `STATUS_RESUMING`, `STATUS_RUNNING`, `STATUS_SUSPENDING`, `STATUS_SUSPENDED`, `STATUS_PAUSING`, `STATUS_PAUSED`, `STATUS_CRASHED`, `STATUS_DELETING`. | | `ATEOM POD` | The worker pod (namespace/name) currently hosting the actor. Empty while suspended. | | `ATEOM IP` | The pod IP of that worker. Empty while suspended. | | `VERSION` | Monotonic integer that increments on every state transition (resume / suspend / checkpoint). Useful for distinguishing snapshots. | @@ -167,10 +167,20 @@ kubectl ate resume actor my-actor -a # Suspend an actor (snapshots its state to storage and frees the worker) kubectl ate suspend actor my-actor -a +# Pause an actor (checkpoints it, but keeps the snapshot on the node VM) +kubectl ate pause actor my-actor -a + # Delete an actor. kubectl ate delete actor my-actor -a ``` +> **Note:** `suspend` and `pause` are both checkpoints, but they differ in where +> the snapshot lands. `suspend` uploads it to snapshot storage, so the actor can +> resume on any node. `pause` keeps it on the node VM, and the next `resume` is +> prioritized onto that same node — cheaper and faster, but tied to one node's +> availability. See [Lifecycle](../../docs/glossary.md#lifecycle) for the full +> definitions. + ### Actor Snapshots Suspending an actor creates a durable snapshot. Tags give snapshots stable, @@ -208,6 +218,36 @@ kubectl ate logs actors my-actor -a -f Logs are streamable only while the actor is bound to a worker (i.e., `STATUS_RUNNING`). For history across worker migrations, route through a centralized log backend (Cloud Logging, Loki, etc.); see `docs/observability.md`. +### Resource Usage + +`kubectl ate top` reports CPU and memory usage of worker pods. `workers` is the +only supported resource type. + +```bash +# Usage for every worker pod +kubectl ate top workers + +# Same filters as `get workers`: Kubernetes namespace, the atespace of the +# assigned actor, or worker pool labels +kubectl ate top workers -n +kubectl ate top workers -a +kubectl ate top workers -l +``` + +Metrics come from the Kubernetes metrics API, so the cluster needs +metrics-server (or an equivalent) installed. + +#### `kubectl ate top workers` output columns + +| Column | Meaning | +|---|---| +| `NAME` | The worker pod name. | +| `POOL` | The `WorkerPool` the pod belongs to. | +| `STATUS` | `FREE` (idle, ready to receive an actor) or `ASSIGNED` (currently hosting an actor). | +| `ASSIGNED ACTOR` | If `STATUS=ASSIGNED`, the actor reference `/