Bolt *Background*
When told to run a task on some nodes, a PE master typically contacts the nodes over the PCP protocol. It sends a formatted request over PCP to the pxp - agent service running on the nodes, directing them to run the task locally. But if the nodes don't have a pxp-agent service running, the PE master must contact them via SSH or WinRM instead. For these cases, the PE master runs a "pe-bolt- server needs " service, which is a sinatra application that waits for post requests to /ssh/run_task or /winrm/run_task, then runs the task via an instance of the bolt executor, just like bolt does when you run a task via the CLI. Basically, it's a thin REST API wrapper around normal bolt "task run" operations that the PE master can use when there's no PXP agent to talk to over PCP.
In PE Kearney, "task run" is the only supported action over PCP, so it follows that the only endpoints in the bolt-server REST API are for "task run". For other typical bolt actions ("command run", "file upload", "script run"), PCP operations are handled by wrapping any non-task action in an ephemeral task in order to use the "task run" endpoints.
PCP-868 and ORCH-2321 describe process of enabling "wait until available" without a task wrapper over PCP on the agent and server. This ticket describes the new endpoint on bolt-server that will support "wait until available" when there is no PCP transport available.
**NOTE** the implementation of [ connection checks for wait until available is different from other bolt actions! Due to the nature of wait_until_available the bolt-server endpoint will *_not_* perform the same operation as an actual "wait_until_available" call. The differences are as follows:
# Orchestrator will be performing the actual process of 'waiting' for nodes to be connected, so the endpoint in bolt-server *_should not wait_*. The bolt-server endpoint should check for the status of all node connections and then return immediately.
# Node checks from the orchestrator are performed in batches, not one target at a time. The schema and implementation for checking connections in bolt server should expect an array of nodes to check.
*Requirements*
Changes will be made to the [bolt server app |https:// puppet github .com/ docs puppetlabs /bolt/ latest tree / plan_functions master/lib/bolt_server]:
* The app follows the [json schema specification|https://json-schema . org/specification. html #wait-until-available ] . Add a description of the JSON schema for orchestrator data passed to use when the SSH or WinRM transports are used new endpoints [here|https://github.com/puppetlabs/bolt/tree/master/lib/bolt_server/schemas]. This schema should match the one defined for nodes not the "check connected to nodes" action in PCP -868 .
As an example, Implementation of the run_task endpoint is available * Add new POST endpoints in the [ transport sinatra app [here |https://github.com/puppetlabs/bolt/blob/master/lib/bolt_server/transport_app.rb] file in bolt. We will likely need to extrapolate what run_task is doing in that file support checking node connections via SSH and extend it to include wait_for_available WinRM, using the new JSON schema .
It appears * Document the schema creation for each API endpoint is included new endpoints in JSON files in a the [ schema directory in bolt developer-docs |https://github.com/puppetlabs/bolt/ tree blob /master/ lib developer-docs / bolt_server/schemas ].
The scope of this ticket _does not include_ actually plugging the new bolt-server endpoint in to orchestrator, that should be done seperately in ORCH-2322.
* in scope Testing *
Any required code
* Write RSpec tests for the changes to bolt to implement a wait_until_available endpoint in [here|https://github.com/puppetlabs/bolt/tree/master/spec/bolt_server].
* Acceptance/integration tests on the transport app orchestrator side exist for this code [here|https://github.com/puppetlabs/ orchestrator to use /blob/lovejoy/test/puppetlabs/orchestrator/integration/bolt_server .
clj], but updating them is *out of scope*
for this ticket. *Do* run a quick manual test that the API endpoints work as expected on a running PE master, but making changes to orchestrator itself to make use of the endpoints should be done as part of an ORCH ticket . |
|
|
