Add document explaining v1beta1 changes

docs/crd-changelog.md

@@ -0,0 +1,138 @@
+# CRD Changelog
+
+This document explains major changes made in new CRD versions. It is intended to help users migrate and take
+advantage of the new features.
+
+## opentelemetry.io/v1beta1 OpenTelemetryCollector
+
+### Migration
+
+There is no need for any user action. The operator will automatically convert existing `v1alpha1` resources to `v1beta1`.
+
+### Structured Configuration
+
+The `Config` field containing the Collector configuration is a string in `v1alpha1`. This has some downsides:
+
+- It's easy to make YAML formatting errors in the content.
+- The field can have a lot of content, and may not show useful diffs for changes.
+- It's more difficult for the operator to reject invalid configurations at admission.
+
+To solve these issues, we've changed the type of this field to a structure aligned with OpenTelemetry Collector configuration
+format. For example:
+
+```yaml
+apiVersion: opentelemetry.io/v1alpha1
+kind: OpenTelemetryCollector
+metadata:
+  name: simplest
+spec:
+  config: |
+    receivers:
+      otlp:
+        protocols:
+          grpc:
+          http:
+    processors:
+      memory_limiter:
+        check_interval: 1s
+        limit_percentage: 75
+        spike_limit_percentage: 15
+      batch:
+        send_batch_size: 10000
+        timeout: 10s
+
+    exporters:
+      debug:
+
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          processors: [memory_limiter, batch]
+          exporters: [debug]
+```
+
+becomes:
+
+```yaml
+apiVersion: opentelemetry.io/v1beta1
+kind: OpenTelemetryCollector
+metadata:
+  name: simplest
+spec:
+  config:
+    receivers:
+      otlp:
+        protocols:
+          grpc: {}
+          http: {}
+    processors:
+      memory_limiter:
+        check_interval: 1s
+        limit_percentage: 75
+        spike_limit_percentage: 15
+      batch:
+        send_batch_size: 10000
+        timeout: 10s
+    exporters:
+      debug: {}
+    service:
+      pipelines:
+        traces:
+          receivers: [otlp]
+          processors: [memory_limiter, batch]
+          exporters: [debug]
+```
+
+> [!NOTE]  
+> Empty maps, like `debug:` in the above configuration, should have an explicit value of `{}`.
+
+### Standard label selectors for Target Allocator
+
+Configuring the target allocator to use Prometheus CRDs can involve setting label selectors for said CRDs. In the
+`v1alpha1` Collector, these were simply maps representing the required labels. In order to allow more complex label
+selection rules and align with Kubernetes' recommended way of solving this kind of problem, we've switched to
+[standard selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
+
+For example, in `v1alpha1` we'd have:
+
+```yaml
+apiVersion: opentelemetry.io/v1alpha1
+kind: OpenTelemetryCollector
+metadata:
+  name: simplest
+spec:
+  targetAllocator:
+    prometheusCR:
+      serviceMonitorSelector:
+        key: value
+```
+
+And in `v1beta1`:
+
+```yaml
+apiVersion: opentelemetry.io/v1beta1
+kind: OpenTelemetryCollector
+metadata:
+  name: simplest
+spec:
+  targetAllocator:
+    prometheusCR:
+      serviceMonitorSelector:
+        matchLabels:   
+          key: value
+```
+
+### Default Collector image
+
+The OpenTelemetry Collector maintainers recently introduced a [Collector distribution][k8s_distro] specifically aimed at 
+Kubernetes workloads.
+
+Our intent is to eventually use this distribution as our default collector image, as opposed to the 
+[core distribution][core_distro] we're currently using. After some debate, we've decided NOT to make this change in
+`v1beta1`, but rather roll it out more gradually, and with more warning to users. See [this issue][k8s_issue] for more information.
+
+
+[core_distro]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol
+[k8s_distro]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-k8s
+[k8s_issue]: https://github.com/open-telemetry/opentelemetry-operator/issues/2835