add a quick start command

README.md

@@ -1 +1,59 @@
-# koach
+# Koach
+
+Koach collects observability data from relay server and save it in database. Koach also provided gRPC method to query this data, which currently used by the KubeArmor CLI.
+Other than that, you can also specify alert rules which will be watched by Koach.
+
+## Prerequisites
+
+### KubeArmor
+You need to have KubeArmor installed on your cluster to use Koach. Follow the guide on this [repository](https://github.com/kubearmor/KubeArmor) to install or deploy KubeArmor.
+
+### KubeArmor CLI
+To interact with Koach, please install the cli from [here](https://github.com/nthnieljson/kubearmor-client/tree/observe-cmd-init).
+
+## Quick Install
+Deploy koach to your cluster using the following command.
+```
+kubectl apply -f https://raw.githubusercontent.com/nthnieljson/koach/alert-rule/deployments/koach-deployment.yaml
+```
+
+To use the alert rules, there are additional CRD that needs to be deployed. You can deploy it using the following command.
+```
+kubectl apply -f https://raw.githubusercontent.com/nthnieljson/koach/alert-rule/deployments/CRD/KubeArmorAlertRule.yaml
+```
+
+## How To Use
+
+### Get Observability Data
+Use KubeArmor cli to get the observability data that have been stored. To install the karmor cli tool, follow the link [here](https://github.com/kubearmor/kubearmor-client/#from-script). Currently there are 4 type of operations that koach support:
+- file
+- process
+- network
+- syscall
+
+Example, get all observabilities data for file operation on `multiubuntu` namespace and output it using a custom column.
+```
+karmor observe file -n multiubuntu --custom-columns=Namespace:.namespace_name,Pod:.pod_name,Resource:.resource
+```
+
+Example, get all observabilities data for process operation since the last 24 hour on all namespaces using specific labels.
+```
+karmor observe process -A --show-labels -l container=ubuntu-5 --since=24h
+``` 
+
+### Create and Watch Alert
+Alert can be defined as a set of rules about operations. Alert rules are defined as a custom resource of k8s. Currently these are the main use case that is supported by koach alert rule:
+- mass file deletion
+- suspicious ip connection
+
+Two example alert rules can be deployed using the following command.
+```
+kubectl apply -f https://raw.githubusercontent.com/nthnieljson/koach/alert-rule/examples/alert-rule/file-delete-alert-rule.yaml
+
+kubectl apply -f https://raw.githubusercontent.com/nthnieljson/koach/alert-rule/examples/alert-rule/suspicious-ip-alert-rule.yaml
+```
+
+Koach provide a gRPC method that can be used to listen or watch alerts. KubeArmor cli also can be used to watch alert, which in the background are using the gRPC method that koach provided.
+```
+karmor observe alert
+```