Merge pull request #10 from simplifi/add-documentation

Add documentation

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
-```

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=<content of the change>
+```
+
+**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.

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.

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
+```

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.