diff --git a/docs/index.rst b/docs/index.rst
index b10a8df901e4b57f299931d09873b9c12f3a5e17..68d3da6c0769bde964f2a663c48f493c954f2631 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -27,6 +27,7 @@ For more information, go to `the OpenAppStack website`_.
    :caption: Contents:
 
    installation_instructions
+   upgrading
    testing_instructions
    design
    reference
diff --git a/docs/upgrading.md b/docs/upgrading.md
new file mode 100644
index 0000000000000000000000000000000000000000..5e54888c9489633501d51aac268cda464b94a37e
--- /dev/null
+++ b/docs/upgrading.md
@@ -0,0 +1,18 @@
+# Upgrading OpenAppStack
+
+## From versions earlier than 0.2.3
+
+Upgrading from versions earlier than `0.2.3` requires manual
+intervention.
+
+* Move your local `settings.yml` file to a different location:
+
+    ```
+    cd CLUSTER_DIR
+    mkdir ./group_vars/all
+    mv settings.yml ./group_vars/all/
+    ```
+
+* remove all helm charts (WARNING: Please backup all data before!):
+
+    `helm delete --purge oas-prod-cert-manager oas-prod-local-storage oas-prod-prometheus oas-prod-proxy`