feat: add install and migration documentation (#78)

* feat: add install and migration documentation

Signed-off-by: Vishal Choudhary <vishal.choudhary@nirmata.com>

* fix: redundant line

Signed-off-by: Vishal Choudhary <vishal.choudhary@nirmata.com>

* fix: update install instructions

Signed-off-by: Vishal Choudhary <vishal.choudhary@nirmata.com>

---------

Signed-off-by: Vishal Choudhary <vishal.choudhary@nirmata.com>
Co-authored-by: shuting <shuting@nirmata.com>

README.md

@@ -23,35 +23,4 @@ Benefits of reports server:
 
 ## Installation
 
-The reports server can be installed in a test cluster, directly from the YAML manifest or via the official Helm chart. 
-
-### Local Install
-To locally install the reports server, run the following command:
-
-```shell
-# create a local kind cluster
-make kind-create
-
-# build docker images, load images in kind cluster, and deploy helm chart
-make kind-install
-```
-
-### YAML Manifest
-To install the latest reports server release from the config/install.yaml manifest, run the following command.
-```shell
-kubectl apply -f config/install.yaml # todo: use a release url
-```
-
-### Helm Chart
-Reports server can be installed via the official Helm chart:
-```shell
-helm install report-server --namespace kyverno --wait ./charts/reports-server/ # todo: use a offical helm chart
-```
-
-Note: if you already have wgpolicy CRDs or kyverno CRDs installed, you won't be able to install api services. Use the following command to install other components:
-
-```shell
-helm install report-server --namespace kyverno --wait ./charts/reports-server/ --set apiServices.enabled=false # todo: use a offical helm chart
-```
-
-Now you can update the [apiservice samples](./config/samples/apiservices.yaml) with the right reports-server name and namespace and apply that manifest.
+See [INSTALL.md](/docs/INSTALL.md)

docs/DBCONFIG.md

@@ -0,0 +1,9 @@
+# Database Configuration
+
+Reports server installation comes with a standard postgres installed. It is highly recommened to setup your own postgres to have finer control over the database configuration.
+
+You need to provide the following to the reports server to use your own database:
+1. Database host name
+2. Database user
+3. Database password
+4. Database name

docs/INSTALL.md

@@ -0,0 +1,69 @@
+# Installation
+
+Reports-server has multiple methods for installation: YAML manifest and Helm Chart.YAML manifest is the recommended method to install reports server when kyverno or policy reports CRDs are already installed in the cluster. Helm chart is the most flexible method as it offers a wide range of configurations.
+
+If kyverno is already installed in the cluster, follow the [migration guide](#migration).
+
+Reports-server comes with a postgreSQL database. It is recommended to bring-your-own postgres database to have finer control of database configurations ([see database configuration guide](#database-configuration)).
+
+### YAML Manifest
+It is recommended to install Reports-server using `kubectl apply`, especially when policy reports CRDs are already installed in the cluster ([see migration guide](#migration)). To install reports server using YAML manifest, run the following command:
+
+```bash
+kubectl apply -f https://raw.githubusercontent.com/kyverno/reports-server/main/config/install.yaml
+```
+
+### Helm Chart
+
+Reports-server can be deployed via a Helm chart for a production install–which is accessible either through the reports-server repository.
+
+In order to install reports-server with Helm, first add the Reports-server Helm repository:
+```bash
+helm repo add reports-server https://kyverno.github.io/reports-server
+```
+
+Scan the new repository for charts:
+```bash
+helm repo update
+```
+
+Optionally, show all available chart versions for reports-server.
+
+```bash
+helm search repo reports-server --l
+```
+
+Create a namespace and install the reports-server chart:
+
+```bash
+helm install reports-server -n reports-server reports-server/reports-server --create-namespace
+```
+
+To install pre-releases, add the --devel switch to Helm:
+
+```bash
+helm install reports-server -n reports-server reports-server/reports-server --create-namespace --devel
+```
+
+### Testing
+
+To install Reports-server on a kind cluster for testing, run the following commands:
+
+Create a local kind cluster
+```bash
+make kind-create
+```
+
+Build docker images, load images in kind cluster, and deploy helm chart
+```bash
+make kind-install
+```
+
+## Migration 
+
+See [MIGRATION.md](./MIGRATION.md)
+
+
+## Database Configuration
+
+See [DBCONFIG.md](./DBCONFIG.md)

docs/MIGRATION.md

@@ -0,0 +1,27 @@
+# Migration
+
+This migration guide is for migrating an existing cluster using etcd to store policy reports to reports-server. 
+
+You need to follow this if:
+1. The cluster has kyverno already installed, or,
+2. The cluster has policy reports crds already installed
+
+Clusters with policy reports CRDs have existing API services for policy reports which need to be overwritten for reports-server to work. We do that by applying new api services with the label `kube-aggregator.kubernetes.io/automanaged: "false"`.
+
+Follow the given methods to migrate to reports server on your existing cluster:
+
+## YAML Manifest
+
+YAML manifest can be installed directly using `kubectl apply` and this will overwrite the existing API services. Run the following command:
+```bash
+kubectl apply -f https://raw.githubusercontent.com/kyverno/reports-server/main/config/install.yaml
+```
+
+## Helm Chart
+
+Helm cannot overwrite resources when they are not managed by helm. Thus we recommend installing the chart without the api services using the following command:
+```bash
+helm install reports-server --namespace reports-server reports-server/reports-server --devel  --set apiServices.enabled=false
+```
+
+Once the helm chart is installed, API services can be manually updated using `kubectl apply`. Update our [apiservices samples](./config/samples/apiservices.yaml) with the right reports-server name and namespace and apply that manifest.