Page Selection
Agents Specification
- Introduction
- The Model
- Changelog
- Example: Kafka
- Example: MongoDB
- Example: Zookeeper
- The Agent Protocol
- Agent Information API
- Shards Information API
- Actions API
Platforms Specification
The Agent Protocol
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.
Information and Monitoring
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.
Agent information API
Shards information API
Actions
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 currentstate.
The action state attribute indicates at which point of the lifecycle the action is:
The states are as follows:
NEW: all actions start of in theNEWstate when they are scheduled.RUNNING: when aNEWaction is picked up for execution and started, it enters theRUNNINGstate.RUNNINGactions can transition fromRUNNINGtoRUNNING, when this happen theirstate_payloadmay change.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.