docs(readme): enhance example sections

Author: maximiliantech

README.md

@@ -4,11 +4,26 @@
 
 ## About this project
 
-A cluster provider for OpenMCP that uses [kind](https://kind.sigs.k8s.io/) to provision clusters. Ideal for local development and E2E tests.
+A cluster provider for [OpenMCP](https://github.com/openmcp-project/openmcp-operator) that uses [kind](https://kind.sigs.k8s.io/) (Kubernetes IN Docker) to provision and manage Kubernetes clusters. This provider enables you to create and manage multiple Kubernetes clusters running as Docker containers, making it ideal for:
 
-## Requirements and Setup
+- **Local Development**: Quickly spin up multiple clusters for testing multi-cluster scenarios
+- **E2E Testing**: Automated testing of multi-cluster applications and operators
+- **CI/CD Pipelines**: Lightweight cluster provisioning for testing environments
+
+## Prerequisites
+
+Before using this cluster provider, ensure you have:
+
+- **Docker**: Running Docker daemon with socket accessible
+- **kind**: [kind CLI tool](https://kind.sigs.k8s.io/docs/user/quick-start/) installed
+- **kubectl**: For interacting with Kubernetes clusters
+
+## Installation
+
+### Production Deployment
+
+In combination with the [OpenMCP Operator](https://github.com/openmcp-project/openmcp-operator), this operator can be deployed via a simple Kubernetes resource:
 
-In combination with the [openMCP Operator](https://github.com/openmcp-project/openmcp-operator), this operator can be deployed via a simple k8s resource:
 ```yaml
 apiVersion: openmcp.cloud/v1alpha1
 kind: ClusterProvider
@@ -19,17 +34,71 @@ spec:
 ```
 
 ### Local Development
-To run it locally, please make sure to have a running [kind](https://kind.sigs.k8s.io/docs/user/quick-start/) cluster with kubectl context set to the kind cluster that serves as the platform cluster. You can then run the operator locally by executing:
+
+To run the operator locally for development:
+
+1. **Start a platform kind cluster**:
+```shell
+kind create cluster --name platform
+kubectl config use-context kind-platform
+```
+2. Install the Platform CRDs of the openmcp-operator:
+Apply the CRDs from the OpenMCP operator repository [here](https://github.com/openmcp-project/openmcp-operator/tree/main/api/crds/manifests).
+
+3. **Initialize the CRDs**:
 ```shell
 go run ./cmd/cluster-provider-kind/main.go init
 ```
-to deploy the CRDs that are required for the operator and then
+
+1. **Run the operator**:
 ```shell
 go run ./cmd/cluster-provider-kind/main.go run
 ```
 
+## Usage Examples
+
+### Creating a Cluster
+
+Create a new kind cluster by applying a Cluster resource:
+
+```yaml
+apiVersion: clusters.openmcp.cloud/v1alpha1
+kind: Cluster
+metadata:
+  name: my-managedcontrolplane
+  namespace: default
+spec:
+  profile: kind  # This tells the kind provider to handle this cluster
+  tenancy: Exclusive
+```
+
+```shell
+kubectl apply -f cluster.yaml
+```
+
+### Requesting Access to a Cluster
+
+Create an AccessRequest to get kubeconfig for a cluster:
+
+```yaml
+apiVersion: clusters.openmcp.cloud/v1alpha1
+kind: AccessRequest
+metadata:
+  name: my-access
+  namespace: default
+spec:
+  clusterRef:
+    name: my-managedcontrolplane
+    namespace: default
+  permissions: []
+```
+
+The kubeconfig will be stored in a Secret in the same namespace as the `AccessRequest`.
+
 ## How it works
 
+### Docker Socket Access
+
 In order to create new kind clusters from within a kind cluster, the Docker socket (usually `/var/run/docker.sock`) needs to be available to the `cluster-provider-kind` pod. As a prerequisite, the Docker socket of the host machine must be mounted into the nodes of the platform kind cluster. In this case, there is only a single node (`platform-control-plane`). The socket can then be mounted by the cluster-provider-kind pod using a `hostPath` volume.
 
 ```mermaid
@@ -59,6 +128,8 @@ end
 style HostMachine fill:#eee
 ```
 
+### Platform Cluster Configuration
+
 The kind configuration for the platform cluster may look like this:
 
 ```yaml
@@ -68,9 +139,12 @@ nodes:
 - role: control-plane
   extraMounts:
   - hostPath: /var/run/docker.sock
-    containerPath: /var/run/host-docker.sock
+    containerPath: /var/run/docker.sock
 ```
- In order to test that the socket is functional, a simple pod can be deployed:
+
+### Testing Docker Socket Access
+
+In order to test that the socket is functional, a simple pod can be deployed:
 
 ```yaml
 apiVersion: v1
@@ -90,7 +164,7 @@ spec:
   volumes:
     - name: docker
       hostPath:
-        path: /var/run/host-docker.sock
+        path: /var/run/docker.sock
         type: Socket
 ```