Skip to content

Commit 5ca66dd

Browse files
authored
Add document explaining v1beta1 changes (#2902)
* Add document explaining v1beta1 changes * Document the CRD stored version migration
1 parent 48bc207 commit 5ca66dd

File tree

1 file changed

+161
-0
lines changed

1 file changed

+161
-0
lines changed

docs/crd-changelog.md

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
# CRD Changelog
2+
3+
This document explains major changes made in new CRD versions. It is intended to help users migrate and take
4+
advantage of the new features.
5+
6+
## OpenTelemetryCollector.opentelemetry.io/v1beta1
7+
8+
### Migration
9+
10+
There is no need for any immediate user action. The operator will continue to support existing `v1alpha1` resources.
11+
12+
In addition, any newly applied `v1alpha1` resource will be converted to `v1beta1` and stored in the new API version.
13+
14+
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`:
15+
16+
1. Update any manifests you have stored outside the cluster, for example in your infrastructure git repository.
17+
2. Apply them, so they're all stored as `v1beta1`.
18+
3. Update the OpenTelemetryCollector CRD to only store `v1beta1`
19+
```bash
20+
kubectl patch customresourcedefinitions opentelemetrycollectors.opentelemetry.io \
21+
--subresource='status' \
22+
--type='merge' \
23+
-p '{"status":{"storedVersions":["v1beta1"]}}'
24+
```
25+
For a more thorough explanation of how and why this migration works, see the relevant [Kubernetes documentation][crd_migration_guide].
26+
27+
#### Operator Lifecycle Manager
28+
29+
If you're installing the opentelemetry-operator in OpenShift using OLM, be advised that
30+
**only `AllNamespaces` install mode is now supported**, due to the conversion webhook from `v1beta1` to `v1alpha1`.
31+
See [OLM docs](https://olm.operatorframework.io/docs/tasks/install-operator-with-olm/) and
32+
[OLM operator groups docs](https://olm.operatorframework.io/docs/advanced-tasks/operator-scoping-with-operatorgroups/).
33+
34+
### Structured Configuration
35+
36+
The `Config` field containing the Collector configuration is a string in `v1alpha1`. This has some downsides:
37+
38+
- It's easy to make YAML formatting errors in the content.
39+
- The field can have a lot of content, and may not show useful diffs for changes.
40+
- It's more difficult for the operator to reject invalid configurations at admission.
41+
42+
To solve these issues, we've changed the type of this field to a structure aligned with OpenTelemetry Collector configuration
43+
format. For example:
44+
45+
```yaml
46+
apiVersion: opentelemetry.io/v1alpha1
47+
kind: OpenTelemetryCollector
48+
metadata:
49+
name: simplest
50+
spec:
51+
config: |
52+
receivers:
53+
otlp:
54+
protocols:
55+
grpc:
56+
http:
57+
processors:
58+
memory_limiter:
59+
check_interval: 1s
60+
limit_percentage: 75
61+
spike_limit_percentage: 15
62+
batch:
63+
send_batch_size: 10000
64+
timeout: 10s
65+
66+
exporters:
67+
debug:
68+
69+
service:
70+
pipelines:
71+
traces:
72+
receivers: [otlp]
73+
processors: [memory_limiter, batch]
74+
exporters: [debug]
75+
```
76+
77+
becomes:
78+
79+
```yaml
80+
apiVersion: opentelemetry.io/v1beta1
81+
kind: OpenTelemetryCollector
82+
metadata:
83+
name: simplest
84+
spec:
85+
config:
86+
receivers:
87+
otlp:
88+
protocols:
89+
grpc: {}
90+
http: {}
91+
processors:
92+
memory_limiter:
93+
check_interval: 1s
94+
limit_percentage: 75
95+
spike_limit_percentage: 15
96+
batch:
97+
send_batch_size: 10000
98+
timeout: 10s
99+
exporters:
100+
debug: {}
101+
service:
102+
pipelines:
103+
traces:
104+
receivers: [otlp]
105+
processors: [memory_limiter, batch]
106+
exporters: [debug]
107+
```
108+
109+
> [!NOTE]
110+
> Empty maps, like `debug:` in the above configuration, should have an explicit value of `{}`.
111+
112+
### Standard label selectors for Target Allocator
113+
114+
Configuring the target allocator to use Prometheus CRDs can involve setting label selectors for said CRDs. In the
115+
`v1alpha1` Collector, these were simply maps representing the required labels. In order to allow more complex label
116+
selection rules and align with Kubernetes' recommended way of solving this kind of problem, we've switched to
117+
[standard selectors](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
118+
119+
For example, in `v1alpha1` we'd have:
120+
121+
```yaml
122+
apiVersion: opentelemetry.io/v1alpha1
123+
kind: OpenTelemetryCollector
124+
metadata:
125+
name: simplest
126+
spec:
127+
targetAllocator:
128+
prometheusCR:
129+
serviceMonitorSelector:
130+
key: value
131+
```
132+
133+
And in `v1beta1`:
134+
135+
```yaml
136+
apiVersion: opentelemetry.io/v1beta1
137+
kind: OpenTelemetryCollector
138+
metadata:
139+
name: simplest
140+
spec:
141+
targetAllocator:
142+
prometheusCR:
143+
serviceMonitorSelector:
144+
matchLabels:
145+
key: value
146+
```
147+
148+
### Default Collector image
149+
150+
The OpenTelemetry Collector maintainers recently introduced a [Collector distribution][k8s_distro] specifically aimed at
151+
Kubernetes workloads.
152+
153+
Our intent is to eventually use this distribution as our default collector image, as opposed to the
154+
[core distribution][core_distro] we're currently using. After some debate, we've decided NOT to make this change in
155+
`v1beta1`, but rather roll it out more gradually, and with more warning to users. See [this issue][k8s_issue] for more information.
156+
157+
158+
[core_distro]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol
159+
[k8s_distro]: https://github.com/open-telemetry/opentelemetry-collector-releases/tree/main/distributions/otelcol-k8s
160+
[k8s_issue]: https://github.com/open-telemetry/opentelemetry-operator/issues/2835
161+
[crd_migration_guide]: https://kubernetes.io/docs/tasks/extend-kubernetes/custom-resources/custom-resource-definition-versioning/#upgrade-existing-objects-to-a-new-stored-version

0 commit comments

Comments
 (0)