mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 06:38:20 +00:00
77556e9f11
This separates uploading a configuration from deploying it to the instances into separate event transactions. set_configuration_request/response remains, but now only conducts validation and storage of the new configuration (upon validation success, and not yet persisted to disk). The response event indicates success or the list of validation errors. Successful upload now returns the configuration's ID in the result record's data struct. The new deploy_request/response event takes a previously uploaded configuration and deploys it to the agents. The controller now tracks uploaded and deployed configurations separately. Uploading assigns g_config_staged; deployment assigns g_config_deployed. Deployment does not affect g_config_staged. The get_config_request/response event pair now allows selecting the configuration the caller would like to retrieve.
206 lines
7.9 KiB
Text
206 lines
7.9 KiB
Text
##! 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.
|
|
|
|
@load policy/frameworks/management/types
|
|
|
|
module Management::Controller::API;
|
|
|
|
export {
|
|
## A simple versioning scheme, used to track basic compatibility of
|
|
## controller, agents, and the client.
|
|
const version = 1;
|
|
|
|
|
|
## The client sends this event to request a list of the currently
|
|
## peered agents/instances.
|
|
##
|
|
## reqid: a request identifier string, echoed in the response event.
|
|
##
|
|
global get_instances_request: event(reqid: string);
|
|
|
|
## Response to a get_instances_request event. The controller sends
|
|
## this back to the client.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
## result: the result record. Its data member is a
|
|
## :zeek:see:`Management::Instance` record.
|
|
##
|
|
global get_instances_response: event(reqid: string,
|
|
result: Management::Result);
|
|
|
|
|
|
## The client sends this event to upload a new cluster configuration,
|
|
## including the full cluster topology. The controller validates the
|
|
## configuration and indicates the outcome in its response event. No
|
|
## deployment takes place yet, and existing deployed configurations and
|
|
## clusters remain intact. To trigger deployment of an uploaded
|
|
## configuration, use :zeek:see:`Management::Controller::API::deploy_request`.
|
|
##
|
|
## reqid: a request identifier string, echoed in the response event.
|
|
##
|
|
## config: a :zeek:see:`Management::Configuration` record
|
|
## specifying the cluster configuration.
|
|
##
|
|
global set_configuration_request: event(reqid: string,
|
|
config: Management::Configuration);
|
|
|
|
## Response to a set_configuration_request event. The controller sends
|
|
## this back to the client.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
## result: a :zeek:see:`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.
|
|
##
|
|
global set_configuration_response: event(reqid: string,
|
|
result: Management::ResultVec);
|
|
|
|
|
|
## The client sends this event to retrieve the currently deployed
|
|
## cluster configuration.
|
|
##
|
|
## 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).
|
|
##
|
|
global get_configuration_request: event(reqid: string, deployed: bool);
|
|
|
|
## Response to a get_configuration_request event. The controller sends
|
|
## this back to the client.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
## result: a :zeek:see:`Management::Result` record with a successful
|
|
## :zeek:see:`Management::Configuration` in the data member, if
|
|
## a configuration is currently deployed. Otherwise, a Result
|
|
## record in error state, with no data value assigned.
|
|
##
|
|
global get_configuration_response: event(reqid: string,
|
|
result: Management::Result);
|
|
|
|
|
|
## The client sends this event to trigger deployment of a previously
|
|
## uploaded configuration. The controller deploys the uploaded
|
|
## configuration to all agents involved in running the former
|
|
## configuration or the new one. The agents 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.
|
|
##
|
|
## reqid: a request identifier string, echoed in the response event.
|
|
##
|
|
global deploy_request: event(reqid: string);
|
|
|
|
## Response to a deploy_request event. The controller sends this
|
|
## back to the client.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
## result: a vector of :zeek:see:`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.
|
|
##
|
|
global deploy_response: event(reqid: string,
|
|
result: Management::ResultVec);
|
|
|
|
|
|
## The client sends this event to request a list of
|
|
## :zeek:see:`Management::NodeStatus` records that capture
|
|
## the status of Supervisor-managed nodes running on the cluster's
|
|
## instances.
|
|
##
|
|
## reqid: a request identifier string, echoed in the response event.
|
|
##
|
|
global get_nodes_request: event(reqid: string);
|
|
|
|
## Response to a get_nodes_request event. The controller sends this
|
|
## back to the client.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
## result: a :zeek:type:`vector` of :zeek:see:`Management::Result`
|
|
## records. Each record covers one cluster instance. Each record's data
|
|
## member is a vector of :zeek:see:`Management::NodeStatus`
|
|
## records, covering the nodes at that instance. Results may also indicate
|
|
## failure, with error messages indicating what went wrong.
|
|
##
|
|
global get_nodes_response: event(reqid: string,
|
|
result: Management::ResultVec);
|
|
|
|
|
|
## 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.
|
|
##
|
|
## 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.
|
|
##
|
|
global get_id_value_request: event(reqid: string, id: string,
|
|
nodes: set[string] &default=set());
|
|
|
|
## Response to a get_id_value_request event. The controller sends this
|
|
## back to the client.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
## result: a :zeek:type:`vector` of :zeek:see:`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 :zeek:id:`to_json`, including the error strings it potentially
|
|
## returns).
|
|
##
|
|
global get_id_value_response: event(reqid: string, result: Management::ResultVec);
|
|
|
|
|
|
# Testing events. These don't provide operational value but expose
|
|
# internal functionality, triggered by test cases.
|
|
|
|
## 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.
|
|
##
|
|
## 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.
|
|
##
|
|
global test_timeout_request: event(reqid: string, with_state: bool);
|
|
|
|
## Response to a test_timeout_request event. The controller sends this
|
|
## back to the client if the original request had the with_state flag.
|
|
##
|
|
## reqid: the request identifier used in the request event.
|
|
##
|
|
global test_timeout_response: event(reqid: string,
|
|
result: Management::Result);
|
|
|
|
|
|
# Notification events
|
|
|
|
## 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.
|
|
##
|
|
## instances: the set of instance names now ready.
|
|
##
|
|
global notify_agents_ready: event(instances: set[string]);
|
|
}
|