Protocol Documentation
Table of Contents
Top
ankaios.proto
The Ankaios communication protocol is used in the communcation between the following components:
Ankaios Agent and Ankaios Server,
Ankaios CLI and Ankaios Server,
Workload and Ankaios Server through the control interface.
The protocol consists of the following top-level message types:
ToServer : agent/cli -> server
FromServer : server -> agent/cli
AddedWorkload
A message containing information about a workload to be added to the Ankaios cluster.
Field
Type
Label
Description
instanceName
WorkloadInstanceName
The instance 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.
restartPolicy
RestartPolicy
An enum value that defines the condition under which a workload is restarted.
tags
Tag
repeated
A list of tags.
runtimeConfig
string
The configuration information specific to the runtime.
AddedWorkload.DependenciesEntry
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 CompleteStateRequest message.
Field
Type
Label
Description
startupState
State
The State information at the startup of the Ankaios System.
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'.
DeletedWorkload
A message containing information about a workload to be deleted from the Anakaios system.
Field
Type
Label
Description
instanceName
WorkloadInstanceName
The instance 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
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.
FromServer
Messages from the Ankaios server to e.g. the Ankaios agent.
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.
response
Response
A message containing a response to a previous request.
Goodbye
A message to the Ankaios server to signalize a client (agent or cli) is shutting down.
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
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
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.
ToServer
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.
request
Request
goodbye
Goodbye
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
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.
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
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.
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
DeleteCondition
An enum type describing the conditions for deleting a workload. Used for dependency management, and update strategies.
Name
Number
Description
DEL_COND_RUNNING
0
The workload is operational.
DEL_COND_NOT_PENDING_NOR_RUNNING
1
The workload is not scheduled or running.
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.
AgentConnection
Method Name
Request Type
Response Type
Description
ConnectAgent
ToServer stream
FromServer stream
CliConnection
Method Name
Request Type
Response Type
Description
ConnectCli
ToServer stream
FromServer 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)