Protocol Documentation

Table of Contents

• ankaios.proto

  • AccessRights
  • AccessRightsRule
  • AddedWorkload
  • AddedWorkload.DependenciesEntry
  • AgentHello
  • CompleteState
  • Cronjob
  • DeletedWorkload
  • DeletedWorkload.DependenciesEntry
  • ExecutionRequest
  • Goodbye
  • Interval
  • RequestCompleteState
  • State
  • State.ConfigsEntry
  • State.CronjobsEntry
  • State.WorkloadsEntry
  • StateChangeRequest
  • Tag
  • UpdateStateRequest
  • UpdateWorkload
  • UpdateWorkloadState
  • Workload
  • Workload.DependenciesEntry

  • WorkloadState

  • ExecutionState

  • ExpectedState
  • PatchOperation

  • UpdateStrategy

  • AgentConnection

  • CliConnection

• Scalar Value Types

Top

ankaios.proto

The Ankaios communication protocol is used in the communcation between the following components:

1. Ankaios Agent and Ankaios Server,

2. Ankaios CLI and Ankaios Server,

3. Workload and Ankaios Server through the control interface.

The protocol consists of the following top-level message types:

1. StateChangeRequest: agent/cli -> server

2. ExecutionRequest: server -> agent/cli

AccessRights

A message containing lists of access rules that are allowed or denied.

Field	Type	Label	Description
allow	AccessRightsRule	repeated	A list of access rules that are allowed.
deny	AccessRightsRule	repeated	A list of access rules that are denied.

AccessRightsRule

A message describing an access rule for the given patch operation for given object fields and values.

Field	Type	Label	Description
operation	PatchOperation		The patch operation of interrest.
updateMask	string	repeated	A List of field names.
value	string	repeated	A list of accepted values.

AddedWorkload

A message containing information about a workload to be added to the Ankaios cluster.

Field	Type	Label	Description
name	string		The name of the workload.
runtime	string		The name of the runtime, e.g., podman.
dependencies	AddedWorkload.DependenciesEntry	repeated	A list of dependencies to other workloads with their corresponding, expected states. Can be used to enable a synchronized start of a workload.
restart	bool		A flag indicating to restart the workload in case of an intentional or an unintentional stop of the workload.
updateStrategy	UpdateStrategy		An enum to specify the update strategy.
accessRights	AccessRights		Lists of authorizations of the workload.
tags	Tag	repeated	A list of tags.
runtimeConfig	string		The configuration information specific to the runtime.

AddedWorkload.DependenciesEntry

Field	Type	Label	Description
key	string
value	ExpectedState

AgentHello

A message to the Ankaios server to register a new agent.

Field	Type	Label	Description
agentName	string		A unique agent name.

CompleteState

A message containing the complete state of the Ankaios system. This is a response to the RequestCompletestate message.

Field	Type	Label	Description
requestId	string		The request id corresponding to a sent RequestCompletestate message.
startupState	State		The State information at the startup of the Ankaios System.
currentState	State		The current state information.
workloadStates	WorkloadState	repeated	The current states of the workloads.

Cronjob

A message containing the cron job information.

Field	Type	Label	Description
workload	string		The name of the workload.
interval	Interval		The interval of the cron job.

DeletedWorkload

A message containing information about a workload to be deleted from the Anakaios system.

Field	Type	Label	Description
name	string		The name of the workload.
dependencies	DeletedWorkload.DependenciesEntry	repeated	A list of dependencies to other workloads with their corresponding, expected states. Can be used to enable a synchronized stop of a workload.

DeletedWorkload.DependenciesEntry

Field	Type	Label	Description
key	string
value	ExpectedState

ExecutionRequest

Messages to the Ankaios server.

Field	Type	Label	Description
updateWorkload	UpdateWorkload		A message containing lists of workloads to be added or deleted.
updateWorkloadState	UpdateWorkloadState		A message containing list of workload execution states.
completeState	CompleteState		A message containing the complete state (startup state, current state, workload states) of the Anakios system.

Goodbye

A message to the Ankaios server to signalize a client (agent or cli) is shutting down.

Interval

A message containing the interval information for the cron job.

Field	Type	Label	Description
hours	uint32		The number of hours.
minutes	uint32		The number of minutes.
seconds	uint32		The number of seconds.

RequestCompleteState

A message containing a request for the complete/partial state of the Ankaios system. This is usually answered with a CompleteState message.

Field	Type	Label	Description
requestId	string		A request id. This can be any string literal.
fieldMask	string	repeated	A list of symbolic field paths within the State message structure e.g. 'currentState.workloads.nginx'.

State

A message containing the state information.

Field	Type	Label	Description
workloads	State.WorkloadsEntry	repeated	A mapping from workload names to workload configurations.
configs	State.ConfigsEntry	repeated	A key value storage for reusable configuration items.
cronjobs	State.CronjobsEntry	repeated	A mapping from workload names to cron job configurations.

State.ConfigsEntry

Field	Type	Label	Description
key	string
value	string

State.CronjobsEntry

Field	Type	Label	Description
key	string
value	Cronjob

State.WorkloadsEntry

Field	Type	Label	Description
key	string
value	Workload

StateChangeRequest

Messages to the Ankaios server.

Field	Type	Label	Description
agentHello	AgentHello		This message is for internal usage only!
updateWorkloadState	UpdateWorkloadState		A message to Ankaios server to update the execution state of a workload.
updateState	UpdateStateRequest		A message to Ankaios server to update the State of one or more agent(s).
requestCompleteState	RequestCompleteState		A message to Ankaios server to request the complete state by the given request id and the optional field mask.
goodbye	Goodbye

Tag

A message to store a tag.

Field	Type	Label	Description
key	string		The key of the tag.
value	string		The value of the tag.

UpdateStateRequest

A message containing a request to update the state of the Ankaios system. The new state is provided as state object. To specify which part(s) of the new state object should be updated a list of update mask (same as field mask) paths needs to be provided.

Field	Type	Label	Description
newState	CompleteState		The new state of the Ankaios system.
updateMask	string	repeated	A list of symbolic field paths within the state message structure e.g. 'currentState.workloads.nginx' to specify what to be updated.

UpdateWorkload

A message providing information about the workloads to be added and/or deleted.

Field	Type	Label	Description
addedWorkloads	AddedWorkload	repeated	A list of messages containing information about a workload to be added by an Ankaios agent.
deletedWorkloads	DeletedWorkload	repeated	A list of messages containing information about a workload to be deleted by an Ankaios agent.

UpdateWorkloadState

A message containing the list the workload states.

Field	Type	Label	Description
workloadStates	WorkloadState	repeated	A list of workload states.

Workload

A message containing the configuration of a workload.

Field	Type	Label	Description
agent	string		The name of the owning Agent.
restart	bool		A flag indicating to restart the workload in case of an intentional or an unintentional stop of the workload.
dependencies	Workload.DependenciesEntry	repeated	A map of workload names and expected states to enable a synchronized start of the workload.
updateStrategy	UpdateStrategy		An enum to specify the update strategy.
tags	Tag	repeated	A list of tag names.
accessRights	AccessRights		Lists of authorizations of the workload.
runtime	string		The name of the runtime e.g. podman.
runtimeConfig	string		The configuration information specific to the runtime.

Workload.DependenciesEntry

Field	Type	Label	Description
key	string
value	ExpectedState

WorkloadState

A message containing the information about the workload state.

Field	Type	Label	Description
workloadName	string		The name of the workload.
agentName	string		The name of the owning Agent.
executionState	ExecutionState		The workload execution state.

ExecutionState

An enum type describing the workload execution state.

Name	Number	Description
EXEC_PENDING	0	The workload is pending.
EXEC_RUNNING	1	The workload is running.
EXEC_SUCCEEDED	2	The workload has run successfully and is stopped.
EXEC_FAILED	3	The workload has failed.
EXEC_UNKNOWN	4	The workload is in unknown state. This is the case if the owning agent is disconnected from the Ankaios server.
EXEC_REMOVED	5	The workload has been deleted.

ExpectedState

An enum type describing the expected workload state. Used for dependency management.

Name	Number	Description
STOPPED	0	The workload is stopped.
RUNNING	1	The workload is running.

PatchOperation

An enum type for specifing the patch operation.

Name	Number	Description
REPLACE	0	The replace operation.
ADD	1	The add operation.
REMOVE	2	the remove operation.

UpdateStrategy

An enum type for specifing the update strategy.

Name	Number	Description
UNSPECIFIED	0	The update order is irrelevant.
AT_LEAST_ONCE	1	At least one instance shall be running - start the new before stopping the old one.
AT_MOST_ONCE	2	At most one instance shall be running - stop the old before starting the new one.

AgentConnection

Method Name	Request Type	Response Type	Description
ConnectAgent	StateChangeRequest stream	ExecutionRequest stream

CliConnection

Method Name	Request Type	Response Type	Description
ConnectCli	StateChangeRequest stream	ExecutionRequest stream

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)