api.zeek

Management::Controller::API

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

Namespace: Management::Controller::API
Imports: policy/frameworks/management/types.zeek

Summary

Constants

Management::Controller::API::version: count

A simple versioning scheme, used to track basic compatibility of controller, agents, and the client.

Events

`Management::Controller::API::deploy_request`: `event`	Trigger deployment of a previously staged configuration.
`Management::Controller::API::deploy_response`: `event`	Response to a `Management::Controller::API::deploy_request` event.
`Management::Controller::API::get_configuration_request`: `event`	The client sends this event to retrieve the controller’s current cluster configuration(s).
`Management::Controller::API::get_configuration_response`: `event`	Response to a `Management::Controller::API::get_configuration_request` event.
`Management::Controller::API::get_id_value_request`: `event`	The client sends this event to retrieve the current value of a variable in Zeek’s global namespace, referenced by the given identifier (i.e., variable name).
`Management::Controller::API::get_id_value_response`: `event`	Response to a `Management::Controller::API::get_id_value_request` event.
`Management::Controller::API::get_instances_request`: `event`	The client sends this event to request a list of the currently peered agents/instances.
`Management::Controller::API::get_instances_response`: `event`	Response to a `Management::Controller::API::get_instances_request` event.
`Management::Controller::API::get_nodes_request`: `event`	The client sends this event to request a list of `Management::NodeStatus` records that capture the status of Supervisor-managed nodes running on the cluster’s instances.
`Management::Controller::API::get_nodes_response`: `event`	Response to a `Management::Controller::API::get_nodes_request` event.
`Management::Controller::API::notify_agents_ready`: `event`	The controller triggers this event when the operational cluster instances align with the ones desired by the cluster configuration.
`Management::Controller::API::restart_request`: `event`	The client sends this event to restart currently running Zeek cluster nodes.
`Management::Controller::API::restart_response`: `event`	Response to a `Management::Controller::API::restart_request` event.
`Management::Controller::API::stage_configuration_request`: `event`	Upload a configuration to the controller for later deployment.
`Management::Controller::API::stage_configuration_response`: `event`	Response to a `Management::Controller::API::stage_configuration_request` event.
`Management::Controller::API::test_timeout_request`: `event`	This event causes no further action (other than getting logged) if with_state is F.
`Management::Controller::API::test_timeout_response`: `event`	Response to a `Management::Controller::API::test_timeout_request` event.

Detailed Interface

Constants

Management::Controller::API::version 

Type: count
Default: 1

A simple versioning scheme, used to track basic compatibility of controller, agents, and the client.

Events

Management::Controller::API::deploy_request 

Type: event (reqid: string)

Trigger deployment of a previously staged configuration. The client sends this event to the controller, which deploys the configuration to the agents. Agents then terminate any previously running cluster nodes and (re-)launch those defined in the new configuration. Once each agent has responded (or a timeout occurs), the controller sends a response event back to the client, aggregating the results from the agents. The controller keeps the staged configuration available for download, or re-deployment. In addition, the deployed configuration becomes available for download as well, with any augmentations (e.g. node ports filled in by auto-assignment) reflected.

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

Management::Controller::API::deploy_response 

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

Response to a Management::Controller::API::deploy_request event. The controller sends this back to the client, conveying the outcome of the deployment.

Parameters

reqid – the request identifier used in the request event.
results – a vector of Management::Result records. Each member captures the result of launching one cluster node captured in the configuration, or an agent-wide error when the result does not indicate a particular node.

Management::Controller::API::get_configuration_request 

Type: event (reqid: string, deployed: bool)

The client sends this event to retrieve the controller’s current cluster configuration(s).

Parameters

reqid – a request identifier string, echoed in the response event.
deployed – when true, returns the deployed configuration (if any), otherwise the staged one (if any).

Management::Controller::API::get_configuration_response 

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

Response to a Management::Controller::API::get_configuration_request event. The controller sends this back to the client, with the requested configuration.

Parameters

reqid – the request identifier used in the request event.
result – a Management::Result record with a successful Management::Configuration in the data member, if a configuration is currently deployed. Otherwise, a Result record in error state, with no data value assigned.

Management::Controller::API::get_id_value_request 

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

The client sends this event to retrieve the current value of a variable in Zeek’s global namespace, referenced by the given identifier (i.e., variable name). The controller asks all agents to retrieve this value from each cluster node, accumulates the returned responses, and responds with a get_id_value_response event back to the client.

Parameters

reqid – a request identifier string, echoed in the response event.
id – the name of the variable whose value to retrieve.
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 current cluster nodes.

Management::Controller::API::get_id_value_response 

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

Response to a Management::Controller::API::get_id_value_request event. The controller sends this back to the client, with a JSON representation of the requested global ID on all relevant instances.

Parameters

reqid – the request identifier used in the request event.
results – a vector of Management::Result records. Each record covers one Zeek cluster node. Each record’s data field contains a string with the JSON rendering (as produced by to_json, including the error strings it potentially returns).

Management::Controller::API::get_instances_request 

Type: event (reqid: string)

The client sends this event to request a list of the currently peered agents/instances.

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

Management::Controller::API::get_instances_response 

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

Response to a Management::Controller::API::get_instances_request event. The controller sends this back to the client.

Parameters

reqid – the request identifier used in the request event.
result – a Management::Result. Its data member is a vector of Management::Instance records.

Management::Controller::API::get_nodes_request 

Type: event (reqid: string)

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

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

Management::Controller::API::get_nodes_response 

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

Response to a Management::Controller::API::get_nodes_request event. The controller sends this back to the client, with a description of the nodes currently managed by the Supervisors on all connected instances. This includes agents and possibly the controller, if it runs jointly with an agent.

Parameters

reqid – the request identifier used in the request event.
results – a vector of Management::Result records. Each record covers one cluster instance. Each record’s data member is a vector of Management::NodeStatus records, covering the nodes at that instance. Results may also indicate failure, with error messages indicating what went wrong.

Management::Controller::API::notify_agents_ready 

Type: event (instances: set [string])

The controller triggers this event when the operational cluster instances align with the ones desired by the cluster configuration. It’s essentially a cluster management readiness event. This event is currently only used internally by the controller, and not published to topics.

Parameters: instances – the set of instance names now ready.

Management::Controller::API::restart_request 

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

The client sends this event to restart currently running Zeek cluster nodes. The controller relays the request to its agents, which respond with a list of Management::Result records summarizing each node restart. The controller combines these lists, and sends a Management::Controller::API::restart_response event with the result.

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 current cluster nodes.

Management::Controller::API::restart_response 

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

Response to a Management::Controller::API::restart_request event. The controller sends this back to the client when it has received responses from all agents involved, or a timeout occurs.

Parameters

reqid – the request identifier used in the request event.
results – a vector of Management::Result, combining the restart results from all agents. Each such result identifies both the instance and node in question. Results that do not identify an instance are generated by the controller, flagging corner cases, including absence of a deployed cluster or unknown nodes.

Management::Controller::API::stage_configuration_request 

Type: event (reqid: string, config: Management::Configuration)

Upload a configuration to the controller for later deployment. The client sends this event to the controller, which validates the configuration and indicates the outcome in its response event. No deployment takes place yet, and existing deployed configurations and the running Zeek cluster remain intact. To trigger deployment of an uploaded configuration, use Management::Controller::API::deploy_request.

Parameters

reqid – a request identifier string, echoed in the response event.
config – a Management::Configuration record specifying the cluster configuration.

Management::Controller::API::stage_configuration_response 

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

Response to a Management::Controller::API::stage_configuration_request event. The controller sends this back to the client, conveying validation results.

Parameters

reqid – the request identifier used in the request event.
results – a Management::Result vector, indicating whether the controller accepts the configuration. In case of a success, a single result record indicates so. Otherwise, the sequence is all errors, each indicating a configuration validation error.

Management::Controller::API::test_timeout_request 

Type: event (reqid: string, with_state: bool)

This event causes no further action (other than getting logged) if with_state is F. When T, the controller establishes request state, and the controller only ever sends the response event when this state times out.

Parameters

reqid – a request identifier string, echoed in the response event when with_state is T.
with_state – flag indicating whether the controller should keep (and time out) request state for this request.

Management::Controller::API::test_timeout_response 

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

Response to a Management::Controller::API::test_timeout_request event. The controller sends this back to the client if the original request had the with_state flag.

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