From 1386e9878701746641a3dd5c91fb1640c2016c47 Mon Sep 17 00:00:00 2001
From: Povilas Versockas <povilas.versockas@coralogix.com>
Date: Tue, 21 Nov 2023 09:47:13 +0200
Subject: [PATCH] [otel-integration] add upgrading docs (#331)

* [otel-integration] add upgrading docs

* Apply suggestions from code review

Co-authored-by: Matej Gera <38492574+matej-g@users.noreply.github.com>

---------

Co-authored-by: Matej Gera <38492574+matej-g@users.noreply.github.com>
---
 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..50506469
--- /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 to add `metricstransform/k8s-dashboard` and `transform/k8s-dashboard` processors to your pipeline.
+
+Previously, we had cluster collector's metrics pipeline that 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.