From e7a5734399de0354dbc8295a829b6217104f9faa Mon Sep 17 00:00:00 2001 From: Charlie Jones Date: Fri, 13 Sep 2024 08:42:42 -0500 Subject: [PATCH 1/2] Add documentation --- README.md | 75 ++++++++++------------- docs/executioners/log_executioner.md | 41 +++++++++++++ docs/executioners/shell_executioner.md | 42 +++++++++++++ docs/watchers/gce_metadata_watcher.md | 83 ++++++++++++++++++++++++++ docs/watchers/time_watcher.md | 33 ++++++++++ 5 files changed, 232 insertions(+), 42 deletions(-) create mode 100644 docs/executioners/log_executioner.md create mode 100644 docs/executioners/shell_executioner.md create mode 100644 docs/watchers/gce_metadata_watcher.md create mode 100644 docs/watchers/time_watcher.md diff --git a/README.md b/README.md index 06854c6..bb8e666 100644 --- a/README.md +++ b/README.md @@ -5,58 +5,49 @@ when a change is detected. In some ways it is similar to consul-template, except Goverseer does not handle templating. Instead it is focused on watching for changes and taking some kind of action based on those changes. -## Supported Watchers & Executioners +## Usage + +Goverseer is configured using a yaml config file. The `goverseer start` command +takes a path to the config file. If a config path is not provided, +`/etc/goverseer.yaml` will be used. + +```yaml +# Example goverseer config +--- +name: example + +watcher: + type: time + config: + poll_seconds: 1 + +executioner: + type: log + config: + tag: example +``` + +The available values for `watcher.type` are: -Overseer currently supports: +- `gce_metadata`: [GCE Metadata Watcher](docs/watchers/gce_metadata_watcher.md) +- `time`: [Time Watcher](docs/watchers/time_watcher.md) -* Time Watcher -* Log Executioner +The available values for `executioner.type` are: -Planned future support includes: +- `log`: [Log Executioner](docs/executioners/log_executioner.md) +- `shell`: [Shell Executioner](docs/executioners/shell_executioner.md) -* GCE Metadata Watcher -* Consul Watcher -* Command Executioner +The configuration options for `watcher.config` and `executioner.config` are +determined by the selected type. See the documentation for the specific watcher +and executioner type for more details on available configuration options. ## Building -To build Goverseer, simply run `make build`. Once complete, you -should see a binary in the root of your checkout. +To build Goverseer, simply run `make build`. Once complete, you should see a +binary in the root of your checkout. ## Development To run locally during development, run `go run ./cmd/goverseer --help`. To run all tests, run `make test`. - -### Accessing GCE Metadata Locally - -It can be useful to test your code locally while listening to an actual GCE -Metadata endpoint. You can achieve this by creating a tunnel to a GCE instance -using `gcloud ssh`. - -The snippet below creates a tunnel to your local machine on port 8888 from your -instance on port 80: - -```bash -INSTANCE_NAME=my-instance-name -PROJECT=sbx-your-sandbox -ZONE=us-central1-a -gcloud compute ssh "${INSTANCE_NAME}" \ - --project="${PROJECT}" \ - --zone="${ZONE}" \ - --internal-ip -- \ - -L 8888:metadata.google.internal:80 -``` - -You can then make metadata changes on the instance to test goverseer: - -```bash -INSTANCE_NAME=my-instance-name -PROJECT=sbx-your-sandbox -ZONE=us-central1-a -gcloud compute instances add-metadata "${INSTANCE_NAME}" \ - --project="${PROJECT}" \ - --zone="${ZONE}" \ - --metadata foo=bar -``` diff --git a/docs/executioners/log_executioner.md b/docs/executioners/log_executioner.md new file mode 100644 index 0000000..e38c0e0 --- /dev/null +++ b/docs/executioners/log_executioner.md @@ -0,0 +1,41 @@ +# Log Executioner + +The Log Executioner provides a simple way to log messages when Goverseer detects +a change. This is useful for debugging and monitoring purposes, allowing you to +track changes and their associated actions. + +## Configuration + +To use the Log Executioner, configure it in your Goverseer config file. The +following configuration option is available: + +- `tag`: (Optional) This allows you to specify a custom tag that will be added + to the log message. This can be helpful for filtering and searching logs. + Defaults to no tag. + +**Example Configuration:** + +```yaml +executioner: + log: + tag: my-application +``` + +With this configuration, every time the watcher detects a change, the log +executioner will output a message like: + +```log +Sep 12 16:12:58.095 INF received data data= +``` + +**Note:** + +- The Log Executioner simply logs the change detected by the watcher; it does + not perform any other actions. +- For more complex actions, consider using the `shell_executioner` or creating a + custom executioner. + +This executioner is particularly useful during development and testing, allowing +you to quickly verify that Goverseer is functioning as expected and that changes +are being detected. It can also be helpful for debugging issues and +understanding the behavior of your application in response to changes. diff --git a/docs/executioners/shell_executioner.md b/docs/executioners/shell_executioner.md new file mode 100644 index 0000000..6de086d --- /dev/null +++ b/docs/executioners/shell_executioner.md @@ -0,0 +1,42 @@ +# Shell Executioner + +The Shell Executioner allows you to execute arbitrary shell commands when +Goverseer detects a change. This is useful for triggering actions like +restarting services, sending notifications, or running custom scripts. The data +from the watcher that triggered the execution is stored in a file in the +executioner's work directory. The path to this data file is passed to the shell +command via an environment variable named `GOVERSEER_DATA`. + +## Configuration + +To use the Shell Executioner, you need to configure it in your Goverseer config +file. The following configuration options are available: + +- `command`: This is the shell command you want to execute.For example, + `echo "Data received: $GOVERSEER_DATA"`. +- `shell`: (Optional) This specifies the shell to use for executing the command. + Defaults to `/bin/sh` if not provided. + +**Example Configuration:** + +```yaml +name: shell_executioner_example +watcher: + time: + poll_seconds: 60 +executioner: + shell: + command: echo "Data received: $GOVERSEER_DATA" + shell: /bin/bash +``` + +**Note:** + +- Ensure that the specified shell is available on your system. +- The Shell Executioner writes the `GOVERSEER_DATA` content to a temporary file + and sets the `GOVERSEER_DATA` environment variable to the path of this file. + +This executioner is particularly useful for automating tasks that require shell +command execution based on dynamic data changes. For example, you can use it to +restart a service whenever a configuration file is updated, or to send +notifications when specific events occur. diff --git a/docs/watchers/gce_metadata_watcher.md b/docs/watchers/gce_metadata_watcher.md new file mode 100644 index 0000000..ad3042c --- /dev/null +++ b/docs/watchers/gce_metadata_watcher.md @@ -0,0 +1,83 @@ +# GCE Metadata Watcher + +The GCE Metadata Watcher allows you to monitor a Google Compute Engine (GCE) +metadata key for changes. When a change is detected, Goverseer can trigger an +executioner to take action based on the updated metadata value. The changed data +is passed to the executioner for processing. + +## Configuration + +To use the GCE Metadata Watcher, you need to configure it in your Goverseer +config file. The following configuration options are available: + +- `source`: (Optional) This is the source of the metadata value you want to + monitor. It must be set to either `instance` or `project`. Defaults to + `instance` if not provided. +- `key`: This is the GCE metadata key you want to monitor. For example, + `instance/attributes/my-key`. +- `recursive`: (Optional) This determines whether to fetch metadata recursively. + If set to `true`, all subkeys under the specified key will be monitored. + Defaults to `false`. +- `metadata_url`: (Optional) This allows overriding the default GCE Metadata + server URL. Useful for testing with a local server. Defaults to + `http://metadata.google.internal/computeMetadata/v1`. +- `metadata_error_wait_seconds`: (Optional) This determines the wait time in + seconds before retrying after a metadata fetch error. Defaults to `10`. + +**Example Configuration:** + +```yaml +name: gce_metadata_watcher_example +watcher: + gce_metadata: + key: instance/attributes/my-key + recursive: true +executioner: + log: +``` + +**Note:** + +- The GCE Metadata Watcher relies on the GCE Metadata server, which is only + accessible from within a GCE instance. +- Ensure that your GCE instance has the necessary permissions to access the + metadata server and the specified key. + +This watcher is particularly useful for dynamically updating your application's +configuration based on changes made to instance metadata. For example, you can +use it to trigger a restart or reload when a new version is deployed, or to +adjust application behavior based on metadata flags. + +## Development + +### Accessing GCE Metadata Locally + +It can be useful to test your code locally while listening to an actual GCE +Metadata endpoint. You can achieve this by creating a tunnel to a GCE instance +using `gcloud ssh`. + +The snippet below creates a tunnel to your local machine on port 8888 from your +instance on port 80: + +```bash +INSTANCE_NAME=my-instance-name +PROJECT=sbx-your-sandbox +ZONE=us-central1-a +gcloud compute ssh "${INSTANCE_NAME}" \ + --project="${PROJECT}" \ + --zone="${ZONE}" \ + --internal-ip -- \ + -L 8888:metadata.google.internal:80 +``` + +You can then make metadata changes on the instance to test goverseer: + +```bash +INSTANCE_NAME=my-instance-name +PROJECT=sbx-your-sandbox +ZONE=us-central1-a +gcloud compute instances add-metadata "${INSTANCE_NAME}" \ + --project="${PROJECT}" \ + --zone="${ZONE}" \ + --metadata foo=bar +``` diff --git a/docs/watchers/time_watcher.md b/docs/watchers/time_watcher.md new file mode 100644 index 0000000..5ac472f --- /dev/null +++ b/docs/watchers/time_watcher.md @@ -0,0 +1,33 @@ +# Time Watcher + +The Time Watcher allows you to trigger at regular intervals. This is mostly +useful for testing and debugging. + +## Configuration + +To use the Time Watcher, configure it in your Goverseer config file. The +following configuration option is available: + +- `poll_seconds`: This specifies the interval, in seconds, at which the watcher + will trigger the executioner. + +**Example Configuration:** + +```yaml +watcher: + time: + poll_seconds: 60 +executioner: + log: +``` + +This configuration would trigger the executioner every 60 seconds. + +**Note:** + +- The Time Watcher will trigger the executioner regardless of whether any + changes have occurred in the system. +- Consider the resource consumption of your executioner when choosing a polling + interval, as frequent executions can impact performance. + +This watcher is ideal for testing. From b196fc4ef921f78e02a6cdfbcc38cdba4ee6f4e7 Mon Sep 17 00:00:00 2001 From: Charlie Jones Date: Fri, 13 Sep 2024 08:45:47 -0500 Subject: [PATCH 2/2] Update config examples --- docs/executioners/log_executioner.md | 3 ++- docs/executioners/shell_executioner.md | 6 ++++-- docs/watchers/gce_metadata_watcher.md | 5 +++-- docs/watchers/time_watcher.md | 5 +++-- 4 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/executioners/log_executioner.md b/docs/executioners/log_executioner.md index e38c0e0..9266101 100644 --- a/docs/executioners/log_executioner.md +++ b/docs/executioners/log_executioner.md @@ -17,7 +17,8 @@ following configuration option is available: ```yaml executioner: - log: + type: log + config: tag: my-application ``` diff --git a/docs/executioners/shell_executioner.md b/docs/executioners/shell_executioner.md index 6de086d..c96dd5f 100644 --- a/docs/executioners/shell_executioner.md +++ b/docs/executioners/shell_executioner.md @@ -22,10 +22,12 @@ file. The following configuration options are available: ```yaml name: shell_executioner_example watcher: - time: + type: time + config: poll_seconds: 60 executioner: - shell: + type: shell + config: command: echo "Data received: $GOVERSEER_DATA" shell: /bin/bash ``` diff --git a/docs/watchers/gce_metadata_watcher.md b/docs/watchers/gce_metadata_watcher.md index ad3042c..c17cd64 100644 --- a/docs/watchers/gce_metadata_watcher.md +++ b/docs/watchers/gce_metadata_watcher.md @@ -29,11 +29,12 @@ config file. The following configuration options are available: ```yaml name: gce_metadata_watcher_example watcher: - gce_metadata: + type: gce_metadata + config: key: instance/attributes/my-key recursive: true executioner: - log: + type: log ``` **Note:** diff --git a/docs/watchers/time_watcher.md b/docs/watchers/time_watcher.md index 5ac472f..234bce0 100644 --- a/docs/watchers/time_watcher.md +++ b/docs/watchers/time_watcher.md @@ -15,10 +15,11 @@ following configuration option is available: ```yaml watcher: - time: + type: time + config: poll_seconds: 60 executioner: - log: + type: log ``` This configuration would trigger the executioner every 60 seconds.