CommandInterface

This script defines the CommandInterfaceConnection class, implementing the Connection abstraction over a direct gRPC connection to the Ankaios server, used to connect to Ankaios from outside a workload.

Classes

• CommandInterfaceConnection:

  Handles the interaction with Ankaios over gRPC.

Enums

• CommandInterfaceState:

  Represents the state of the gRPC connection.

Usage

• Create a CommandInterfaceConnection instance, connect and disconnect.

  conn = CommandInterfaceConnection(
      "http://127.0.0.1:25551", <callbacks from Ankaios>
  )
  conn.connect()
  ...
  conn.disconnect()
  

CommandInterfaceConnection Class

class ankaios_sdk._components.connection.command_interface.CommandInterfaceConnection(server_url, add_response_callback, add_log_callback, add_event_callback, *, ca_pem=None, crt_pem=None, key_pem=None)

Bases: Connection

This class handles the interaction with an Ankaios server over the command interface: a direct gRPC connection to the server, playing the commander role via the CommandConnection service.

The initial connect() attempt is never retried. Once a connection has been established, losing it is treated as transient: it is retried every RECONNECT_INTERVAL seconds until it succeeds or disconnect() is called.

RECONNECT_INTERVAL = 0.5

Seconds to wait between reconnect attempts.

Type:

(float)

CHANNEL_READY_TIMEOUT = 5.0

Seconds to wait for a single (re)connect attempt.

Type:

(float)

SERVER_TLS_NAME = 'ank-server'

The domain name Ankaios server certificates are issued for.

Type:

(str)

__init__(server_url, add_response_callback, add_log_callback, add_event_callback, *, ca_pem=None, crt_pem=None, key_pem=None)

Initialize the CommandInterfaceConnection object. This is used to interact with an Ankaios server directly over the command interface.

If none of ca_pem, crt_pem and key_pem are provided, the connection is a plaintext (insecure) one. If all three are provided, the connection is mTLS-secured. Providing only some of them is invalid.

Parameters:

• server_url (str) – The URL of the Ankaios server, e.g. “http://127.0.0.1:25551” (insecure) or “https://127.0.0.1:25551” (mTLS-secured).

• add_response_callback (Callable) – The callback function to add a response to the Ankaios class.

• add_log_callback (Callable) – The callback function to add a log to the Ankaios class.

• add_event_callback (Callable) – The callback function to add an event to the Ankaios class.

• ca_pem (Optional[str]) – The PEM-encoded CA certificate content.

• crt_pem (Optional[str]) – The PEM-encoded client certificate content.

• key_pem (Optional[str]) – The PEM-encoded client private key content.

Raises:

ValueError – If only some of ca_pem, crt_pem and key_pem are provided.

property connected: bool

Check if the gRPC connection is established.

Returns:

True if connected, False otherwise.

Return type:

bool

connect()

Establish the gRPC connection to the Ankaios server.

This attempt is never retried by this method; once established, a later lost connection is retried transparently every RECONNECT_INTERVAL seconds.

Raises:

ConnectionException – If already connected, or if the connection could not be established.

Return type:

None

disconnect()

Disconnect from the gRPC connection.

Return type:

None

write_request(request)

Sends the request through the gRPC connection.

Parameters:

request (Request) – The request object to be written.

Raises:

ConnectionException – If not connected.

Return type:

None

change_state(state)

Change the state of the connection.

Unlike the control interface, there is no separate unrecoverable state here: TERMINATED is both the initial state and the one disconnect() ends in, and connect() must be able to leave it again.

Parameters:

state (CommandInterfaceState) – The new state.

Return type:

None

CommandInterfaceState Enum

class ankaios_sdk._components.connection.command_interface.CommandInterfaceState(value)

Bases: Enum

The state of the gRPC connection.

INITIALIZED = 1

The connection was initialized but not yet accepted.

Type:

(int)

CONNECTED = 2

The connection is established.

Type:

(int)

TERMINATED = 3

The connection is terminated.

Type:

(int)

RECONNECTING = 4

A lost connection is being retried.

Type:

(int)

__str__()

Returns the string representation of the state.

Returns:

The state as a string.

Return type:

str