From 5361eb4ac6fd4a82c8c0d42a28b58bee48be3ff9 Mon Sep 17 00:00:00 2001 From: Lamont Granquist Date: Thu, 7 Mar 2019 17:26:16 -0800 Subject: document configuration Signed-off-by: Lamont Granquist --- docs/dev/data_collector.md | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/docs/dev/data_collector.md b/docs/dev/data_collector.md index 73eba91826..0ac229a5fc 100644 --- a/docs/dev/data_collector.md +++ b/docs/dev/data_collector.md @@ -27,6 +27,43 @@ The Data Collector also collects: Most of this is done through hooking events directly in the Data Collector itself. The ErrorHandlers module is broken out into a module which is directly mixed into the Data Collector to separate that concern out into a different file (it is straightforwards with fairly little state, but is just a lot of hooked methods). +## Basic Configuration Modes + +### Configured for Automate + +Do nothing. The URL is constructed from the base `Chef::Config[:chef_server_url]`, auth is just Chef Server API authentication, and the default behavior is that it +is configured. + +### Configured to Log to a File + +Setup a file output location, no token is necessary: + +``` +Chef::Config[:data_collector][:output_locations] = { files: [ "/Users/lamont/data_collector.out" ] } +``` + +Note the fact that you can't assign to `Chef::Config[:data_collector][:output_locations][:files]` and will NoMethodError if you try. + +### Configured to Log to a Non-Chef Server Endpoint + +Setup a server url, requiring a token: + +``` +Chef::Config[:data_collector][:server_url] = "https://chef.acme.local/myendpoint.html" +Chef::Config[:data_collector][:token] = "mytoken" +``` + +This works for chef-clients which are configured to hit a chef server, but use a custom non-Chef-Automate endpoint for reporting, or for chef-solo/zero users. + +XXX: There is also the `Chef::Config[:data_collector][:output_locations] = { uri: [ "https://chef.acme.local/myendpoint.html" ] }` method -- which is going to behave +differently, particularly on non-chef-solo use cases. In that case the data collector `server_url` will still be automatically derived from the `chef_server_url` and +the data collector will attempt to contact that endpoint, but with the token being supplied it will use that and will not use Chef Server authentication, and the +server should 403 back, and if `raise_on_failure` is left to the default of false then it will simply drop that failure and continue without raising, which will +appear to work, and output will be send to the configured `output_locations`. But given how hopelessly complicated this is, the recommendation is to use the +`server_url` and to avoid using any `url` options in the `output_locations` since that feature is fairly poorly designed at this point in time. Note that the presence of +a token flips all external URIs to using the token so that it is not possible to use this feature to talk to both a Chef Automate endpoint and a custom URI reporting +endpoint (which would seem to be the most useful of an incredibly marginally useful feature and it does not work). + ## Resiliency to Failures The Data Collector in Chef >= 15.0 is resilient to failures that occur anywhere in the main loop of the `Chef::Client#run` method. In order to do this there is a lot @@ -70,8 +107,11 @@ As it happens in the actual chef-client run: * failures during cookbook resolution will cause `events.cookbook_resolution_failed(node, exception)` here and skip to #13 * failures during cookbook synch will cause `events.cookbook_sync_failed(node, exception)` and skip to #13 10. `events.cookbook_compilation_start(run_context)` -11. < the resource events happen here which hit the action collection > +11. < the resource events happen here which hit the action collection, may throw any of the other failure events > 12. `events.converge_complete` or `events.converge_failed(exception)` 13. `run_status.stop_clock` 14. `run_status.exception = exception` if it failed 15. `events.run_completed(node, run_status)` or `events.run_failed(exception, run_status)` + + + -- cgit v1.2.1