Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add a separate compatibility document #3393

Merged
merged 1 commit into from
Oct 29, 2024
Merged

Add a separate compatibility document #3393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 3 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -790,53 +790,9 @@ The priority for setting resource attributes is as follows (first found wins):
This priority is applied for each resource attribute separately, so it is possible to set some attributes via
annotations and others via labels.

## Compatibility matrix

### OpenTelemetry Operator vs. OpenTelemetry Collector

The OpenTelemetry Operator follows the same versioning as the operand (OpenTelemetry Collector) up to the minor part of the version. For example, the OpenTelemetry Operator v0.18.1 tracks OpenTelemetry Collector 0.18.0. The patch part of the version indicates the patch level of the operator itself, not that of OpenTelemetry Collector. Whenever a new patch version is released for OpenTelemetry Collector, we'll release a new patch version of the operator.

By default, the OpenTelemetry Operator ensures consistent versioning between itself and the managed `OpenTelemetryCollector` resources. That is, if the OpenTelemetry Operator is based on version `0.40.0`, it will create resources with an underlying OpenTelemetry Collector at version `0.40.0`.

When a custom `Spec.Image` is used with an `OpenTelemetryCollector` resource, the OpenTelemetry Operator will not manage this versioning and upgrading. In this scenario, it is best practice that the OpenTelemetry Operator version should match the underlying core version. Given a `OpenTelemetryCollector` resource with a `Spec.Image` configured to a custom image based on underlying OpenTelemetry Collector at version `0.40.0`, it is recommended that the OpenTelemetry Operator is kept at version `0.40.0`.

### OpenTelemetry Operator vs. Kubernetes vs. Cert Manager vs Prometheus Operator

We strive to be compatible with the widest range of Kubernetes versions as possible, but some changes to Kubernetes itself require us to break compatibility with older Kubernetes versions, be it because of code incompatibilities, or in the name of maintainability. Every released operator will support a specific range of Kubernetes versions, to be determined at the latest during the release.

We use `cert-manager` for some features of this operator and the third column shows the versions of the `cert-manager` that are known to work with this operator's versions.

The Target Allocator supports prometheus-operator CRDs like ServiceMonitor, and it does so by using packages imported from prometheus-operator itself. The table shows which version is shipped with a given operator version.
Generally speaking, these are backwards compatible, but specific features require the appropriate package versions.

The OpenTelemetry Operator _might_ work on versions outside of the given range, but when opening new issues, please make sure to test your scenario on a supported version.

| OpenTelemetry Operator | Kubernetes | Cert-Manager | Prometheus-Operator |
|------------------------|----------------| ------------ |---------------------|
| v0.111.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.110.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.109.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.108.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.107.0 | v1.23 to v1.30 | v1 | v0.75.0 |
| v0.106.0 | v1.23 to v1.30 | v1 | v0.75.0 |
| v0.105.0 | v1.23 to v1.30 | v1 | v0.74.0 |
| v0.104.0 | v1.23 to v1.30 | v1 | v0.74.0 |
| v0.103.0 | v1.23 to v1.30 | v1 | v0.74.0 |
| v0.102.0 | v1.23 to v1.30 | v1 | v0.71.2 |
| v0.101.0 | v1.23 to v1.30 | v1 | v0.71.2 |
| v0.100.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.99.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.98.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.97.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.96.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.95.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.94.0 | v1.23 to v1.29 | v1 | v0.71.0 |
| v0.93.0 | v1.23 to v1.29 | v1 | v0.71.0 |
| v0.92.0 | v1.23 to v1.29 | v1 | v0.71.0 |
| v0.91.0 | v1.23 to v1.29 | v1 | v0.70.0 |
| v0.90.0 | v1.23 to v1.28 | v1 | v0.69.1 |
| v0.89.0 | v1.23 to v1.28 | v1 | v0.69.1 |
| v0.88.0 | v1.23 to v1.28 | v1 | v0.68.0 |
## Compatibility

See [here](docs/compatibility.md).

## Contributing and Developing

Expand Down
2 changes: 1 addition & 1 deletion RELEASE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Steps to release a new version of the OpenTelemetry Operator:
> DO NOT BUMP JAVA PAST `1.X.X` AND DO NOT BUMP .NET PAST `1.2.0`. Upgrades past these versions will introduce breaking HTTP semantic convention changes.
1. Check if the compatible OpenShift versions are updated in the `Makefile`.
1. Update the bundle by running `make bundle VERSION=$VERSION`.
1. Change the compatibility matrix in the [readme](./README.md) file, using the OpenTelemetry Operator version to be released and the current latest Kubernetes version as the latest supported version. Remove the oldest entry.
1. Change the compatibility matrix in the [compatibility doc](./docs/compatibility.md) file, using the OpenTelemetry Operator version to be released and the current latest Kubernetes version as the latest supported version. Remove the oldest entry.
1. Update release schedule table, by moving the current release manager to the end of the table with updated release version.
1. Add the changes to the changelog by running `make chlog-update VERSION=$VERSION`.
1. Check the OpenTelemetry Collector's changelog and ensure migration steps are present in `pkg/collector/upgrade`
Expand Down
49 changes: 49 additions & 0 deletions docs/compatibility.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
# Compatibility

This document details compatibility guarantees the OpenTelemetry Operator offers for its dependencies and platforms.

## OpenTelemetry Operator vs. OpenTelemetry Collector

The OpenTelemetry Operator follows the same versioning as the operand (OpenTelemetry Collector) up to the minor part of the version. For example, the OpenTelemetry Operator v0.18.1 tracks OpenTelemetry Collector 0.18.0. The patch part of the version indicates the patch level of the operator itself, not that of OpenTelemetry Collector. Whenever a new patch version is released for OpenTelemetry Collector, we'll release a new patch version of the operator.

By default, the OpenTelemetry Operator ensures consistent versioning between itself and the managed `OpenTelemetryCollector` resources. That is, if the OpenTelemetry Operator is based on version `0.40.0`, it will create resources with an underlying OpenTelemetry Collector at version `0.40.0`.

When a custom `Spec.Image` is used with an `OpenTelemetryCollector` resource, the OpenTelemetry Operator will not manage this versioning and upgrading. In this scenario, it is best practice that the OpenTelemetry Operator version should match the underlying core version. Given a `OpenTelemetryCollector` resource with a `Spec.Image` configured to a custom image based on underlying OpenTelemetry Collector at version `0.40.0`, it is recommended that the OpenTelemetry Operator is kept at version `0.40.0`.

## Compatibility matrix

We strive to be compatible with the widest range of Kubernetes versions as possible, but some changes to Kubernetes itself require us to break compatibility with older Kubernetes versions, be it because of code incompatibilities, or in the name of maintainability. Every released operator will support a specific range of Kubernetes versions, to be determined at the latest during the release.

We use `cert-manager` for some features of this operator and the third column shows the versions of the `cert-manager` that are known to work with this operator's versions.

The Target Allocator supports prometheus-operator CRDs like ServiceMonitor, and it does so by using packages imported from prometheus-operator itself. The table shows which version is shipped with a given operator version.
Generally speaking, these are backwards compatible, but specific features require the appropriate package versions.

The OpenTelemetry Operator _might_ work on versions outside of the given range, but when opening new issues, please make sure to test your scenario on a supported version.

| OpenTelemetry Operator | Kubernetes | Cert-Manager | Prometheus-Operator |
|------------------------|----------------| ------------ |---------------------|
| v0.111.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.110.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.109.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.108.0 | v1.23 to v1.31 | v1 | v0.76.0 |
| v0.107.0 | v1.23 to v1.30 | v1 | v0.75.0 |
| v0.106.0 | v1.23 to v1.30 | v1 | v0.75.0 |
| v0.105.0 | v1.23 to v1.30 | v1 | v0.74.0 |
| v0.104.0 | v1.23 to v1.30 | v1 | v0.74.0 |
| v0.103.0 | v1.23 to v1.30 | v1 | v0.74.0 |
| v0.102.0 | v1.23 to v1.30 | v1 | v0.71.2 |
| v0.101.0 | v1.23 to v1.30 | v1 | v0.71.2 |
| v0.100.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.99.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.98.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.97.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.96.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.95.0 | v1.23 to v1.29 | v1 | v0.71.2 |
| v0.94.0 | v1.23 to v1.29 | v1 | v0.71.0 |
| v0.93.0 | v1.23 to v1.29 | v1 | v0.71.0 |
| v0.92.0 | v1.23 to v1.29 | v1 | v0.71.0 |
| v0.91.0 | v1.23 to v1.29 | v1 | v0.70.0 |
| v0.90.0 | v1.23 to v1.28 | v1 | v0.69.1 |
| v0.89.0 | v1.23 to v1.28 | v1 | v0.69.1 |
| v0.88.0 | v1.23 to v1.28 | v1 | v0.68.0 |
Loading