Update docs

README.md

@@ -1,2 +1,54 @@
-# kreaper
+# kreaper - *K*ubernetes _Reaper_
-A Kubernetes pod reaper
+
+_kreaper_ is (yet another) *K*ubernetes pod _reaper_.
+It's main purpose is to delete pods matching a certain pod selector after a deadline is reached.
+
+The `testdata/` directory contains a Kubernetes manifest example how to deploy _kreaper_ as `Job` that is automatically
+cleaned after 30s.
+
+## Configuration
+
+_kreaper_ only requires a few config options that are available as CLI flags or as environment variables.
+For the sake of simplicity environment variables are favored.
+
+| Env                      | Flag                | Purpose                                                       | Example                           | Default   |
+|--------------------------|---------------------|---------------------------------------------------------------|-----------------------------------|-----------|
+| KREAPER_TARGET           | `-target`           | Target selection in the form of `key=value`                   | `app.kubernetes.io/name=ee8dcc4d` | `""`      |
+| KREAPER_TARGET_NAMESPACE | `-target-namespace` | Namespace in which pods are watched and deleted               | `my-app`                          | `default` |
+| KREAPER_DRY_RUN          | `-dry-run`          | Skip actual deletion                                          | `true`                            | `false`   |
+| KREAPER_LIFETIME         | `-lifetime`         | Duration after which all pods matching the target are deleted | `30s`                             | `5m`      |
+
+## Kubeconfig
+
+_kreaper_ is meant to be running __within__ a Kubernetes cluster and therefore tries at first to read a in-cluster API config.
+If it fails to read the in-cluster config it tries to read the default `$HOME/.kube/config` file.
+The config file location can be modified either with the `KUBECONFIG` environment variable or by supplying a `-kubeconfig` flag.
+
+## RBAC
+
+_kreaper_ only needs:
+
+- `list`
+- `watch`
+- `deletecollection`
+
+permissions for Pods in the `KREAPER_TARGET_NAMESPACE`.
+A very basic `Role` would look like so:
+
+```yml
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: kreaper
+rules:
+  - verbs:
+      - list
+      - watch
+      - deletecollection
+    apiGroups:
+      - ""
+    resources:
+      - pods
+```
+
+alternatively a `RoleBinding` or a `ClusterRoleBinding` to the `edit` `ClusterRole` might be a little bit overkill but therefore also possible.

main.go

@@ -27,7 +27,7 @@ var (
 	dryRun     bool
 	logLevel   *zapcore.Level
 	kreaper    = reaper.Kreaper{
-		Target: lookupEnvOr[reaper.Target]("KREAPER_TARGET", "", reaper.ParseTarget),
+		Target: lookupEnvOr("KREAPER_TARGET", "", reaper.ParseTarget),
 	}
 )
 
@@ -97,9 +97,9 @@ func prepareFlags() {
 	)
 
 	if home := homedir.HomeDir(); home != "" {
-		flag.StringVar(&kubeconfig, "kubeconfig", filepath.Join(home, ".kube", "config"), "(optional) absolute path to the kubeconfig file")
+		flag.StringVar(&kubeconfig, "kubeconfig", lookupEnvOr("KUBECONFIG", filepath.Join(home, ".kube", "config"), identity[string]), "(optional) absolute path to the kubeconfig file")
 	} else {
-		flag.StringVar(&kubeconfig, "kubeconfig", "", "absolute path to the kubeconfig file")
+		flag.StringVar(&kubeconfig, "kubeconfig", lookupEnvOr("KUBECONFIG", "", identity[string]), "absolute path to the kubeconfig file")
 	}
 
 	flag.Parse()

testdata/deployment.yaml

@@ -9,7 +9,6 @@ metadata:
   name: kreaper-debug
 rules:
   - verbs:
-      - get
       - list
       - watch
       - deletecollection