docs: update readme

flanksource · Dec 19, 2023 · 42cadce · 42cadce
1 parent 699f31a
commit 42cadce
Show file tree

Hide file tree

Showing 4 changed files with 217 additions and 79 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,70 @@
+# Contributing
+
+Firstly, thank you for considering contributing to Canary-Checker! Here are some guidelines to help you get started.
+
+## 📖 Code of Conduct
+
+This project adheres to the CNCF Code of Conduct. By participating in this project, you agree to abide by its terms.
+
+## Setup
+
+Ensure that you have the latest version of Go installed on your machine.
+
+1. Build the project by checking it out and running `make build` this will create a `.bin/canary-checker` binary
+
+## Testing
+
+1. Test an individual fixture using `canary-checker run fixtures/minimal/http_auth.yaml`, you can pass a directory or multiple files
+1. Run a kubernetes based E2E test using `./test/e2e.sh` e.g. `fixtures/minimal`, this will spin up a kind cluster to run tests using a Kubernetes environment
+    * Fixture folders can also include setup/teardown files:
+      * `_setup.yaml` - Any kubernetes resources that need to be applied
+      * `_setup.sh` - A bash script to run before the suite
+      * `_post_setup.sh` - A bash script to run after test execution
+1. Run a full operator test with a postgres DB: `./test/e2e-operator.sh`
+
+
+## :bulb: Asking Questions
+
+Always refer to the [docs](https://canarychecker.io/getting-started) before asking questions. You may create new issues for questions and help, just prefix the issue title with **Question:** or **Help:** and try and provide as much detail as possible.
+
+## :inbox_tray: Opening an Issue
+
+Before [creating an issue](https://help.github.com/en/github/managing-your-work-on-github/creating-an-issue), check if you are using the latest version of the project. If you are not up-to-date, see if updating fixes your issue first.
+
+### :lock: Reporting Security Issues
+
+Review our [Security Policy](https://github.com/flanksource/canary-checker?tab=security-ov-file). **Do not** file a public issue for security vulnerabilities.
+
+## :love_letter: Feature Requests
+
+Feature requests are welcome! While we will consider all requests, we cannot guarantee your request will be accepted. We want to avoid [feature creep](https://en.wikipedia.org/wiki/Feature_creep). Your idea may be great, but also out-of-scope for the project. If accepted, we cannot make any commitments regarding the timeline for implementation and release. However, you are welcome to submit a pull request to help!
+
+- **Do not open a duplicate feature request.** Search for existing feature requests first. If you find your feature (or one very similar) previously requested, comment on that issue.
+
+## Pull Requests
+
+Pull requests are always welcome. To create a pull request, ensure that your changes are in a separate branch or fork that is based off `master`. When your changes are ready, submit your branch as a pull request against `master`.
+
+- **Smaller is better.** Submit **one** pull request per bug fix or feature. A pull request should contain isolated changes pertaining to a single bug fix or feature implementation. **Do not** refactor or reformat code that is unrelated to your change. It is better to **submit many small pull requests** rather than a single large one. Enormous pull requests will take enormous amounts of time to review, or may be rejected altogether.
+
+- **Prioritize understanding over cleverness.** Write code clearly and concisely. Remember that source code usually gets written once and read often. Ensure the code is clear to the reader. The purpose and logic should be obvious to a reasonably skilled developer, otherwise you should add a comment that explains it.
+
+- **Comments should be used for why not what.** Many comments that merely explain what a piece of code is doing can be refactored away with better variable and function names and/or using shorter method.
+
+- **Follow existing coding style and conventions.** Keep your code consistent with the style, formatting, and conventions in the rest of the code base. When possible, these will be enforced with a linter. Consistency makes it easier to review and modify in the future.
+
+- **Include test coverage.** For new check types always include a passing (`_pass.yaml`) and failing (`_fail.yaml`) fixture
+
+
+## :white_check_mark: Code Review
+
+- **Review the code, not the author.** Look for and suggest improvements without disparaging or insulting the author. Provide actionable feedback and explain your reasoning.
+
+- **You are not your code.** When your code is critiqued, questioned, or constructively criticized, remember that you are not your code. Do not take code review personally.
+
+- **Always do your best.** No one writes bugs on purpose. Do your best, and learn from your mistakes.
+
+
+## :pray: Credits
+
+Adapted from [@jessesquires](https://github.com/jessesquires/.github/blob/main/CONTRIBUTING.md)
diff --git a/README.md b/README.md
@@ -3,8 +3,8 @@
     <source srcset="https://canarychecker.io/img/canary-checker-white.svg" media="(prefers-color-scheme: dark)">
     <img src="https://canarychecker.io/img/canary-checker.svg">
   </picture>
-  
-  <p>Kubernetes operator for executing synthetic tests</p>
+
+  <p>Kubernetes Native Health Check Platform</p>
   <p>
     <a href="https://github.com/flanksource/canary-checker/actions"><img src="https://github.com/flanksource/canary-checker/workflows/Test/badge.svg"></a>
     <a href="https://goreportcard.com/report/github.com/flanksource/canary-checker"><img src="https://goreportcard.com/badge/github.com/flanksource/canary-checker"></a>
@@ -33,15 +33,20 @@ Canary checker is a kubernetes-native platform for monitoring health across appl
 
 ## Getting Started
 
-1. Install canary checker:
+1. Install canary checker CLI
 
   ```shell
 helm repo add flanksource https://flanksource.github.io/charts
 helm repo update
-helm install canary-checker
+helm install \
+  canary-checker \
+  flanksource/canary-checker \
+ -n canary-checker \
+ --create-namespace
+ --wait
   ```
 
-2. Create a new check:
+2. Create a new check
 
   ```yaml title="canary.yaml"
 apiVersion: canaries.flanksource.com/v1
@@ -59,8 +64,12 @@ spec:
 
 2a. Run the check locally (Optional)
 
+
 ```shell
-canary-checker run canary.yaml
+wget  https://github.com/flanksource/canary-checker/releases/latest/download/canary-checker_linux_amd64   \
+  -O canary-checker && \
+  chmod +x canary-checker
+./canary-checker run canary.yaml
 ```
 
 [![asciicast](https://asciinema.org/a/cYS6hlmX516JQeECHH7za3IDG.svg)](https://asciinema.org/a/cYS6hlmX516JQeECHH7za3IDG)
@@ -80,14 +89,131 @@ NAME               INTERVAL   STATUS   LAST CHECK   UPTIME 1H        LATENCY 1H
 http-check.        30         Passed   13s          18/18 (100.0%)   480ms        13s
 ```
 
+
+Ne
+
+## Use Cases
+
+### Synthetic Testing
+
+Run simple HTTP/DNS/ICMP probes or more advanced full test suites using JMeter, K6, Playright, Postman.
+
+```yaml
+# Run a container that executes a playwright test, and then collect the
+# JUnit formatted test results from the /tmp folder
+apiVersion: canaries.flanksource.com/v1
+kind: Canary
+metadata:
+  name: playwright-junit
+spec:
+  interval: 120
+  junit:
+    - testResults: "/tmp/"
+      name: playwright-junit
+      spec:
+        containers:
+          - name: playwright
+            image: ghcr.io/flanksource/canary-playwright:latest
+```
+
+### Infrastructure Testing
+
+Verify that infrastructure is fully operational by deploying new pods, spinning up new EC2 instances and pushing/pulling from docker and helm repositories.
+
+### Backup Checks / Batch File Monitoring
+
+Check that batch file processes are functioning correctly by checking the age and size of files in local file systems, SFTP, SMB, S3 and GCS.
+
+```yaml
+# Checks that a recent DB backup has been uploaded
+apiVersion: canaries.flanksource.com/v1
+kind: Canary
+metadata:
+  name: folder-check
+spec:
+  schedule: 0 22 * * *
+  folder:
+    - path: s3://database-backups/prod
+      name: prod-backup
+      maxAge: 1d
+      minSize: 10gb
+```
+
+### Alert Aggregation
+
+Aggregate alerts and recommendations from Prometheus, AWS Cloudwatch, Dynatrace, etc.
+
+```yaml
+apiVersion: canaries.flanksource.com/v1
+kind: Canary
+metadata:
+  name: alertmanager-check
+spec:
+  schedule: "*/5 * * * *"
+  alertmanager:
+    - url: alertmanager.monitoring.svc
+      alerts:
+        - .*
+      ignore:
+        - KubeScheduler.*
+        - Watchdog
+      transform:
+        javascript: |
+          var out = _.map(results, function(r) {
+            return {
+              name: r.name,
+              labels: r.labels,
+              icon: 'alert',
+              message: r.message,
+              description: r.message,
+            }
+          })
+          JSON.stringify(out);
+```
+
+### Prometheus Exporter Replacement
+
+Export [custom metrics](https://canarychecker.io/concepts/metrics-exporter) from the result of any check, making it possible to replace various other promethus exporters that collect metrics via HTTP, SQL, etc..
+
+```yaml
+apiVersion: canaries.flanksource.com/v1
+kind: Canary
+metadata:
+  name: exchange-rates
+spec:
+  schedule: "every 1 @hour"
+  http:
+    - name: exchange-rates
+      url: https://api.frankfurter.app/latest?from=USD&to=GBP,EUR,ILS
+      metrics:
+        - name: exchange_rate
+          type: gauge
+          value: result.json.rates.GBP
+          labels:
+            - name: "from"
+              value: "USD"
+            - name: to
+              value: GBP
+```
+
+> Note canary-checker is not a replacement for exporters with significant amount of logic like node-exporter or postgresql-exporter
+
+## Dashboard
+
+Canary checker comes with a built-in dashboard by default
+
+![](https://canarychecker.io/img/canary-ui.png)
+
+There is also a [grafana](https://canarychecker.io/concepts/grafana) dashboard, or build your own using the metrics exposed.
+
 ## Getting Help
 
 If you have any questions about canary checker:
 
 * Read the [docs](https://canarychecker.io)
 * Invite yourself to the [CNCF community slack](https://slack.cncf.io/) and join the [#canary-checker](https://cloud-native.slack.com/messages/canary-checker/) channel.
 * Check out the [Youtube Playlist](https://www.youtube.com/playlist?list=PLz4F_KggvA58D6krlw433TNr8qMbu1aIU).
-* File an [issue](https://github.com/flanksource/canary-checker/issues/new) - (We do provide user support via Github Issues, so don't worry  if your issue a real bug or not)
+* File an [issue](https://github.com/flanksource/canary-checker/issues/new) - (We do provide user support via Github Issues, so don't worry if your issue is a bug or not)
 
 Your feedback is always welcome!
 
@@ -112,10 +238,13 @@ Your feedback is always welcome!
 | [Dynatrace Problems](./reference/dynatrace.md)               | Beta       | Problems deteced                                             |
 | **DevOps**                                                   |            |                                                              |
 | [Git](https://canarychecker.io/reference/git)                                      | GA         | Query Git and Github repositories via SQL                    |
-| [Azure Devops](https://canarychecker.io/reference)                                 |            |                                                              |
+| [Azure Devops](https://canarychecker.io/reference)                                 | Beta |                                                              |
 | **Integration Testing**                                      |            |                                                              |
 | [JMeter](https://canarychecker.io/reference/jmeter)                                | Beta       | Runs and checks the result of a JMeter test                  |
 | [JUnit / BYO](https://canarychecker.io/reference/junit)                            | Beta       | Run a pod that saves Junit test results                      |
+| [K6](https://canarychecker.io/reference/k6) | Beta | Runs K6 tests that export JUnit via a container |
+| [Newman](https://canarychecker.io/reference/newman) | Beta |  Runs Newman / Postman tests that export JUnit via a container  |
+| [Playwright](https://canarychecker.io/reference/Playwright) | Beta |  Runs Playwright tests that export JUnit via a container  |
 | **File Systems / Batch**                                     |            |                                                              |
 | [Local Disk / NFS](https://canarychecker.io/reference/folder)                      | GA         | Check folders for files that are:  too few/many, too old/new, too small/large |
 | [S3](https://canarychecker.io/reference/s3-bucket)                                 | GA         | Check contents of AWS S3 Buckets                             |
@@ -137,6 +266,16 @@ Your feedback is always welcome!
 | [Helm](https://canarychecker.io/reference/helm)                                    | Deprecated | Ability to push and pull helm charts                         |
 | [S3 Protocol](https://canarychecker.io/reference/s3-protocol)                      | GA         | Ability to read/write/list objects on an S3 compatible object store |
 
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md)
+
+Thank you to all our contributors !
+
+<a href="https://github.com/flanksource/canary-checker/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=flanksource/canary-checker" />
+</a>
+
 ## License
 
 Canary Checker core (the code in this repository) is licensed under [Apache 2.0](https://raw.githubusercontent.com/flanksource/canary-checker/main/LICENSE) and accepts contributions via GitHub pull requests after signing a CLA.

diff --git a/development.md b/development.md
diff --git a/mkdocs.yml b/mkdocs.yml