Allow instrumentation versions to be marked as unupgradable

.chloggen/feat_blocked-upgrades.yaml

@@ -0,0 +1,20 @@
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. collector, target allocator, auto-instrumentation, opamp, github action)
+component: auto-instrumentation
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Allow instrumentation upgrades to be blocked for versions containing major breaking changes.
+
+# One or more tracking issues related to the change
+issues: [4646, 2542]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Some instrumentation upgrades involve major breaking changes. The operator can't help with those, but it can
+  alert the user about them. This change makes this possible. It will also allow us to set the latest version
+  for new Instrumentation resources by default.
+  See https://github.com/open-telemetry/opentelemetry-operator/issues/2542 for the primary example.

apis/v1alpha1/instrumentation_types.go

@@ -378,7 +378,14 @@ type Nginx struct {
 }
 
 // InstrumentationStatus defines status of the instrumentation.
-type InstrumentationStatus struct{}
+type InstrumentationStatus struct {
+	// UpgradeBlockedVersions contains instrumentation language images whose
+	// versions could not be automatically upgraded, mapped to a message
+	// explaining why. The operator will not auto-upgrade these images until
+	// the user manually changes them to a supported version.
+	// +optional
+	UpgradeBlockedVersions map[string]string `json:"upgradeBlockedVersions,omitempty"`
+}
 
 // +kubebuilder:object:root=true
 // +kubebuilder:resource:shortName=otelinst;otelinsts

bundle/community/manifests/opentelemetry-operator.clusterserviceversion.yaml

@@ -99,7 +99,7 @@ metadata:
     categories: Logging & Tracing,Monitoring,Observability
     certified: "false"
     containerImage: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator
-    createdAt: "2026-04-10T09:34:47Z"
+    createdAt: "2026-04-12T16:43:57Z"
     description: Provides the OpenTelemetry components, including the Collector
     operators.operatorframework.io/builder: operator-sdk-v1.29.0
     operators.operatorframework.io/project_layout: go.kubebuilder.io/v3
@@ -475,6 +475,7 @@ spec:
           - opentelemetry.io
           resources:
           - clusterobservabilities/status
+          - instrumentations/status
           - opampbridges/status
           - opentelemetrycollectors/finalizers
           - opentelemetrycollectors/status

bundle/community/manifests/opentelemetry.io_instrumentations.yaml

@@ -2049,6 +2049,11 @@ spec:
                 type: object
             type: object
           status:
+            properties:
+              upgradeBlockedVersions:
+                additionalProperties:
+                  type: string
+                type: object
             type: object
         type: object
     served: true

bundle/openshift/manifests/opentelemetry-operator.clusterserviceversion.yaml

@@ -99,7 +99,7 @@ metadata:
     categories: Logging & Tracing,Monitoring,Observability
     certified: "false"
     containerImage: ghcr.io/open-telemetry/opentelemetry-operator/opentelemetry-operator
-    createdAt: "2026-04-10T09:34:52Z"
+    createdAt: "2026-04-12T16:43:57Z"
     description: Provides the OpenTelemetry components, including the Collector
     operators.operatorframework.io/builder: operator-sdk-v1.29.0
     operators.operatorframework.io/project_layout: go.kubebuilder.io/v3
@@ -475,6 +475,7 @@ spec:
           - opentelemetry.io
           resources:
           - clusterobservabilities/status
+          - instrumentations/status
           - opampbridges/status
           - opentelemetrycollectors/finalizers
           - opentelemetrycollectors/status

bundle/openshift/manifests/opentelemetry.io_instrumentations.yaml

@@ -2049,6 +2049,11 @@ spec:
                 type: object
             type: object
           status:
+            properties:
+              upgradeBlockedVersions:
+                additionalProperties:
+                  type: string
+                type: object
             type: object
         type: object
     served: true

config/crd/bases/opentelemetry.io_instrumentations.yaml

@@ -2047,6 +2047,11 @@ spec:
                 type: object
             type: object
           status:
+            properties:
+              upgradeBlockedVersions:
+                additionalProperties:
+                  type: string
+                type: object
             type: object
         type: object
     served: true

config/rbac/role.yaml

@@ -183,6 +183,7 @@ rules:
   - opentelemetry.io
   resources:
   - clusterobservabilities/status
+  - instrumentations/status
   - opampbridges/status
   - opentelemetrycollectors/finalizers
   - opentelemetrycollectors/status

docs/api/instrumentations.md

@@ -57,7 +57,7 @@ Instrumentation is the spec for OpenTelemetry instrumentation.
         </td>
         <td>false</td>
       </tr><tr>
-        <td><b>status</b></td>
+        <td><b><a href="#instrumentationstatus">status</a></b></td>
         <td>object</td>
         <td>
           InstrumentationStatus defines status of the instrumentation.<br/>
@@ -8158,4 +8158,34 @@ The value can be for instance parentbased_always_on, parentbased_always_off, par
         </td>
         <td>false</td>
       </tr></tbody>
+</table>
+
+
+### Instrumentation.status
+<sup><sup>[↩ Parent](#instrumentation)</sup></sup>
+
+
+
+InstrumentationStatus defines status of the instrumentation.
+
+<table>
+    <thead>
+        <tr>
+            <th>Name</th>
+            <th>Type</th>
+            <th>Description</th>
+            <th>Required</th>
+        </tr>
+    </thead>
+    <tbody><tr>
+        <td><b>upgradeBlockedVersions</b></td>
+        <td>map[string]string</td>
+        <td>
+          UpgradeBlockedVersions contains instrumentation language images whose
+versions could not be automatically upgraded, mapped to a message
+explaining why. The operator will not auto-upgrade these images until
+the user manually changes them to a supported version.<br/>
+        </td>
+        <td>false</td>
+      </tr></tbody>
 </table>

internal/instrumentation/upgrade/upgrade.go

@@ -6,20 +6,25 @@ package upgrade
 import (
 	"context"
 	"fmt"
+	"maps"
 	"reflect"
 
 	"github.com/go-logr/logr"
+	corev1 "k8s.io/api/core/v1"
 	"k8s.io/client-go/tools/events"
 	"sigs.k8s.io/controller-runtime/pkg/client"
 
 	"github.com/open-telemetry/opentelemetry-operator/apis/v1alpha1"
 	"github.com/open-telemetry/opentelemetry-operator/internal/config"
+	"github.com/open-telemetry/opentelemetry-operator/internal/version"
 	"github.com/open-telemetry/opentelemetry-operator/pkg/constants"
 )
 
 type autoInstConfig struct {
-	id      string
-	enabled bool
+	id           string
+	enabled      bool
+	language     constants.InstrumentationLanguage
+	defaultImage string
 }
 
 type InstrumentationUpgrade struct {
@@ -38,13 +43,13 @@ type InstrumentationUpgrade struct {
 
 func NewInstrumentationUpgrade(client client.Client, logger logr.Logger, recorder events.EventRecorder, cfg config.Config) *InstrumentationUpgrade {
 	defaultAnnotationToConfig := map[string]autoInstConfig{
-		constants.AnnotationDefaultAutoInstrumentationApacheHttpd: {"enable-apache-httpd-instrumentation", cfg.EnableApacheHttpdInstrumentation},
-		constants.AnnotationDefaultAutoInstrumentationDotNet:      {"enable-dotnet-instrumentation", cfg.EnableDotNetAutoInstrumentation},
-		constants.AnnotationDefaultAutoInstrumentationGo:          {"enable-go-instrumentation", cfg.EnableGoAutoInstrumentation},
-		constants.AnnotationDefaultAutoInstrumentationNginx:       {"enable-nginx-instrumentation", cfg.EnableNginxAutoInstrumentation},
-		constants.AnnotationDefaultAutoInstrumentationPython:      {"enable-python-instrumentation", cfg.EnablePythonAutoInstrumentation},
-		constants.AnnotationDefaultAutoInstrumentationNodeJS:      {"enable-nodejs-instrumentation", cfg.EnableNodeJSAutoInstrumentation},
-		constants.AnnotationDefaultAutoInstrumentationJava:        {"enable-java-instrumentation", cfg.EnableJavaAutoInstrumentation},
+		constants.AnnotationDefaultAutoInstrumentationApacheHttpd: {id: "enable-apache-httpd-instrumentation", enabled: cfg.EnableApacheHttpdInstrumentation, language: constants.InstrumentationLanguageApacheHttpd, defaultImage: cfg.AutoInstrumentationApacheHttpdImage},
+		constants.AnnotationDefaultAutoInstrumentationDotNet:      {id: "enable-dotnet-instrumentation", enabled: cfg.EnableDotNetAutoInstrumentation, language: constants.InstrumentationLanguageDotNet, defaultImage: cfg.AutoInstrumentationDotNetImage},
+		constants.AnnotationDefaultAutoInstrumentationGo:          {id: "enable-go-instrumentation", enabled: cfg.EnableGoAutoInstrumentation, language: constants.InstrumentationLanguageGo, defaultImage: cfg.AutoInstrumentationGoImage},
+		constants.AnnotationDefaultAutoInstrumentationNginx:       {id: "enable-nginx-instrumentation", enabled: cfg.EnableNginxAutoInstrumentation, language: constants.InstrumentationLanguageNginx, defaultImage: cfg.AutoInstrumentationNginxImage},
+		constants.AnnotationDefaultAutoInstrumentationPython:      {id: "enable-python-instrumentation", enabled: cfg.EnablePythonAutoInstrumentation, language: constants.InstrumentationLanguagePython, defaultImage: cfg.AutoInstrumentationPythonImage},
+		constants.AnnotationDefaultAutoInstrumentationNodeJS:      {id: "enable-nodejs-instrumentation", enabled: cfg.EnableNodeJSAutoInstrumentation, language: constants.InstrumentationLanguageNodeJS, defaultImage: cfg.AutoInstrumentationNodeJSImage},
+		constants.AnnotationDefaultAutoInstrumentationJava:        {id: "enable-java-instrumentation", enabled: cfg.EnableJavaAutoInstrumentation, language: constants.InstrumentationLanguageJava, defaultImage: cfg.AutoInstrumentationJavaImage},
 	}
 
 	return &InstrumentationUpgrade{
@@ -63,6 +68,7 @@ func NewInstrumentationUpgrade(client client.Client, logger logr.Logger, recorde
 }
 
 // +kubebuilder:rbac:groups=opentelemetry.io,resources=instrumentations,verbs=get;list;watch;update;patch
+// +kubebuilder:rbac:groups=opentelemetry.io,resources=instrumentations/status,verbs=get;update;patch
 
 // ManagedInstances upgrades managed instances by the opentelemetry-operator.
 func (u *InstrumentationUpgrade) ManagedInstances(ctx context.Context) error {
@@ -74,14 +80,21 @@ func (u *InstrumentationUpgrade) ManagedInstances(ctx context.Context) error {
 
 	for i := range list.Items {
 		toUpgrade := list.Items[i]
-		upgraded := u.upgrade(ctx, toUpgrade)
+		upgraded, blockedVersions := u.upgrade(ctx, toUpgrade)
 		if !reflect.DeepEqual(upgraded, toUpgrade) {
 			// use update instead of patch because the patch does not upgrade annotations
 			if err := u.Client.Update(ctx, upgraded); err != nil {
 				u.Logger.Error(err, "failed to apply changes to instance", "name", upgraded.Name, "namespace", upgraded.Namespace)
 				continue
 			}
 		}
+		// Update status if the blocked versions set has changed (including clearing it when no longer blocked).
+		if !maps.Equal(upgraded.Status.UpgradeBlockedVersions, blockedVersions) {
+			upgraded.Status.UpgradeBlockedVersions = blockedVersions
+			if err := u.Client.Status().Update(ctx, upgraded); err != nil {
+				u.Logger.Error(err, "failed to update status for blocked upgrade", "name", upgraded.Name, "namespace", upgraded.Namespace)
+			}
+		}
 	}
 
 	if len(list.Items) == 0 {
@@ -90,12 +103,33 @@ func (u *InstrumentationUpgrade) ManagedInstances(ctx context.Context) error {
 	return nil
 }
 
-func (u *InstrumentationUpgrade) upgrade(_ context.Context, inst v1alpha1.Instrumentation) *v1alpha1.Instrumentation {
-	upgraded := inst.DeepCopy()
+func (u *InstrumentationUpgrade) upgrade(_ context.Context, inst v1alpha1.Instrumentation) (
+	upgraded *v1alpha1.Instrumentation, blockedVersions map[string]string,
+) {
+	upgraded = inst.DeepCopy()
 	for annotation, instCfg := range u.defaultAnnotationToConfig {
 		autoInst := upgraded.Annotations[annotation]
 		if autoInst != "" {
 			if instCfg.enabled {
+				// Check if the current version is unupgradable
+				if isUnupgradable, warningMsg := version.IsInstrumentationVersionUnupgradable(instCfg.language, autoInst, instCfg.defaultImage); isUnupgradable {
+					msg := fmt.Sprintf("Automated upgrade blocked for %s: version is marked as unupgradable. Manual upgrade required.", instCfg.language)
+					if warningMsg != "" {
+						msg = fmt.Sprintf("Automated upgrade blocked for %s: %s", instCfg.language, warningMsg)
+					}
+					u.Recorder.Eventf(upgraded, nil, corev1.EventTypeWarning, "UpgradeBlocked", "Upgrade", msg)
+					u.Logger.Info("upgrade blocked for unupgradable instrumentation version",
+						"name", inst.Name,
+						"namespace", inst.Namespace,
+						"language", instCfg.language,
+						"image", autoInst)
+					if blockedVersions == nil {
+						blockedVersions = make(map[string]string)
+					}
+					blockedVersions[string(instCfg.language)] = msg
+					continue // Skip upgrade for this language
+				}
+
 				switch annotation {
 				case constants.AnnotationDefaultAutoInstrumentationApacheHttpd:
 					if inst.Spec.ApacheHttpd.Image == autoInst {
@@ -139,5 +173,5 @@ func (u *InstrumentationUpgrade) upgrade(_ context.Context, inst v1alpha1.Instru
 		}
 	}
 
-	return upgraded
+	return upgraded, blockedVersions
 }