Protocol Documentation

Table of Contents

• control_api.proto

  • FromAnkaios
  • ToAnkaios

• ank_base.proto

  • CompleteState
  • CompleteStateRequest
  • Error
  • ExecutionState
  • Request
  • Response
  • State
  • State.WorkloadsEntry
  • Tag
  • UpdateStateRequest
  • UpdateStateSuccess
  • Workload
  • Workload.DependenciesEntry
  • WorkloadInstanceName

  • WorkloadState

  • AddCondition

  • AgentDisconnected
  • Failed
  • NotScheduled
  • Pending
  • 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

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	WorkloadState	repeated	The current 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'.

Error

Field	Type	Label	Description
message	string

ExecutionState

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.

Request

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

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	State.WorkloadsEntry	repeated	A mapping from workload names to workload configurations.

State.WorkloadsEntry

Field	Type	Label	Description
key	string
value	Workload

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

UpdateStateSuccess

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		The name of the owning Agent.
restartPolicy	RestartPolicy		An enum value that defines the condition under which a workload is restarted.
dependencies	Workload.DependenciesEntry	repeated	A map of workload names and expected states to enable a synchronized start of the workload.
tags	Tag	repeated	A list of tag names.
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	AddCondition

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.

WorkloadState

A message containing the information about the workload state.

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

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.

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)