diff --git a/docs/api-guide.md b/docs/api-guide.md index 2469dd9b9..17da7daf1 100644 --- a/docs/api-guide.md +++ b/docs/api-guide.md @@ -15,6 +15,7 @@ The `WorkerPool` defines the pool of physical "warm" compute capacity. It manage | `sandboxClass` | `string` | Optional. The sandbox runtime family for the pool: `gvisor` (default) or `microvm`. Drives the worker pod shape (e.g. KVM device mounts, node placement) and which `SandboxConfig`s are eligible. | | `sandboxConfigName` | `string` | Optional. Name of a cluster-scoped [`SandboxConfig`](#3-sandboxconfig-sandbox-binaries) providing the sandbox binaries. If empty, the cluster default `SandboxConfig` for the pool's `sandboxClass` is used. | | `template` | `WorkerPoolPodTemplate` | **Optional.** Pod scheduling and resource settings for worker pods. | +| `terminationGracePeriodSeconds` | `int32` | Optional. Termination grace period for the pool's worker pods, default `300`. On eviction `ateom` forwards `SIGTERM` to the actor so it can save state before the kubelet sends `SIGKILL`. Set it to the longest shutdown your actors need. | #### `WorkerPoolPodTemplate` (`spec.template`) @@ -98,7 +99,8 @@ The `ActorTemplate` defines the code, environment, and state-management policies | `containers` | `[]Container` | **Required.** The workload definition — see [Container Fields](#container-fields) below. Each container may also declare an optional `readyz` HTTP probe — see [Container Readiness Probe](#container-readiness-probe-readyz). | | `sandboxClass` | `string` | Optional. The sandbox runtime family this template's actors require: `gvisor` (default) or `microvm`. Only `WorkerPool`s whose `sandboxClass` matches are eligible. | | `workerSelector` | `*LabelSelector` | Optional. Gates which `WorkerPool`s actors from this template may use, by matching against each pool's labels. If unset, all pools are eligible (subject to the actor's own `worker_selector`). | -| `snapshotsConfig` | `SnapshotsConfig` | **Required.** GCS bucket and folder where memory snapshots are stored. | +| `snapshotsConfig` | `SnapshotsConfig` | **Required.** Where snapshots are stored and what each one contains. See [Snapshots Config](#snapshots-config-snapshotsconfig). | +| `volumes` | `[]Volume` | Optional. Named volumes containers may mount through `volumeMounts` (max 32). Each entry sets one source: `durableDir` for a directory on rootfs that persists across resumes, or `externalVolumeTemplate` for a per-actor external volume. | | `pauseImage` | `string` | **Required.** The image used for the sandbox root (e.g. `gcr.io/gke-release/pause`). | | `volumes` | `[]Volume` | Optional. Volumes the containers may mount, each either a `durableDir` or an `externalVolumeTemplate`. Every declared volume must be mounted by at least one container. A `microvm` template may declare several `durableDir` volumes; a `gvisor` template is limited to one, and `externalVolumeTemplate` is `gvisor`-only. | @@ -118,6 +120,19 @@ Substrate bind-mounts a read-only, per-actor identity directory at **`/run/ate`* Read it fresh rather than caching it at process start. It is delivered as a per-actor bind mount, not an environment variable, precisely so it carries the correct name after a resume from the golden snapshot — an env var (or a file baked into the image) would be frozen at the *golden* actor's name, since it lives in the checkpointed process memory, and would therefore be identical for every actor of the template. +### Snapshots Config (`snapshotsConfig`) + +| Field | Type | Description | +| :--- | :--- | :--- | +| `location` | `string` | **Required.** Object store URL where snapshots are written, e.g. `gs://my-bucket/snapshots/my-template/`. | +| `onPause` | `SnapshotScope` | Optional. What a Pause captures (kept on the node). `Full` (default) or `Data`. | +| `onCommit` | `SnapshotScope` | Optional. What a Suspend captures (uploaded to storage). `Full` (default) or `Data`, and must be a subset of `onPause`. | + +`Full` captures process memory, the rootfs delta, and any attached volumes that +support snapshots. `Data` captures only those volumes, so the actor cold-boots +from the image on the next resume with its `durableDir` contents restored. See +the [glossary](glossary.md#snapshots) for the full definitions. + ### Container Fields Each entry in `containers` describes one process to run in the actor's sandbox. @@ -262,7 +277,14 @@ The Substrate Control Plane (`ate-api-server`) exposes a gRPC interface for mana Registers a new logical actor in the system. * **Request:** `CreateActorRequest` * `actor`: `Actor` — the actor to create. Its `metadata` carries the atespace and name (name must be a DNS-1123 label); `actor_template_namespace` and `actor_template_name` select the `ActorTemplate`. -* **Response:** `CreateActorResponse` containing the initialized `Actor` object. +* **Response:** the initialized `Actor`. + +#### `UpdateActor` +Changes mutable fields on an existing actor. +* **Request:** `UpdateActorRequest` + * `actor`: `ObjectRef` of the actor to update. + * `worker_selector`: replaces the actor's placement constraint. It takes effect on the next `ResumeActor`, not immediately. +* **Response:** `UpdateActorResponse` containing the updated `Actor`. #### `ResumeActor` Activates a suspended actor by restoring it onto a physical worker. @@ -277,22 +299,35 @@ Hibernate a running actor, capturing its current RAM and disk state into a snaps * `actor`: `ObjectRef` of the actor to suspend. * **Response:** `SuspendActorResponse` containing the `Actor` object in `STATUS_SUSPENDED`. +#### `PauseActor` +Checkpoint a running actor but keep its snapshots on the node VM, so the next resume can be prioritized back onto that node. +* **Request:** `PauseActorRequest` + * `actor`: `ObjectRef` of the actor to pause. +* **Response:** `PauseActorResponse` containing the updated `Actor`. + #### `DeleteActor` Removes an actor from the registry. * **Constraints:** Only actors in `STATUS_SUSPENDED` can be deleted. * **Request:** `DeleteActorRequest` -* **Response:** `DeleteActorResponse` (empty). +* **Response:** the deleted `Actor` as it was before removal. #### `GetActor` / `ListActors` Query the state of logical actors. -* **GetActor:** Retrieves a single actor by ID. -* **ListActors:** Lists all actors currently tracked in the database. +* **GetActor:** Retrieves a single actor by `ObjectRef`, which carries its atespace and name. +* **ListActors:** Lists actors in one atespace, or across all of them when `atespace` is empty. Paginated through `page_size` and `page_token`. #### `ListWorkers` Query the physical resource pool. -* **Request:** `ListWorkersRequest` +* **Request:** `ListWorkersRequest`, paginated through `page_size` and `page_token`. * **Response:** `ListWorkersResponse` containing a list of `Worker` objects (Pods) and their current assignment status. +#### Atespaces +An **atespace** is the isolation boundary an actor belongs to. It must exist before any actor can be created in it. +* **`CreateAtespace`:** takes the `Atespace` to create, returns the created one. Atespaces are global-scoped, so the name must be unique across the cluster. +* **`GetAtespace`:** takes an `ObjectRef`, returns the `Atespace`. +* **`ListAtespaces`:** returns `ListAtespacesResponse`, paginated through `page_size` and `page_token`. +* **`DeleteAtespace`:** takes an `ObjectRef` and returns the deleted `Atespace`. It rejects with `FailedPrecondition` if any actors remain; there is no cascade delete. + --- ## 7. Advanced: Actor Identity Credentials