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..9266101 --- /dev/null +++ b/docs/executioners/log_executioner.md @@ -0,0 +1,42 @@ +# 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: + type: log + config: + 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..c96dd5f --- /dev/null +++ b/docs/executioners/shell_executioner.md @@ -0,0 +1,44 @@ +# 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: + type: time + config: + poll_seconds: 60 +executioner: + type: shell + config: + 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..c17cd64 --- /dev/null +++ b/docs/watchers/gce_metadata_watcher.md @@ -0,0 +1,84 @@ +# 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: + type: gce_metadata + config: + key: instance/attributes/my-key + recursive: true +executioner: + type: 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..234bce0 --- /dev/null +++ b/docs/watchers/time_watcher.md @@ -0,0 +1,34 @@ +# 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: + type: time + config: + poll_seconds: 60 +executioner: + type: 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.