Skip to content

Protocol Documentation

Table of Contents

Top

cells.proto

Cell

An isolation resource used to divide a system into smaller resource boundaries.

Field Type Label Description
name string Resource parameters for control groups (cgroups) Build on the cgroups-rs crate. See examples
cpu CpuController
cpuset CpusetController
memory MemoryController
isolate_process bool Will isolate the process (and proc filesystem) from the host. Will unshare the pid, ipc, uts, and mount namespaces. The cgroup namespace is always unshared with the host.

Default: false | | isolate_network | bool | | Will isolate the network from the host. Will unshare the net namespaces. The cgroup namespace is always unshared with the host.

Default: false |

CellGraphNode

Field Type Label Description
cell Cell
children CellGraphNode repeated

CellServiceAllocateRequest

An Aurae cell is a name given to Linux control groups (cgroups) that also includes a name, and special pre-exec functionality that is executed from within the same context as any executables scheduled.

A cell must be allocated for every executable scheduled. A cell defines the resource constraints of the system to allocate for an arbitrary use case.

Field Type Label Description
cell Cell A smaller resource constrained section of the system.

CellServiceAllocateResponse

The response after a cell has been allocated.

Field Type Label Description
cell_name string
cgroup_v2 bool A bool that will be set to true if the cgroup was created with cgroup v2 controller.

CellServiceFreeRequest

Used to remove or free a cell after it has been allocated.

Field Type Label Description
cell_name string

CellServiceFreeResponse

Response after removing or freeing a cell.

CellServiceListRequest

CellServiceListResponse

Field Type Label Description
cells CellGraphNode repeated

CellServiceStartRequest

A request for starting an executable inside of a Cell.

This is the lowest level of raw executive functionality. Here you can define shell commands, and meta information about the command. An executable is started synchronously.

Field Type Label Description
cell_name string optional
executable Executable

CellServiceStartResponse

The response after starting an executable within a Cell.

Field Type Label Description
pid int32 Return a pid as an int32 based on the pid_t type in various libc libraries.

CellServiceStopRequest

Request to stop an executable at runtime.

Field Type Label Description
cell_name string optional
executable_name string

CellServiceStopResponse

CpuController

Docs: https://docs.kernel.org/admin-guide/cgroup-v2.html#cpu

Field Type Label Description
weight uint64 optional Weight of how much of the total CPU time should this control group get. Note that this is hierarchical, so this is weighted against the siblings of this control group.
  • Minimum: 1 * Maximum: 10_000 | | max | int64 | optional | In one period (1_000_000), how much can the tasks run.

  • Minimum: 0

By default a cgroup has no limit, represented as the literal string "max". Not settings this field retains the default of no limit. | | period | uint64 | optional | The period is used as the scheduling slice. It interacts with max (see above) as a given workload will only run for max microseconds within period microseconds.

  • Minimum: 0

By default a cgroup has period 100000. |

CpusetController

Docs: https://docs.kernel.org/admin-guide/cgroup-v2.html#cpuset

Field Type Label Description
cpus string optional A comma-separated list of CPU IDs where the task in the control group can run. Dashes between numbers indicate ranges.
mems string optional Same syntax as the cpus field of this structure, but applies to memory nodes instead of processors.

Executable

The most primitive workload in Aurae, a standard executable process.

Field Type Label Description
name string
command string
description string

MemoryController

Docs: https://docs.kernel.org/admin-guide/cgroup-v2.html#memory-interface-files

Field Type Label Description
min int64 optional Hard memory protection. If the memory usage of a cgroup is within its effective min boundary, the cgroup’s memory won’t be reclaimed under any conditions. If there is no unprotected reclaimable memory available, OOM killer is invoked. Above the effective min boundary (or effective low boundary if it is higher), pages are reclaimed proportionally to the overage, reducing reclaim pressure for smaller overages. NOTE: unused by aurae
low int64 optional Best-effort memory protection. If the memory usage of a cgroup is within its effective low boundary, the cgroup’s memory won’t be reclaimed unless there is no reclaimable memory available in unprotected cgroups. Above the effective low boundary (or effective min boundary if it is higher), pages are reclaimed proportionally to the overage, reducing reclaim pressure for smaller overages.
high int64 optional Memory usage throttle limit. This is the main mechanism to control memory usage of a cgroup. If a cgroup’s usage goes over the high boundary, the processes of the cgroup are throttled and put under heavy reclaim pressure. NOTE: unused by aurae
max int64 optional Memory usage hard limit. This is the final protection mechanism. If a cgroup’s memory usage reaches this limit and can’t be reduced, the OOM killer is invoked in the cgroup. Under certain circumstances, the usage may go over the limit temporarily.

CellService

Cells is the most fundamental isolation boundary for Aurae. A cell is an isolate set of resources of the system which can be used to run workloads.

A cell is composed of a unique cgroup namespace, and unshared kernel namespaces.

Method Name Request Type Response Type Description
Allocate CellServiceAllocateRequest CellServiceAllocateResponse Reserve requested system resources for a new cell. For cells specifically this will allocate and reserve cgroup resources only.
Free CellServiceFreeRequest CellServiceFreeResponse Free up previously requested resources for an existing cell
Start CellServiceStartRequest CellServiceStartResponse Start a new Executable inside of an existing cell. Can be called in serial to start more than one executable in the same cell.
Stop CellServiceStopRequest CellServiceStopResponse Stop one or more Executables inside of an existing cell. Can be called in serial to stop/retry more than one executable.
List CellServiceListRequest CellServiceListResponse

Top

discovery.proto

DiscoverRequest

DiscoverResponse

Field Type Label Description
healthy bool
version string

DiscoveryService

Method Name Request Type Response Type Description
Discover DiscoverRequest DiscoverResponse Used to confirm that the host is running Aurae and to get some information including the version of Aurae that is running.

Top

observe.proto

GetAuraeDaemonLogStreamRequest

GetAuraeDaemonLogStreamResponse

Field Type Label Description
item LogItem

GetPosixSignalsStreamRequest

Request a stream of POSIX signals

Field Type Label Description
workload Workload The workload to which te response will be scoped. If no workload is / specified, a stream of all POSIX signals on the host will be returned.

GetPosixSignalsStreamResponse

Field Type Label Description
signal Signal

GetSubProcessStreamRequest

TODO: not implemented in auraescript

Field Type Label Description
process_id int32
channel_type LogChannelType

GetSubProcessStreamResponse

Field Type Label Description
item LogItem

LogItem

Field Type Label Description
channel string
line string
timestamp int64

Signal

Field Type Label Description
signal int32
process_id int32

Workload

Field Type Label Description
workload_type WorkloadType
id string

LogChannelType

Name Number Description
LOG_CHANNEL_TYPE_UNSPECIFIED 0
LOG_CHANNEL_TYPE_STDOUT 1
LOG_CHANNEL_TYPE_STDERR 2

WorkloadType

Name Number Description
WORKLOAD_TYPE_UNSPECIFIED 0
WORKLOAD_TYPE_CELL 1
WORKLOAD_TYPE_POD_SANDBOX 2
WORKLOAD_TYPE_VM 3

ObserveService

Method Name Request Type Response Type Description
GetAuraeDaemonLogStream GetAuraeDaemonLogStreamRequest GetAuraeDaemonLogStreamResponse stream request log stream for aurae. everything logged via log macros in aurae (info!, error!, trace!, ... ).
GetSubProcessStream GetSubProcessStreamRequest GetSubProcessStreamResponse stream TODO: request log stream for a sub process
GetPosixSignalsStream GetPosixSignalsStreamRequest GetPosixSignalsStreamResponse stream request POSIX signals stream for the host

Top

vms.proto

DriveMount

Field Type Label Description
host_path string The path on the host to the filesystem image or device that will be mounted inside the VM.
vm_path string The path inside the VM guest at which the filesystem image or device will be mounted.
fs_type string The filesystem type (i.e. ext4, xfs, etc.), as used when mounting the filesystem image inside the VM. The VM guest kernel is expected to have support for this filesystem.
is_writeable bool Mount the root filesystem as read-write. (Default: false)

IPConfiguration

Static IP configuration for a VM network interface

Field Type Label Description
primary_addr string PrimaryAddr specifies, in CIDR notation, the primary address and subnet that a network interface will be assigned inside the VM.
gateway_addr string GatewayAddr specifies the default gateway that a network interface should use inside the VM.
nameservers string repeated Nameservers is a list of nameservers that the VM will be configured to use internally

RootDrive

Message to specify the block device config for a VM

Field Type Label Description
host_path string The path on the host to the filesystem image or device that will supply the rootfs of the VM.
is_writeable bool Mount the root filesystem as read-write. (Default: false)

VirtualMachine

An Aurae virtual machine

Field Type Label Description
id string The identifier of the VM
mem_size_mb uint32 The memory size of VM
vcpu_count uint32 The number of vCPUs for the VM
kernel_img_path string The path to the VM kernel image
kernel_args string repeated Arguments to pass to the kernel
root_drive RootDrive Root drive config
drive_mounts DriveMount repeated Additional drive mount configs

VmServiceCreateRequest

Field Type Label Description
machine VirtualMachine

VmServiceCreateResponse

Field Type Label Description
vm_id string

VmServiceFreeRequest

VmServiceFreeResponse

Field Type Label Description
vm_id string

VmServiceStartRequest

Field Type Label Description
vm_id string

VmServiceStartResponse

VmServiceStopRequest

Field Type Label Description
vm_id string

VmServiceStopResponse

VmService

Method Name Request Type Response Type Description
Create VmServiceCreateRequest VmServiceCreateResponse Reserve requested system resources for a new VM.
Free VmServiceFreeRequest VmServiceFreeResponse Free up previously requested resources for an existing VM
Start VmServiceStartRequest VmServiceStartResponse Start a new VM.
Stop VmServiceStopRequest VmServiceStopResponse Stop one or more VMs.

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)