Alpha state disclaimer
The protocol defined below is in early development cycle and is subject to (potentially breaking) change.
The Agents interface is a JSON encoded HTTP API.
The API is versioned so that breaking changes can be rolled out gradually with version compatibility “windows”.
Any date or time returned or receiver by the agent API MUST be in UTC.
The Agent API MUST expose dates and times as RFC 3339 encoded strings.
One of the tasks an agent is expected to do is provide specialised information and monitoring data. Replicante Core will collect and aggregate this data to estimate (distributed systems, remember?) the state and health of the cluster.
A note about monitoring
Just because “monitoring” was mentioned as one of the agent’s responsibilities it does not mean the agent is responsible for general purpose moniotring.
Use Prometheus or other tools for general purpose monitoring.
Replicante Agents MAY be built to also provide general purpose monitoring services but that is outside the scope of this specification.
Another task the agent is responsible for is the execution of actions. Actions are the execution layer on which any automation is built.
Agents allow clients to schedule as many actions as they like and can start rejecting actions if too many actions are schedule and have not been processed yet. Agents MUST execute only one action at a time. Actions MUST be executed in the order they have been successfully scheduled with the agent.
Actions have the following set of properties:
args: Arguments passed to the action when invoked.
created_ts: Time the action was first created (by the agent, by core, …).
finished_ts: Time the action entered a final state.
headers: Additional metadata headers attached to the action.
id: Unique ID of the action.
kind: Type ID of the action to run. Consult the agent documentation for information about actions discovery.
requester: Entity (system or user) requesting the execution of the action.
scheduled_ts: Time the agent recorded the action in the DB.
state: State the action is currently in (see below).
state_payload: Optional payload attached to the current
state attribute indicates at which point of the lifecycle the action is:
The states are as follows:
NEW: all actions start of in the
NEWstate when they are scheduled.
RUNNING: when a
NEWaction is picked up for execution and started, it enters the
RUNNINGactions can transition from
RUNNING, when this happen their
DONE: the agent completed execution of the action successfully.
FAILED: the action encountered an error or was otherwise unable to transition the system to the desired state.