diff --git a/README.md b/README.md
index 3867f6225748687ef3b85335cc5a6134555e9618..8f1b731324578388045e9623800d547e98723c44 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,198 @@
 # org.etsi.osl.controllers.sylva
 
-An experimental kubernetes operator to manage Sylva Workload clusters
+A  kubernetes operator to manage Sylva Workload clusters
+
 
 ## Getting started
 
-helm install oslsylva . --set-file  kubeconfig=../src/main/resources/config --set-file sylvamgtconfig=../src/main/resources/management-cluster-kubeconfig
\ No newline at end of file
+
+To install the operator you need as input a kubeconfig to the OSL management cluster and a kubeconfig of the Sylva management cluster
+
+```
+helm install oslsylva . --set-file  kubeconfig=../src/main/resources/config --set-file sylvamgtconfig=../src/main/resources/management-cluster-kubeconfig
+```
+
+Then you need to:
+
+Install kustomization.sylvamd.configmaps.osl.etsi.org in default namespace
+
+Install secrets.sylvamd.configmaps.osl.etsi.org in default namespace
+
+examples of such files are available in src/main/resources folder.
+
+Example usage of the operator:
+
+the kind installed is of  SylvaMDResource under group: controllers.osl.etsi.org 
+
+
+It accepts either simple a number of clusterControlPlaneReplicas and clusterMd0Replicas or a full values yaml file.
+
+
+Examples:
+
+request a sylva workload cluster with 1 master 3 worker nodes
+
+```
+apiVersion: controllers.osl.etsi.org/v1alpha1
+kind: SylvaMDResource
+metadata:
+  name: wc12345-aaeeff
+spec:
+  clusterControlPlaneReplicas: "1"
+  clusterMd0Replicas: "3"
+```
+
+
+
+request a sylva workload cluster with 1 master 3 worker nodes, but with a values.yaml spec
+
+
+```
+apiVersion: controllers.osl.etsi.org/v1alpha1
+kind: SylvaMDResource
+metadata:
+  name: wc67890-bbccdd
+spec:
+  valuesyaml: |
+    ---
+    cluster:
+
+      capi_providers:
+        infra_provider: capo
+        bootstrap_provider: cabpr
+
+      capo:
+        image_key: ubuntu-jammy-plain-rke2-1-28-8  # OpenStack Glance image (key of image in sylva_diskimagebuilder_images/os_images)
+        ssh_key_name: sylva # OpenStack Nova SSH keypair is provided by runner context in CI
+        network_id: 7b490a0c-0f5c-4475-a436-e4bcbecc7f5e # OpenStack Neutron network id is provided by runner context in CI
+        flavor_name: cpu8.m16384.d40g
+        control_plane_az:
+          - nova
+
+      machine_deployments:
+        md0:
+          replicas: 3
+          capo:
+            failure_domain: nova
+            flavor_name: cpu8.m16384.d40g
+
+      control_plane_replicas: 1
+
+    openstack:
+      control_plane_affinity_policy: soft-anti-affinity
+      storageClass:
+        name: "rbd1"
+        type: "rbd1"
+
+    proxies:
+      http_proxy: ""
+      https_proxy: ""
+      no_proxy: ""
+
+    ntp:
+      enabled: false
+      servers:
+      # - 1.2.3.4
+      # - 1.2.3.5
+
+    sylva_diskimagebuilder_images:
+     ubuntu-jammy-plain-rke2-1-28-8:
+        enabled: true
+
+     ubuntu-jammy-plain-kubeadm-1-28-9:
+        enabled: true
+
+
+```
+
+
+
+The status returns the state of the process as well as a kubeconf to connect to the remote WC, in the secret field as BASE64 encoded string. 
+Example:
+
+```
+Name:         cr77935ae9
+Namespace:    fb9cdc53-e880-4faa-9ac1-b0f3f39800b5
+Labels:       org.etsi.osl.namespace=fb9cdc53-e880-4faa-9ac1-b0f3f39800b5
+              org.etsi.osl.prefixName=cr77935ae9
+              org.etsi.osl.resourceId=77935ae9-055a-449a-ac9c-e8d0d7a57e24
+              org.etsi.osl.serviceId=1674a3b5-2f5d-49a8-8029-77e04dd86a0c
+              org.etsi.osl.serviceOrderId=fb9cdc53-e880-4faa-9ac1-b0f3f39800b5
+              org.etsi.osl.statusCheckFieldName=status.state
+              org.etsi.osl.statusCheckValueAlarm=FAILED
+              org.etsi.osl.statusCheckValueAvailable=ACTIVE
+              org.etsi.osl.statusCheckValueReserved=
+              org.etsi.osl.statusCheckValueStandby=
+              org.etsi.osl.statusCheckValueSuspended=
+              org.etsi.osl.statusCheckValueUnknown=DELETED
+Annotations:  <none>
+API Version:  controllers.osl.etsi.org/v1alpha1
+Kind:         SylvaMDResource
+Metadata:
+  Creation Timestamp:  2024-10-13T17:35:01Z
+  Finalizers:
+    sylva.osl.etsi.org
+  Generation:        5
+  Resource Version:  360840
+  UID:               f478c552-34b4-488c-ac04-ce6e73c152de
+Spec:
+  Valuesyaml:  ---
+cluster:
+
+  capi_providers:
+    infra_provider: capo
+    bootstrap_provider: cabpr
+
+  capo:
+    image_key: ubuntu-jammy-plain-rke2-1-28-8  # OpenStack Glance image (key of image in sylva_diskimagebuilder_images/os_images)
+    ssh_key_name: sylva # OpenStack Nova SSH keypair is provided by runner context in CI
+    network_id: 7b490a0c-0f5c-4475-a436-e4bcbecc7f5e # OpenStack Neutron network id is provided by runner context in CI
+    flavor_name: cpu8.m16384.d40g
+    control_plane_az:
+      - nova
+
+  machine_deployments:
+    md0:
+      replicas: 3
+      capo:
+        failure_domain: nova
+        flavor_name: cpu8.m16384.d40g
+
+  control_plane_replicas: 1
+
+openstack:
+  control_plane_affinity_policy: soft-anti-affinity
+  storageClass:
+    name: "rbd1"
+    type: "rbd1"
+
+proxies:
+  http_proxy: ""
+  https_proxy: ""
+  no_proxy: ""
+
+ntp:
+  enabled: false
+  servers:
+  # - 1.2.3.4
+  # - 1.2.3.5
+
+sylva_diskimagebuilder_images:
+ ubuntu-jammy-plain-rke2-1-28-8:
+    enabled: true
+
+ ubuntu-jammy-plain-kubeadm-1-28-9:
+    enabled: true
+
+Status:
+  Info Text:   executing apply-workload-cluster.sh success
+  Secret:      YXB...PQo=
+  State:       ACTIVE
+  State Text:  ACTIVE
+Events:        <none>
+
+
+```
+
+
+