From 255092fcfb8a86cd07d1ce9736eeabcf8009f90b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miko=C5=82aj=20=C5=9Awi=C4=85tek?= Date: Tue, 30 Apr 2024 18:45:42 +0000 Subject: [PATCH] Add document explaining v1beta1 changes (#2902) * Add document explaining v1beta1 changes * Document the CRD stored version migration --- docs/crd-changelog.md | 161 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/crd-changelog.md diff --git a/docs/crd-changelog.md b/docs/crd-changelog.md new file mode 100644 index 0000000000..a3e54660b9 --- /dev/null +++ b/docs/crd-changelog.md @@ -0,0 +1,161 @@ +# 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. + +## OpenTelemetryCollector.opentelemetry.io/v1beta1 + +### Migration + +There is no need for any immediate user action. The operator will continue to support existing `v1alpha1` resources. + +In addition, any newly applied `v1alpha1` resource will be converted to `v1beta1` and stored in the new API version. + +The plan is to remove support for `v1alpha1` in a future operator version, so users should migrate promptly. In order to migrate fully to `v1beta1`: + +1. Update any manifests you have stored outside the cluster, for example in your infrastructure git repository. +2. Apply them, so they're all stored as `v1beta1`. +3. Update the OpenTelemetryCollector CRD to only store `v1beta1` + ```bash + kubectl patch customresourcedefinitions opentelemetrycollectors.opentelemetry.io \ + --subresource='status' \ + --type='merge' \ + -p '{"status":{"storedVersions":["v1beta1"]}}' + ``` +For a more thorough explanation of how and why this migration works, see the relevant [Kubernetes documentation][crd_migration_guide]. + +#### Operator Lifecycle Manager + +If you're installing the opentelemetry-operator in OpenShift using OLM, be advised that +**only `AllNamespaces` install mode is now supported**, due to the conversion webhook from `v1beta1` to `v1alpha1`. +See [OLM docs](https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/) and +[OLM operator groups docs](https://olm.operatorframework.io/docs/advanced-tasks/operator-scoping-with-operatorgroups/). + +### 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 +[crd_migration_guide]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#upgrade-existing-objects-to-a-new-stored-version \ No newline at end of file