Protocol Documentation

Table of Contents

• control_api.proto

  • FromAnkaios
  • ToAnkaios

• ank_base.proto

  • AccessRightsRule
  • CompleteState
  • CompleteStateRequest
  • ControlInterfaceAccess
  • Dependencies
  • Dependencies.DependenciesEntry
  • Error
  • ExecutionState
  • ExecutionsStatesForId
  • ExecutionsStatesForId.IdStateMapEntry
  • ExecutionsStatesOfWorkload
  • ExecutionsStatesOfWorkload.WlNameStateMapEntry
  • Request
  • Response
  • State
  • StateRule
  • Tag
  • Tags
  • UpdateStateRequest
  • UpdateStateSuccess
  • Workload
  • WorkloadInstanceName
  • WorkloadMap
  • WorkloadMap.WorkloadsEntry
  • WorkloadState
  • WorkloadStatesMap

  • WorkloadStatesMap.AgentStateMapEntry

  • AddCondition

  • AgentDisconnected
  • Failed
  • NotScheduled
  • Pending
  • ReadWriteEnum
  • Removed
  • RestartPolicy
  • Running
  • Stopping
  • Succeeded

• Scalar Value Types

Top

control_api.proto

The Ankaios Control Interface is used in the communcation between a workload and Ankaios

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

1. ToAnkaios: workload -> ankaios

2. FromAnkaios: ankaios -> workload

FromAnkaios

Messages from the Ankaios server to e.g. the Ankaios agent.

Field	Type	Label	Description
response	ank_base.Response		A message containing a response to a previous request.

ToAnkaios

Messages to the Ankaios server.

Field	Type	Label	Description
request	ank_base.Request

Top

ank_base.proto

AccessRightsRule

A message containing an allow or deny rule.

Field	Type	Label	Description
stateRule	StateRule		Rule for getting or setting the state

CompleteState

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

Field	Type	Label	Description
desiredState	State		The state the user wants to reach.
workloadStates	WorkloadStatesMap		The current execution states of the workloads.

CompleteStateRequest

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
fieldMask	string	repeated	A list of symbolic field paths within the State message structure e.g. 'desiredState.workloads.nginx'.

ControlInterfaceAccess

A message containing the parts of the control interface the workload as authorized to access. By default, all access is denied. Only if a matching allow rule is found, and no matching deny rules is found, the access is allowed.

Field	Type	Label	Description
allowRules	AccessRightsRule	repeated	Rules allow the access
denyRules	AccessRightsRule	repeated	Rules denying the access

Dependencies

This is a workaround for proto not supporing optional maps

Field	Type	Label	Description
dependencies	Dependencies.DependenciesEntry	repeated

Dependencies.DependenciesEntry

Field	Type	Label	Description
key	string
value	AddCondition

Error

Field	Type	Label	Description
message	string

ExecutionState

A message containing information about the detailed state of a workload in the Ankaios system.

Field	Type	Label	Description
additionalInfo	string		The additional info contains more detailed information from the runtime regarding the execution state.
agentDisconnected	AgentDisconnected		The exact state of the workload cannot be determined, e.g., because of a broken connection to the responsible agent.
pending	Pending		The workload is going to be started eventually.
running	Running		The workload is operational.
stopping	Stopping		The workload is scheduled for stopping.
succeeded	Succeeded		The workload has successfully finished its operation.
failed	Failed		The workload has failed or is in a degraded state.
notScheduled	NotScheduled		The workload is not scheduled to run at any agent. This is signalized with an empty agent in the workload specification.
removed	Removed		The workload was removed from Ankaios. This state is used only internally in Ankaios. The outside world removed states are just not there.

ExecutionsStatesForId

A map providing the execution state of a specific workload for a given id. This level is needed as a workload could be running more than once on one agent in different versions.

Field	Type	Label	Description
idStateMap	ExecutionsStatesForId.IdStateMapEntry	repeated

ExecutionsStatesForId.IdStateMapEntry

Field	Type	Label	Description
key	string
value	ExecutionState

ExecutionsStatesOfWorkload

A map providing the execution state of a workload for a given name.

Field	Type	Label	Description
wlNameStateMap	ExecutionsStatesOfWorkload.WlNameStateMapEntry	repeated

ExecutionsStatesOfWorkload.WlNameStateMapEntry

Field	Type	Label	Description
key	string
value	ExecutionsStatesForId

Request

A message containing a request to the Ankaios server to update the state or to request the complete state of the Ankaios system.

Field	Type	Label	Description
requestId	string
updateStateRequest	UpdateStateRequest		A message to Ankaios server to update the state of one or more agent(s).
completeStateRequest	CompleteStateRequest		A message to Ankaios server to request the complete state by the given request id and the optional field mask.

Response

A message containing a response from the Ankaios server to a particular request. The response content depends on the request content previously sent to the Ankaios server.

Field	Type	Label	Description
requestId	string
error	Error
completeState	CompleteState
UpdateStateSuccess	UpdateStateSuccess

State

A message containing the state information.

Field	Type	Label	Description
apiVersion	string		The current version of the API.
workloads	WorkloadMap		A mapping from workload names to workload configurations.

StateRule

Message containing a rule for getting or setting the state

Field	Type	Label	Description
operation	ReadWriteEnum		Defines which actions are allowed
filterMasks	string	repeated	Pathes definind what can be accessed. Segements of path can be a wildcare "*".

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.

Tags

This is a workaround for proto not supporing optional repeated values

Field	Type	Label	Description
tags	Tag	repeated

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. 'desiredState.workloads.nginx' to specify what to be updated.

UpdateStateSuccess

A message from the server containing the ids of the workloads that have been started and stopped in response to a previously sent UpdateStateRequest.

Field	Type	Label	Description
addedWorkloads	string	repeated	Workload istance names of workloads which will be started
deletedWorkloads	string	repeated	Workload instance names of workloads which will be stopped

Workload

A message containing the configuration of a workload.

Field	Type	Label	Description
agent	string	optional	The name of the owning Agent.
restartPolicy	RestartPolicy	optional	An enum value that defines the condition under which a workload is restarted.
dependencies	Dependencies		A map of workload names and expected states to enable a synchronized start of the workload.
tags	Tags		A list of tag names.
runtime	string	optional	The name of the runtime e.g. podman.
runtimeConfig	string	optional	The configuration information specific to the runtime.
controlInterfaceAccess	ControlInterfaceAccess

WorkloadInstanceName

Field	Type	Label	Description
workloadName	string		The name of the workload.
agentName	string		The name of the owning Agent.
id	string		A unique identifier of the workload.

WorkloadMap

This is a workaround for proto not supporing optional maps

Field	Type	Label	Description
workloads	WorkloadMap.WorkloadsEntry	repeated

WorkloadMap.WorkloadsEntry

Field	Type	Label	Description
key	string
value	Workload

WorkloadState

A message containing the information about the workload state.

Field	Type	Label	Description
instanceName	WorkloadInstanceName
executionState	ExecutionState		The workload execution state.

WorkloadStatesMap

A nested map that provides the execution state of a workload in a structured way. The first level allows searches by agent.

Field	Type	Label	Description
agentStateMap	WorkloadStatesMap.AgentStateMapEntry	repeated

WorkloadStatesMap.AgentStateMapEntry

Field	Type	Label	Description
key	string
value	ExecutionsStatesOfWorkload

AddCondition

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

Name	Number	Description
ADD_COND_RUNNING	0	The workload is operational.
ADD_COND_SUCCEEDED	1	The workload has successfully exited.
ADD_COND_FAILED	2	The workload has exited with an error or could not be started.

AgentDisconnected

The exact state of the workload cannot be determined, e.g., because of a broken connection to the responsible agent.

Name	Number	Description
AGENT_DISCONNECTED	0

Failed

The workload has failed or is in a degraded state.

Name	Number	Description
FAILED_EXEC_FAILED	0	The workload has failed during operation
FAILED_UNKNOWN	1	The workload is in an unsupported by Ankaios runtime state. The workload was possibly altered outside of Ankaios.
FAILED_LOST	2	The workload cannot be found anymore. The workload was possibly altered outside of Ankaios or was auto-removed by the runtime.

NotScheduled

The workload is not scheduled to run at any agent. This is signalized with an empty agent in the workload specification.

Name	Number	Description
NOT_SCHEDULED	0

Pending

The workload is going to be started eventually.

Name	Number	Description
PENDING_INITIAL	0	The workload specification has not yet being scheduled
PENDING_WAITING_TO_START	1	The start of the workload will be triggered once all its dependencies are met.
PENDING_STARTING	2	Starting the workload was scheduled at the corresponding runtime.
PENDING_STARTING_FAILED	8	The starting of the workload by the runtime failed.

ReadWriteEnum

An enum type describing which action is allowed.

Name	Number	Description
RW_NOTHING	0	Allow nothing
RW_READ	1	Allow read
RW_WRITE	2	Allow write
RW_READ_WRITE	5	Allow read and write

Removed

The workload was removed from Ankaios. This state is used only internally in Ankaios. The outside world removed states are just not there.

Name	Number	Description
REMOVED	0

RestartPolicy

An enum type describing the restart behavior of a workload.

Name	Number	Description
NEVER	0	The workload is never restarted. Once the workload exits, it remains in the exited state.
ON_FAILURE	1	If the workload exits with a non-zero exit code, it will be restarted.
ALWAYS	2	The workload is restarted upon termination, regardless of the exit code.

Running

The workload is operational.

Name	Number	Description
RUNNING_OK	0	The workload is operational.

Stopping

The workload is scheduled for stopping.

Name	Number	Description
STOPPING	0	The workload is being stopped.
STOPPING_WAITING_TO_STOP	1	The deletion of the workload will be triggered once neither 'pending' nor 'running' workload depending on it exists.
STOPPING_REQUESTED_AT_RUNTIME	2	This is an Ankaios generated state returned when the stopping was explicitly trigged by the user and the request was sent to the runtime.
STOPPING_DELETE_FAILED	8	The deletion of the workload by the runtime failed.

Succeeded

The workload has successfully finished operation.

Name	Number	Description
SUCCEEDED_OK	0	The workload has successfully finished operation.

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)