update api

Signed-off-by: Huabing (Robin) Zhao <zhaohuabing@gmail.com>

Author: zhaohuabing

api/v1alpha1/envoygateway_helpers.go

@@ -109,27 +109,27 @@ func (e *EnvoyGateway) GatewayNamespaceMode() bool {
 		*e.Provider.Kubernetes.Deploy.Type == KubernetesDeployModeTypeGatewayNamespace
 }
 
-// featureFlags are the default feature flags for Envoy Gateway.
-var featureFlags = map[FeatureFlag]bool{
-	FeatureUseAddressAsListenerName: false,
+// runtimeFlags are the default runtime flags for Envoy Gateway.
+var runtimeFlags = map[RuntimeFlag]bool{
+	UseAddressAsListenerName: false,
 }
 
-// IsFeatureEnabled checks if a feature is enabled in the EnvoyGateway configuration.
-func (f *FeatureFlags) IsFeatureEnabled(feature FeatureFlag) bool {
+// IsEnabled checks if a runtime flag is enabled in the EnvoyGateway configuration.
+func (f *RuntimeFlags) IsEnabled(flag RuntimeFlag) bool {
 	if f != nil {
 		for _, disable := range f.Disabled {
-			if disable == feature {
+			if disable == flag {
 				return false
 			}
 		}
 		for _, enable := range f.Enabled {
-			if enable == feature {
+			if enable == flag {
 				return true
 			}
 		}
 	}
 
-	if enabled, found := featureFlags[feature]; found {
+	if enabled, found := runtimeFlags[flag]; found {
 		return enabled
 	}
 	return false

api/v1alpha1/envoygateway_types.go

@@ -94,26 +94,27 @@ type EnvoyGatewaySpec struct {
 	// +optional
 	ExtensionAPIs *ExtensionAPISettings `json:"extensionApis,omitempty"`
 
-	// FeatureFlags defines the feature flags for Envoy Gateway.
-	// Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the features are stable.
-	FeatureFlags *FeatureFlags `json:"featureFlags,omitempty"`
+// RuntimeFlags defines the runtime flags for Envoy Gateway.
+	// Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the related features are stable.
+	RuntimeFlags *RuntimeFlags `json:"runtimeFlags,omitempty"`
 }
 
-// FeatureFlag defines a feature flag for Envoy Gateway.
-type FeatureFlag string
+// RuntimeFlag defines a runtime flag used to guard breaking changes or risky experimental features in new Envoy Gateway releases.
+// A runtime flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource.
+type RuntimeFlag string
 
 const (
-	// FeatureUseAddressAsListenerName indicates that the listener name should be derived from the address and port.
-	FeatureUseAddressAsListenerName FeatureFlag = "UseAddressAsListenerName"
+	// UseAddressAsListenerName indicates that the listener name should be derived from the address and port.
+	UseAddressAsListenerName RuntimeFlag = "UseAddressAsListenerName"
 )
 
-// FeatureFlags provide a mechanism to gate breaking changes or experimental features in new Envoy Gateway releases.
+// RuntimeFlags provide a mechanism to guard breaking changes or risky experimental features in new Envoy Gateway releases.
 // Each flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource.
 // The names of these flags will be included in the release notes alongside an explanation of the change.
-// Please note that these flags are temporary and will be removed in future releases once the features are stable.
-type FeatureFlags struct {
-	Enabled  []FeatureFlag `json:"enabled,omitempty"`
-	Disabled []FeatureFlag `json:"disabled,omitempty"`
+// Please note that these flags are temporary and will be removed in future releases once the related features are stable.
+type RuntimeFlags struct {
+	Enabled  []RuntimeFlag `json:"enabled,omitempty"`
+	Disabled []RuntimeFlag `json:"disabled,omitempty"`
 }
 
 type KubernetesClient struct {

api/v1alpha1/zz_generated.deepcopy.go

@@ -193,7 +193,7 @@ func buildXdsTCPListener(
 	keepalive *ir.TCPKeepalive,
 	connection *ir.ClientConnection,
 	accesslog *ir.AccessLog,
-	featureFlags *egv1a1.FeatureFlags,
+	useAddressAsListenerName bool,
 ) (*listenerv3.Listener, error) {
 	socketOptions := buildTCPSocketOptions(keepalive)
 	al, err := buildXdsAccessLog(accesslog, ir.ProxyAccessLogTypeListener)
@@ -203,7 +203,7 @@ func buildXdsTCPListener(
 	bufferLimitBytes := buildPerConnectionBufferLimitBytes(connection)
 	maxAcceptPerSocketEvent := buildMaxAcceptPerSocketEvent(connection)
 	listener := &listenerv3.Listener{
-		Name:                                 xdsListenerName(name, address, port, featureFlags),
+		Name:                                 xdsListenerName(name, address, port, useAddressAsListenerName),
 		AccessLog:                            al,
 		SocketOptions:                        socketOptions,
 		PerConnectionBufferLimitBytes:        bufferLimitBytes,
@@ -229,8 +229,8 @@ func buildXdsTCPListener(
 	return listener, nil
 }
 
-func xdsListenerName(name, address string, port uint32, featureFlags *egv1a1.FeatureFlags) string {
-	if featureFlags.IsFeatureEnabled(egv1a1.FeatureUseAddressAsListenerName) {
+func xdsListenerName(name, address string, port uint32, useAddressAsListenerName bool) string {
+	if useAddressAsListenerName {
 		return fmt.Sprintf("%s-%d", address, port)
 	}
 
@@ -265,14 +265,14 @@ func buildXdsQuicListener(
 	port uint32,
 	ipFamily *egv1a1.IPFamily,
 	accesslog *ir.AccessLog,
-	featureFlags *egv1a1.FeatureFlags,
+	useAddressAsListenerName bool,
 ) (*listenerv3.Listener, error) {
 	log, err := buildXdsAccessLog(accesslog, ir.ProxyAccessLogTypeListener)
 	if err != nil {
 		return nil, err
 	}
 	xdsListener := &listenerv3.Listener{
-		Name:      quicXDSListenerName(xdsListenerName(name, address, port, featureFlags)),
+		Name:      quicXDSListenerName(xdsListenerName(name, address, port, useAddressAsListenerName)),
 		AccessLog: log,
 		Address: &corev3.Address{
 			Address: &corev3.Address_SocketAddress{
@@ -949,7 +949,7 @@ func buildXdsUDPListener(
 	clusterName string,
 	udpListener *ir.UDPListener,
 	accesslog *ir.AccessLog,
-	featureFlags *egv1a1.FeatureFlags,
+	useAddressAsListenerName bool,
 ) (*listenerv3.Listener, error) {
 	if udpListener == nil {
 		return nil, errors.New("udp listener is nil")
@@ -994,7 +994,7 @@ func buildXdsUDPListener(
 		return nil, err
 	}
 	xdsListener := &listenerv3.Listener{
-		Name:      xdsListenerName(udpListener.Name, udpListener.Address, udpListener.Port, featureFlags),
+		Name:      xdsListenerName(udpListener.Name, udpListener.Address, udpListener.Port, useAddressAsListenerName),
 		AccessLog: al,
 		Address: &corev3.Address{
 			Address: &corev3.Address_SocketAddress{

internal/xds/translator/listener.go

@@ -69,7 +69,7 @@ func (r *Runner) subscribeAndTranslate(sub <-chan watchable.Snapshot[string, *ir
 				t := &translator.Translator{
 					ControllerNamespace: r.ControllerNamespace,
 					FilterOrder:         val.FilterOrder,
-					FeatureFlag:         r.EnvoyGateway.FeatureFlags,
+					FeatureFlag:         r.EnvoyGateway.RuntimeFlags,
 					Logger:              r.Logger,
 				}
 

internal/xds/translator/runner/runner.go

@@ -66,7 +66,7 @@ type Translator struct {
 	FilterOrder []egv1a1.FilterPosition
 
 	// FeatureFlag holds the feature flags for the translator.
-	FeatureFlag *egv1a1.FeatureFlags
+	FeatureFlag *egv1a1.RuntimeFlags
 
 	Logger logging.Logger
 }
@@ -285,7 +285,8 @@ func (t *Translator) processHTTPListenerXdsTranslation(
 			// Create a new UDP(QUIC) listener for HTTP3 traffic if HTTP3 is enabled
 			if http3Enabled {
 				if quicXDSListener, err = buildXdsQuicListener(httpListener.Name, httpListener.Address,
-					httpListener.Port, httpListener.IPFamily, accessLog, t.FeatureFlag); err != nil {
+					httpListener.Port, httpListener.IPFamily, accessLog,
+					t.FeatureFlag.IsEnabled(egv1a1.UseAddressAsListenerName)); err != nil {
 					errs = errors.Join(errs, err)
 					continue
 				}
@@ -300,7 +301,8 @@ func (t *Translator) processHTTPListenerXdsTranslation(
 			// Create a new TCP listener for HTTP1/HTTP2 traffic.
 			if tcpXDSListener, err = buildXdsTCPListener(
 				httpListener.Name, httpListener.Address, httpListener.Port, httpListener.IPFamily,
-				httpListener.TCPKeepalive, httpListener.Connection, accessLog, t.FeatureFlag); err != nil {
+				httpListener.TCPKeepalive, httpListener.Connection, accessLog,
+				t.FeatureFlag.IsEnabled(egv1a1.UseAddressAsListenerName)); err != nil {
 				errs = errors.Join(errs, err)
 				continue
 			}
@@ -721,7 +723,8 @@ func (t *Translator) processTCPListenerXdsTranslation(
 		if xdsListener == nil {
 			if xdsListener, err = buildXdsTCPListener(
 				tcpListener.Name, tcpListener.Address, tcpListener.Port, tcpListener.IPFamily,
-				tcpListener.TCPKeepalive, tcpListener.Connection, accesslog, t.FeatureFlag); err != nil {
+				tcpListener.TCPKeepalive, tcpListener.Connection, accesslog,
+				t.FeatureFlag.IsEnabled(egv1a1.UseAddressAsListenerName)); err != nil {
 				// skip this listener if failed to build xds listener
 				errs = errors.Join(errs, err)
 				continue
@@ -840,7 +843,9 @@ func (t *Translator) processUDPListenerXdsTranslation(
 			}
 		}
 
-		xdsListener, err := buildXdsUDPListener(udpListener.Route.Destination.Name, udpListener, accesslog, t.FeatureFlag)
+		xdsListener, err := buildXdsUDPListener(
+			udpListener.Route.Destination.Name, udpListener, accesslog,
+			 t.FeatureFlag.IsEnabled(egv1a1.UseAddressAsListenerName))
 		if err != nil {
 			// skip this listener if failed to build xds listener
 			errs = errors.Join(errs, err)

internal/xds/translator/translator.go

@@ -4,7 +4,7 @@ date: Pending
 breaking changes: |
   Use gateway name as proxy fleet name for gateway namespace mode.
   Endpoints that are absent from service discovery are removed even if their active health checks succeed.
-  The xDS listener name are now renamed based on its listening address and port, instead of the Gateway name and section name. This change is gated by the `UseAddressAsListenerName` feature flag. This flag is disabled by default in v1.5, and it will be enabled in v1.6.
+  The xDS listener name are now renamed based on its listening address and port, instead of the Gateway name and section name. This breaks existing EnvoyPatchPolicies and ExtensionManagers as they depend on the old naming scheme. This change is guarded by the `UseAddressAsListenerName` runtime flag. This flag is disabled by default in v1.5, and it will be enabled in v1.6. We recommend users to migrate their EnvoyPatchPolicies and ExtensionManagers to use the new listener names before v1.6.
 
 # Updates addressing vulnerabilities, security flaws, or compliance requirements.
 security updates: |

release-notes/current.yaml

@@ -1219,7 +1219,7 @@ EnvoyGateway is the schema for the envoygateways API.
 | `rateLimit` | _[RateLimit](#ratelimit)_ |  false  |  | RateLimit defines the configuration associated with the Rate Limit service<br />deployed by Envoy Gateway required to implement the Global Rate limiting<br />functionality. The specific rate limit service used here is the reference<br />implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.<br />This configuration is unneeded for "Local" rate limiting. |
 | `extensionManager` | _[ExtensionManager](#extensionmanager)_ |  false  |  | ExtensionManager defines an extension manager to register for the Envoy Gateway Control Plane. |
 | `extensionApis` | _[ExtensionAPISettings](#extensionapisettings)_ |  false  |  | ExtensionAPIs defines the settings related to specific Gateway API Extensions<br />implemented by Envoy Gateway |
-| `featureFlags` | _[FeatureFlags](#featureflags)_ |  true  |  | FeatureFlags defines the feature flags for Envoy Gateway.<br />Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the features are stable. |
+| `runtimeFlags` | _[RuntimeFlags](#runtimeflags)_ |  true  |  | RuntimeFlags defines the runtime flags for Envoy Gateway.<br />Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the related features are stable. |
 
 
 #### EnvoyGatewayAdmin
@@ -1479,7 +1479,7 @@ _Appears in:_
 | `rateLimit` | _[RateLimit](#ratelimit)_ |  false  |  | RateLimit defines the configuration associated with the Rate Limit service<br />deployed by Envoy Gateway required to implement the Global Rate limiting<br />functionality. The specific rate limit service used here is the reference<br />implementation in Envoy. For more details visit https://github.com/envoyproxy/ratelimit.<br />This configuration is unneeded for "Local" rate limiting. |
 | `extensionManager` | _[ExtensionManager](#extensionmanager)_ |  false  |  | ExtensionManager defines an extension manager to register for the Envoy Gateway Control Plane. |
 | `extensionApis` | _[ExtensionAPISettings](#extensionapisettings)_ |  false  |  | ExtensionAPIs defines the settings related to specific Gateway API Extensions<br />implemented by Envoy Gateway |
-| `featureFlags` | _[FeatureFlags](#featureflags)_ |  true  |  | FeatureFlags defines the feature flags for Envoy Gateway.<br />Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the features are stable. |
+| `runtimeFlags` | _[RuntimeFlags](#runtimeflags)_ |  true  |  | RuntimeFlags defines the runtime flags for Envoy Gateway.<br />Unlike ExtensionAPIs, these flags are temporary and will be removed in future releases once the related features are stable. |
 
 
 #### EnvoyGatewayTelemetry
@@ -1964,39 +1964,6 @@ _Appears in:_
 | `percentage` | _float_ |  false  | 100 | Percentage specifies the percentage of requests to be delayed. Default 100%, if set 0, no requests will be delayed. Accuracy to 0.0001%. |
 
 
-#### FeatureFlag
-
-_Underlying type:_ _string_
-
-FeatureFlag defines a feature flag for Envoy Gateway.
-
-_Appears in:_
-- [FeatureFlags](#featureflags)
-
-| Value | Description |
-| ----- | ----------- |
-| `UseAddressAsListenerName` | FeatureUseAddressAsListenerName indicates that the listener name should be derived from the address and port.<br /> | 
-
-
-#### FeatureFlags
-
-
-
-FeatureFlags provide a mechanism to gate breaking changes or experimental features in new Envoy Gateway releases.
-Each flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource.
-The names of these flags will be included in the release notes alongside an explanation of the change.
-Please note that these flags are temporary and will be removed in future releases once the features are stable.
-
-_Appears in:_
-- [EnvoyGateway](#envoygateway)
-- [EnvoyGatewaySpec](#envoygatewayspec)
-
-| Field | Type | Required | Default | Description |
-| ---   | ---  | ---      | ---     | ---         |
-| `enabled` | _[FeatureFlag](#featureflag) array_ |  true  |  |  |
-| `disabled` | _[FeatureFlag](#featureflag) array_ |  true  |  |  |
-
-
 #### FileEnvoyProxyAccessLog
 
 
@@ -4464,6 +4431,40 @@ _Appears in:_
 | `Endpoint` | EndpointRoutingType is the RoutingType for Endpoint routing.<br /> | 
 
 
+#### RuntimeFlag
+
+_Underlying type:_ _string_
+
+RuntimeFlag defines a runtime flag used to guard breaking changes or risky experimental features in new Envoy Gateway releases.
+A runtime flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource.
+
+_Appears in:_
+- [RuntimeFlags](#runtimeflags)
+
+| Value | Description |
+| ----- | ----------- |
+| `UseAddressAsListenerName` | UseAddressAsListenerName indicates that the listener name should be derived from the address and port.<br /> | 
+
+
+#### RuntimeFlags
+
+
+
+RuntimeFlags provide a mechanism to guard breaking changes or risky experimental features in new Envoy Gateway releases.
+Each flag may be enabled or disabled by default and can be toggled through the EnvoyGateway resource.
+The names of these flags will be included in the release notes alongside an explanation of the change.
+Please note that these flags are temporary and will be removed in future releases once the related features are stable.
+
+_Appears in:_
+- [EnvoyGateway](#envoygateway)
+- [EnvoyGatewaySpec](#envoygatewayspec)
+
+| Field | Type | Required | Default | Description |
+| ---   | ---  | ---      | ---     | ---         |
+| `enabled` | _[RuntimeFlag](#runtimeflag) array_ |  true  |  |  |
+| `disabled` | _[RuntimeFlag](#runtimeflag) array_ |  true  |  |  |
+
+
 
 
 #### SecretTranslationConfig

site/content/en/latest/api/extension_types.md

@@ -19,6 +19,6 @@ data:
         type: Redis
         redis:
           url: redis.redis-system.svc.cluster.local:6379
-    featureFlags:
+    runtimeFlags:
       enabled:
       - UseAddressAsListenerName

test/config/envoy-gateaway-config/address-as-listener-name.yaml

@@ -1,5 +1,5 @@
 config:
   envoyGateway:
-    featureFlags:
+    runtimeFlags:
       enabled:
       - UseAddressAsListenerName