:tocdepth: 3

policy/frameworks/management/controller/api.zeek
================================================
.. zeek:namespace:: 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: :doc:`policy/frameworks/management/types.zeek </scripts/policy/frameworks/management/types.zeek>`

Summary
~~~~~~~
Constants
#########
=================================================================== ================================================================
:zeek:id:`Management::Controller::API::version`: :zeek:type:`count` A simple versioning scheme, used to track basic compatibility of
                                                                    controller, agents, and the client.
=================================================================== ================================================================

Events
######
======================================================================================== ======================================================================
:zeek:id:`Management::Controller::API::deploy_request`: :zeek:type:`event`               Trigger deployment of a previously staged configuration.
:zeek:id:`Management::Controller::API::deploy_response`: :zeek:type:`event`              Response to a :zeek:see:`Management::Controller::API::deploy_request`
                                                                                         event.
:zeek:id:`Management::Controller::API::get_configuration_request`: :zeek:type:`event`    The client sends this event to retrieve the controller's current
                                                                                         cluster configuration(s).
:zeek:id:`Management::Controller::API::get_configuration_response`: :zeek:type:`event`   Response to a
                                                                                         :zeek:see:`Management::Controller::API::get_configuration_request`
                                                                                         event.
:zeek:id:`Management::Controller::API::get_id_value_request`: :zeek:type:`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).
:zeek:id:`Management::Controller::API::get_id_value_response`: :zeek:type:`event`        Response to a
                                                                                         :zeek:see:`Management::Controller::API::get_id_value_request`
                                                                                         event.
:zeek:id:`Management::Controller::API::get_instances_request`: :zeek:type:`event`        The client sends this event to request a list of the currently
                                                                                         peered agents/instances.
:zeek:id:`Management::Controller::API::get_instances_response`: :zeek:type:`event`       Response to a
                                                                                         :zeek:see:`Management::Controller::API::get_instances_request`
                                                                                         event.
:zeek:id:`Management::Controller::API::get_nodes_request`: :zeek:type:`event`            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.
:zeek:id:`Management::Controller::API::get_nodes_response`: :zeek:type:`event`           Response to a
                                                                                         :zeek:see:`Management::Controller::API::get_nodes_request` event.
:zeek:id:`Management::Controller::API::notify_agents_ready`: :zeek:type:`event`          The controller triggers this event when the operational cluster
                                                                                         instances align with the ones desired by the cluster
                                                                                         configuration.
:zeek:id:`Management::Controller::API::restart_request`: :zeek:type:`event`              The client sends this event to restart currently running Zeek cluster
                                                                                         nodes.
:zeek:id:`Management::Controller::API::restart_response`: :zeek:type:`event`             Response to a :zeek:see:`Management::Controller::API::restart_request`
                                                                                         event.
:zeek:id:`Management::Controller::API::stage_configuration_request`: :zeek:type:`event`  Upload a configuration to the controller for later deployment.
:zeek:id:`Management::Controller::API::stage_configuration_response`: :zeek:type:`event` Response to a
                                                                                         :zeek:see:`Management::Controller::API::stage_configuration_request`
                                                                                         event.
:zeek:id:`Management::Controller::API::test_timeout_request`: :zeek:type:`event`         This event causes no further action (other than getting logged) if
                                                                                         with_state is F.
:zeek:id:`Management::Controller::API::test_timeout_response`: :zeek:type:`event`        Response to a
                                                                                         :zeek:see:`Management::Controller::API::test_timeout_request`
                                                                                         event.
======================================================================================== ======================================================================


Detailed Interface
~~~~~~~~~~~~~~~~~~
Constants
#########
.. zeek:id:: Management::Controller::API::version
   :source-code: policy/frameworks/management/controller/api.zeek 13 13

   :Type: :zeek:type:`count`
   :Default: ``1``

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

Events
######
.. zeek:id:: Management::Controller::API::deploy_request
   :source-code: policy/frameworks/management/controller/main.zeek 1088 1128

   :Type: :zeek:type:`event` (reqid: :zeek:type:`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.


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


.. zeek:id:: Management::Controller::API::deploy_response
   :source-code: policy/frameworks/management/controller/api.zeek 119 119

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)

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


   :param reqid: the request identifier used in the request event.


   :param results: 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.


.. zeek:id:: Management::Controller::API::get_configuration_request
   :source-code: policy/frameworks/management/controller/main.zeek 1063 1086

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, deployed: :zeek:type:`bool`)

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


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


   :param deployed: when true, returns the deployed configuration (if any),
       otherwise the staged one (if any).


.. zeek:id:: Management::Controller::API::get_configuration_response
   :source-code: policy/frameworks/management/controller/api.zeek 89 89

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, result: :zeek:type:`Management::Result`)

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


   :param reqid: the request identifier used in the request event.


   :param 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.


.. zeek:id:: Management::Controller::API::get_id_value_request
   :source-code: policy/frameworks/management/controller/main.zeek 1297 1374

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, id: :zeek:type:`string`, nodes: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&default` = ``{  }`` :zeek:attr:`&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.


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


   :param id: the name of the variable whose value to retrieve.


   :param 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.


.. zeek:id:: Management::Controller::API::get_id_value_response
   :source-code: policy/frameworks/management/controller/api.zeek 182 182

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)

   Response to a
   :zeek:see:`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.


   :param reqid: the request identifier used in the request event.


   :param results: 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).


.. zeek:id:: Management::Controller::API::get_instances_request
   :source-code: policy/frameworks/management/controller/main.zeek 1130 1151

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`)

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


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


.. zeek:id:: Management::Controller::API::get_instances_response
   :source-code: policy/frameworks/management/controller/api.zeek 32 32

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, result: :zeek:type:`Management::Result`)

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


   :param reqid: the request identifier used in the request event.


   :param result: a :zeek:see:`Management::Result`. Its data member is a vector
       of :zeek:see:`Management::Instance` records.


.. zeek:id:: Management::Controller::API::get_nodes_request
   :source-code: policy/frameworks/management/controller/main.zeek 1199 1228

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`)

   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.


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


.. zeek:id:: Management::Controller::API::get_nodes_response
   :source-code: policy/frameworks/management/controller/api.zeek 147 147

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)

   Response to a
   :zeek:see:`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.


   :param reqid: the request identifier used in the request event.


   :param results: 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.


.. zeek:id:: Management::Controller::API::notify_agents_ready
   :source-code: policy/frameworks/management/controller/main.zeek 801 833

   :Type: :zeek:type:`event` (instances: :zeek:type:`set` [:zeek:type:`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.


   :param instances: the set of instance names now ready.


.. zeek:id:: Management::Controller::API::restart_request
   :source-code: policy/frameworks/management/controller/main.zeek 1416 1509

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, nodes: :zeek:type:`set` [:zeek:type:`string`] :zeek:attr:`&default` = ``{  }`` :zeek:attr:`&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 :zeek:see:`Management::Result` records summarizing
   each node restart. The controller combines these lists, and sends a
   :zeek:see:`Management::Controller::API::restart_response` event with
   the result.


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


   :param 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.


.. zeek:id:: Management::Controller::API::restart_response
   :source-code: policy/frameworks/management/controller/api.zeek 213 213

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)

   Response to a :zeek:see:`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.


   :param reqid: the request identifier used in the request event.


   :param results: a :zeek:type:`vector` of :zeek:see:`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.


.. zeek:id:: Management::Controller::API::stage_configuration_request
   :source-code: policy/frameworks/management/controller/main.zeek 1002 1061

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, config: :zeek:type:`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 :zeek:see:`Management::Controller::API::deploy_request`.


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


   :param config: a :zeek:see:`Management::Configuration` record
       specifying the cluster configuration.


.. zeek:id:: Management::Controller::API::stage_configuration_response
   :source-code: policy/frameworks/management/controller/api.zeek 63 63

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, results: :zeek:type:`Management::ResultVec`)

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


   :param reqid: the request identifier used in the request event.


   :param results: 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.


.. zeek:id:: Management::Controller::API::test_timeout_request
   :source-code: policy/frameworks/management/controller/main.zeek 1588 1599

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, with_state: :zeek:type:`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.


   :param reqid: a request identifier string, echoed in the response event when
       with_state is T.


   :param with_state: flag indicating whether the controller should keep (and
       time out) request state for this request.


.. zeek:id:: Management::Controller::API::test_timeout_response
   :source-code: policy/frameworks/management/controller/api.zeek 238 238

   :Type: :zeek:type:`event` (reqid: :zeek:type:`string`, result: :zeek:type:`Management::Result`)

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


   :param reqid: the request identifier used in the request event.



