ActorCrash
| Field | Description | Type |
|---|---|---|
| message | message is a human-readable description of the failure. | string |
| crash_time | crash_time is when the Actor entered CRASHED. | google.protobuf.Timestamp |
AccessPolicy
subresource of Global singleton
AccessPolicy is an access policy resource nested under a parent resource (or the global singleton installation). Every parent resource has at most one access policy resource, named "default".
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| GetGlobalAccessPolicy | Get the deployment-wide global access policy singleton. Returns NotFound until the policy has been created. | GetGlobalAccessPolicyRequest | AccessPolicy |
| CreateGlobalAccessPolicy | Create the deployment-wide global access policy singleton. The server's configured bootstrap owners are global owners whether or not this policy exists, so they can create it. | CreateGlobalAccessPolicyRequest | AccessPolicy |
| UpdateGlobalAccessPolicy | Replace the deployment-wide global access policy singleton. Empty bindings revoke every grant held through the policy; bootstrap owners keep access. | UpdateGlobalAccessPolicyRequest | AccessPolicy |
Fields
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent resource (empty for global-scoped parents like Global and Atespace) and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
bindings
repeated Binding
Role bindings granting permissions on the parent resource.
role
string
The role name for the parent resource type (e.g., "owner", "editor", "viewer").
members
repeated string
Principal identities granted this role. Examples:
- "user:alice@example.com"
- "user:sa-ci-runner"
Example
{ "metadata": { "name": "default", "uid": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c", "version": "4", "createTime": "2026-06-01T00:05:00Z", "updateTime": "2026-08-10T16:30:00Z" }, "bindings": [ { "role": "owner", "members": [ "user:alice@example.com" ] }, { "role": "viewer", "members": [ "user:sa-ci-runner" ] } ]}
Methods
GetGlobalAccessPolicy
Get the deployment-wide global access policy singleton. Returns NotFound until the policy has been created.
Request (GetGlobalAccessPolicyRequest)
name
string
Name of the singleton access policy. Must be "default".
Response (AccessPolicy)
The AccessPolicy resource.
GetGlobalAccessPolicy
rpc GetGlobalAccessPolicy(GetGlobalAccessPolicyRequest) returns (AccessPolicy);GetGlobalAccessPolicyRequest
message GetGlobalAccessPolicyRequest { string name = 1;}
CreateGlobalAccessPolicy
Create the deployment-wide global access policy singleton. The server's configured bootstrap owners are global owners whether or not this policy exists, so they can create it.
Request (CreateGlobalAccessPolicyRequest)
access_policy
AccessPolicy
The policy to create. metadata.name must be "default" and metadata.atespace must be empty.
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent resource (empty for global-scoped parents like Global and Atespace) and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
bindings
repeated Binding
Role bindings granting permissions on the parent resource.
role
string
The role name for the parent resource type (e.g., "owner", "editor", "viewer").
members
repeated string
Principal identities granted this role. Examples:
- "user:alice@example.com"
- "user:sa-ci-runner"
Response (AccessPolicy)
The AccessPolicy resource.
CreateGlobalAccessPolicy
rpc CreateGlobalAccessPolicy(CreateGlobalAccessPolicyRequest) returns (AccessPolicy);CreateGlobalAccessPolicyRequest
message CreateGlobalAccessPolicyRequest { AccessPolicy access_policy = 1;}
UpdateGlobalAccessPolicy
Replace the deployment-wide global access policy singleton. Empty bindings revoke every grant held through the policy; bootstrap owners keep access.
Request (UpdateGlobalAccessPolicyRequest)
access_policy
AccessPolicy
Full replacement. Metadata UID and version are required preconditions; metadata.name must be "default" and metadata.atespace must be empty.
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent resource (empty for global-scoped parents like Global and Atespace) and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
bindings
repeated Binding
Role bindings granting permissions on the parent resource.
role
string
The role name for the parent resource type (e.g., "owner", "editor", "viewer").
members
repeated string
Principal identities granted this role. Examples:
- "user:alice@example.com"
- "user:sa-ci-runner"
Response (AccessPolicy)
The AccessPolicy resource.
UpdateGlobalAccessPolicy
rpc UpdateGlobalAccessPolicy(UpdateGlobalAccessPolicyRequest) returns (AccessPolicy);UpdateGlobalAccessPolicyRequest
message UpdateGlobalAccessPolicyRequest { AccessPolicy access_policy = 1;}
AccessPolicy
subresource of Atespace singleton
AccessPolicy is an access policy resource nested under a parent resource (or the global singleton installation). Every parent resource has at most one access policy resource, named "default".
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| GetAtespaceAccessPolicy | Get the access policy resource nested under an Atespace. | GetAtespaceAccessPolicyRequest | AccessPolicy |
| CreateAtespaceAccessPolicy | Create the access policy resource nested under an Atespace. | CreateAtespaceAccessPolicyRequest | AccessPolicy |
| UpdateAtespaceAccessPolicy | Replace the access policy resource nested under an Atespace. | UpdateAtespaceAccessPolicyRequest | AccessPolicy |
| DeleteAtespaceAccessPolicy | Delete the access policy resource nested under an Atespace. | DeleteAtespaceAccessPolicyRequest | AccessPolicy |
Fields
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent resource (empty for global-scoped parents like Global and Atespace) and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
bindings
repeated Binding
Role bindings granting permissions on the parent resource.
role
string
The role name for the parent resource type (e.g., "owner", "editor", "viewer").
members
repeated string
Principal identities granted this role. Examples:
- "user:alice@example.com"
- "user:sa-ci-runner"
Example
{ "metadata": { "name": "default", "uid": "6f7a8b9c-0d1e-4f2a-9b3c-4d5e6f7a8b9c", "version": "4", "createTime": "2026-06-01T00:05:00Z", "updateTime": "2026-08-10T16:30:00Z" }, "bindings": [ { "role": "owner", "members": [ "user:alice@example.com" ] }, { "role": "viewer", "members": [ "user:sa-ci-runner" ] } ]}
Methods
GetAtespaceAccessPolicy
Get the access policy resource nested under an Atespace.
Request (GetAtespaceAccessPolicyRequest)
atespace
ObjectRef
The parent Atespace of the access policy resource to retrieve.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
name
string
Name of the singleton access policy. Must be "default".
Response (AccessPolicy)
The AccessPolicy resource.
GetAtespaceAccessPolicy
rpc GetAtespaceAccessPolicy(GetAtespaceAccessPolicyRequest) returns (AccessPolicy);GetAtespaceAccessPolicyRequest
message GetAtespaceAccessPolicyRequest { ObjectRef atespace = 1; string name = 2;}
CreateAtespaceAccessPolicy
Create the access policy resource nested under an Atespace.
Request (CreateAtespaceAccessPolicyRequest)
atespace
ObjectRef
Parent Atespace under which to create the policy resource.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
access_policy
AccessPolicy
The policy to create. metadata.name must be "default" and metadata.atespace must be empty.
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent resource (empty for global-scoped parents like Global and Atespace) and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
bindings
repeated Binding
Role bindings granting permissions on the parent resource.
role
string
The role name for the parent resource type (e.g., "owner", "editor", "viewer").
members
repeated string
Principal identities granted this role. Examples:
- "user:alice@example.com"
- "user:sa-ci-runner"
Response (AccessPolicy)
The AccessPolicy resource.
CreateAtespaceAccessPolicy
rpc CreateAtespaceAccessPolicy(CreateAtespaceAccessPolicyRequest) returns (AccessPolicy);CreateAtespaceAccessPolicyRequest
message CreateAtespaceAccessPolicyRequest { ObjectRef atespace = 1; AccessPolicy access_policy = 2;}
UpdateAtespaceAccessPolicy
Replace the access policy resource nested under an Atespace.
Request (UpdateAtespaceAccessPolicyRequest)
atespace
ObjectRef
Parent Atespace under which to update the policy resource.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
access_policy
AccessPolicy
Full replacement. Metadata UID and version are required preconditions; metadata.name must be "default" and metadata.atespace must be empty.
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent resource (empty for global-scoped parents like Global and Atespace) and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
bindings
repeated Binding
Role bindings granting permissions on the parent resource.
role
string
The role name for the parent resource type (e.g., "owner", "editor", "viewer").
members
repeated string
Principal identities granted this role. Examples:
- "user:alice@example.com"
- "user:sa-ci-runner"
Response (AccessPolicy)
The AccessPolicy resource.
UpdateAtespaceAccessPolicy
rpc UpdateAtespaceAccessPolicy(UpdateAtespaceAccessPolicyRequest) returns (AccessPolicy);UpdateAtespaceAccessPolicyRequest
message UpdateAtespaceAccessPolicyRequest { ObjectRef atespace = 1; AccessPolicy access_policy = 2;}
DeleteAtespaceAccessPolicy
Delete the access policy resource nested under an Atespace.
Request (DeleteAtespaceAccessPolicyRequest)
atespace
ObjectRef
The parent Atespace of the access policy resource to delete.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
name
string
Name of the singleton access policy. Must be "default".
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
Response (AccessPolicy)
The AccessPolicy resource.
DeleteAtespaceAccessPolicy
rpc DeleteAtespaceAccessPolicy(DeleteAtespaceAccessPolicyRequest) returns (AccessPolicy);DeleteAtespaceAccessPolicyRequest
message DeleteAtespaceAccessPolicyRequest { ObjectRef atespace = 1; string name = 2; DeleteOptions options = 3;}
Actor
atespace
Subresources
- EgressPolicy singleton
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| GetActor | Get an Actor. | GetActorRequest | Actor |
| CreateActor | Create a new Actor deriving from a given ActorTemplate. | CreateActorRequest | Actor |
| UpdateActor | Update mutable fields on an existing Actor. | UpdateActorRequest | Actor |
| SuspendActor | Suspend a given actor to a new snapshot. A running actor is checkpointed on its worker. A SUSPENDED actor is returned as it is. | SuspendActorRequest | SuspendActorResponse |
| ResumeActor | Resume an actor from its latest snapshot. | ResumeActorRequest | ResumeActorResponse |
| RevertActor | Revert an actor to SUSPENDED state at its durable snapshot. Only crashed or running actors, or suspended actors with a node-local snapshot, can be reverted. A suspended actor without a node-local snapshot is already at its durable snapshot, so there is nothing to revert. | RevertActorRequest | RevertActorResponse |
| DeleteActor | Delete an actor. A running actor's workload is terminated, its volumes detached, and its worker released before the record is removed. | DeleteActorRequest | Actor |
| MintActorJwt | Create a Substrate-issued JWT asserting the actor identity. | MintActorJwtRequest | MintActorJwtResponse |
| ListActors | List Actors. | ListActorsRequest | ListActorsResponse |
Fields
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
Example
{ "metadata": { "atespace": "prod", "name": "c0a8012e-4b7d-4f3a-9e21-6d5f8a9b0c1d", "uid": "8f14e45f-ceea-4c3e-9d5b-1a2b3c4d5e6f", "version": "14", "createTime": "2026-08-01T18:22:04Z", "updateTime": "2026-08-13T09:47:31Z" }, "actorTemplate": { "atespace": "prod", "name": "a7d3e9f1-2c4b-4e8a-b5d6-7f9e0a1b2c3d" }, "workerSelector": { "matchLabels": { "tier": "1" } }, "status": { "state": "ACTOR_STATE_RUNNING", "workerAssignment": { "worker": { "name": "3c9e1a2b-6d4f-4b8e-9a71-2c5f0d8b3e94" }, "workerNamespace": "substrate-workers", "workerPool": "default-pool", "workerPod": "default-pool-6b9d4f-x2p7q", "workerPodUid": "3c9e1a2b-6d4f-4b8e-9a71-2c5f0d8b3e94", "workerPodIps": [ "10.4.12.31" ], "nodeName": "worker-node-1", "workerEpoch": "1", "sandboxRuntime": { "sandboxClass": "gvisor", "version": { "schemaVersion": "v1", "attributes": [ { "key": "architecture", "value": "amd64" }, { "key": "sandbox_bundle_hash", "value": "b5bb9d8014a0f9b1d61e21e796d78dcc" } ] } }, "workerSpiffeId": "spiffe://cluster.local/ns/substrate-workers/sa/ateworker" }, "assignedNode": "worker-node-1", "snapshots": [ { "uuid": "5d2c7e1a-9b3f-4c8d-a6e2-0f1b2c3d4e5f", "generation": 3, "owner": "SNAPSHOT_OWNER_ACTOR", "fidelity": "SNAPSHOT_FIDELITY_MEMORY", "actorTemplateUid": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "durableSnapshot": { "state": "SNAPSHOT_STORAGE_STATE_COMPLETED", "object": { "snapshotUri": "objectstore://substrate-snapshots/atespaces/prod/actors/8f14e45f-ceea-4c3e-9d5b-1a2b3c4d5e6f/snapshots/5d2c7e1a-9b3f-4c8d-a6e2-0f1b2c3d4e5f" } }, "sandboxRuntime": { "sandboxClass": "gvisor", "version": { "schemaVersion": "v1", "attributes": [ { "key": "architecture", "value": "amd64" }, { "key": "sandbox_bundle_hash", "value": "b5bb9d8014a0f9b1d61e21e796d78dcc" } ] } } } ], "lastAssignedGeneration": 3 }}
Methods
GetActor
Get an Actor.
Request (GetActorRequest)
actor
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
GetActor
rpc GetActor(GetActorRequest) returns (Actor);GetActorRequest
message GetActorRequest { ObjectRef actor = 1;}
CreateActor
Create a new Actor deriving from a given ActorTemplate.
Request (CreateActorRequest)
actor
Actor
The actor to create.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
CreateActor
rpc CreateActor(CreateActorRequest) returns (Actor);CreateActorRequest
message CreateActorRequest { Actor actor = 1;}
UpdateActor
Update mutable fields on an existing Actor.
Request (UpdateActorRequest)
actor
Actor
The actor to update. actor.metadata.atespace and actor.metadata.name identify which resource to update. actor.metadata.version and actor.metadata.uid are required preconditions.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
UpdateActor
rpc UpdateActor(UpdateActorRequest) returns (Actor);UpdateActorRequest
message UpdateActorRequest { Actor actor = 1;}
SuspendActor
Suspend a given actor to a new snapshot. A running actor is checkpointed on its worker. A SUSPENDED actor is returned as it is.
Request (SuspendActorRequest)
actor
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
SuspendOptions
options controls how SuspendActor persists the actor's snapshot.
mode
DurabilityMode
mode selects when SuspendActor returns relative to the snapshot reaching durable storage. If unspecified, defaults to DURABILITY_MODE_ASYNCHRONOUS.
Response (SuspendActorResponse)
actor
Actor
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
SuspendActor
rpc SuspendActor(SuspendActorRequest) returns (SuspendActorResponse);SuspendActorRequest
message SuspendActorRequest { ObjectRef actor = 1; SuspendOptions options = 2;}
SuspendActorResponse
message SuspendActorResponse { Actor actor = 1;}
ResumeActor
Resume an actor from its latest snapshot.
Request (ResumeActorRequest)
actor
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
Response (ResumeActorResponse)
actor
Actor
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
resumed
bool
True if a resume workflow was executed to activate the actor. False if the actor was already RUNNING.
ResumeActor
rpc ResumeActor(ResumeActorRequest) returns (ResumeActorResponse);ResumeActorRequest
message ResumeActorRequest { ObjectRef actor = 1;}
ResumeActorResponse
message ResumeActorResponse { Actor actor = 1; bool resumed = 2;}
RevertActor
Revert an actor to SUSPENDED state at its durable snapshot. Only crashed or running actors, or suspended actors with a node-local snapshot, can be reverted. A suspended actor without a node-local snapshot is already at its durable snapshot, so there is nothing to revert.
Request (RevertActorRequest)
actor
ObjectRef
actor to revert.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
Response (RevertActorResponse)
actor
Actor
actor as it stands after the revert, SUSPENDED and still holding the external snapshot it was reverted to.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
RevertActor
rpc RevertActor(RevertActorRequest) returns (RevertActorResponse);RevertActorRequest
message RevertActorRequest { ObjectRef actor = 1;}
RevertActorResponse
message RevertActorResponse { Actor actor = 1;}
DeleteActor
Delete an actor. A running actor's workload is terminated, its volumes detached, and its worker released before the record is removed.
Request (DeleteActorRequest)
actor
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
DeleteActor
rpc DeleteActor(DeleteActorRequest) returns (Actor);DeleteActorRequest
message DeleteActorRequest { ObjectRef actor = 1; DeleteOptions options = 2;}
MintActorJwt
Create a Substrate-issued JWT asserting the actor identity.
- Called by the egress gateway when actor JWT injection is configured for outbound requests.
Request (MintActorJwtRequest)
actor
ObjectRef
The actor for which the JWT should be issued.
Must be a valid actor that currently exists according to the actor store.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
audiences
repeated string
The audiences the minted JWT is bound to. Tokens are only issued with audience bindings, so at least one is required.
expiration_seconds
int64
Lifetime of the JWT, in seconds.
Response (MintActorJwtResponse)
actor_jwt
string
The signed actor JWT. Relying parties verify it with OpenID Connect Discovery against its issuer.
Claims:
- iss: The issuer URL. Relying parties fetch
<iss>/.well-known/openid-configurationto find the signing keys. - sub:
actor/<atespace>/<name>. - aud: The requested audiences, always a JSON array.
- exp, nbf, iat: Numeric Unix timestamps. nbf is five minutes before iat to allow for clock skew.
- jti: A random token ID.
actor.ate.dev: A JSON object with the actor'satespace,actorName, andactorUID.
The subject and claim name say the token speaks for the actor itself.
A token minted for a Substrate component acting on the actor's behalf
(WorkerService.MintWorkerActorJwt) uses worker-for-actor in both places
instead, so a relying party can grant the two different access.
expire_time
google.protobuf.Timestamp
expire_time is when actor_jwt expires. Equal to its exp claim.
MintActorJwt
rpc MintActorJwt(MintActorJwtRequest) returns (MintActorJwtResponse);MintActorJwtRequest
message MintActorJwtRequest { ObjectRef actor = 1; repeated string audiences = 2; int64 expiration_seconds = 3;}
MintActorJwtResponse
message MintActorJwtResponse { string actor_jwt = 1 [debug_redact = true]; google.protobuf.Timestamp expire_time = 2;}
ListActors
List Actors.
Request (ListActorsRequest)
atespace
string
The atespace to list actors from. Empty lists across all atespaces.
options
ListOptions
Pagination controls.
page_size
int32
Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000.
page_token
string
Pagination token from a previous response of the same List method. Omit or leave empty for the first request.
Response (ListActorsResponse)
actors
repeated Actor
The page of actors. This list may be empty even if there are more results.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor_template
ObjectRef
actor_template references the ActorTemplate this Actor is based on.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_selector
Selector
worker_selector is the per-actor placement constraint. The scheduler evaluates the AND of this selector and the template's workerSelector to find eligible pools. It narrows the template's selection; pinning a sandbox class belongs on the template's worker_selector. Changes take effect on the next ResumeActor call.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
source_tag
ObjectRef
The tag specified by the caller at CreateActor to seed this Actor from an ActorSnapshot. Unset if the Actor was not created from a snapshot. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
status
ActorStatus
status is the system-managed state of the Actor. It is updated by the server and ignored on input. It is always present in output.
state
ActorState
state is the Actor's current lifecycle state.
worker_assignment
WorkerAssignment
worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED).
It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set.
worker
ObjectRef
worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all.
Workers are global-scoped, so this carries no atespace.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
worker_namespace
string
worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod.
worker_pool
string
worker_pool is the name of the WorkerPool the worker belongs to.
worker_pod
string
worker_pod is the name of the Kubernetes pod hosting the Actor.
worker_pod_uid
string
worker_pod_uid is the Kubernetes UID of worker_pod.
worker_pod_ips
repeated string
worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING.
node_name
string
node_name is the Kubernetes node hosting worker_pod.
worker_epoch
int64
worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id.
external_volumes
ExternalVolumes
external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it.
volumes
repeated ExternalVolumeStatus
volumes has one entry per external volume of the template. Each template volume appears at most once.
name
string
Name of the volume specified in the actor template. Template volume names are DNS labels.
storage_volume_id
string
The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed.
volume_type
string
Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax).
volume_context
map<string, string>
volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated.
crash
ActorCrash
crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED.
message
string
message is a human-readable description of the failure.
crash_time
google.protobuf.Timestamp
crash_time is when the Actor entered CRASHED.
assigned_node
string
assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding.
snapshots
repeated Snapshot
snapshots holds the Actor's active and in-progress snapshot generations.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
last_assigned_generation
int32
last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up.
next_page_token
string
Pagination token for the next page. Empty if this is the last page.
ListActors
rpc ListActors(ListActorsRequest) returns (ListActorsResponse);ListActorsRequest
message ListActorsRequest { string atespace = 1; ListOptions options = 2;}
ListActorsResponse
message ListActorsResponse { repeated Actor actors = 1; string next_page_token = 2;}
ActorAssignment
subresource of Worker
ActorAssignment binds an Actor to a Worker. This is a subresource of the Worker.
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| ListWorkerActorAssignments | List the Actors hosted by a given Worker. | ListWorkerActorAssignmentsRequest | ListWorkerActorAssignmentsResponse |
Fields
metadata
ResourceMetadata
Metadata about the assignment.
The atespace field is always empty, since it corresponds to a Worker, and Workers are not atespaced. The name field is the Actor's UID, so the Actor that caused an assignment is what addresses it.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor
ObjectRef
actor is the Actor that is assigned to the Worker.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
actor_uid
string
resources
Resources
The resources allocated to the Actor when it was assigned: its limits, plus the actor_overhead of the runtime it runs under on the Worker.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
Example
{ "metadata": { "name": "8f14e45f-ceea-4c3e-9d5b-1a2b3c4d5e6f", "uid": "7a8b9c0d-1e2f-4a3b-8c4d-5e6f7a8b9c0d", "version": "1", "createTime": "2026-08-13T09:47:30Z", "updateTime": "2026-08-13T09:47:30Z" }, "actor": { "atespace": "prod", "name": "c0a8012e-4b7d-4f3a-9e21-6d5f8a9b0c1d" }, "actorUid": "8f14e45f-ceea-4c3e-9d5b-1a2b3c4d5e6f", "resources": { "cpuMillicores": "2000", "memoryBytes": "4294967296" }}
Methods
ListWorkerActorAssignments
List the Actors hosted by a given Worker.
Request (ListWorkerActorAssignmentsRequest)
worker
ObjectRef
The Worker under which to list Actors.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
ListOptions
Pagination controls.
page_size
int32
Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000.
page_token
string
Pagination token from a previous response of the same List method. Omit or leave empty for the first request.
Response (ListWorkerActorAssignmentsResponse)
actor_assignments
repeated ActorAssignment
The Actors this page of the listing covers.
metadata
ResourceMetadata
Metadata about the assignment.
The atespace field is always empty, since it corresponds to a Worker, and Workers are not atespaced. The name field is the Actor's UID, so the Actor that caused an assignment is what addresses it.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
actor
ObjectRef
actor is the Actor that is assigned to the Worker.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
actor_uid
string
resources
Resources
The resources allocated to the Actor when it was assigned: its limits, plus the actor_overhead of the runtime it runs under on the Worker.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
next_page_token
string
Pagination token for the next page. Empty if this is the last page.
ListWorkerActorAssignments
rpc ListWorkerActorAssignments(ListWorkerActorAssignmentsRequest) returns (ListWorkerActorAssignmentsResponse);ListWorkerActorAssignmentsRequest
message ListWorkerActorAssignmentsRequest { ObjectRef worker = 1; ListOptions options = 2;}
ListWorkerActorAssignmentsResponse
message ListWorkerActorAssignmentsResponse { repeated ActorAssignment actor_assignments = 1; string next_page_token = 2;}
ActorTemplate
atespace
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| CreateActorTemplate | CreateActorTemplateRequest | ActorTemplate | |
| GetActorTemplate | GetActorTemplateRequest | ActorTemplate | |
| ListActorTemplates | ListActorTemplatesRequest | ListActorTemplatesResponse | |
| DeleteActorTemplate | Delete an ActorTemplate together with its golden actor and golden tag in the template's atespace. | DeleteActorTemplateRequest | ActorTemplate |
Fields
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_selector
Selector
worker_selector restricts which worker pools actors from this template may use, by matching the pools' labels. Unset, every pool is eligible.
The pool decides the sandbox class an actor runs in, so this selector is also how a template pins one: if the cluster runs pools of more than one sandbox class and the workload needs a particular one, select only pools of that class. An actor booting with no snapshot and no selector may land on a pool of any class, and keeps that class from its first checkpoint on.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
containers
repeated Container
name
string
image
string
image is the OCI image reference the container runs: [registry/]repository[:tag]@digest. Must be pinned by digest (e.g. "name@sha256:...").
command
repeated string
Entrypoint array; when set, the image's ENTRYPOINT and CMD are both ignored and the process argv is command + args. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded.
args
repeated string
Arguments to the entrypoint; the image's CMD is used if unset (unless command is set, which discards the image's CMD).
env
repeated EnvVar
Env variables to set in the container's process environment. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded in this field.
name
string
name may be any printable ASCII character except '='.
value
string
value is the literal value.
wakeup_probe
WakeupProbe
wakeup_probe gates each wakeup on this container: ResumeActor returns only after the probe answers HTTP 200. Without it, ResumeActor returns as soon as the container has started, which may be before it listens.
http_get
HttpGetAction
http_get is the request to poll.
path
string
path must be a URL path starting with "/", using only RFC 3986 path-segment characters, without query or fragment. Defaults to "/" when unset.
port
int32
port is the container port to connect to.
timeout_seconds
int32
timeout_seconds is how long to keep polling before giving up. Defaults to 30 when unset.
volume_mounts
repeated VolumeMount
Keyed by mount_path: each path hosts exactly one mount, while a volume may be mounted at multiple paths.
name
string
name must match the name of a Volume.
mount_path
string
mount_path within the container. Must be a clean absolute Unix path: must start with '/', not be '/', and contain no ':', '..', '.', '//', trailing '/', or control characters.
security_context
SecurityContext
security_context adjusts the container's security settings. Unset leaves the default capability set.
capabilities
Capabilities
capabilities adjusts the Linux capabilities of the container's process.
add
repeated string
add lists capabilities to grant on top of the default set. "ALL" is rejected: name the individual capabilities the container needs.
drop
repeated string
drop lists capabilities to remove from the default set. "ALL" drops the whole set, so drop+add expresses an exact set rather than a relative one.
resources
ResourceRequirements
resources carries this container's compute limits, enforced inside the actor's sandbox. A limit of 0 leaves that resource unlimited.
limits
Resources
limits is the maximum amount of compute resources allowed.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
volumes
repeated Volume
name
string
name of the volume. Must be a DNS label.
durable_dir
DurableDirVolumeSource
Exactly one of durable_dir / external / image / system_info must be set.
external
ExternalVolumeSource
external is a CSI volume: provisioned for this actor from a template.
template
ExternalVolumeTemplate
template provisions a volume for this actor alone; it is deleted with the actor.
capacity_bytes
int64
capacity_bytes is the size of the volume to create, in bytes. Required.
storage_class_name
string
storage_class_name names the cluster-scoped Kubernetes StorageClass to create the volume from. Required.
system_info
SystemInfoVolumeSource
data_sources
repeated SystemInfoDataSource
data_sources lists the projections to place within the volume. At most one actor_metadata entry may appear, and file paths must be unique across all entries.
actor_metadata
ActorMetadataDataSource
Exactly one of actor_metadata / trust_bundle must be set.
items must not project the same field twice, and item paths must be unique.
field
ActorMetadataField
path
string
path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte.
trust_bundle
TrustBundleDataSource
names
repeated string
One or more named trust bundles to unify and place at the specified path.
Substrate supports a short list of predefined names:
egress-mitm.ate.dev --- The trust anchors for the Substrate egress gateway TLS man-in-the-middle interceptor.
system-roots.ate.dev --- A selection of well-known public CA root certificates, built into Substrate
path
string
path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte.
image
ImageVolumeSource
image mounts the contents of an OCI image, read-only.
reference
string
reference is the OCI image reference. Must include a digest (e.g. "name@sha256:...").
snapshot_config
SnapshotConfig
snapshot_config selects what actor snapshots capture and where they are stored. Optional: when omitted, every field takes its default.
storage_location
string
storage_location is the base object-storage URI snapshots of actors on this version are stored under. If unset, ate-api-server's --snapshot-location is used. Requires the PerTemplateSnapshotLocation preview gate. Each path segment may contain only ASCII letters, digits, '_' and '-'. Each owner's snapshots are stored under <storage_location>/atespaces/..., so no segment may be "atespaces" in any letter case.
preferred_fidelity
SnapshotFidelity
preferred_fidelity is the highest fidelity the system packages when it snapshots the actor. It is a best-effort ceiling, not a guarantee: the system never packages more than this level, and it may package less when a layer cannot be captured or is too expensive to capture at the time, for example memory under host pressure. A process resumed in place on its worker keeps its memory regardless of this setting. Defaults to MEMORY when unset.
golden_snapshot_config
GoldenSnapshotConfig
golden_snapshot_config configures automated golden snapshot creation. Golden snapshots are enabled when this config is omitted.
mode
GoldenSnapshotMode
mode defaults to ENABLED when unspecified. DISABLED skips creating the template's golden actor and tag.
resources
ResourceRequirements
resources is the actor's compute size. Both cpu and memory limits are required: the scheduler books them against worker capacity, and a micro-VM is booted at that size.
limits
Resources
limits is the maximum amount of compute resources allowed.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
golden_egress_policy
EgressPolicyTemplate
Egress policy for the golden Actor during initialization. The template controller creates a policy with these rules through CreateActorEgressPolicy before it resumes the golden Actor. Other Actors created from this template do not inherit this policy, including when using the golden snapshot. If absent, no policy is created. When set, at least one rule is required. May not be set when snapshot_config.golden_snapshot_config.mode is DISABLED.
rules
repeated EgressRule
Rules are an unordered set of allows, with the same precedence and effects as EgressPolicy.rules. At least one rule is required. Traffic is denied when no rule matches.
http
HttpRule
Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule.
hostnames
repeated string
Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches.
The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot.
A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination.
Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid.
ports
Ports
Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
https
HttpsRule
HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported.
hostnames
repeated string
Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames.
ports
Ports
Ports of the destination the Actor connected to. Defaults to port 443.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
tls_passthrough
TlsPassthroughRule
TLS to the named servers, forwarded without decryption.
status
ActorTemplateStatus
golden_snapshot_status
GoldenSnapshotStatus
golden_tag
ObjectRef
golden_tag owns the immutable snapshot built by the template controller. Set after tagging the snapshot and deleting the temporary golden Actor.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
snapshot_time
google.protobuf.Timestamp
snapshot_time is when the golden-actor warmup ends and the golden snapshot may be taken.
error_message
string
error_message is set when the golden snapshot build fails and will not be
retried, formatted as <Reason>: <detail>. A nonempty value is terminal.
Example
{ "metadata": { "atespace": "prod", "name": "a7d3e9f1-2c4b-4e8a-b5d6-7f9e0a1b2c3d", "uid": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "version": "3", "createTime": "2026-07-15T10:00:00Z", "updateTime": "2026-07-15T10:04:12Z" }, "workerSelector": { "matchLabels": { "tier": "1" } }, "containers": [ { "name": "agent", "image": "registry.example.com/agents/checkout@sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08", "args": [ "--port=8080" ], "env": [ { "name": "LOG_LEVEL", "value": "info" } ], "wakeupProbe": { "httpGet": { "path": "/healthz", "port": 8080 }, "timeoutSeconds": 30 }, "volumeMounts": [ { "name": "workspace", "mountPath": "/workspace" } ] } ], "volumes": [ { "name": "workspace", "durableDir": {} } ], "snapshotConfig": { "storageLocation": "objectstore://substrate-snapshots", "preferredFidelity": "SNAPSHOT_FIDELITY_MEMORY", "goldenSnapshotConfig": { "mode": "GOLDEN_SNAPSHOT_MODE_ENABLED" } }, "resources": { "limits": { "cpuMillicores": "2000", "memoryBytes": "4294967296" } }, "status": { "goldenSnapshotStatus": { "goldenTag": { "atespace": "ate-golden", "name": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a" }, "snapshotTime": "2026-07-15T10:02:00Z" } }}
Methods
CreateActorTemplate
Request (CreateActorTemplateRequest)
actor_template
ActorTemplate
The actor template version to create. Server-assigned metadata (uid, version, timestamps) is ignored, as are the status fields.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_selector
Selector
worker_selector restricts which worker pools actors from this template may use, by matching the pools' labels. Unset, every pool is eligible.
The pool decides the sandbox class an actor runs in, so this selector is also how a template pins one: if the cluster runs pools of more than one sandbox class and the workload needs a particular one, select only pools of that class. An actor booting with no snapshot and no selector may land on a pool of any class, and keeps that class from its first checkpoint on.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
containers
repeated Container
name
string
image
string
image is the OCI image reference the container runs: [registry/]repository[:tag]@digest. Must be pinned by digest (e.g. "name@sha256:...").
command
repeated string
Entrypoint array; when set, the image's ENTRYPOINT and CMD are both ignored and the process argv is command + args. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded.
args
repeated string
Arguments to the entrypoint; the image's CMD is used if unset (unless command is set, which discards the image's CMD).
env
repeated EnvVar
Env variables to set in the container's process environment. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded in this field.
name
string
name may be any printable ASCII character except '='.
value
string
value is the literal value.
wakeup_probe
WakeupProbe
wakeup_probe gates each wakeup on this container: ResumeActor returns only after the probe answers HTTP 200. Without it, ResumeActor returns as soon as the container has started, which may be before it listens.
http_get
HttpGetAction
http_get is the request to poll.
path
string
path must be a URL path starting with "/", using only RFC 3986 path-segment characters, without query or fragment. Defaults to "/" when unset.
port
int32
port is the container port to connect to.
timeout_seconds
int32
timeout_seconds is how long to keep polling before giving up. Defaults to 30 when unset.
volume_mounts
repeated VolumeMount
Keyed by mount_path: each path hosts exactly one mount, while a volume may be mounted at multiple paths.
name
string
name must match the name of a Volume.
mount_path
string
mount_path within the container. Must be a clean absolute Unix path: must start with '/', not be '/', and contain no ':', '..', '.', '//', trailing '/', or control characters.
security_context
SecurityContext
security_context adjusts the container's security settings. Unset leaves the default capability set.
capabilities
Capabilities
capabilities adjusts the Linux capabilities of the container's process.
add
repeated string
add lists capabilities to grant on top of the default set. "ALL" is rejected: name the individual capabilities the container needs.
drop
repeated string
drop lists capabilities to remove from the default set. "ALL" drops the whole set, so drop+add expresses an exact set rather than a relative one.
resources
ResourceRequirements
resources carries this container's compute limits, enforced inside the actor's sandbox. A limit of 0 leaves that resource unlimited.
limits
Resources
limits is the maximum amount of compute resources allowed.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
volumes
repeated Volume
name
string
name of the volume. Must be a DNS label.
durable_dir
DurableDirVolumeSource
Exactly one of durable_dir / external / image / system_info must be set.
external
ExternalVolumeSource
external is a CSI volume: provisioned for this actor from a template.
template
ExternalVolumeTemplate
template provisions a volume for this actor alone; it is deleted with the actor.
capacity_bytes
int64
capacity_bytes is the size of the volume to create, in bytes. Required.
storage_class_name
string
storage_class_name names the cluster-scoped Kubernetes StorageClass to create the volume from. Required.
system_info
SystemInfoVolumeSource
data_sources
repeated SystemInfoDataSource
data_sources lists the projections to place within the volume. At most one actor_metadata entry may appear, and file paths must be unique across all entries.
actor_metadata
ActorMetadataDataSource
Exactly one of actor_metadata / trust_bundle must be set.
items must not project the same field twice, and item paths must be unique.
field
ActorMetadataField
path
string
path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte.
trust_bundle
TrustBundleDataSource
names
repeated string
One or more named trust bundles to unify and place at the specified path.
Substrate supports a short list of predefined names:
egress-mitm.ate.dev --- The trust anchors for the Substrate egress gateway TLS man-in-the-middle interceptor.
system-roots.ate.dev --- A selection of well-known public CA root certificates, built into Substrate
path
string
path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte.
image
ImageVolumeSource
image mounts the contents of an OCI image, read-only.
reference
string
reference is the OCI image reference. Must include a digest (e.g. "name@sha256:...").
snapshot_config
SnapshotConfig
snapshot_config selects what actor snapshots capture and where they are stored. Optional: when omitted, every field takes its default.
storage_location
string
storage_location is the base object-storage URI snapshots of actors on this version are stored under. If unset, ate-api-server's --snapshot-location is used. Requires the PerTemplateSnapshotLocation preview gate. Each path segment may contain only ASCII letters, digits, '_' and '-'. Each owner's snapshots are stored under <storage_location>/atespaces/..., so no segment may be "atespaces" in any letter case.
preferred_fidelity
SnapshotFidelity
preferred_fidelity is the highest fidelity the system packages when it snapshots the actor. It is a best-effort ceiling, not a guarantee: the system never packages more than this level, and it may package less when a layer cannot be captured or is too expensive to capture at the time, for example memory under host pressure. A process resumed in place on its worker keeps its memory regardless of this setting. Defaults to MEMORY when unset.
golden_snapshot_config
GoldenSnapshotConfig
golden_snapshot_config configures automated golden snapshot creation. Golden snapshots are enabled when this config is omitted.
mode
GoldenSnapshotMode
mode defaults to ENABLED when unspecified. DISABLED skips creating the template's golden actor and tag.
resources
ResourceRequirements
resources is the actor's compute size. Both cpu and memory limits are required: the scheduler books them against worker capacity, and a micro-VM is booted at that size.
limits
Resources
limits is the maximum amount of compute resources allowed.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
golden_egress_policy
EgressPolicyTemplate
Egress policy for the golden Actor during initialization. The template controller creates a policy with these rules through CreateActorEgressPolicy before it resumes the golden Actor. Other Actors created from this template do not inherit this policy, including when using the golden snapshot. If absent, no policy is created. When set, at least one rule is required. May not be set when snapshot_config.golden_snapshot_config.mode is DISABLED.
rules
repeated EgressRule
Rules are an unordered set of allows, with the same precedence and effects as EgressPolicy.rules. At least one rule is required. Traffic is denied when no rule matches.
http
HttpRule
Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule.
hostnames
repeated string
Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches.
The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot.
A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination.
Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid.
ports
Ports
Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
https
HttpsRule
HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported.
hostnames
repeated string
Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames.
ports
Ports
Ports of the destination the Actor connected to. Defaults to port 443.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
tls_passthrough
TlsPassthroughRule
TLS to the named servers, forwarded without decryption.
status
ActorTemplateStatus
golden_snapshot_status
GoldenSnapshotStatus
golden_tag
ObjectRef
golden_tag owns the immutable snapshot built by the template controller. Set after tagging the snapshot and deleting the temporary golden Actor.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
snapshot_time
google.protobuf.Timestamp
snapshot_time is when the golden-actor warmup ends and the golden snapshot may be taken.
error_message
string
error_message is set when the golden snapshot build fails and will not be
retried, formatted as <Reason>: <detail>. A nonempty value is terminal.
Response (ActorTemplate)
The ActorTemplate resource.
CreateActorTemplate
rpc CreateActorTemplate(CreateActorTemplateRequest) returns (ActorTemplate);CreateActorTemplateRequest
message CreateActorTemplateRequest { ActorTemplate actor_template = 1;}
GetActorTemplate
Request (GetActorTemplateRequest)
actor_template
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
Response (ActorTemplate)
The ActorTemplate resource.
GetActorTemplate
rpc GetActorTemplate(GetActorTemplateRequest) returns (ActorTemplate);GetActorTemplateRequest
message GetActorTemplateRequest { ObjectRef actor_template = 1;}
ListActorTemplates
Request (ListActorTemplatesRequest)
atespace
string
The atespace to list actor templates from. Empty lists across all atespaces.
options
ListOptions
Pagination controls.
page_size
int32
Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000.
page_token
string
Pagination token from a previous response of the same List method. Omit or leave empty for the first request.
Response (ListActorTemplatesResponse)
actor_templates
repeated ActorTemplate
The page of actor template versions. This list may be empty even if there are more results.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_selector
Selector
worker_selector restricts which worker pools actors from this template may use, by matching the pools' labels. Unset, every pool is eligible.
The pool decides the sandbox class an actor runs in, so this selector is also how a template pins one: if the cluster runs pools of more than one sandbox class and the workload needs a particular one, select only pools of that class. An actor booting with no snapshot and no selector may land on a pool of any class, and keeps that class from its first checkpoint on.
match_labels
map<string, string>
match_labels selects by exact equality on a set of labels.
containers
repeated Container
name
string
image
string
image is the OCI image reference the container runs: [registry/]repository[:tag]@digest. Must be pinned by digest (e.g. "name@sha256:...").
command
repeated string
Entrypoint array; when set, the image's ENTRYPOINT and CMD are both ignored and the process argv is command + args. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded.
args
repeated string
Arguments to the entrypoint; the image's CMD is used if unset (unless command is set, which discards the image's CMD).
env
repeated EnvVar
Env variables to set in the container's process environment. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded in this field.
name
string
name may be any printable ASCII character except '='.
value
string
value is the literal value.
wakeup_probe
WakeupProbe
wakeup_probe gates each wakeup on this container: ResumeActor returns only after the probe answers HTTP 200. Without it, ResumeActor returns as soon as the container has started, which may be before it listens.
http_get
HttpGetAction
http_get is the request to poll.
path
string
path must be a URL path starting with "/", using only RFC 3986 path-segment characters, without query or fragment. Defaults to "/" when unset.
port
int32
port is the container port to connect to.
timeout_seconds
int32
timeout_seconds is how long to keep polling before giving up. Defaults to 30 when unset.
volume_mounts
repeated VolumeMount
Keyed by mount_path: each path hosts exactly one mount, while a volume may be mounted at multiple paths.
name
string
name must match the name of a Volume.
mount_path
string
mount_path within the container. Must be a clean absolute Unix path: must start with '/', not be '/', and contain no ':', '..', '.', '//', trailing '/', or control characters.
security_context
SecurityContext
security_context adjusts the container's security settings. Unset leaves the default capability set.
capabilities
Capabilities
capabilities adjusts the Linux capabilities of the container's process.
add
repeated string
add lists capabilities to grant on top of the default set. "ALL" is rejected: name the individual capabilities the container needs.
drop
repeated string
drop lists capabilities to remove from the default set. "ALL" drops the whole set, so drop+add expresses an exact set rather than a relative one.
resources
ResourceRequirements
resources carries this container's compute limits, enforced inside the actor's sandbox. A limit of 0 leaves that resource unlimited.
limits
Resources
limits is the maximum amount of compute resources allowed.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
volumes
repeated Volume
name
string
name of the volume. Must be a DNS label.
durable_dir
DurableDirVolumeSource
Exactly one of durable_dir / external / image / system_info must be set.
external
ExternalVolumeSource
external is a CSI volume: provisioned for this actor from a template.
template
ExternalVolumeTemplate
template provisions a volume for this actor alone; it is deleted with the actor.
capacity_bytes
int64
capacity_bytes is the size of the volume to create, in bytes. Required.
storage_class_name
string
storage_class_name names the cluster-scoped Kubernetes StorageClass to create the volume from. Required.
system_info
SystemInfoVolumeSource
data_sources
repeated SystemInfoDataSource
data_sources lists the projections to place within the volume. At most one actor_metadata entry may appear, and file paths must be unique across all entries.
actor_metadata
ActorMetadataDataSource
Exactly one of actor_metadata / trust_bundle must be set.
items must not project the same field twice, and item paths must be unique.
field
ActorMetadataField
path
string
path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte.
trust_bundle
TrustBundleDataSource
names
repeated string
One or more named trust bundles to unify and place at the specified path.
Substrate supports a short list of predefined names:
egress-mitm.ate.dev --- The trust anchors for the Substrate egress gateway TLS man-in-the-middle interceptor.
system-roots.ate.dev --- A selection of well-known public CA root certificates, built into Substrate
path
string
path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte.
image
ImageVolumeSource
image mounts the contents of an OCI image, read-only.
reference
string
reference is the OCI image reference. Must include a digest (e.g. "name@sha256:...").
snapshot_config
SnapshotConfig
snapshot_config selects what actor snapshots capture and where they are stored. Optional: when omitted, every field takes its default.
storage_location
string
storage_location is the base object-storage URI snapshots of actors on this version are stored under. If unset, ate-api-server's --snapshot-location is used. Requires the PerTemplateSnapshotLocation preview gate. Each path segment may contain only ASCII letters, digits, '_' and '-'. Each owner's snapshots are stored under <storage_location>/atespaces/..., so no segment may be "atespaces" in any letter case.
preferred_fidelity
SnapshotFidelity
preferred_fidelity is the highest fidelity the system packages when it snapshots the actor. It is a best-effort ceiling, not a guarantee: the system never packages more than this level, and it may package less when a layer cannot be captured or is too expensive to capture at the time, for example memory under host pressure. A process resumed in place on its worker keeps its memory regardless of this setting. Defaults to MEMORY when unset.
golden_snapshot_config
GoldenSnapshotConfig
golden_snapshot_config configures automated golden snapshot creation. Golden snapshots are enabled when this config is omitted.
mode
GoldenSnapshotMode
mode defaults to ENABLED when unspecified. DISABLED skips creating the template's golden actor and tag.
resources
ResourceRequirements
resources is the actor's compute size. Both cpu and memory limits are required: the scheduler books them against worker capacity, and a micro-VM is booted at that size.
limits
Resources
limits is the maximum amount of compute resources allowed.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). 0 means none.
memory_bytes
int64
memory_bytes is memory in bytes. 0 means none.
golden_egress_policy
EgressPolicyTemplate
Egress policy for the golden Actor during initialization. The template controller creates a policy with these rules through CreateActorEgressPolicy before it resumes the golden Actor. Other Actors created from this template do not inherit this policy, including when using the golden snapshot. If absent, no policy is created. When set, at least one rule is required. May not be set when snapshot_config.golden_snapshot_config.mode is DISABLED.
rules
repeated EgressRule
Rules are an unordered set of allows, with the same precedence and effects as EgressPolicy.rules. At least one rule is required. Traffic is denied when no rule matches.
http
HttpRule
Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule.
hostnames
repeated string
Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches.
The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot.
A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination.
Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid.
ports
Ports
Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
https
HttpsRule
HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported.
hostnames
repeated string
Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames.
ports
Ports
Ports of the destination the Actor connected to. Defaults to port 443.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
tls_passthrough
TlsPassthroughRule
TLS to the named servers, forwarded without decryption.
status
ActorTemplateStatus
golden_snapshot_status
GoldenSnapshotStatus
golden_tag
ObjectRef
golden_tag owns the immutable snapshot built by the template controller. Set after tagging the snapshot and deleting the temporary golden Actor.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
snapshot_time
google.protobuf.Timestamp
snapshot_time is when the golden-actor warmup ends and the golden snapshot may be taken.
error_message
string
error_message is set when the golden snapshot build fails and will not be
retried, formatted as <Reason>: <detail>. A nonempty value is terminal.
next_page_token
string
Pagination token for the next page. Empty if this is the last page.
ListActorTemplates
rpc ListActorTemplates(ListActorTemplatesRequest) returns (ListActorTemplatesResponse);ListActorTemplatesRequest
message ListActorTemplatesRequest { string atespace = 1; ListOptions options = 2;}
ListActorTemplatesResponse
message ListActorTemplatesResponse { repeated ActorTemplate actor_templates = 1; string next_page_token = 2;}
DeleteActorTemplate
Delete an ActorTemplate together with its golden actor and golden tag in the template's atespace.
Request (DeleteActorTemplateRequest)
actor_template
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
Response (ActorTemplate)
The ActorTemplate resource.
DeleteActorTemplate
rpc DeleteActorTemplate(DeleteActorTemplateRequest) returns (ActorTemplate);DeleteActorTemplateRequest
message DeleteActorTemplateRequest { ObjectRef actor_template = 1; DeleteOptions options = 2;}
Atespace
global
Atespace is the isolation boundary an Actor is created into. Global-scoped: metadata.atespace is always empty; the atespace's identity is metadata.name.
Subresources
- AccessPolicy singleton
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| CreateAtespace | Create a new Atespace. Substrate-native, stored in database. | CreateAtespaceRequest | Atespace |
| GetAtespace | Get an Atespace by name. | GetAtespaceRequest | Atespace |
| ListAtespaces | List Atespaces. | ListAtespacesRequest | ListAtespacesResponse |
| DeleteAtespace | Delete an empty Atespace. Rejects (FailedPrecondition) if any Actors or Tags remain. | DeleteAtespaceRequest | Atespace |
Fields
metadata
ResourceMetadata
Common resource metadata: name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
Example
{ "metadata": { "name": "prod", "uid": "3c4d5e6f-7a8b-4c9d-8e1f-2a3b4c5d6e7f", "version": "1", "createTime": "2026-06-01T00:00:00Z", "updateTime": "2026-06-01T00:00:00Z" }}
Methods
CreateAtespace
Create a new Atespace. Substrate-native, stored in database.
Request (CreateAtespaceRequest)
atespace
Atespace
The atespace to create.
metadata
ResourceMetadata
Common resource metadata: name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
CreateAtespace
rpc CreateAtespace(CreateAtespaceRequest) returns (Atespace);CreateAtespaceRequest
message CreateAtespaceRequest { Atespace atespace = 1;}
GetAtespace
Get an Atespace by name.
Request (GetAtespaceRequest)
atespace
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
GetAtespace
rpc GetAtespace(GetAtespaceRequest) returns (Atespace);GetAtespaceRequest
message GetAtespaceRequest { ObjectRef atespace = 1;}
ListAtespaces
List Atespaces.
Request (ListAtespacesRequest)
options
ListOptions
Pagination controls.
page_size
int32
Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000.
page_token
string
Pagination token from a previous response of the same List method. Omit or leave empty for the first request.
Response (ListAtespacesResponse)
atespaces
repeated Atespace
The page of atespaces. This list may be empty even if there are more results.
metadata
ResourceMetadata
Common resource metadata: name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
next_page_token
string
Pagination token for the next page. Empty if this is the last page.
ListAtespaces
rpc ListAtespaces(ListAtespacesRequest) returns (ListAtespacesResponse);ListAtespacesRequest
message ListAtespacesRequest { ListOptions options = 1;}
ListAtespacesResponse
message ListAtespacesResponse { repeated Atespace atespaces = 1; string next_page_token = 2;}
DeleteAtespace
Delete an empty Atespace. Rejects (FailedPrecondition) if any Actors or Tags remain.
Request (DeleteAtespaceRequest)
atespace
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
DeleteAtespace
rpc DeleteAtespace(DeleteAtespaceRequest) returns (Atespace);DeleteAtespaceRequest
message DeleteAtespaceRequest { ObjectRef atespace = 1; DeleteOptions options = 2;}
EgressPolicy
subresource of Actor singleton
EgressPolicy is an egress policy resource nested under an Actor. An Actor has at most one egress policy resource, named "default".
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| GetActorEgressPolicy | Get the egress policy resource nested under an Actor. | GetActorEgressPolicyRequest | EgressPolicy |
| CreateActorEgressPolicy | Create the egress policy resource nested under an Actor. | CreateActorEgressPolicyRequest | EgressPolicy |
| UpdateActorEgressPolicy | Replace the egress policy resource nested under an Actor. | UpdateActorEgressPolicyRequest | EgressPolicy |
| DeleteActorEgressPolicy | Delete the egress policy resource nested under an Actor. | DeleteActorEgressPolicyRequest | EgressPolicy |
Fields
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent Actor and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
rules
repeated EgressRule
Rules are an unordered set of allows. Traffic is denied when no rule matches.
For a given destination name and port, exactly one rule decides, whatever its protocol. When more than one rule matches, the winner is chosen by these criteria, in order, moving to the next one on a tie:
- A matching hostname without a wildcard.
- A matching port number rather than all ports.
Two rules with the same pattern on the same port, or both on all ports, are rejected at admission.
These criteria apply within a protocol and across protocols that decide on the same input, such as an https and a tls_passthrough rule that match the same pattern. Only the winning rule's effects are applied.
http
HttpRule
Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule.
hostnames
repeated string
Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches.
The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot.
A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination.
Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid.
ports
Ports
Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
https
HttpsRule
HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported.
hostnames
repeated string
Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames.
ports
Ports
Ports of the destination the Actor connected to. Defaults to port 443.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
tls_passthrough
TlsPassthroughRule
TLS to the named servers, forwarded without decryption.
Example
{ "metadata": { "atespace": "prod", "name": "default", "uid": "1a2b3c4d-5e6f-4a3b-8c9d-0e1f2a3b4c5d", "version": "2", "createTime": "2026-08-01T18:22:04Z", "updateTime": "2026-08-02T11:05:40Z" }, "rules": [ { "https": { "hostnames": [ "api.example.com" ], "effects": { "replaceHeaders": [ { "header": "Authorization", "prefix": "Bearer ", "credentialUri": "ate-secret://example-provider/prod/checkout-api-key" } ] } } }, { "tlsPassthrough": { "hostnames": [ "*.example.com" ], "ports": { "numbers": [ 443 ] } } } ]}
Methods
GetActorEgressPolicy
Get the egress policy resource nested under an Actor.
Request (GetActorEgressPolicyRequest)
actor
ObjectRef
The parent Actor of the egress policy resource to retrieve.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
name
string
Name of the singleton egress policy. Must be "default".
Response (EgressPolicy)
The EgressPolicy resource.
GetActorEgressPolicy
rpc GetActorEgressPolicy(GetActorEgressPolicyRequest) returns (EgressPolicy);GetActorEgressPolicyRequest
message GetActorEgressPolicyRequest { ObjectRef actor = 1; string name = 2;}
CreateActorEgressPolicy
Create the egress policy resource nested under an Actor.
Request (CreateActorEgressPolicyRequest)
actor
ObjectRef
Parent Actor under which to create the policy resource.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
egress_policy
EgressPolicy
The policy to create. metadata.name must be "default" and metadata.atespace must match actor.atespace.
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent Actor and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
rules
repeated EgressRule
Rules are an unordered set of allows. Traffic is denied when no rule matches.
For a given destination name and port, exactly one rule decides, whatever its protocol. When more than one rule matches, the winner is chosen by these criteria, in order, moving to the next one on a tie:
- A matching hostname without a wildcard.
- A matching port number rather than all ports.
Two rules with the same pattern on the same port, or both on all ports, are rejected at admission.
These criteria apply within a protocol and across protocols that decide on the same input, such as an https and a tls_passthrough rule that match the same pattern. Only the winning rule's effects are applied.
http
HttpRule
Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule.
hostnames
repeated string
Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches.
The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot.
A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination.
Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid.
ports
Ports
Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
https
HttpsRule
HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported.
hostnames
repeated string
Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames.
ports
Ports
Ports of the destination the Actor connected to. Defaults to port 443.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
tls_passthrough
TlsPassthroughRule
TLS to the named servers, forwarded without decryption.
Response (EgressPolicy)
The EgressPolicy resource.
CreateActorEgressPolicy
rpc CreateActorEgressPolicy(CreateActorEgressPolicyRequest) returns (EgressPolicy);CreateActorEgressPolicyRequest
message CreateActorEgressPolicyRequest { ObjectRef actor = 1; EgressPolicy egress_policy = 2;}
UpdateActorEgressPolicy
Replace the egress policy resource nested under an Actor.
Request (UpdateActorEgressPolicyRequest)
actor
ObjectRef
Parent Actor under which to update the policy resource.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
egress_policy
EgressPolicy
Full replacement. Metadata UID and version are required preconditions; atespace and name are immutable and must match the existing policy.
metadata
ResourceMetadata
Standard resource metadata. Atespace must match the parent Actor and name must be "default". Both are caller-specified on create and immutable. UID, version, create_time, and update_time are server-managed.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
rules
repeated EgressRule
Rules are an unordered set of allows. Traffic is denied when no rule matches.
For a given destination name and port, exactly one rule decides, whatever its protocol. When more than one rule matches, the winner is chosen by these criteria, in order, moving to the next one on a tie:
- A matching hostname without a wildcard.
- A matching port number rather than all ports.
Two rules with the same pattern on the same port, or both on all ports, are rejected at admission.
These criteria apply within a protocol and across protocols that decide on the same input, such as an https and a tls_passthrough rule that match the same pattern. Only the winning rule's effects are applied.
http
HttpRule
Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule.
hostnames
repeated string
Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches.
The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot.
A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination.
Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid.
ports
Ports
Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
https
HttpsRule
HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported.
hostnames
repeated string
Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames.
ports
Ports
Ports of the destination the Actor connected to. Defaults to port 443.
all
AllPorts
Every port.
numbers
repeated int32
Port numbers, without repeats.
effects
HttpRuleEffects
Effects do not authorize traffic. They are applied only when this is the deciding rule.
replace_headers
repeated CredentialHeader
Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively.
Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination.
header
string
The case-insensitive HTTP request header to replace when present.
prefix
string
Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization.
credential_uri
string
Source-agnostic reference interpreted by a registered credential provider:
ate-secret://<provider-class>/<provider-name>/<provider-specific-tail>
Exactly one of credential_uri and actor_jwt must be set.
actor_jwt
ActorJwtSource
A Substrate-issued JWT asserting the identity of the Actor that sent the request.
audiences
repeated string
The audiences the JWT is bound to, which become its aud claim.
expiration_seconds
int64
Lifetime of each JWT, in seconds.
tls_passthrough
TlsPassthroughRule
TLS to the named servers, forwarded without decryption.
Response (EgressPolicy)
The EgressPolicy resource.
UpdateActorEgressPolicy
rpc UpdateActorEgressPolicy(UpdateActorEgressPolicyRequest) returns (EgressPolicy);UpdateActorEgressPolicyRequest
message UpdateActorEgressPolicyRequest { ObjectRef actor = 1; EgressPolicy egress_policy = 2;}
DeleteActorEgressPolicy
Delete the egress policy resource nested under an Actor.
Request (DeleteActorEgressPolicyRequest)
actor
ObjectRef
The parent Actor of the egress policy resource to delete.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
name
string
Name of the singleton egress policy. Must be "default".
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
Response (EgressPolicy)
The EgressPolicy resource.
DeleteActorEgressPolicy
rpc DeleteActorEgressPolicy(DeleteActorEgressPolicyRequest) returns (EgressPolicy);DeleteActorEgressPolicyRequest
message DeleteActorEgressPolicyRequest { ObjectRef actor = 1; string name = 2; DeleteOptions options = 3;}
Tag
atespace
Tag is an Atespace-owned, stable name for one external snapshot. The external snapshot pointed by a tag is a copy of an actor snapshot. The snapshot is copied when the tag is created, and deleted when the tag is. Its owning Atespace cannot be deleted until the tag is removed.
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| CreateTag | Tag the external snapshot a suspended Actor holds. The tag gets its own copy of that snapshot, so suspending or deleting the Actor afterwards cannot collect it. When the Actor's latest snapshot is not uploaded yet, atelet uploads it first, so the call can take as long as that upload. | CreateTagRequest | Tag |
| GetTag | Get a Tag. | GetTagRequest | Tag |
| ListTags | List Tags. | ListTagsRequest | ListTagsResponse |
| UpdateTag | Publish or unpublish a Tag without changing its address. | UpdateTagRequest | Tag |
| DeleteTag | Delete a Tag and the external snapshot it owns. Actors created from the tag that have not yet been suspended still point at that external snapshot and become unrecoverable, so do not delete a tag while such Actors exist. | DeleteTagRequest | Tag |
Fields
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
status
TagStatus
status is set by the control plane; it is ignored on write.
snapshot
Snapshot
snapshot is the external snapshot this tag points at: the tag's own copy, stored under a prefix keyed on the tag's UID. It is recorded with its durable_snapshot PENDING right after the tag is reserved, before anything is copied, and transitions to COMPLETED once the copy finishes: a tag never moves between snapshots and is usable only once COMPLETED. Unset until it is recorded; a tag whose creation failed first never gets one.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_template_uid
string
UID of the ActorTemplate the snapshot was taken under. Actors can only be seeded from a tag under the same template.
scope
TagScope
scope controls who may create an Actor from this tag.
source_actor
ObjectRef
source_actor is the suspended Actor whose external snapshot this tag captures. The tag lives in this Actor's Atespace. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
Example
{ "metadata": { "atespace": "prod", "name": "e2f4a6b8-1c3d-4e5f-8a7b-9c0d1e2f3a4b", "uid": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "version": "3", "createTime": "2026-08-13T10:00:00Z", "updateTime": "2026-08-13T10:01:15Z" }, "status": { "snapshot": { "uuid": "5d2c7e1a-9b3f-4c8d-a6e2-0f1b2c3d4e5f", "generation": 3, "owner": "SNAPSHOT_OWNER_TAG", "fidelity": "SNAPSHOT_FIDELITY_MEMORY", "actorTemplateUid": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a", "durableSnapshot": { "state": "SNAPSHOT_STORAGE_STATE_COMPLETED", "object": { "snapshotUri": "objectstore://substrate-snapshots/atespaces/prod/tags/2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e" } }, "sandboxRuntime": { "sandboxClass": "gvisor", "version": { "schemaVersion": "v1", "attributes": [ { "key": "architecture", "value": "amd64" }, { "key": "sandbox_bundle_hash", "value": "b5bb9d8014a0f9b1d61e21e796d78dcc" } ] } } }, "actorTemplateUid": "4d5e6f7a-8b9c-4d0e-9f2a-3b4c5d6e7f8a" }, "scope": "TAG_SCOPE_ATESPACE", "sourceActor": { "atespace": "prod", "name": "c0a8012e-4b7d-4f3a-9e21-6d5f8a9b0c1d" }}
Methods
CreateTag
Tag the external snapshot a suspended Actor holds. The tag gets its own copy of that snapshot, so suspending or deleting the Actor afterwards cannot collect it. When the Actor's latest snapshot is not uploaded yet, atelet uploads it first, so the call can take as long as that upload.
Request (CreateTagRequest)
tag
Tag
The tag to create. metadata.atespace, metadata.name, scope and source_actor are honored; metadata.atespace must match source_actor's, and status is ignored on write.
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
status
TagStatus
status is set by the control plane; it is ignored on write.
snapshot
Snapshot
snapshot is the external snapshot this tag points at: the tag's own copy, stored under a prefix keyed on the tag's UID. It is recorded with its durable_snapshot PENDING right after the tag is reserved, before anything is copied, and transitions to COMPLETED once the copy finishes: a tag never moves between snapshots and is usable only once COMPLETED. Unset until it is recorded; a tag whose creation failed first never gets one.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_template_uid
string
UID of the ActorTemplate the snapshot was taken under. Actors can only be seeded from a tag under the same template.
scope
TagScope
scope controls who may create an Actor from this tag.
source_actor
ObjectRef
source_actor is the suspended Actor whose external snapshot this tag captures. The tag lives in this Actor's Atespace. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
CreateTag
rpc CreateTag(CreateTagRequest) returns (Tag);CreateTagRequest
message CreateTagRequest { Tag tag = 1;}
GetTag
Get a Tag.
Request (GetTagRequest)
tag
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
GetTag
rpc GetTag(GetTagRequest) returns (Tag);GetTagRequest
message GetTagRequest { ObjectRef tag = 1;}
ListTags
List Tags.
Request (ListTagsRequest)
atespace
string
The atespace to list tags from. Empty lists across all atespaces.
options
ListOptions
Pagination controls.
page_size
int32
Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000.
page_token
string
Pagination token from a previous response of the same List method. Omit or leave empty for the first request.
Response (ListTagsResponse)
tags
repeated Tag
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
status
TagStatus
status is set by the control plane; it is ignored on write.
snapshot
Snapshot
snapshot is the external snapshot this tag points at: the tag's own copy, stored under a prefix keyed on the tag's UID. It is recorded with its durable_snapshot PENDING right after the tag is reserved, before anything is copied, and transitions to COMPLETED once the copy finishes: a tag never moves between snapshots and is usable only once COMPLETED. Unset until it is recorded; a tag whose creation failed first never gets one.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_template_uid
string
UID of the ActorTemplate the snapshot was taken under. Actors can only be seeded from a tag under the same template.
scope
TagScope
scope controls who may create an Actor from this tag.
source_actor
ObjectRef
source_actor is the suspended Actor whose external snapshot this tag captures. The tag lives in this Actor's Atespace. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
next_page_token
string
ListTags
rpc ListTags(ListTagsRequest) returns (ListTagsResponse);ListTagsRequest
message ListTagsRequest { string atespace = 1; ListOptions options = 2;}
ListTagsResponse
message ListTagsResponse { repeated Tag tags = 1; string next_page_token = 2;}
UpdateTag
Publish or unpublish a Tag without changing its address.
Request (UpdateTagRequest)
tag
Tag
The tag to update. tag.metadata.atespace and tag.metadata.name identify which resource to update. tag.metadata.version and tag.metadata.uid are required preconditions
metadata
ResourceMetadata
Common resource metadata: atespace, name, uid, version, timestamps.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
status
TagStatus
status is set by the control plane; it is ignored on write.
snapshot
Snapshot
snapshot is the external snapshot this tag points at: the tag's own copy, stored under a prefix keyed on the tag's UID. It is recorded with its durable_snapshot PENDING right after the tag is reserved, before anything is copied, and transitions to COMPLETED once the copy finishes: a tag never moves between snapshots and is usable only once COMPLETED. Unset until it is recorded; a tag whose creation failed first never gets one.
uuid
string
uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage.
generation
int32
generation is the monotonically increasing generation number of this snapshot, starting at 1.
owner
SnapshotOwner
owner identifies the origin and ownership of this snapshot.
fidelity
SnapshotFidelity
fidelity is what this snapshot holds.
actor_template_uid
string
UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from.
locality
string
locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files.
durable_snapshot
SnapshotStorage
durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded.
state
SnapshotStorageState
state is the lifecycle state of the durable snapshot.
object
ObjectSnapshot
object snapshot is stored in object storage.
snapshot_uri
string
snapshot_uri addresses the snapshot's prefix in object storage.
sandbox_runtime
ActorSandboxRuntime
sandbox_runtime is the runtime the actor ran under when the snapshot was taken.
sandbox_class
string
e.g. "gvisor", "microvm"
version
VersionedSandboxCompat
Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_template_uid
string
UID of the ActorTemplate the snapshot was taken under. Actors can only be seeded from a tag under the same template.
scope
TagScope
scope controls who may create an Actor from this tag.
source_actor
ObjectRef
source_actor is the suspended Actor whose external snapshot this tag captures. The tag lives in this Actor's Atespace. Set once at creation and immutable afterward.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
UpdateTag
rpc UpdateTag(UpdateTagRequest) returns (Tag);UpdateTagRequest
message UpdateTagRequest { Tag tag = 1;}
DeleteTag
Delete a Tag and the external snapshot it owns. Actors created from the tag that have not yet been suspended still point at that external snapshot and become unrecoverable, so do not delete a tag while such Actors exist.
Request (DeleteTagRequest)
tag
ObjectRef
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
DeleteTag
rpc DeleteTag(DeleteTagRequest) returns (Tag);DeleteTagRequest
message DeleteTagRequest { ObjectRef tag = 1; DeleteOptions options = 2;}
Worker
global
Worker is a schedulable worker pod.
Global-scoped: metadata.atespace is always empty. metadata.name is assigned by the control plane and is opaque to clients — never parse it or derive it from anything else; read pod identity from the named fields below.
labels and epoch are the only mutable fields; every other field is either immutable after creation or output-only. UpdateWorker replaces the whole resource, so an immutable field that a request changes — including by omitting it, which would clear it — is rejected with INVALID_ARGUMENT.
Subresources
Methods
| Method | Description | Request | Response |
|---|---|---|---|
| ListWorkers | List Workers. | ListWorkersRequest | ListWorkersResponse |
| GetWorker | Get a Worker. | GetWorkerRequest | Worker |
| CreateWorker | Register a Worker. Called once its Pod has an IP. A Worker is registered UNAVAILABLE and takes no Actors until MarkWorkerAvailable. | CreateWorkerRequest | Worker |
| UpdateWorker | Update observed pool state on a Worker. | UpdateWorkerRequest | Worker |
| DeleteWorker | Deregister a Worker. Does not cascade: the caller is responsible for cleaning up related resources first. | DeleteWorkerRequest | Worker |
| DrainWorker | Mark a Worker as terminating so the scheduler stops routing new Actors to it. Idempotent; one-way. Deliberately leaves any bound Actor alone. Returns ABORTED if another write lands on the Worker first; retry. | DrainWorkerRequest | DrainWorkerResponse |
| MarkWorkerAvailable | Mark an UNAVAILABLE Worker ACTIVE so the scheduler places Actors on it. Idempotent. Returns FAILED_PRECONDITION for a DRAINING Worker, and ABORTED if another write lands on the Worker first; retry. | MarkWorkerAvailableRequest | MarkWorkerAvailableResponse |
| MarkWorkerUnavailable | Mark an ACTIVE Worker UNAVAILABLE so the scheduler stops placing Actors on it, as while its Pod is not Ready. Idempotent. Leaves any bound Actor alone. Returns FAILED_PRECONDITION for a DRAINING Worker, and ABORTED if another write lands on the Worker first; retry. | MarkWorkerUnavailableRequest | MarkWorkerUnavailableResponse |
Fields
metadata
ResourceMetadata
Output-only: name, uid, version and timestamps are all server-assigned. uid and version are echoed back on UpdateWorker as preconditions.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_namespace
string
Kubernetes coordinates. Immutable, set at creation.
worker_pool
string
worker_pod
string
worker_pod_uid
string
node_name
string
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID the worker pod's certificate carries. atenet-router requires it on the certificate of the worker's atunnel.
labels
map<string, string>
labels mirror the WorkerPool object's Kubernetes labels, which selectors match against. Kubernetes does not cap an object's label count, so the bound below is a generous guardrail, not a mirror of an upstream limit.
status
WorkerStatus
Output-only server-managed state. Absent from Create/Update request payloads; whatever a request carries here is ignored. A client moves state only through DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable, and the assignments are the scheduler's.
state
WorkerState
capacity
WorkerResources
The total resource capacity of the Worker.
A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker.
Shrinking capacity below allocated prevents new placements but does not evicts running Actors.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
allocated
WorkerResources
The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
observed_epoch
int64
observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running.
sandbox_classes
repeated WorkerSandboxClass
The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class.
sandbox_class
string
e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name.
default_runtime
WorkerSandboxRuntime
Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
restorable_runtimes
repeated WorkerSandboxRuntime
Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
ips
repeated string
ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs.
issued_epoch
int64
issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup.
registered_epoch
int64
registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then.
Example
{ "metadata": { "name": "3c9e1a2b-6d4f-4b8e-9a71-2c5f0d8b3e94", "uid": "5e6f7a8b-9c0d-4e1f-8a3b-4c5d6e7f8a9b", "version": "7", "createTime": "2026-08-01T08:00:00Z", "updateTime": "2026-08-13T09:47:31Z" }, "workerNamespace": "substrate-workers", "workerPool": "default-pool", "workerPod": "default-pool-6b9d4f-x2p7q", "workerPodUid": "3c9e1a2b-6d4f-4b8e-9a71-2c5f0d8b3e94", "nodeName": "worker-node-1", "workerSpiffeId": "spiffe://cluster.local/ns/substrate-workers/sa/ateworker", "labels": { "tier": "1" }, "status": { "state": "WORKER_STATE_ACTIVE", "capacity": { "cpuMillicores": "4000", "memoryBytes": "17179869184", "actors": 1 }, "allocated": { "cpuMillicores": "2000", "memoryBytes": "4294967296", "actors": 1 }, "observedEpoch": "1", "sandboxClasses": [ { "sandboxClass": "gvisor", "defaultRuntime": { "version": { "schemaVersion": "v1", "attributes": [ { "key": "architecture", "value": "amd64" }, { "key": "sandbox_bundle_hash", "value": "b5bb9d8014a0f9b1d61e21e796d78dcc" } ] } } } ], "ips": [ "10.4.12.31" ], "issuedEpoch": "1", "registeredEpoch": "1" }}
Methods
ListWorkers
List Workers.
Request (ListWorkersRequest)
options
ListOptions
Pagination controls.
page_size
int32
Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000.
page_token
string
Pagination token from a previous response of the same List method. Omit or leave empty for the first request.
Response (ListWorkersResponse)
workers
repeated Worker
The page of workers. This list may be empty even if there are more results.
metadata
ResourceMetadata
Output-only: name, uid, version and timestamps are all server-assigned. uid and version are echoed back on UpdateWorker as preconditions.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_namespace
string
Kubernetes coordinates. Immutable, set at creation.
worker_pool
string
worker_pod
string
worker_pod_uid
string
node_name
string
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID the worker pod's certificate carries. atenet-router requires it on the certificate of the worker's atunnel.
labels
map<string, string>
labels mirror the WorkerPool object's Kubernetes labels, which selectors match against. Kubernetes does not cap an object's label count, so the bound below is a generous guardrail, not a mirror of an upstream limit.
status
WorkerStatus
Output-only server-managed state. Absent from Create/Update request payloads; whatever a request carries here is ignored. A client moves state only through DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable, and the assignments are the scheduler's.
state
WorkerState
capacity
WorkerResources
The total resource capacity of the Worker.
A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker.
Shrinking capacity below allocated prevents new placements but does not evicts running Actors.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
allocated
WorkerResources
The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
observed_epoch
int64
observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running.
sandbox_classes
repeated WorkerSandboxClass
The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class.
sandbox_class
string
e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name.
default_runtime
WorkerSandboxRuntime
Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
restorable_runtimes
repeated WorkerSandboxRuntime
Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
ips
repeated string
ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs.
issued_epoch
int64
issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup.
registered_epoch
int64
registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then.
next_page_token
string
Pagination token for the next page. Empty if this is the last page.
ListWorkers
rpc ListWorkers(ListWorkersRequest) returns (ListWorkersResponse);ListWorkersRequest
message ListWorkersRequest { ListOptions options = 1;}
ListWorkersResponse
message ListWorkersResponse { repeated Worker workers = 1; string next_page_token = 2;}
GetWorker
Get a Worker.
Request (GetWorkerRequest)
worker
ObjectRef
The Worker to fetch. atespace is always empty; Workers are global-scoped.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
GetWorker
rpc GetWorker(GetWorkerRequest) returns (Worker);GetWorkerRequest
message GetWorkerRequest { ObjectRef worker = 1;}
CreateWorker
Register a Worker. Called once its Pod has an IP. A Worker is registered UNAVAILABLE and takes no Actors until MarkWorkerAvailable.
Request (CreateWorkerRequest)
worker
Worker
The Worker to register.
metadata
ResourceMetadata
Output-only: name, uid, version and timestamps are all server-assigned. uid and version are echoed back on UpdateWorker as preconditions.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_namespace
string
Kubernetes coordinates. Immutable, set at creation.
worker_pool
string
worker_pod
string
worker_pod_uid
string
node_name
string
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID the worker pod's certificate carries. atenet-router requires it on the certificate of the worker's atunnel.
labels
map<string, string>
labels mirror the WorkerPool object's Kubernetes labels, which selectors match against. Kubernetes does not cap an object's label count, so the bound below is a generous guardrail, not a mirror of an upstream limit.
status
WorkerStatus
Output-only server-managed state. Absent from Create/Update request payloads; whatever a request carries here is ignored. A client moves state only through DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable, and the assignments are the scheduler's.
state
WorkerState
capacity
WorkerResources
The total resource capacity of the Worker.
A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker.
Shrinking capacity below allocated prevents new placements but does not evicts running Actors.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
allocated
WorkerResources
The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
observed_epoch
int64
observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running.
sandbox_classes
repeated WorkerSandboxClass
The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class.
sandbox_class
string
e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name.
default_runtime
WorkerSandboxRuntime
Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
restorable_runtimes
repeated WorkerSandboxRuntime
Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
ips
repeated string
ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs.
issued_epoch
int64
issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup.
registered_epoch
int64
registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then.
CreateWorker
rpc CreateWorker(CreateWorkerRequest) returns (Worker);CreateWorkerRequest
message CreateWorkerRequest { Worker worker = 1;}
UpdateWorker
Update observed pool state on a Worker.
Request (UpdateWorkerRequest)
worker
Worker
The Worker to update. worker.metadata.name identifies which resource to update. atespace is always empty; Workers are global-scoped. worker.metadata.version and worker.metadata.uid are required preconditions.
labels is the only field an update may change. Every other field is replaced with what the request carries, and a field left unset is cleared — so read the Worker, change what you mean to change, and send the whole thing back. A request that alters an immutable field, by changing it or by omitting it, returns INVALID_ARGUMENT naming the field. status is output-only and whatever it carries is ignored.
metadata
ResourceMetadata
Output-only: name, uid, version and timestamps are all server-assigned. uid and version are echoed back on UpdateWorker as preconditions.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_namespace
string
Kubernetes coordinates. Immutable, set at creation.
worker_pool
string
worker_pod
string
worker_pod_uid
string
node_name
string
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID the worker pod's certificate carries. atenet-router requires it on the certificate of the worker's atunnel.
labels
map<string, string>
labels mirror the WorkerPool object's Kubernetes labels, which selectors match against. Kubernetes does not cap an object's label count, so the bound below is a generous guardrail, not a mirror of an upstream limit.
status
WorkerStatus
Output-only server-managed state. Absent from Create/Update request payloads; whatever a request carries here is ignored. A client moves state only through DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable, and the assignments are the scheduler's.
state
WorkerState
capacity
WorkerResources
The total resource capacity of the Worker.
A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker.
Shrinking capacity below allocated prevents new placements but does not evicts running Actors.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
allocated
WorkerResources
The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
observed_epoch
int64
observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running.
sandbox_classes
repeated WorkerSandboxClass
The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class.
sandbox_class
string
e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name.
default_runtime
WorkerSandboxRuntime
Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
restorable_runtimes
repeated WorkerSandboxRuntime
Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
ips
repeated string
ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs.
issued_epoch
int64
issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup.
registered_epoch
int64
registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then.
UpdateWorker
rpc UpdateWorker(UpdateWorkerRequest) returns (Worker);UpdateWorkerRequest
message UpdateWorkerRequest { Worker worker = 1;}
DeleteWorker
Deregister a Worker. Does not cascade: the caller is responsible for cleaning up related resources first.
Request (DeleteWorkerRequest)
worker
ObjectRef
The Worker to deregister.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
options
DeleteOptions
Optional per-delete preconditions.
version
int64
Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check.
uid
string
Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check.
DeleteWorker
rpc DeleteWorker(DeleteWorkerRequest) returns (Worker);DeleteWorkerRequest
message DeleteWorkerRequest { ObjectRef worker = 1; DeleteOptions options = 2;}
DrainWorker
Mark a Worker as terminating so the scheduler stops routing new Actors to it. Idempotent; one-way. Deliberately leaves any bound Actor alone. Returns ABORTED if another write lands on the Worker first; retry.
Request (DrainWorkerRequest)
worker
ObjectRef
The Worker to mark as terminating.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
Response (DrainWorkerResponse)
worker
Worker
The worker being drained.
metadata
ResourceMetadata
Output-only: name, uid, version and timestamps are all server-assigned. uid and version are echoed back on UpdateWorker as preconditions.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_namespace
string
Kubernetes coordinates. Immutable, set at creation.
worker_pool
string
worker_pod
string
worker_pod_uid
string
node_name
string
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID the worker pod's certificate carries. atenet-router requires it on the certificate of the worker's atunnel.
labels
map<string, string>
labels mirror the WorkerPool object's Kubernetes labels, which selectors match against. Kubernetes does not cap an object's label count, so the bound below is a generous guardrail, not a mirror of an upstream limit.
status
WorkerStatus
Output-only server-managed state. Absent from Create/Update request payloads; whatever a request carries here is ignored. A client moves state only through DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable, and the assignments are the scheduler's.
state
WorkerState
capacity
WorkerResources
The total resource capacity of the Worker.
A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker.
Shrinking capacity below allocated prevents new placements but does not evicts running Actors.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
allocated
WorkerResources
The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
observed_epoch
int64
observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running.
sandbox_classes
repeated WorkerSandboxClass
The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class.
sandbox_class
string
e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name.
default_runtime
WorkerSandboxRuntime
Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
restorable_runtimes
repeated WorkerSandboxRuntime
Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
ips
repeated string
ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs.
issued_epoch
int64
issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup.
registered_epoch
int64
registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then.
DrainWorker
rpc DrainWorker(DrainWorkerRequest) returns (DrainWorkerResponse);DrainWorkerRequest
message DrainWorkerRequest { ObjectRef worker = 1;}
DrainWorkerResponse
message DrainWorkerResponse { Worker worker = 1;}
MarkWorkerAvailable
Mark an UNAVAILABLE Worker ACTIVE so the scheduler places Actors on it. Idempotent. Returns FAILED_PRECONDITION for a DRAINING Worker, and ABORTED if another write lands on the Worker first; retry.
Every Actor placed after this call is stamped with the Worker's epoch as it stands then, so a caller raises epoch for a restarted the worker first.
Request (MarkWorkerAvailableRequest)
worker
ObjectRef
The Worker to mark ACTIVE.
atespace
string
The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field.
References to atespaced resources should add +k8s:subfield(atespace)=+k8s:required
References to non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
The name of the referenced resource. This field is required.
Response (MarkWorkerAvailableResponse)
worker
Worker
The Worker marked ACTIVE.
metadata
ResourceMetadata
Output-only: name, uid, version and timestamps are all server-assigned. uid and version are echoed back on UpdateWorker as preconditions.
atespace
string
atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter.
Atespaced resources should add +k8s:subfield(atespace)=+k8s:required
Non-atespaced resources should add +k8s:subfield(atespace)=+k8s:forbidden
name
string
name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter.
uid
string
uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource.
This field is ignored during create operations and used as precondition for update operations.
version
int64
version is increased on every mutation.
This field is ignored during create operations and used as precondition for update operations.
create_time
google.protobuf.Timestamp
create_time is the time the resource was created.
This field is ignored on input.
update_time
google.protobuf.Timestamp
update_time is the time the resource was last updated.
This field is ignored on input.
delete_time
google.protobuf.Timestamp
delete_time is the time the resource started its deletion.
This field is ignored on input.
worker_namespace
string
Kubernetes coordinates. Immutable, set at creation.
worker_pool
string
worker_pod
string
worker_pod_uid
string
node_name
string
worker_spiffe_id
string
worker_spiffe_id is the SPIFFE ID the worker pod's certificate carries. atenet-router requires it on the certificate of the worker's atunnel.
labels
map<string, string>
labels mirror the WorkerPool object's Kubernetes labels, which selectors match against. Kubernetes does not cap an object's label count, so the bound below is a generous guardrail, not a mirror of an upstream limit.
status
WorkerStatus
Output-only server-managed state. Absent from Create/Update request payloads; whatever a request carries here is ignored. A client moves state only through DrainWorker, MarkWorkerAvailable and MarkWorkerUnavailable, and the assignments are the scheduler's.
state
WorkerState
capacity
WorkerResources
The total resource capacity of the Worker.
A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker.
Shrinking capacity below allocated prevents new placements but does not evicts running Actors.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
allocated
WorkerResources
The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead.
cpu_millicores
int64
cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement.
memory_bytes
int64
memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement.
actors
int32
A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc.
observed_epoch
int64
observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running.
sandbox_classes
repeated WorkerSandboxClass
The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class.
sandbox_class
string
e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name.
default_runtime
WorkerSandboxRuntime
Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
restorable_runtimes
repeated WorkerSandboxRuntime
Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now.
version
VersionedSandboxCompat
Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime.
schema_version
string
Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed.
attributes
repeated AttributeEntry
Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them.
key
string
Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash").
value
string
Attribute value corresponding to key.
actor_overhead
RuntimeOverhead
The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead.
memory_bytes
int64
memory_bytes is a fixed amount of memory for each Actor.
memory_bytes_per_gib
int64
memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it.
ips
repeated string
ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs.
issued_epoch
int64
issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup.
registered_epoch
int64
registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then.
MarkWorkerAvailable
rpc MarkWorkerAvailable(MarkWorkerAvailableRequest) returns (MarkWorkerAvailableResponse);MarkWorkerAvailableRequest
message MarkWorkerAvailableRequest { ObjectRef worker = 1;}
MarkWorkerAvailableResponse
message MarkWorkerAvailableResponse { Worker worker = 1;}
Messages
ActorJwtSource
ActorJwtSource has the gateway mint a JWT for the Actor that sent the request. Relying parties verify it with OpenID Connect Discovery against its issuer. The gateway reuses a JWT across requests while enough of its lifetime remains, so its jti does not identify a single request.
| Field | Description | Type |
|---|---|---|
| audiences | The audiences the JWT is bound to, which become its aud claim. | repeated string |
| expiration_seconds | Lifetime of each JWT, in seconds. | int64 |
ActorMetadataDataSource
ActorMetadataDataSource projects the actor's identity fields to files, one per item.
| Field | Description | Type |
|---|---|---|
| items | items must not project the same field twice, and item paths must be unique. | repeated ActorMetadataItem |
ActorMetadataItem
ActorMetadataItem projects one actor identity field to a file at path, a clean relative Unix path from the root of the volume.
| Field | Description | Type |
|---|---|---|
| field | ActorMetadataField | |
| path | path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte. | string |
ActorSandboxRuntime
ActorSandboxRuntime is the runtime an actor runs under, as recorded on its assignment and on the snapshots taken from it: one class and one of the compatibility versions a Worker reports for it.
| Field | Description | Type |
|---|---|---|
| sandbox_class | e.g. "gvisor", "microvm" | string |
| version | Compatibility version of the runtime. A snapshot stamped with it can warm-boot on a worker whose runtime of this class matches it. | VersionedSandboxCompat |
ActorStatus
| Field | Description | Type |
|---|---|---|
| state | state is the Actor's current lifecycle state. | ActorState |
| worker_assignment | worker_assignment points at the worker currently hosting this Actor. Unset whenever the Actor has no worker (SUSPENDED, CRASHED). It can be set and cleared, but not pointed at another Worker in place: the fields that identify the Worker cannot change while it is set. | WorkerAssignment |
| external_volumes | external_volumes is the state of the external volumes attached to the actor. These volumes only live as long as the actor and are deleted with it. | ExternalVolumes |
| crash | crash records why and when the Actor entered CRASHED. It is set with the CRASHED state and cleared when a revert returns the Actor to SUSPENDED. | ActorCrash |
| assigned_node | assigned_node is the node hosting the Actor's worker or local snapshot. A suspended Actor remains attached while its local snapshot is kept. Detach or revert clears the binding. | string |
| snapshots | snapshots holds the Actor's active and in-progress snapshot generations. | repeated Snapshot |
| last_assigned_generation | last_assigned_generation tracks the last snapshot generation assigned for this Actor during a Suspend request. Even during Revert, the generation is not decreased to keep track of snapshots that have become stale and need to be cleaned up. | int32 |
ActorTemplateStatus
| Field | Description | Type |
|---|---|---|
| golden_snapshot_status | GoldenSnapshotStatus |
AllPorts
AllPorts selects every port. It has no fields.
No fields.
AttributeEntry
AttributeEntry is a single key-value compatibility attribute.
| Field | Description | Type |
|---|---|---|
| key | Attribute name (e.g. "architecture", "cpu_features", "sandbox_bundle_hash"). | string |
| value | Attribute value corresponding to key. | string |
Binding
Binding associates a list of principals (members) with a single role.
| Field | Description | Type |
|---|---|---|
| role | The role name for the parent resource type (e.g., "owner", "editor", "viewer"). | string |
| members | Principal identities granted this role. Examples:
| repeated string |
Capabilities
Capabilities adjusts a container's Linux capabilities relative to the default set. Drop applies first, then add, so a capability in both is granted. Capabilities are named without the "CAP_" prefix; "ALL" in drop removes the whole default set.
| Field | Description | Type |
|---|---|---|
| add | add lists capabilities to grant on top of the default set. "ALL" is rejected: name the individual capabilities the container needs. | repeated string |
| drop | drop lists capabilities to remove from the default set. "ALL" drops the whole set, so drop+add expresses an exact set rather than a relative one. | repeated string |
Container
Container is a single application container of an ActorTemplate.
| Field | Description | Type |
|---|---|---|
| name | string | |
| image | image is the OCI image reference the container runs: [registry/]repository[:tag]@digest. Must be pinned by digest (e.g. "name@sha256:..."). | string |
| command | Entrypoint array; when set, the image's ENTRYPOINT and CMD are both ignored and the process argv is command + args. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded. | repeated string |
| args | Arguments to the entrypoint; the image's CMD is used if unset (unless command is set, which discards the image's CMD). | repeated string |
| env | Env variables to set in the container's process environment. Unlike Kubernetes, $(VAR_NAME) references are NOT expanded in this field. | repeated EnvVar |
| wakeup_probe | wakeup_probe gates each wakeup on this container: ResumeActor returns only after the probe answers HTTP 200. Without it, ResumeActor returns as soon as the container has started, which may be before it listens. | WakeupProbe |
| volume_mounts | Keyed by mount_path: each path hosts exactly one mount, while a volume may be mounted at multiple paths. | repeated VolumeMount |
| security_context | security_context adjusts the container's security settings. Unset leaves the default capability set. | SecurityContext |
| resources | resources carries this container's compute limits, enforced inside the actor's sandbox. A limit of 0 leaves that resource unlimited. | ResourceRequirements |
CreateActorEgressPolicyRequest
CreateActorEgressPolicyRequest creates an egress policy for an Actor.
| Field | Description | Type |
|---|---|---|
| actor | Parent Actor under which to create the policy resource. | ObjectRef |
| egress_policy | The policy to create. metadata.name must be "default" and metadata.atespace must match actor.atespace. | EgressPolicy |
CreateActorRequest
Request to create a new Actor.
| Field | Description | Type |
|---|---|---|
| actor | The actor to create. | Actor |
CreateActorTemplateRequest
| Field | Description | Type |
|---|---|---|
| actor_template | The actor template version to create. Server-assigned metadata (uid, version, timestamps) is ignored, as are the status fields. | ActorTemplate |
CreateAtespaceAccessPolicyRequest
CreateAtespaceAccessPolicyRequest creates an access policy for an Atespace.
| Field | Description | Type |
|---|---|---|
| atespace | Parent Atespace under which to create the policy resource. | ObjectRef |
| access_policy | The policy to create. metadata.name must be "default" and metadata.atespace must be empty. | AccessPolicy |
CreateAtespaceRequest
| Field | Description | Type |
|---|---|---|
| atespace | The atespace to create. | Atespace |
CreateGlobalAccessPolicyRequest
CreateGlobalAccessPolicyRequest creates the deployment-wide global access policy singleton.
| Field | Description | Type |
|---|---|---|
| access_policy | The policy to create. metadata.name must be "default" and metadata.atespace must be empty. | AccessPolicy |
CreateTagRequest
Request to tag the external snapshot a suspended Actor holds.
The tag captures whichever snapshot the Actor holds when the call runs. An Actor keeps no snapshot history — each suspend replaces the last — so a suspend that lands between taking a snapshot and tagging it moves what gets tagged. That race is inherent and accepted: the tag means "the Actor as of this call", not "the snapshot some earlier suspend returned".
The tag is given its own copy of that snapshot, so it survives the Actor being suspended again or deleted. To retry a create that failed or timed out, delete the tag first, which collects whatever that attempt stranded, and create it again.
| Field | Description | Type |
|---|---|---|
| tag | The tag to create. metadata.atespace, metadata.name, scope and source_actor are honored; metadata.atespace must match source_actor's, and status is ignored on write. | Tag |
CreateWorkerRequest
| Field | Description | Type |
|---|---|---|
| worker | The Worker to register. | Worker |
CredentialHeader
CredentialHeader replaces the value of an HTTP request header with a
credential. The Actor sends the header with a placeholder value, such as
Authorization: <something>; the gateway discards that value and forwards
the header with the credential instead. The placeholder itself is not
inspected, so any value works. A request without the header is not
modified.
| Field | Description | Type |
|---|---|---|
| header | The case-insensitive HTTP request header to replace when present. | string |
| prefix | Prepended verbatim to the credential value. Include any desired separator; for example, use "Bearer " (including the space) for Authorization. | string |
| credential_uri | Source-agnostic reference interpreted by a registered credential provider:
Exactly one of credential_uri and actor_jwt must be set. | string |
| actor_jwt | A Substrate-issued JWT asserting the identity of the Actor that sent the request. | ActorJwtSource |
DeleteActorEgressPolicyRequest
DeleteActorEgressPolicyRequest identifies an Actor's egress policy.
| Field | Description | Type |
|---|---|---|
| actor | The parent Actor of the egress policy resource to delete. | ObjectRef |
| name | Name of the singleton egress policy. Must be "default". | string |
| options | Optional per-delete preconditions. | DeleteOptions |
DeleteActorRequest
| Field | Description | Type |
|---|---|---|
| actor | ObjectRef | |
| options | Optional per-delete preconditions. | DeleteOptions |
DeleteActorTemplateRequest
| Field | Description | Type |
|---|---|---|
| actor_template | ObjectRef | |
| options | Optional per-delete preconditions. | DeleteOptions |
DeleteAtespaceAccessPolicyRequest
DeleteAtespaceAccessPolicyRequest identifies an Atespace's access policy.
| Field | Description | Type |
|---|---|---|
| atespace | The parent Atespace of the access policy resource to delete. | ObjectRef |
| name | Name of the singleton access policy. Must be "default". | string |
| options | Optional per-delete preconditions. | DeleteOptions |
DeleteAtespaceRequest
| Field | Description | Type |
|---|---|---|
| atespace | ObjectRef | |
| options | Optional per-delete preconditions. | DeleteOptions |
DeleteOptions
DeleteOptions are the optional guards a Delete request may carry.
| Field | Description | Type |
|---|---|---|
| version | Delete only if the resource is still at this version, that is, unchanged since the caller read it. Zero skips the check. | int64 |
| uid | Delete only if the resource still has this uid, that is, it is the one the caller read and not a later one created under the same name. Empty skips the check. | string |
DeleteTagRequest
| Field | Description | Type |
|---|---|---|
| tag | ObjectRef | |
| options | Optional per-delete preconditions. | DeleteOptions |
DeleteWorkerRequest
| Field | Description | Type |
|---|---|---|
| worker | The Worker to deregister. | ObjectRef |
| options | Optional per-delete preconditions. | DeleteOptions |
DrainWorkerRequest
| Field | Description | Type |
|---|---|---|
| worker | The Worker to mark as terminating. | ObjectRef |
DrainWorkerResponse
DrainWorkerResponse holds the drained Worker.
| Field | Description | Type |
|---|---|---|
| worker | The worker being drained. | Worker |
DurableDirVolumeSource
DurableDirVolumeSource is a durable directory on rootfs that persists across resumes and participates in snapshots.
No fields.
EgressPolicyTemplate
EgressPolicyTemplate defines an initial Actor egress policy without resource metadata. Each rule has the same defaults, validation, and semantics as EgressPolicy.rules.
| Field | Description | Type |
|---|---|---|
| rules | Rules are an unordered set of allows, with the same precedence and effects as EgressPolicy.rules. At least one rule is required. Traffic is denied when no rule matches. | repeated EgressRule |
EgressRule
EgressRule allows traffic for a given protocol and destination (host name or IP, and port). The protocol fixes what the gateway matches on and when: a request, or a TLS connection at its ClientHello. Traffic that matches no rule is refused. All protocols here run over TCP; UDP is blocked. Protocols where the server sends first after connect are not supported.
Users should expect additional protocols to be supported in the future.
| Field | Description | Type |
|---|---|---|
| http | Cleartext HTTP to the named hosts: HTTP/1.1, and h2c as used by gRPC. TLS to these names is not allowed by this rule. | HttpRule |
| https | HTTPS to the named hosts, intercepted (man-in-the-middle) so the gateway can authorize and modify each request. HTTP/1.1 and HTTP/2 inside the TLS connection; HTTP/3 is not supported. | HttpsRule |
| tls_passthrough | TLS to the named servers, forwarded without decryption. | TlsPassthroughRule |
EnvVar
EnvVar supplies one environment variable to a container. Values are not expanded with Kubernetes-style $(VAR) references.
| Field | Description | Type |
|---|---|---|
| name | name may be any printable ASCII character except '='. | string |
| value | value is the literal value. | string |
ExternalVolumeSource
ExternalVolumeSource is a CSI volume provisioned for the actor from a template.
| Field | Description | Type |
|---|---|---|
| template | template provisions a volume for this actor alone; it is deleted with the actor. | ExternalVolumeTemplate |
ExternalVolumeStatus
ExternalVolumeStatus is one actor's view of an external volume it mounts.
| Field | Description | Type |
|---|---|---|
| name | Name of the volume specified in the actor template. Template volume names are DNS labels. | string |
| storage_volume_id | The globally unique volume_id returned from the storage system. This will be initially empty during volume creation. Its format is the storage system's own, so it is only bounded and checked for control characters (U+0000-U+0008, U+000B, U+000C, U+000E-U+001F, U+007F-U+009F). The CSI spec caps IDs at 128 bytes but does not require it, so allow some slack. Set once when provisioning completes, then never changed. | string |
| volume_type | Internal volume plugin name or CSI driver name, from the StorageClass provisioner. Must be a DNS subdomain, optionally prefixed with "substrate.io/" (per the CSI spec's driver-name syntax). | string |
| volume_context | volume_context contains metadata returned by the CSI driver during volume provisioning, needed by the node plugin for mounting (e.g. attachment info). Keys and values are the driver's own, so the map is only bounded, not validated. | map<string, string> |
ExternalVolumeTemplate
ExternalVolumeTemplate provisions an external volume per actor; the volume lives only as long as the actor.
| Field | Description | Type |
|---|---|---|
| capacity_bytes | capacity_bytes is the size of the volume to create, in bytes. Required. | int64 |
| storage_class_name | storage_class_name names the cluster-scoped Kubernetes StorageClass to create the volume from. Required. | string |
ExternalVolumes
ExternalVolumes is the external volume state recorded on an actor, wrapped so later additions do not reshape ActorStatus.
| Field | Description | Type |
|---|---|---|
| volumes | volumes has one entry per external volume of the template. Each template volume appears at most once. | repeated ExternalVolumeStatus |
GetActorEgressPolicyRequest
GetActorEgressPolicyRequest identifies an Actor's egress policy.
| Field | Description | Type |
|---|---|---|
| actor | The parent Actor of the egress policy resource to retrieve. | ObjectRef |
| name | Name of the singleton egress policy. Must be "default". | string |
GetActorRequest
| Field | Description | Type |
|---|---|---|
| actor | ObjectRef |
GetActorTemplateRequest
| Field | Description | Type |
|---|---|---|
| actor_template | ObjectRef |
GetAtespaceAccessPolicyRequest
GetAtespaceAccessPolicyRequest identifies an Atespace's access policy.
| Field | Description | Type |
|---|---|---|
| atespace | The parent Atespace of the access policy resource to retrieve. | ObjectRef |
| name | Name of the singleton access policy. Must be "default". | string |
GetAtespaceRequest
| Field | Description | Type |
|---|---|---|
| atespace | ObjectRef |
GetGlobalAccessPolicyRequest
GetGlobalAccessPolicyRequest retrieves the deployment-wide global access policy singleton.
| Field | Description | Type |
|---|---|---|
| name | Name of the singleton access policy. Must be "default". | string |
GetTagRequest
| Field | Description | Type |
|---|---|---|
| tag | ObjectRef |
GetWorkerRequest
| Field | Description | Type |
|---|---|---|
| worker | The Worker to fetch. atespace is always empty; Workers are global-scoped. | ObjectRef |
GoldenSnapshotConfig
GoldenSnapshotConfig controls automated golden snapshot creation for a template.
| Field | Description | Type |
|---|---|---|
| mode | mode defaults to ENABLED when unspecified. DISABLED skips creating the template's golden actor and tag. | GoldenSnapshotMode |
GoldenSnapshotStatus
| Field | Description | Type |
|---|---|---|
| golden_tag | golden_tag owns the immutable snapshot built by the template controller. Set after tagging the snapshot and deleting the temporary golden Actor. | ObjectRef |
| snapshot_time | snapshot_time is when the golden-actor warmup ends and the golden snapshot may be taken. | google.protobuf.Timestamp |
| error_message | error_message is set when the golden snapshot build fails and will not be
retried, formatted as | string |
HttpGetAction
HttpGetAction describes the HTTP GET the probe polls.
| Field | Description | Type |
|---|---|---|
| path | path must be a URL path starting with "/", using only RFC 3986 path-segment characters, without query or fragment. Defaults to "/" when unset. | string |
| port | port is the container port to connect to. | int32 |
HttpRule
HttpRule allows cleartext HTTP and is evaluated per request on the request authority (Host or :authority) and port. The gateway resolves the name and dials it.
| Field | Description | Type |
|---|---|---|
| hostnames | Hostname patterns: a DNS name, or a DNS name with "*" as its leftmost label. The rule matches when any pattern matches. The DNS name must conform to RFC 1034 and RFC 1123. It must be lowercase and must not have a trailing dot. A wildcard replaces the complete leftmost label. ".example.com" matches exactly one non-empty label, such as "api.example.com". It does not match "example.com" or "nested.api.example.com". "" alone matches every name. No other wildcard syntax is accepted. A pattern without a wildcard matches only the complete normalized name. Patterns may overlap: the rule ranks by the most specific pattern that matches the destination. Internationalized names must use their IDNA A-label (punycode) form; no Unicode conversion is performed. URLs, IP addresses, names with ports, malformed DNS names (for example, "foo..example.com"), and more than one trailing dot are invalid. | repeated string |
| ports | Ports of the destination the Actor connected to. A port in a request's authority is neither matched nor dialed. Defaults to port 80. | Ports |
| effects | Effects do not authorize traffic. They are applied only when this is the deciding rule. | HttpRuleEffects |
HttpRuleEffects
HttpRuleEffects contains effects applied by a matching HTTP or HTTPS rule.
| Field | Description | Type |
|---|---|---|
| replace_headers | Replaces placeholder request headers with credentials. A header is replaced only when the request from the Actor carries it; requests without the header are forwarded unchanged, so a credential reaches only the requests that ask for it. Header names must be unique case-insensitively. Replacement is supported on HTTP and HTTPS. On HTTP, the gateway does not originate TLS to the destination. Without separate transport protection, observers can read the credential and attackers on the path can modify the request. Deployments may encrypt traffic outside the gateway; policy authors must account for any unprotected segments between credential injection and the intended destination. | repeated CredentialHeader |
HttpsRule
HttpsRule allows HTTPS that the gateway intercepts (MITM). Every Actor behind such a rule must trust the gateway CA. Without it, TLS to these names fails in the Actor.
A TLS connection whose SNI and port match is terminated with a leaf certificate for that name issued by the gateway CA. Each request inside it is then decided on its authority, and the gateway re-originates TLS to that authority; the SNI only selects the leaf.
Interception is for HTTP. A connection that sends no SNI does not match, and a non-HTTP protocol inside an intercepted connection fails.
| Field | Description | Type |
|---|---|---|
| hostnames | Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames. | repeated string |
| ports | Ports of the destination the Actor connected to. Defaults to port 443. | Ports |
| effects | Effects do not authorize traffic. They are applied only when this is the deciding rule. | HttpRuleEffects |
ImageVolumeSource
ImageVolumeSource mounts the contents of an OCI image, read-only. The reference must include a digest: changing the image invalidates snapshots.
| Field | Description | Type |
|---|---|---|
| reference | reference is the OCI image reference. Must include a digest (e.g. "name@sha256:..."). | string |
ListActorTemplatesRequest
| Field | Description | Type |
|---|---|---|
| atespace | The atespace to list actor templates from. Empty lists across all atespaces. | string |
| options | Pagination controls. | ListOptions |
ListActorTemplatesResponse
| Field | Description | Type |
|---|---|---|
| actor_templates | The page of actor template versions. This list may be empty even if there are more results. | repeated ActorTemplate |
| next_page_token | Pagination token for the next page. Empty if this is the last page. | string |
ListActorsRequest
List actors with pagination. Provides "soft" guarantees: actors may be missed or duplicated if the system state changes during pagination.
| Field | Description | Type |
|---|---|---|
| atespace | The atespace to list actors from. Empty lists across all atespaces. | string |
| options | Pagination controls. | ListOptions |
ListActorsResponse
| Field | Description | Type |
|---|---|---|
| actors | The page of actors. This list may be empty even if there are more results. | repeated Actor |
| next_page_token | Pagination token for the next page. Empty if this is the last page. | string |
ListAtespacesRequest
| Field | Description | Type |
|---|---|---|
| options | Pagination controls. | ListOptions |
ListAtespacesResponse
| Field | Description | Type |
|---|---|---|
| atespaces | The page of atespaces. This list may be empty even if there are more results. | repeated Atespace |
| next_page_token | Pagination token for the next page. Empty if this is the last page. | string |
ListOptions
ListOptions are the pagination controls a List request may carry.
| Field | Description | Type |
|---|---|---|
| page_size | Requested page size; the server may return fewer, or occasionally slightly more. If unspecified, defaults to a server-chosen value; values above 1000 are coerced to 1000. | int32 |
| page_token | Pagination token from a previous response of the same List method. Omit or leave empty for the first request. | string |
ListTagsRequest
| Field | Description | Type |
|---|---|---|
| atespace | The atespace to list tags from. Empty lists across all atespaces. | string |
| options | Pagination controls. | ListOptions |
ListTagsResponse
| Field | Description | Type |
|---|---|---|
| tags | repeated Tag | |
| next_page_token | string |
ListWorkerActorAssignmentsRequest
ListWorkerActorAssignmentsRequest asks for a page of the Actors hosted by a given Worker.
| Field | Description | Type |
|---|---|---|
| worker | The Worker under which to list Actors. | ObjectRef |
| options | Pagination controls. | ListOptions |
ListWorkerActorAssignmentsResponse
ListWorkerActorAssignmentsResponse is one page of a Worker's Actors.
| Field | Description | Type |
|---|---|---|
| actor_assignments | The Actors this page of the listing covers. | repeated ActorAssignment |
| next_page_token | Pagination token for the next page. Empty if this is the last page. | string |
ListWorkersRequest
| Field | Description | Type |
|---|---|---|
| options | Pagination controls. | ListOptions |
ListWorkersResponse
| Field | Description | Type |
|---|---|---|
| workers | The page of workers. This list may be empty even if there are more results. | repeated Worker |
| next_page_token | Pagination token for the next page. Empty if this is the last page. | string |
MarkWorkerAvailableRequest
MarkWorkerAvailableRequest names the Worker to mark ACTIVE.
| Field | Description | Type |
|---|---|---|
| worker | The Worker to mark ACTIVE. | ObjectRef |
MarkWorkerAvailableResponse
MarkWorkerAvailableResponse holds the Worker marked ACTIVE.
| Field | Description | Type |
|---|---|---|
| worker | The Worker marked ACTIVE. | Worker |
MarkWorkerUnavailableRequest
MarkWorkerUnavailableRequest names the Worker to mark UNAVAILABLE.
| Field | Description | Type |
|---|---|---|
| worker | The Worker to mark UNAVAILABLE. | ObjectRef |
MarkWorkerUnavailableResponse
MarkWorkerUnavailableResponse holds the Worker marked UNAVAILABLE.
| Field | Description | Type |
|---|---|---|
| worker | The Worker marked UNAVAILABLE. | Worker |
MintActorJwtRequest
Request message for MintActorJwt.
| Field | Description | Type |
|---|---|---|
| actor | The actor for which the JWT should be issued. Must be a valid actor that currently exists according to the actor store. | ObjectRef |
| audiences | The audiences the minted JWT is bound to. Tokens are only issued with audience bindings, so at least one is required. | repeated string |
| expiration_seconds | Lifetime of the JWT, in seconds. | int64 |
MintActorJwtResponse
Response message for MintActorJwt.
| Field | Description | Type |
|---|---|---|
| actor_jwt | The signed actor JWT. Relying parties verify it with OpenID Connect Discovery against its issuer. Claims:
The subject and claim name say the token speaks for the actor itself.
A token minted for a Substrate component acting on the actor's behalf
(WorkerService.MintWorkerActorJwt) uses | string |
| expire_time | expire_time is when actor_jwt expires. Equal to its exp claim. | google.protobuf.Timestamp |
ObjectRef
ObjectRef references a Substrate resource by its atespace and name.
| Field | Description | Type |
|---|---|---|
| atespace | The atespace of the referenced resource. This field should be empty if the target resource is global-scoped, but references to objects in the same atespace as the referrer must still populate this field. References to atespaced resources should add | string |
| name | The name of the referenced resource. This field is required. | string |
ObjectSnapshot
ObjectSnapshot addresses a snapshot held in object storage.
| Field | Description | Type |
|---|---|---|
| snapshot_uri | snapshot_uri addresses the snapshot's prefix in object storage. | string |
Ports
Ports selects the destination ports a rule matches. Every port, or a set of port numbers. all and numbers can not be set together.
| Field | Description | Type |
|---|---|---|
| all | Every port. | AllPorts |
| numbers | Port numbers, without repeats. | repeated int32 |
ResourceMetadata
ResourceMetadata holds the common fields carried by every Substrate resource.
| Field | Description | Type |
|---|---|---|
| atespace | atespace is the namespace the resource belongs to. Empty for global-scoped resources. Caller-specified at creation and immutable thereafter. Atespaced resources should add | string |
| name | name is the resource's name, unique within its atespace (or globally, for global-scoped resources). Caller-specified at creation and immutable thereafter. | string |
| uid | uid is a server-assigned, globally unique identifier for this resource. Immutable throughout the lifecycle of the resource. This field is ignored during create operations and used as precondition for update operations. | string |
| version | version is increased on every mutation. This field is ignored during create operations and used as precondition for update operations. | int64 |
| create_time | create_time is the time the resource was created. This field is ignored on input. | google.protobuf.Timestamp |
| update_time | update_time is the time the resource was last updated. This field is ignored on input. | google.protobuf.Timestamp |
| delete_time | delete_time is the time the resource started its deletion. This field is ignored on input. | google.protobuf.Timestamp |
ResourceRequirements
ResourceRequirements are the compute resources a workload may use.
| Field | Description | Type |
|---|---|---|
| limits | limits is the maximum amount of compute resources allowed. | Resources |
Resources
Resources is an amount of each compute resource.
| Field | Description | Type |
|---|---|---|
| cpu_millicores | cpu_millicores is CPU in millicores (1000 = one core). 0 means none. | int64 |
| memory_bytes | memory_bytes is memory in bytes. 0 means none. | int64 |
ResumeActorRequest
| Field | Description | Type |
|---|---|---|
| actor | ObjectRef |
ResumeActorResponse
| Field | Description | Type |
|---|---|---|
| actor | Actor | |
| resumed | True if a resume workflow was executed to activate the actor. False if the actor was already RUNNING. | bool |
RevertActorRequest
RevertActorRequest identifies the Actor to revert.
| Field | Description | Type |
|---|---|---|
| actor | actor to revert. | ObjectRef |
RevertActorResponse
RevertActorResponse holds the reverted Actor.
| Field | Description | Type |
|---|---|---|
| actor | actor as it stands after the revert, SUSPENDED and still holding the external snapshot it was reverted to. | Actor |
RuntimeOverhead
RuntimeOverhead is the memory an Actor uses on its Worker outside its own limits: a fixed amount, plus an amount in proportion to its memory limit.
| Field | Description | Type |
|---|---|---|
| memory_bytes | memory_bytes is a fixed amount of memory for each Actor. | int64 |
| memory_bytes_per_gib | memory_bytes_per_gib is memory per GiB of the Actor's memory limit, e.g. host page tables for a microVM's guest RAM. It scales in proportion and rounds down to a byte, so an Actor with a 512MiB limit adds half of it. | int64 |
SecurityContext
SecurityContext holds security settings for a container's process, modeling a subset of the Kubernetes container securityContext.
| Field | Description | Type |
|---|---|---|
| capabilities | capabilities adjusts the Linux capabilities of the container's process. | Capabilities |
Selector
Selector matches worker pools by label. Only equality-based matching is supported.
| Field | Description | Type |
|---|---|---|
| match_labels | match_labels selects by exact equality on a set of labels. | map<string, string> |
Snapshot
Snapshot represents one generation of an Actor's or Tag's snapshot state.
| Field | Description | Type |
|---|---|---|
| uuid | uuid is the server-generated unique identifier for this snapshot, passed to atelet to identify the local checkpoint on disk and used as the snapshot name in object storage. | string |
| generation | generation is the monotonically increasing generation number of this snapshot, starting at 1. | int32 |
| owner | owner identifies the origin and ownership of this snapshot. | SnapshotOwner |
| fidelity | fidelity is what this snapshot holds. | SnapshotFidelity |
| actor_template_uid | UID of the ActorTemplate whose sandbox this snapshot's guest state was captured from. | string |
| locality | locality identifies the Kubernetes node holding this snapshot's files. Detach, revert, or a later checkpoint clears it. Resume keeps the files. | string |
| durable_snapshot | durable_snapshot holds the durable storage representation of this snapshot. PENDING while the snapshot is uploaded, including an asynchronous suspend's snapshot that so far exists only on the node named by locality. COMPLETED once the upload is recorded. | SnapshotStorage |
| sandbox_runtime | sandbox_runtime is the runtime the actor ran under when the snapshot was taken. | ActorSandboxRuntime |
SnapshotConfig
SnapshotConfig selects what actor snapshots capture and where they are stored.
| Field | Description | Type |
|---|---|---|
| storage_location | storage_location is the base object-storage URI snapshots of actors on this version are stored under. If unset, ate-api-server's --snapshot-location is used. Requires the PerTemplateSnapshotLocation preview gate. Each path segment may contain only ASCII letters, digits, '_' and '-'. Each owner's snapshots are stored under <storage_location>/atespaces/..., so no segment may be "atespaces" in any letter case. | string |
| preferred_fidelity | preferred_fidelity is the highest fidelity the system packages when it snapshots the actor. It is a best-effort ceiling, not a guarantee: the system never packages more than this level, and it may package less when a layer cannot be captured or is too expensive to capture at the time, for example memory under host pressure. A process resumed in place on its worker keeps its memory regardless of this setting. Defaults to MEMORY when unset. | SnapshotFidelity |
| golden_snapshot_config | golden_snapshot_config configures automated golden snapshot creation. Golden snapshots are enabled when this config is omitted. | GoldenSnapshotConfig |
SnapshotStorage
SnapshotStorage records the durable storage representation of a Snapshot.
| Field | Description | Type |
|---|---|---|
| state | state is the lifecycle state of the durable snapshot. | SnapshotStorageState |
| object | object snapshot is stored in object storage. | ObjectSnapshot |
SuspendActorRequest
| Field | Description | Type |
|---|---|---|
| actor | ObjectRef | |
| options | options controls how SuspendActor persists the actor's snapshot. | SuspendOptions |
SuspendActorResponse
| Field | Description | Type |
|---|---|---|
| actor | Actor |
SuspendOptions
SuspendOptions tunes how SuspendActor persists the actor's snapshot.
| Field | Description | Type |
|---|---|---|
| mode | mode selects when SuspendActor returns relative to the snapshot reaching durable storage. If unspecified, defaults to DURABILITY_MODE_ASYNCHRONOUS. | DurabilityMode |
SystemInfoDataSource
| Field | Description | Type |
|---|---|---|
| actor_metadata | Exactly one of actor_metadata / trust_bundle must be set. | ActorMetadataDataSource |
| trust_bundle | TrustBundleDataSource |
SystemInfoVolumeSource
SystemInfoVolumeSource is a read-only volume of substrate-generated per-actor files (identity fields, projected trust bundles), regenerated by atelet on every Run/Restore.
| Field | Description | Type |
|---|---|---|
| data_sources | data_sources lists the projections to place within the volume. At most one actor_metadata entry may appear, and file paths must be unique across all entries. | repeated SystemInfoDataSource |
TagStatus
TagStatus is the server-owned state of a Tag. The tag is fixed to one external snapshot once its creation completes, so the rest is immutable provenance.
| Field | Description | Type |
|---|---|---|
| snapshot | snapshot is the external snapshot this tag points at: the tag's own copy, stored under a prefix keyed on the tag's UID. It is recorded with its durable_snapshot PENDING right after the tag is reserved, before anything is copied, and transitions to COMPLETED once the copy finishes: a tag never moves between snapshots and is usable only once COMPLETED. Unset until it is recorded; a tag whose creation failed first never gets one. | Snapshot |
| actor_template_uid | UID of the ActorTemplate the snapshot was taken under. Actors can only be seeded from a tag under the same template. | string |
TlsPassthroughRule
TlsPassthroughRule allows TLS that the gateway forwards without decryption. It is evaluated once per connection at the ClientHello, on the SNI and port, for any protocol carried over TLS. A connection that sends no SNI does not match. Protocols that upgrade to TLS after a cleartext exchange (STARTTLS) do not match. Because the gateway reads nothing after the ClientHello, a passthrough rule has no effects, and a policy change reaches an open connection only when it ends.
| Field | Description | Type |
|---|---|---|
| hostnames | Server names matched against the SNI, in the pattern syntax of HttpRule.hostnames. | repeated string |
| ports | Ports of the destination the Actor connected to. | Ports |
TrustBundleDataSource
TrustBundleDataSource projects the trust anchors of the named trust bundle to a PEM file at path. Supported names are allowlisted in atelet.
| Field | Description | Type |
|---|---|---|
| names | One or more named trust bundles to unify and place at the specified path. Substrate supports a short list of predefined names:
| repeated string |
| path | path must be a clean relative Unix path: at most 16 '/'-separated segments, none of them empty, '.' or '..', and no NUL byte. | string |
UpdateActorEgressPolicyRequest
UpdateActorEgressPolicyRequest replaces an Actor's egress policy.
| Field | Description | Type |
|---|---|---|
| actor | Parent Actor under which to update the policy resource. | ObjectRef |
| egress_policy | Full replacement. Metadata UID and version are required preconditions; atespace and name are immutable and must match the existing policy. | EgressPolicy |
UpdateActorRequest
Request to update mutable fields on an existing Actor. May be called regardless of the actor's current state. Changes take effect on the next ResumeActor call.
| Field | Description | Type |
|---|---|---|
| actor | The actor to update. actor.metadata.atespace and actor.metadata.name identify which resource to update. actor.metadata.version and actor.metadata.uid are required preconditions. | Actor |
UpdateAtespaceAccessPolicyRequest
UpdateAtespaceAccessPolicyRequest replaces an Atespace's access policy.
| Field | Description | Type |
|---|---|---|
| atespace | Parent Atespace under which to update the policy resource. | ObjectRef |
| access_policy | Full replacement. Metadata UID and version are required preconditions; metadata.name must be "default" and metadata.atespace must be empty. | AccessPolicy |
UpdateGlobalAccessPolicyRequest
UpdateGlobalAccessPolicyRequest replaces the deployment-wide global access policy singleton.
| Field | Description | Type |
|---|---|---|
| access_policy | Full replacement. Metadata UID and version are required preconditions; metadata.name must be "default" and metadata.atespace must be empty. | AccessPolicy |
UpdateTagRequest
Request to update mutable fields on an existing Tag. The tag keeps its address: the snapshot it points at cannot be changed.
| Field | Description | Type |
|---|---|---|
| tag | The tag to update. tag.metadata.atespace and tag.metadata.name identify which resource to update. tag.metadata.version and tag.metadata.uid are required preconditions | Tag |
UpdateWorkerRequest
| Field | Description | Type |
|---|---|---|
| worker | The Worker to update. worker.metadata.name identifies which resource to update. atespace is always empty; Workers are global-scoped. worker.metadata.version and worker.metadata.uid are required preconditions. labels is the only field an update may change. Every other field is replaced with what the request carries, and a field left unset is cleared — so read the Worker, change what you mean to change, and send the whole thing back. A request that alters an immutable field, by changing it or by omitting it, returns INVALID_ARGUMENT naming the field. status is output-only and whatever it carries is ignored. | Worker |
VersionedSandboxCompat
VersionedSandboxCompat holds the compatibility schema version and the key-value compatibility attributes of a sandbox runtime.
| Field | Description | Type |
|---|---|---|
| schema_version | Compatibility schema version (e.g. "v1") defining which runtime and hardware attributes are recorded and how they are computed. | string |
| attributes | Key-value compatibility attributes defined by this schema version, covering both runtime assets (e.g. "sandbox_bundle_hash") and effective guest hardware features after masking (e.g. "architecture", "cpu_features"). Matched against a snapshot under the same schema_version: every attribute on the snapshot must be present on the worker with an equal value (except "cpu_features", where the snapshot's hexadecimal bitmask must be a bitwise subset of the worker's); keys only the worker has are ignored, so a worker can gain keys under one schema_version without invalidating older snapshots. Removing or recomputing a key is a new schema_version, under which older snapshots no longer match. Order as sent does not matter: ate-api-server sorts attributes by key before recording them. | repeated AttributeEntry |
Volume
| Field | Description | Type |
|---|---|---|
| name | name of the volume. Must be a DNS label. | string |
| durable_dir | Exactly one of durable_dir / external / image / system_info must be set. | DurableDirVolumeSource |
| external | external is a CSI volume: provisioned for this actor from a template. | ExternalVolumeSource |
| system_info | SystemInfoVolumeSource | |
| image | image mounts the contents of an OCI image, read-only. | ImageVolumeSource |
VolumeMount
VolumeMount mounts a named Volume into a container.
| Field | Description | Type |
|---|---|---|
| name | name must match the name of a Volume. | string |
| mount_path | mount_path within the container. Must be a clean absolute Unix path: must start with '/', not be '/', and contain no ':', '..', '.', '//', trailing '/', or control characters. | string |
WakeupProbe
WakeupProbe tells the platform when a container is serving. It is polled on every wakeup, whether the actor cold-boots or is restored from a snapshot, and not again while the actor stays running. A probe that does not answer 200 within timeout_seconds crashes the actor.
| Field | Description | Type |
|---|---|---|
| http_get | http_get is the request to poll. | HttpGetAction |
| timeout_seconds | timeout_seconds is how long to keep polling before giving up. Defaults to 30 when unset. | int32 |
WorkerAssignment
WorkerAssignment points at the Worker currently hosting an Actor.
This is a denormalized snapshot, not merely a reference: atenet reads worker_pod_ips on the request-routing path and must not need a second lookup, and kubectl-ate displays the pod name. The copies of the Worker's identity fields stay valid for the life of the assignment because those fields are immutable, and cannot change in place. worker_pod_ips and worker_epoch describe the worker process the Actor runs under, and are updated when the Actor becomes RUNNING.
Pass worker to GetWorker; none of the denormalized fields identify the
Worker to the API.
| Field | Description | Type |
|---|---|---|
| worker | worker references the assigned Worker. This is the field to look the Worker up by; the worker_* fields below are a denormalized copy kept so that readers on a hot path do not have to fetch the Worker at all. Workers are global-scoped, so this carries no atespace. | ObjectRef |
| worker_namespace | worker_namespace is the Kubernetes namespace of the WorkerPool and worker Pod. | string |
| worker_pool | worker_pool is the name of the WorkerPool the worker belongs to. | string |
| worker_pod | worker_pod is the name of the Kubernetes pod hosting the Actor. | string |
| worker_pod_uid | worker_pod_uid is the Kubernetes UID of worker_pod. | string |
| worker_pod_ips | worker_pod_ips are the IPs of worker_pod, copied from Worker.status.ips when the Actor is placed, and again when it becomes RUNNING. | repeated string |
| node_name | node_name is the Kubernetes node hosting worker_pod. | string |
| worker_epoch | worker_epoch is the epoch of the worker process the Actor runs under, as that process reports it from Run or Restore. 0 until the Actor becomes RUNNING. | int64 |
| sandbox_runtime | sandbox_runtime is the sandbox runtime and compatibility version the Actor was started or restored under on this Worker. | ActorSandboxRuntime |
| worker_spiffe_id | worker_spiffe_id is the SPIFFE ID worker_pod's certificate carries, copied from Worker.worker_spiffe_id. | string |
WorkerResources
WorkerResources represents a set of resources.
| Field | Description | Type |
|---|---|---|
| cpu_millicores | cpu_millicores is CPU in millicores (1000 = one core). Compared against the Actor's resource limits for placement. | int64 |
| memory_bytes | memory_bytes is memory in bytes. Compared against the Actor's resource limits for placement. | int64 |
| actors | A count of Actors. Workers can use this to limit the number of Actors that can be placed on them, constraining the costs of other things that are not captured in the resources above, but which still have costs - netns, mounts, file descriptors, etc. | int32 |
WorkerSandboxClass
WorkerSandboxClass is one sandbox class a Worker runs, with the runtimes it runs it under. A Worker has one entry per WorkerPool sandboxClasses entry, so exactly one today.
| Field | Description | Type |
|---|---|---|
| sandbox_class | e.g. "gvisor", "microvm", as on WorkerPool.spec.sandboxClasses[].name. | string |
| default_runtime | Runtime new and cold-booted actors of this class start under. Snapshots matching its version can also warm-boot on this worker. | WorkerSandboxRuntime |
| restorable_runtimes | Additional runtimes of this class (excluding default_runtime) that this worker can restore snapshots from right now. | repeated WorkerSandboxRuntime |
WorkerSandboxRuntime
WorkerSandboxRuntime is one runtime a Worker runs for the class of its WorkerSandboxClass entry. ActorSandboxRuntime, the stamp on an assignment or snapshot, pairs the entry's sandbox_class with this runtime's version.
| Field | Description | Type |
|---|---|---|
| version | Compatibility version stamped onto an actor's snapshot when a checkpoint is taken on this runtime. Snapshots matching it can warm-boot on this runtime. | VersionedSandboxCompat |
| actor_overhead | The resource overhead incurred by a Worker for each Actor running under this runtime, on top of the Actor's stated limits. Placement considers this when deciding if a Worker has enough capacity for an Actor, and it is accounted for in allocated. If not specified, Actors under this runtime are assumed to have negligible overhead. | RuntimeOverhead |
WorkerStatus
| Field | Description | Type |
|---|---|---|
| state | WorkerState | |
| capacity | The total resource capacity of the Worker. A Worker should report every dimension of resources it has available to be consumed by Actors. Any resource not specified here is assumed to be 0. An Actor which requests a resource which is not present in a Worker's capacity will prevent that Actor from running on that Worker. Shrinking capacity below allocated prevents new placements but does not evicts running Actors. | WorkerResources |
| allocated | The allocated resources of the Worker. This is the sum of all the resources consumed by the Actors currently assigned to this Worker, including their runtime's actor_overhead. | WorkerResources |
| observed_epoch | observed_epoch is the latest epoch whose earlier Actors the control plane has crashed and released. While it is below registered_epoch, Actors placed before the worker's last restart may still be reported as running. | int64 |
| sandbox_classes | The sandbox classes this Worker runs and the runtimes it runs them under, as the registered worker process reports them through WorkerService.SetWorkerSandboxRuntimes. Cleared when a new worker process registers, and nothing is placed on the Worker until it reports them. One entry today, like WorkerPoolSpec.sandboxClasses. Its sandbox_class is the Worker's class. | repeated WorkerSandboxClass |
| ips | ips are the worker pod's IPs, at most one per IP family, in the order Kubernetes reports them; the first is in the cluster's primary family. The worker process reports them when it registers, so they follow a pod sandbox that is recreated with new IPs. | repeated string |
| issued_epoch | issued_epoch is the last epoch handed out by WorkerService.AcquireWorkerEpoch. Each worker process acquires one at startup. | int64 |
| registered_epoch | registered_epoch is the epoch of the worker process that registered last, through WorkerService.RegisterWorker. Only one worker process runs in a pod at a time, and a process registers only an epoch it acquired, so a rise means every earlier process has exited and lost its sandboxes. The control plane then crashes the Actors that ran under an earlier epoch. 0 until the first registration; a Worker takes no Actors before then. | int64 |
Enums
ActorMetadataField
ActorMetadataField selects one identity field of the actor.
| Value | Description | Number |
|---|---|---|
| ACTOR_METADATA_FIELD_UNSPECIFIED | 0 | |
| ACTOR_METADATA_FIELD_NAME | 1 | |
| ACTOR_METADATA_FIELD_ATESPACE | 2 | |
| ACTOR_METADATA_FIELD_UID | 3 |
ActorState
| Value | Description | Number |
|---|---|---|
| ACTOR_STATE_UNSPECIFIED | 0 | |
| ACTOR_STATE_RESUMING | 1 | |
| ACTOR_STATE_RUNNING | 2 | |
| ACTOR_STATE_SUSPENDING | 3 | |
| ACTOR_STATE_SUSPENDED | 4 | |
| ACTOR_STATE_CRASHED | 5 | |
| ACTOR_STATE_DELETING | 6 | |
| ACTOR_STATE_REVERTING | 7 |
DurabilityMode
DurabilityMode selects when a suspend is acknowledged relative to its snapshot being stored durably.
| Value | Description | Number |
|---|---|---|
| DURABILITY_MODE_UNSPECIFIED | 0 | |
| DURABILITY_MODE_SYNCHRONOUS | Return only after the snapshot is complete in durable storage. Applies only when the call checkpoints a running actor: an actor that is already SUSPENDED is returned with the snapshot it holds, which may still be on its node. | 1 |
| DURABILITY_MODE_ASYNCHRONOUS | Return once the snapshot is captured on the node. The upload to durable storage continues in the background. | 2 |
GoldenSnapshotMode
GoldenSnapshotMode selects whether a template builds a golden snapshot.
| Value | Description | Number |
|---|---|---|
| GOLDEN_SNAPSHOT_MODE_UNSPECIFIED | 0 | |
| GOLDEN_SNAPSHOT_MODE_ENABLED | 1 | |
| GOLDEN_SNAPSHOT_MODE_DISABLED | 2 |
SnapshotFidelity
SnapshotFidelity orders the state layers a snapshot can hold, lowest to highest. Each level includes the ones below it.
| Value | Description | Number |
|---|---|---|
| SNAPSHOT_FIDELITY_UNSPECIFIED | 0 | |
| SNAPSHOT_FIDELITY_VOLUMES | Durable volumes only. The actor resumes by cold-booting its containers from the OCI image with the volumes restored. | 1 |
| SNAPSHOT_FIDELITY_ROOTFS | Volumes plus the root filesystem changes made since boot. The actor cold-boots on resume with its rootfs writes back in place. | 2 |
| SNAPSHOT_FIDELITY_MEMORY | Volumes, root filesystem changes, and process memory. The actor resumes where it left off. | 3 |
SnapshotOwner
SnapshotOwner indicates the owner of a snapshot.
| Value | Description | Number |
|---|---|---|
| SNAPSHOT_OWNER_UNSPECIFIED | 0 | |
| SNAPSHOT_OWNER_ACTOR | Snapshot captured directly from this Actor. | 1 |
| SNAPSHOT_OWNER_TAG | Snapshot owned by a Tag (also includes Golden Snapshot) | 2 |
SnapshotStorageState
SnapshotStorageState indicates the lifecycle stage of a durable snapshot.
| Value | Description | Number |
|---|---|---|
| SNAPSHOT_STORAGE_STATE_UNSPECIFIED | 0 | |
| SNAPSHOT_STORAGE_STATE_PENDING | Snapshot creation in durable storage is in progress. | 1 |
| SNAPSHOT_STORAGE_STATE_COMPLETED | Snapshot is complete and ready for use in durable storage. | 2 |
TagScope
| Value | Description | Number |
|---|---|---|
| TAG_SCOPE_UNSPECIFIED | Not set and rejected wherever a client supplies a scope | 0 |
| TAG_SCOPE_ATESPACE | May initialize Actors only in the tag's owning Atespace. | 1 |
| TAG_SCOPE_PUBLISHED | Published for use by Actors in any Atespace. The tag remains addressed through its owning Atespace. | 2 |
WorkerState
| Value | Description | Number |
|---|---|---|
| WORKER_STATE_UNSPECIFIED | 0 | |
| WORKER_STATE_ACTIVE | Ready; schedulable. | 1 |
| WORKER_STATE_DRAINING | Pod terminating. Not schedulable. Final: a draining Worker never becomes active or unavailable again. | 2 |
| WORKER_STATE_UNAVAILABLE | Registered but not Ready, or its the worker restarting. Not schedulable. Every Worker starts here until MarkWorkerAvailable. | 3 |
ActorCrash describes the failure that moved an Actor to CRASHED.