add extensions framework to supervisor

Author: dpaasman00

.chloggen/dpaasman00_supervisor-extensions-framework.yaml

@@ -0,0 +1,27 @@
+# Use this changelog template to create an entry for release notes.
+
+# 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. receiver/filelog)
+component: cmd/opampsupervisor
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Adds a framework for the supervisor to utilize extensions from the collector ecosystem
+
+# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists.
+issues: [47690]
+
+# (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:
+
+# If your change doesn't affect end users or the exported elements of any package,
+# you should instead start your pull request title with [chore] or use the "Skip Changelog" label.
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: []

cmd/opampsupervisor/documentation.md

@@ -0,0 +1,13 @@
+[comment]: <> (Code generated by mdatagen. DO NOT EDIT.)
+
+# opampsupervisor
+
+## Feature Gates
+
+This component has the following feature gates:
+
+| Feature Gate | Stage | Description | From Version | To Version | Reference |
+| ------------ | ----- | ----------- | ------------ | ---------- | --------- |
+| `opampsupervisor.Extensions` | alpha | When enabled, the opampsupervisor can be configured with and use specific extensions from the collector ecosystem. | v0.151.0 | N/A | [Link](https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/47690) |
+
+For more information about feature gates, see the [Feature Gates](https://github.com/open-telemetry/opentelemetry-collector/blob/main/featuregate/README.md) documentation.

cmd/opampsupervisor/e2e_test.go

@@ -41,11 +41,13 @@ import (
 	"github.com/open-telemetry/opamp-go/server/types"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
+	"go.opentelemetry.io/collector/featuregate"
 	"go.opentelemetry.io/collector/pdata/ptrace"
 	"go.uber.org/zap"
 	"go.uber.org/zap/zapcore"
 	"google.golang.org/protobuf/proto"
 
+	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/internal/metadata"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor/config"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor/telemetry"
@@ -2694,3 +2696,54 @@ func TestSupervisorValidatesConfigBeforeApplying(t *testing.T) {
 		})
 	}
 }
+
+func TestSupervisorExtensionsFeatureGateRequired(t *testing.T) {
+	t.Run("feature-gate disabled", func(t *testing.T) {
+		// Render configuration with nop extension
+		cfgFile := getSupervisorConfig(t, "extensions", map[string]string{
+			"url": "localhost:0",
+		})
+		cfg, err := config.Load(cfgFile.Name())
+		require.NoError(t, err)
+
+		// Attempt to create a supervisor with an extensions config. The feature
+		// gate is disabled by default, so supervisor.NewSupervisor must fail with an error
+		// that references the feature gate and how to enable it.
+		s, err := supervisor.NewSupervisor(t.Context(), zap.NewNop(), cfg)
+		require.Nil(t, s)
+		require.Contains(t, err.Error(), metadata.OpampsupervisorExtensionsFeatureGate.ID())
+		require.Contains(t, err.Error(), "--feature-gates=")
+	})
+
+	t.Run("feature-gate enabled", func(t *testing.T) {
+		// Create basic opamp server to check that the supervisor connects
+		connected := atomic.Bool{}
+		server := newOpAMPServer(t, defaultConnectingHandler, types.ConnectionCallbacks{
+			OnConnected: func(context.Context, types.Connection) {
+				connected.Store(true)
+			},
+		})
+
+		// Enable extensions feature-gate
+		err := featuregate.GlobalRegistry().Set(metadata.OpampsupervisorExtensionsFeatureGate.ID(), true)
+		require.NoError(t, err)
+		t.Cleanup(func() {
+			require.NoError(t, featuregate.GlobalRegistry().Set(metadata.OpampsupervisorExtensionsFeatureGate.ID(), false))
+		})
+
+		// Create supervisor with configuration that has nop extension
+		s, _ := newSupervisor(t,
+			"extensions",
+			map[string]string{
+				"url": server.addr,
+			},
+		)
+
+		// Start supervisor and wait for successful connection
+		t.Cleanup(s.Shutdown)
+		require.NoError(t, s.Start(t.Context()))
+
+		waitForSupervisorConnection(server.supervisorConnected, true)
+		require.True(t, connected.Load(), "Supervisor failed to connect")
+	})
+}

cmd/opampsupervisor/go.mod

@@ -13,6 +13,7 @@ require (
 	github.com/open-telemetry/opentelemetry-collector-contrib/testbed v0.150.0
 	github.com/stretchr/testify v1.11.1
 	go.opentelemetry.io/collector/component v1.56.1-0.20260415114935-307e3abdbae9
+	go.opentelemetry.io/collector/component/componenttest v0.150.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/config/confighttp v0.150.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/config/confignet v1.56.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/config/configopaque v1.56.1-0.20260415114935-307e3abdbae9
@@ -21,6 +22,10 @@ require (
 	go.opentelemetry.io/collector/confmap v1.56.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/confmap/provider/envprovider v1.56.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/confmap/provider/fileprovider v1.56.1-0.20260415114935-307e3abdbae9
+	go.opentelemetry.io/collector/confmap/xconfmap v0.150.1-0.20260415114935-307e3abdbae9
+	go.opentelemetry.io/collector/extension v1.56.1-0.20260415114935-307e3abdbae9
+	go.opentelemetry.io/collector/extension/extensiontest v0.150.1-0.20260415114935-307e3abdbae9
+	go.opentelemetry.io/collector/featuregate v1.56.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/pdata v1.56.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/collector/service v0.150.1-0.20260415114935-307e3abdbae9
 	go.opentelemetry.io/contrib/bridges/otelzap v0.18.0
@@ -154,14 +159,12 @@ require (
 	go.opentelemetry.io/collector v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/client v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/component/componentstatus v0.150.1-0.20260415114935-307e3abdbae9 // indirect
-	go.opentelemetry.io/collector/component/componenttest v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/config/configauth v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/config/configcompression v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/config/configgrpc v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/config/configmiddleware v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/config/configoptional v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/config/configretry v1.56.1-0.20260415114935-307e3abdbae9 // indirect
-	go.opentelemetry.io/collector/confmap/xconfmap v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/connector v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/connector/connectortest v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/connector/xconnector v0.150.1-0.20260415114935-307e3abdbae9 // indirect
@@ -178,14 +181,11 @@ require (
 	go.opentelemetry.io/collector/exporter/otlpexporter v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/exporter/otlphttpexporter v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/exporter/xexporter v0.150.1-0.20260415114935-307e3abdbae9 // indirect
-	go.opentelemetry.io/collector/extension v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/extension/extensionauth v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/extension/extensioncapabilities v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/extension/extensionmiddleware v0.150.1-0.20260415114935-307e3abdbae9 // indirect
-	go.opentelemetry.io/collector/extension/extensiontest v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/extension/xextension v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/extension/zpagesextension v0.150.1-0.20260415114935-307e3abdbae9 // indirect
-	go.opentelemetry.io/collector/featuregate v1.56.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/internal/componentalias v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/internal/fanoutconsumer v0.150.1-0.20260415114935-307e3abdbae9 // indirect
 	go.opentelemetry.io/collector/internal/memorylimiter v0.150.1-0.20260415114935-307e3abdbae9 // indirect

cmd/opampsupervisor/internal/metadata/generated_feature_gates.go

@@ -11,6 +11,8 @@ import (
 	"os"
 	"os/signal"
 
+	"go.opentelemetry.io/collector/featuregate"
+
 	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor/config"
 	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor/telemetry"
@@ -24,6 +26,7 @@ func main() {
 
 func runInteractive() error {
 	configFlag := flag.String("config", "", "Path to a supervisor configuration file")
+	featuregate.GlobalRegistry().RegisterFlags(flag.CommandLine)
 	flag.Parse()
 
 	cfg, err := config.Load(*configFlag)

cmd/opampsupervisor/main.go

@@ -7,3 +7,11 @@ status:
     alpha: [metrics]
   codeowners:
     active: [evan-bradley, atoulme, tigrannajaryan]
+
+feature_gates:
+  - id: opampsupervisor.Extensions
+    stage: alpha
+    description: >-
+      When enabled, the opampsupervisor can be configured with and use specific extensions from the collector ecosystem.
+    from_version: v0.151.0
+    reference_url: https://github.com/open-telemetry/opentelemetry-collector-contrib/issues/47690

cmd/opampsupervisor/metadata.yaml

@@ -31,16 +31,19 @@ import (
 	"go.opentelemetry.io/collector/service/telemetry/otelconftelemetry"
 	config "go.opentelemetry.io/contrib/otelconf/v0.3.0"
 	"go.uber.org/zap/zapcore"
+
+	"github.com/open-telemetry/opentelemetry-collector-contrib/cmd/opampsupervisor/supervisor/extensions"
 )
 
 // Supervisor is the Supervisor config file format.
 type Supervisor struct {
-	Server       OpAMPServer  `mapstructure:"server"`
-	Agent        Agent        `mapstructure:"agent"`
-	Capabilities Capabilities `mapstructure:"capabilities"`
-	Storage      Storage      `mapstructure:"storage"`
-	Telemetry    Telemetry    `mapstructure:"telemetry"`
-	HealthCheck  HealthCheck  `mapstructure:"healthcheck"`
+	Server       OpAMPServer    `mapstructure:"server"`
+	Agent        Agent          `mapstructure:"agent"`
+	Capabilities Capabilities   `mapstructure:"capabilities"`
+	Storage      Storage        `mapstructure:"storage"`
+	Telemetry    Telemetry      `mapstructure:"telemetry"`
+	HealthCheck  HealthCheck    `mapstructure:"healthcheck"`
+	Extensions   map[string]any `mapstructure:"extensions,omitempty"`
 }
 
 // Load loads the Supervisor config from a file.
@@ -74,13 +77,10 @@ func Load(configFile string) (Supervisor, error) {
 		return Supervisor{}, err
 	}
 
-	if err := cfg.Validate(); err != nil {
-		return Supervisor{}, fmt.Errorf("cannot validate supervisor config %s: %w", configFile, err)
-	}
-
 	return cfg, nil
 }
 
+// Validate validates the Supervisor configuration
 func (s Supervisor) Validate() error {
 	if err := s.Server.Validate(); err != nil {
 		return err
@@ -94,6 +94,11 @@ func (s Supervisor) Validate() error {
 		return err
 	}
 
+	// extensions have their own validation in the extensions package
+	if err := extensions.ValidateConfigs(s.Extensions); err != nil {
+		return err
+	}
+
 	return nil
 }
 

cmd/opampsupervisor/supervisor/config/config.go

@@ -19,6 +19,7 @@ import (
 	"go.opentelemetry.io/collector/config/confignet"
 	"go.opentelemetry.io/collector/config/configopaque"
 	"go.opentelemetry.io/collector/config/configtls"
+	"go.opentelemetry.io/collector/confmap"
 	"go.uber.org/zap/zapcore"
 )
 
@@ -558,6 +559,30 @@ func TestValidate(t *testing.T) {
 	}
 }
 
+func TestSupervisor_UnmarshalExtensionsRawMap(t *testing.T) {
+	conf := confmap.NewFromStringMap(map[string]any{
+		"extensions": map[string]any{
+			"foo": map[string]any{
+				"key": "value",
+			},
+			"bar/named": map[string]any{
+				"token": "secret",
+			},
+		},
+	})
+
+	cfg := DefaultSupervisor()
+	require.NoError(t, conf.Unmarshal(&cfg))
+	require.Equal(t, map[string]any{
+		"foo": map[string]any{
+			"key": "value",
+		},
+		"bar/named": map[string]any{
+			"token": "secret",
+		},
+	}, cfg.Extensions)
+}
+
 func TestOpAMPServer_OpaqueHeaders(t *testing.T) {
 	testCases := []struct {
 		name     string
@@ -867,20 +892,6 @@ agent:
 				runSupervisorConfigLoadTest(t, cfgPath, Supervisor{}, errors.New("cannot retrieve the configuration: unable to read the file"))
 			},
 		},
-		{
-			desc: "Failed Validation Supervisor",
-			testFunc: func(t *testing.T) {
-				config := `
-server:
-
-agent:
-  executable: %s
-`
-				config = fmt.Sprintf(config, executablePath)
-				cfgPath := setupSupervisorConfigFile(t, tmpDir, config)
-				runSupervisorConfigLoadTest(t, cfgPath, Supervisor{}, errors.New("cannot validate supervisor config"))
-			},
-		},
 	}
 
 	for _, tc := range testCases {