-
Notifications
You must be signed in to change notification settings - Fork 459
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add document explaining v1beta1 changes (#2902)
* Add document explaining v1beta1 changes * Document the CRD stored version migration
- Loading branch information
Showing
1 changed file
with
161 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 |