policy/frameworks/management/agent/api.zeek

Management::Agent::API

The event API of cluster agents. Most endpoints consist of event pairs, where the agent answers a request event with a corresponding response event. Such event pairs share the same name prefix and end in “_request” and “_response”, respectively.

Namespace

Management::Agent::API

Imports

base/frameworks/supervisor/control.zeek, policy/frameworks/management/types.zeek

Summary

Constants

Management::Agent::API::version: count

A simple versioning scheme, used to track basic compatibility of controller and agent.

Events

Management::Agent::API::agent_standby_request: event

The controller sends this event to convey that the agent is not currently required.

Management::Agent::API::agent_standby_response: event

Response to a Management::Agent::API::agent_standby_request event.

Management::Agent::API::agent_welcome_request: event

The controller sends this event to confirm to the agent that it is part of the current cluster topology.

Management::Agent::API::agent_welcome_response: event

Response to a Management::Agent::API::agent_welcome_request event.

Management::Agent::API::deploy_request: event

The controller sends this event to deploy a cluster configuration to this instance.

Management::Agent::API::deploy_response: event

Response to a Management::Agent::API::deploy_request event.

Management::Agent::API::get_nodes_request: event

The controller sends this event to request a list of Management::NodeStatus records that capture the status of Supervisor-managed nodes running on this instance.

Management::Agent::API::get_nodes_response: event

Response to a Management::Agent::API::get_nodes_request event.

Management::Agent::API::node_dispatch_request: event

The controller sends this to every agent to request a dispatch (the execution of a pre-implemented activity) to all cluster nodes.

Management::Agent::API::node_dispatch_response: event

Response to a Management::Agent::API::node_dispatch_request event.

Management::Agent::API::notify_agent_hello: event

The agent sends this event upon peering as a “check-in”, informing the controller that an agent of the given name is now available to communicate with.

Management::Agent::API::notify_change: event

Management::Agent::API::notify_error: event

Management::Agent::API::notify_log: event

Management::Agent::API::restart_request: event

The controller sends this event to ask the agent to restart currently running Zeek cluster nodes.

Management::Agent::API::restart_response: event

Response to a Management::Agent::API::restart_request event.

Detailed Interface

Constants

Management::Agent::API::version
Type

count

Default

1

A simple versioning scheme, used to track basic compatibility of controller and agent.

Events

Management::Agent::API::agent_standby_request
Type

event (reqid: string)

The controller sends this event to convey that the agent is not currently required. This status may later change, depending on updates from the client, so the Broker-level peering can remain active. The agent releases any cluster-related resources (including shutdown of existing Zeek cluster nodes) when processing the request, and confirms via the response event. Shutting down an agent at this point has no operational impact on the running cluster.

Parameters

reqid – a request identifier string, echoed in the response event.

Management::Agent::API::agent_standby_response
Type

event (reqid: string, result: Management::Result)

Response to a Management::Agent::API::agent_standby_request event. The agent sends this back to the controller.

Parameters
  • reqid – the request identifier used in the request event.

  • result – the result record.

Management::Agent::API::agent_welcome_request
Type

event (reqid: string)

The controller sends this event to confirm to the agent that it is part of the current cluster topology. The agent acknowledges with a Management::Agent::API::agent_welcome_response event, upon which the controller may proceed with a cluster deployment to this agent.

Parameters

reqid – a request identifier string, echoed in the response event.

Management::Agent::API::agent_welcome_response
Type

event (reqid: string, result: Management::Result)

Response to a Management::Agent::API::agent_welcome_request event. The agent sends this back to the controller.

Parameters
  • reqid – the request identifier used in the request event.

  • result – the result record.

Management::Agent::API::deploy_request
Type

event (reqid: string, config: Management::Configuration, force: bool &default = F &optional)

The controller sends this event to deploy a cluster configuration to this instance. Once processed, the agent responds with a Management::Agent::API::deploy_response event. event.

Parameters
  • reqid – a request identifier string, echoed in the response event.

  • config – a Management::Configuration record describing the cluster topology. This contains the full topology, not just the part pertaining to this instance: the cluster framework requires full cluster visibility to establish needed peerings.

  • force – whether to re-deploy (i.e., restart its Zeek cluster nodes) when the agent already runs this configuration. This relies on the config ID to determine config equality.

Management::Agent::API::deploy_response
Type

event (reqid: string, results: Management::ResultVec)

Response to a Management::Agent::API::deploy_request event. The agent sends this back to the controller.

Parameters
  • reqid – the request identifier used in the request event.

  • results – A vector of Management::Result records, each capturing the outcome of a single launched node. For failing nodes, the result’s data field is a Management::NodeOutputs record.

Management::Agent::API::get_nodes_request
Type

event (reqid: string)

The controller sends this event to request a list of Management::NodeStatus records that capture the status of Supervisor-managed nodes running on this instance. instances.

Parameters

reqid – a request identifier string, echoed in the response event.

Management::Agent::API::get_nodes_response
Type

event (reqid: string, result: Management::Result)

Response to a Management::Agent::API::get_nodes_request event. The agent sends this back to the controller.

Parameters
  • reqid – the request identifier used in the request event.

  • result – a Management::Result record. Its data member is a vector of Management::NodeStatus records, covering the nodes at this instance. The result may also indicate failure, with error messages indicating what went wrong.

Management::Agent::API::node_dispatch_request
Type

event (reqid: string, action: vector of string, nodes: set [string] &default = {  } &optional)

The controller sends this to every agent to request a dispatch (the execution of a pre-implemented activity) to all cluster nodes. This is the generic controller-agent “back-end” implementation of explicit client-controller “front-end” interactions, including:

Parameters
  • reqid – a request identifier string, echoed in the response event.

  • action – the requested dispatch command, with any arguments.

  • nodes – a set of cluster node names (e.g. “worker-01”) to retrieve the values from. An empty set, supplied by default, means retrieval from all nodes managed by the agent.

Management::Agent::API::node_dispatch_response
Type

event (reqid: string, results: Management::ResultVec)

Response to a Management::Agent::API::node_dispatch_request event. Each agent sends this back to the controller to report the dispatch outcomes on all nodes managed by that agent.

Parameters
  • reqid – the request identifier used in the request event.

  • results – a vector of Management::Result records. Each record covers one Zeek cluster node managed by this agent. Upon success, each Management::Result record’s data member contains the dispatches’ response in a data type appropriate for the respective dispatch.

Management::Agent::API::notify_agent_hello
Type

event (instance: string, id: string, connecting: bool, api_version: count)

The agent sends this event upon peering as a “check-in”, informing the controller that an agent of the given name is now available to communicate with. It is a controller-level equivalent of :zeek:see:`Broker::peer_added and triggered by it.

Parameters
  • instance – an instance name, really the agent’s name as per Management::Agent::get_name.

  • id – the Broker ID of the agent.

  • connecting – true if this agent connected to the controller, false if the controller connected to the agent.

  • api_version – the API version of this agent.

Management::Agent::API::notify_change
Type

event (instance: string, n: Management::Node, old: Management::State, new: Management::State)

Management::Agent::API::notify_error
Type

event (instance: string, msg: string, node: string &default = "" &optional)

Management::Agent::API::notify_log
Type

event (instance: string, msg: string, node: string &default = "" &optional)

Management::Agent::API::restart_request
Type

event (reqid: string, nodes: set [string] &default = {  } &optional)

The controller sends this event to ask the agent to restart currently running Zeek cluster nodes. For nodes currently running, the agent places these nodes into PENDING state and sends restart events to the Supervisor, rendering its responses into a list of Management::Result records summarizing each node restart. When restarted nodes check in with the agent, they switch back to RUNNING state. The agent ignores nodes not currently running.

Parameters
  • reqid – a request identifier string, echoed in the response event.

  • nodes – a set of cluster node names (e.g. “worker-01”) to restart. An empty set, supplied by default, means restart of all of the agent’s current cluster nodes.

Management::Agent::API::restart_response
Type

event (reqid: string, results: Management::ResultVec)

Response to a Management::Agent::API::restart_request event. The agent sends this back to the controller when the Supervisor has restarted all nodes affected, or a timeout occurs.

Parameters
  • reqid – the request identifier used in the request event.

  • results – a vector of Management::Result, one for each Supervisor transaction. Each such result identifies both the instance and node.