[confmap] Add featuregate to use stable expansion rules

.chloggen/confmap-add-expand-featuregate-2.yaml

@@ -0,0 +1,25 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: deprecation
+
+# The name of the component, or a single word describing the area of concern, (e.g. otlpreceiver)
+component: expandconverter
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Expanding `$ENV` is no longer supported.  Use `DefaultScheme="env"` or the `otelcol.useStableExpansionRules` feature gate to expand `${}`.
+
+# One or more tracking issues or pull requests related to the change
+issues: [10259]
+
+# (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:
+
+# 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: []

.chloggen/confmap-add-expand-featuregate.yaml

@@ -0,0 +1,25 @@
+# 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. otlpreceiver)
+component: confmap
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add `otelcol.useStableExpansionRules` feature gate to allow enabling stable expansion rules.
+
+# One or more tracking issues or pull requests related to the change
+issues: [10259]
+
+# (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:
+
+# 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/builder/internal/builder/templates/main.go.tmpl

@@ -35,14 +35,21 @@ func main() {
 					{{.Name}}.NewFactory(),
 					{{- end}}
 				},
-				ConverterFactories: []confmap.ConverterFactory{
-					expandconverter.NewFactory(),
-				},
 			},
 		},
 		{{- end}}
 	}
 
+    {{ if .Distribution.SupportsConfmapFactories }}
+	if otelcol.UseStableExpansionRules.IsEnabled() {
+		set.ConfigProviderSettings.ResolverSettings.DefaultScheme = "env"
+	} else {
+		set.ConfigProviderSettings.ResolverSettings.ConverterFactories = []confmap.ConverterFactory{
+			expandconverter.NewFactory(),
+		}
+	}
+    {{- end}}
+
 	if err := run(set); err != nil {
 		log.Fatal(err)
 	}

confmap/converter/expandconverter/expand.go

@@ -24,6 +24,9 @@ type converter struct {
 
 // NewFactory returns a factory for a  confmap.Converter,
 // which expands all environment variables for a given confmap.Conf.
+//
+// Deprecated: [v0.102.0] Expanding $ENV is no longer supported.
+// To expand ${} using env vars use DefaultScheme="env" or the otelcol.useStableExpansionRules feature gate.
 func NewFactory() confmap.ConverterFactory {
 	return confmap.NewConverterFactory(newConverter)
 }
@@ -35,6 +38,8 @@ func newConverter(set confmap.ConverterSettings) confmap.Converter {
 	}
 }
 
+// Deprecated: [v0.102.0] Expanding $ENV is no longer supported.
+// To expand ${} using env vars use DefaultScheme="env" or the otelcol.useStableExpansionRules feature gate.
 func (c converter) Convert(_ context.Context, conf *confmap.Conf) error {
 	var err error
 	out := make(map[string]any)

otelcol/command.go

@@ -12,6 +12,11 @@ import (
 	"go.opentelemetry.io/collector/featuregate"
 )
 
+var UseStableExpansionRules = featuregate.GlobalRegistry().MustRegister("otelcol.useStableExpansionRules",
+	featuregate.StageAlpha,
+	featuregate.WithRegisterFromVersion("v0.102.0"),
+	featuregate.WithRegisterDescription("Uses the env provider to expand `${}` instead of the expandconverter and no longer expands $ENV syntax"))
+
 // NewCommand constructs a new cobra.Command using the given CollectorSettings.
 // Any URIs specified in CollectorSettings.ConfigProviderSettings.ResolverSettings.URIs
 // are considered defaults and will be overwritten by config flags passed as