From 8cc2c5551241cd9785545a012083a0e0d008a91d Mon Sep 17 00:00:00 2001
From: Povilas Versockas <povilas.versockas@coralogix.com>
Date: Mon, 20 Nov 2023 15:20:52 +0200
Subject: [PATCH] [otel-integration] add upgrading docs

---
 otel-integration/README.md    |  4 +++
 otel-integration/UPGRADING.md | 52 +++++++++++++++++++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 otel-integration/UPGRADING.md

diff --git a/otel-integration/README.md b/otel-integration/README.md
index 956a2864..3ccf80fc 100644
--- a/otel-integration/README.md
+++ b/otel-integration/README.md
@@ -1,3 +1,7 @@
 # OpenTelemetry Integration
 
 The OpenTelemetry integration projects offers a full-fledged integration to collect and export telemetry signals from your infrastructure and applications. Currently this integration is available for Kubernetes on Linux platforms, please see the [`k8s-helm`](./k8s-helm) subdirectory for installation instructions.
+
+## Upgrading
+
+See [UPGRADING.md](UPGRADING.md).
diff --git a/otel-integration/UPGRADING.md b/otel-integration/UPGRADING.md
new file mode 100644
index 00000000..1c48b4da
--- /dev/null
+++ b/otel-integration/UPGRADING.md
@@ -0,0 +1,52 @@
+# Upgrade guidelines
+
+These upgrade guidelines only contain instructions for version upgrades which require manual modifications on the user's side.
+If the version you want to upgrade to is not listed here, then there is nothing to do for you.
+Just upgrade and enjoy.
+
+## 0.0.32 to 0.0.33
+
+Opentelemetry Integration v0.33 has removed Kube State Metrics deployment, as the needed resource attributes and metrics are now part of OpenTelemetry Kubernetes Cluster Receiver.
+
+We removed `metricstransform/kube-extra-metrics` processor, as it was transforming `kube-state-metrics` metrics. And added two processors `metricstransform/k8s-dashboard` and `transform/k8s-dashboard` which transforms OTEL format into the format which Coralogix Kubernetes Dashboard uses.
+
+If you manually configured the opentelemetry-cluster-collectors metrics pipeline, you will need add `metricstransform/k8s-dashboard` and `transform/k8s-dashboard` processors to your pipeline.
+
+Previously, we had cluster collector's metrics pipeline looked like this:
+
+```
+opentelemetry-cluster-collector:
+   ...
+        metrics:
+          exporters:
+            - coralogix
+          processors:
+            - k8sattributes
+            - metricstransform/kube-extra-metrics
+            - resourcedetection/env
+            - resourcedetection/region
+            - memory_limiter
+            - batch
+
+```
+
+Now, the new cluster collector's metrics pipeline should look like this:
+
+```
+opentelemetry-cluster-collector:
+   ...
+        metrics:
+          exporters:
+            - coralogix
+          processors:
+            - k8sattributes
+            - metricstransform/k8s-dashboard
+            - transform/k8s-dashboard
+            - resourcedetection/env
+            - resourcedetection/region
+            - memory_limiter
+            - batch
+
+```
+
+If you didn't configure the metrics pipeline for opentelemetry-cluster-collector, this is not a breaking change.