From 2c1cd1d4016a6ddbc35bc60d3b0d18c67d148892 Mon Sep 17 00:00:00 2001 From: Christian Kreibich Date: Wed, 22 Jun 2022 11:48:11 -0700 Subject: [PATCH] Management framework: rename set_configuration events to stage_configuration This reflects corresponding renaming of the client's set-config command to stage-config, to make it more clear what's happening. --- .../frameworks/management/controller/api.zeek | 35 ++++++++++--------- .../management/controller/main.zeek | 16 ++++----- .../policy/frameworks/management/types.zeek | 8 ++--- 3 files changed, 31 insertions(+), 28 deletions(-) diff --git a/scripts/policy/frameworks/management/controller/api.zeek b/scripts/policy/frameworks/management/controller/api.zeek index 42b870b4e5..9b5de9087c 100644 --- a/scripts/policy/frameworks/management/controller/api.zeek +++ b/scripts/policy/frameworks/management/controller/api.zeek @@ -32,11 +32,11 @@ export { result: Management::Result); - ## The client sends this event to upload a new cluster configuration, - ## including the full cluster topology. The controller validates the + ## 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 - ## clusters remain intact. To trigger deployment of an uploaded + ## the running Zeek cluster 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. @@ -44,11 +44,11 @@ export { ## config: a :zeek:see:`Management::Configuration` record ## specifying the cluster configuration. ## - global set_configuration_request: event(reqid: string, + global stage_configuration_request: event(reqid: string, config: Management::Configuration); - ## Response to a set_configuration_request event. The controller sends - ## this back to the client. + ## Response to a stage_configuration_request event. The controller sends + ## this back to the client, conveying validation results. ## ## reqid: the request identifier used in the request event. ## @@ -57,12 +57,12 @@ export { ## 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, + global stage_configuration_response: event(reqid: string, result: Management::ResultVec); - ## The client sends this event to retrieve the currently deployed - ## cluster configuration. + ## The client sends this event to retrieve the controller's current + ## cluster configuration(s). ## ## reqid: a request identifier string, echoed in the response event. ## @@ -85,13 +85,16 @@ export { 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. + ## 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. ## ## reqid: a request identifier string, echoed in the response event. ## diff --git a/scripts/policy/frameworks/management/controller/main.zeek b/scripts/policy/frameworks/management/controller/main.zeek index ecbdfc4e53..a5c1840b18 100644 --- a/scripts/policy/frameworks/management/controller/main.zeek +++ b/scripts/policy/frameworks/management/controller/main.zeek @@ -866,9 +866,9 @@ event Management::Agent::API::deploy_response(reqid: string, results: Management Management::Request::finish(req$id); } -event Management::Controller::API::set_configuration_request(reqid: string, config: Management::Configuration) +event Management::Controller::API::stage_configuration_request(reqid: string, config: Management::Configuration) { - Management::Log::info(fmt("rx Management::Controller::API::set_configuration_request %s", reqid)); + Management::Log::info(fmt("rx Management::Controller::API::stage_configuration_request %s", reqid)); local req = Management::Request::create(reqid); local res = Management::Result($reqid=req$id); @@ -877,10 +877,10 @@ event Management::Controller::API::set_configuration_request(reqid: string, conf if ( ! config_validate(config, req) ) { Management::Request::finish(req$id); - Management::Log::info(fmt("tx Management::Controller::API::set_configuration_response %s", + Management::Log::info(fmt("tx Management::Controller::API::stage_configuration_response %s", Management::Request::to_string(req))); Broker::publish(Management::Controller::topic, - Management::Controller::API::set_configuration_response, req$id, req$results); + Management::Controller::API::stage_configuration_response, req$id, req$results); return; } @@ -896,10 +896,10 @@ event Management::Controller::API::set_configuration_request(reqid: string, conf res$error = fmt("port auto-assignment disabled but nodes %s lack ports", nodes_str); req$results += res; - Management::Log::info(fmt("tx Management::Controller::API::set_configuration_response %s", + Management::Log::info(fmt("tx Management::Controller::API::stage_configuration_response %s", Management::Request::to_string(req))); Broker::publish(Management::Controller::topic, - Management::Controller::API::set_configuration_response, req$id, req$results); + Management::Controller::API::stage_configuration_response, req$id, req$results); Management::Request::finish(req$id); return; } @@ -918,10 +918,10 @@ event Management::Controller::API::set_configuration_request(reqid: string, conf req$results += res; Management::Log::info(fmt( - "tx Management::Controller::API::set_configuration_response %s", + "tx Management::Controller::API::stage_configuration_response %s", Management::result_to_string(res))); Broker::publish(Management::Controller::topic, - Management::Controller::API::set_configuration_response, reqid, req$results); + Management::Controller::API::stage_configuration_response, reqid, req$results); Management::Request::finish(req$id); } diff --git a/scripts/policy/frameworks/management/types.zeek b/scripts/policy/frameworks/management/types.zeek index f28706a313..796c943754 100644 --- a/scripts/policy/frameworks/management/types.zeek +++ b/scripts/policy/frameworks/management/types.zeek @@ -109,10 +109,10 @@ export { type ResultVec: vector of Result; - ## In :zeek:see:`Management::Controller::API::set_configuration_response`, - ## events, each :zeek:see:`Management::Result` indicates the outcome of a - ## requested cluster node. If a node does not launch properly (meaning - ## it doesn't check in with the agent on thee machine it's running on), + ## In :zeek:see:`Management::Controller::API::deploy_response` events, + ## each :zeek:see:`Management::Result` indicates the outcome of a + ## launched cluster node. If a node does not launch properly (meaning + ## it doesn't check in with the agent on the machine it's running on), ## the result will indicate failure, and its data field will be an ## instance of this record, capturing the stdout and stderr output of ## the failing node.