Protocol Documentation

Table of Contents

• cells.proto

  • Cell
  • CellGraphNode
  • CellServiceAllocateRequest
  • CellServiceAllocateResponse
  • CellServiceFreeRequest
  • CellServiceFreeResponse
  • CellServiceListRequest
  • CellServiceListResponse
  • CellServiceStartRequest
  • CellServiceStartResponse
  • CellServiceStopRequest
  • CellServiceStopResponse
  • CpuController
  • CpusetController
  • Executable

  • MemoryController

  • CellService

• discovery.proto

  • DiscoverRequest

  • DiscoverResponse

  • DiscoveryService

• observe.proto

  • GetAuraeDaemonLogStreamRequest
  • GetAuraeDaemonLogStreamResponse
  • GetPosixSignalsStreamRequest
  • GetPosixSignalsStreamResponse
  • GetSubProcessStreamRequest
  • GetSubProcessStreamResponse
  • LogItem
  • Signal

  • Workload

  • LogChannelType

  • WorkloadType

  • ObserveService

• vms.proto

  • DriveMount
  • IPConfiguration
  • RootDrive
  • VirtualMachine
  • VmServiceCreateRequest
  • VmServiceCreateResponse
  • VmServiceFreeRequest
  • VmServiceFreeResponse
  • VmServiceStartRequest
  • VmServiceStartResponse
  • VmServiceStopRequest

  • VmServiceStopResponse

  • VmService

• Scalar Value Types

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)