feat: Add overview section to README

README.md

@@ -4,11 +4,24 @@
 
 Implementation of [Kardinal](https://github.com/kurtosis-tech/kardinal) as a K8S Operator.
 
+## Overview
+
+The Kardinal operator watches the cluster K8S resources, generates a cluster topology and applies changes to satisfy the cluster topology.  One difference with today is that the operator only manages what needs to be added to the user cluster (dev services, network resources…).  The operator does not reconcile user resources.  We introduce some k8s custom resources: service dependencies, flows, plugins and templates.  Those resources will be namespaced.
+
+The operator performs the same operation each time one of the watched Flow custom resources is added or removed.
+
+- Generate the base cluster topology from the list of services, dependencies, deployments, gateways…
+- Generate flow topologies from the list of flows, plugins and templates.  Every operation performed by the operator needs to be idempotent which means the plugins need to be idempotent.
+- Merge the topologies
+- Generate the K8s resources needed (dev services, network resources…) to satisfy the merged topology and reconcile the cluster.
+
+![](images/overview.png)
+
 ## Install
 
 ### Requirements
 
-Istio is required and your namespaces should be labeled for injection. 
+Istio is required and your namespaces should be labeled for injection.
 
 ```
 istioctl manifest install --set profile=default
@@ -68,7 +81,7 @@ make run (Run operator against your local cluster)
 Manage custom resources with kubectl:
 
 ```
-# Create a flow 
+# Create a flow
 kubectl create -f ./ci/flow-test.yaml
 
 # Delete a flow
@@ -77,7 +90,7 @@ kubectl delete -f ./ci/flow-test.yaml
 # Get all flows in namespace
 kubectl get flows -n baseline
 
-# Describe a flow by its name 
+# Describe a flow by its name
 kubectl describe flows flow-test -n baseline
 ```
 
@@ -105,9 +118,9 @@ kubectl describe flows flow-test -n baseline
 
 #### Gateway
 
-If you previously ran `Kardinal Manager`, you may already have a `gateway-istio` deployment in your cluster. This could lead to requests being 
-routed through it instead of the `gateway-istio` deployment in the `baseline` namespace. This issue arises because a gateway resource may 
-still exist. We recommend removing it —only if you're certain it was created by Kardinal— before deploying the `./ci/obd-demo.yaml` manifest. 
+If you previously ran `Kardinal Manager`, you may already have a `gateway-istio` deployment in your cluster. This could lead to requests being
+routed through it instead of the `gateway-istio` deployment in the `baseline` namespace. This issue arises because a gateway resource may
+still exist. We recommend removing it —only if you're certain it was created by Kardinal— before deploying the `./ci/obd-demo.yaml` manifest.
 You can do this with the following command: `kubectl delete Gateway gateway`
 
 [api-design-doc]: https://book.kubebuilder.io/cronjob-tutorial/api-design