Repository: envoyproxy/gateway
Pull request #4121 (2024-08-29 02:23:45)

rename `failover` to `fallback` backend
`fallback` has been historically used for more to descibe a backend / server, while `failover` has been used to describe the operation of handling the case when the primary has failed


arkodg: cc @alexwo 
codecov[bot]: ## [Codecov](https://app.codecov.io/gh/envoyproxy/gateway/pull/4121?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy) Report
All modified and coverable lines are covered by tests :white_check_mark:
> Project coverage is 67.90%. Comparing base [(`fe07093`)](https://app.codecov.io/gh/envoyproxy/gateway/commit/fe070932a1db0fca8c1539620e0f8a9a1f7f6f17?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy) to head [(`36a14d3`)](https://app.codecov.io/gh/envoyproxy/gateway/commit/36a14d366f0e5091a8c284718722e25b4dfc3c78?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy).

<details><summary>Additional details and impacted files</summary>


```diff
@@            Coverage Diff             @@
##             main    #4121      +/-   ##
==========================================
+ Coverage   67.86%   67.90%   +0.03%     
==========================================
  Files         187      187              
  Lines       23023    23023              
==========================================
+ Hits        15624    15633       +9     
+ Misses       6277     6271       -6     
+ Partials     1122     1119       -3     
```

</details>

[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/envoyproxy/gateway/pull/4121?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy).   
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=envoyproxy).

zirain: /retest

Patch:
diff --git a/api/v1alpha1/backend_types.go b/api/v1alpha1/backend_types.go
index 6a039a5b4..a2022c2c5 100644
--- a/api/v1alpha1/backend_types.go
+++ b/api/v1alpha1/backend_types.go
@@ -124,15 +124,15 @@ type BackendSpec struct {
 	// +optional
 	AppProtocols []AppProtocolType `json:"appProtocols,omitempty"`
 
-	// Failover indicates whether the backend is designated as a failover.
+	// Fallback indicates whether the backend is designated as a fallback.
 	// It is highly recommended to configure active or passive health checks to ensure that failover can be detected
 	// when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-	// The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+	// The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
 	// the health of the active backends falls below 72%.
 	//
 	// +optional
 	// +notImplementedHide
-	Failover *bool `json:"failover,omitempty"`
+	Fallback *bool `json:"fallback,omitempty"`
 }
 
 // BackendConditionType is a type of condition for a backend. This type should be
diff --git a/api/v1alpha1/shared_types.go b/api/v1alpha1/shared_types.go
index d1e6e01e2..a94ca2d53 100644
--- a/api/v1alpha1/shared_types.go
+++ b/api/v1alpha1/shared_types.go
@@ -473,15 +473,15 @@ type BackendRef struct {
 	// BackendObjectReference references a Kubernetes object that represents the backend.
 	// Only Service kind is supported for now.
 	gwapiv1.BackendObjectReference `json:",inline"`
-	// Failover indicates whether the backend is designated as a failover.
-	// Multiple failover backends can be configured.
+	// Fallback indicates whether the backend is designated as a fallback.
+	// Multiple fallback backends can be configured.
 	// It is highly recommended to configure active or passive health checks to ensure that failover can be detected
 	// when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-	// The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+	// The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
 	// the health of the active backends falls below 72%.
 	//
 	// +optional
-	Failover *bool `json:"failover,omitempty"`
+	Fallback *bool `json:"fallback,omitempty"`
 }
 
 // BackendCluster contains all the configuration required for configuring access
diff --git a/api/v1alpha1/zz_generated.deepcopy.go b/api/v1alpha1/zz_generated.deepcopy.go
index b58bc5a20..c0b8e8c65 100644
--- a/api/v1alpha1/zz_generated.deepcopy.go
+++ b/api/v1alpha1/zz_generated.deepcopy.go
@@ -374,8 +374,8 @@ func (in *BackendList) DeepCopyObject() runtime.Object {
 func (in *BackendRef) DeepCopyInto(out *BackendRef) {
 	*out = *in
 	in.BackendObjectReference.DeepCopyInto(&out.BackendObjectReference)
-	if in.Failover != nil {
-		in, out := &in.Failover, &out.Failover
+	if in.Fallback != nil {
+		in, out := &in.Fallback, &out.Fallback
 		*out = new(bool)
 		**out = **in
 	}
@@ -406,8 +406,8 @@ func (in *BackendSpec) DeepCopyInto(out *BackendSpec) {
 		*out = make([]AppProtocolType, len(*in))
 		copy(*out, *in)
 	}
-	if in.Failover != nil {
-		in, out := &in.Failover, &out.Failover
+	if in.Fallback != nil {
+		in, out := &in.Fallback, &out.Fallback
 		*out = new(bool)
 		**out = **in
 	}
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml
index d45b3076e..be16ceff8 100644
--- a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml
+++ b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_backends.yaml
@@ -137,12 +137,12 @@ spec:
                 x-kubernetes-validations:
                 - message: fqdn addresses cannot be mixed with other address types
                   rule: self.all(f, has(f.fqdn)) || !self.exists(f, has(f.fqdn))
-              failover:
+              fallback:
                 description: |-
-                  Failover indicates whether the backend is designated as a failover.
+                  Fallback indicates whether the backend is designated as a fallback.
                   It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                   when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                  The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                  The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                   the health of the active backends falls below 72%.
                 type: boolean
             type: object
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml
index 1e095c055..92a538cf4 100644
--- a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml
+++ b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyextensionpolicies.yaml
@@ -136,13 +136,13 @@ spec:
                         description: BackendRef defines how an ObjectReference that
                           is specific to BackendRef.
                         properties:
-                          failover:
+                          fallback:
                             description: |-
-                              Failover indicates whether the backend is designated as a failover.
-                              Multiple failover backends can be configured.
+                              Fallback indicates whether the backend is designated as a fallback.
+                              Multiple fallback backends can be configured.
                               It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                               when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                              The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                              The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                               the health of the active backends falls below 72%.
                             type: boolean
                           group:
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
index 46fb3818e..40590f379 100644
--- a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
+++ b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
@@ -10357,13 +10357,13 @@ spec:
                                           description: BackendRef defines how an ObjectReference
                                             that is specific to BackendRef.
                                           properties:
-                                            failover:
+                                            fallback:
                                               description: |-
-                                                Failover indicates whether the backend is designated as a failover.
-                                                Multiple failover backends can be configured.
+                                                Fallback indicates whether the backend is designated as a fallback.
+                                                Multiple fallback backends can be configured.
                                                 It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                                                 when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                                                The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                                                The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                                                 the health of the active backends falls below 72%.
                                               type: boolean
                                             group:
@@ -11243,13 +11243,13 @@ spec:
                                           description: BackendRef defines how an ObjectReference
                                             that is specific to BackendRef.
                                           properties:
-                                            failover:
+                                            fallback:
                                               description: |-
-                                                Failover indicates whether the backend is designated as a failover.
-                                                Multiple failover backends can be configured.
+                                                Fallback indicates whether the backend is designated as a fallback.
+                                                Multiple fallback backends can be configured.
                                                 It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                                                 when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                                                The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                                                The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                                                 the health of the active backends falls below 72%.
                                               type: boolean
                                             group:
@@ -12207,13 +12207,13 @@ spec:
                                     description: BackendRef defines how an ObjectReference
                                       that is specific to BackendRef.
                                     properties:
-                                      failover:
+                                      fallback:
                                         description: |-
-                                          Failover indicates whether the backend is designated as a failover.
-                                          Multiple failover backends can be configured.
+                                          Fallback indicates whether the backend is designated as a fallback.
+                                          Multiple fallback backends can be configured.
                                           It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                                           when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                                          The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                                          The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                                           the health of the active backends falls below 72%.
                                         type: boolean
                                       group:
@@ -13106,13 +13106,13 @@ spec:
                               description: BackendRef defines how an ObjectReference
                                 that is specific to BackendRef.
                               properties:
-                                failover:
+                                fallback:
                                   description: |-
-                                    Failover indicates whether the backend is designated as a failover.
-                                    Multiple failover backends can be configured.
+                                    Fallback indicates whether the backend is designated as a fallback.
+                                    Multiple fallback backends can be configured.
                                     It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                                     when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                                    The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                                    The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                                     the health of the active backends falls below 72%.
                                   type: boolean
                                 group:
diff --git a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml
index 4256957a6..7631ed68f 100644
--- a/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml
+++ b/charts/gateway-helm/crds/generated/gateway.envoyproxy.io_securitypolicies.yaml
@@ -331,13 +331,13 @@ spec:
                           description: BackendRef defines how an ObjectReference that
                             is specific to BackendRef.
                           properties:
-                            failover:
+                            fallback:
                               description: |-
-                                Failover indicates whether the backend is designated as a failover.
-                                Multiple failover backends can be configured.
+                                Fallback indicates whether the backend is designated as a fallback.
+                                Multiple fallback backends can be configured.
                                 It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                                 when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                                The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                                The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                                 the health of the active backends falls below 72%.
                               type: boolean
                             group:
@@ -1128,13 +1128,13 @@ spec:
                           description: BackendRef defines how an ObjectReference that
                             is specific to BackendRef.
                           properties:
-                            failover:
+                            fallback:
                               description: |-
-                                Failover indicates whether the backend is designated as a failover.
-                                Multiple failover backends can be configured.
+                                Fallback indicates whether the backend is designated as a fallback.
+                                Multiple fallback backends can be configured.
                                 It is highly recommended to configure active or passive health checks to ensure that failover can be detected
                                 when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.
-                                The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when
+                                The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when
                                 the health of the active backends falls below 72%.
                               type: boolean
                             group:
diff --git a/internal/gatewayapi/ext_service.go b/internal/gatewayapi/ext_service.go
index 65cf4c2cc..aa38008ab 100644
--- a/internal/gatewayapi/ext_service.go
+++ b/internal/gatewayapi/ext_service.go
@@ -78,9 +78,9 @@ func (t *Translator) processExtServiceDestination(
 
 	// TODO: support weighted non-xRoute backends
 	ds.Weight = ptr.To(uint32(1))
-	if backendRef.Failover != nil {
+	if backendRef.Fallback != nil {
 		// set only the secondary priority, the backend defaults to a primary priority if unset.
-		if ptr.Deref(backendRef.Failover, false) {
+		if ptr.Deref(backendRef.Fallback, false) {
 			ds.Priority = ptr.To(uint32(1))
 		}
 	}


Test patch:
diff --git a/internal/gatewayapi/testdata/envoyproxy-priority-backend.in.yaml b/internal/gatewayapi/testdata/envoyproxy-priority-backend.in.yaml
index f44174b6d..64b0b7a3a 100644
--- a/internal/gatewayapi/testdata/envoyproxy-priority-backend.in.yaml
+++ b/internal/gatewayapi/testdata/envoyproxy-priority-backend.in.yaml
@@ -203,16 +203,16 @@ envoyExtensionPolicies:
               Port: 8000
             - Name: grpc-backend-2
               Port: 9000
-              failover: true
+              fallback: true
             - Name: backend-ip
               Kind: Backend
               Group: gateway.envoyproxy.io
-              failover: true
+              fallback: true
             - Name: backend-ip-tls
               Namespace: envoy-gateway
               Kind: Backend
               Group: gateway.envoyproxy.io
-              failover: true
+              fallback: true
 backends:
   - apiVersion: gateway.envoyproxy.io/v1alpha1
     kind: Backend
diff --git a/internal/gatewayapi/testdata/envoyproxy-priority-backend.out.yaml b/internal/gatewayapi/testdata/envoyproxy-priority-backend.out.yaml
index 9933d77c5..33ee92402 100644
--- a/internal/gatewayapi/testdata/envoyproxy-priority-backend.out.yaml
+++ b/internal/gatewayapi/testdata/envoyproxy-priority-backend.out.yaml
@@ -112,14 +112,14 @@ envoyExtensionPolicies:
       - name: grpc-backend
         namespace: envoy-gateway
         port: 8000
-      - failover: true
+      - fallback: true
         name: grpc-backend-2
         port: 9000
-      - failover: true
+      - fallback: true
         group: gateway.envoyproxy.io
         kind: Backend
         name: backend-ip
-      - failover: true
+      - fallback: true
         group: gateway.envoyproxy.io
         kind: Backend
         name: backend-ip-tls
diff --git a/site/content/en/latest/api/extension_types.md b/site/content/en/latest/api/extension_types.md
index 39a7e955c..ae48e513e 100644
--- a/site/content/en/latest/api/extension_types.md
+++ b/site/content/en/latest/api/extension_types.md
@@ -364,7 +364,7 @@ _Appears in:_
 | `name` | _[ObjectName](#objectname)_ |  true  | Name is the name of the referent. |
 | `namespace` | _[Namespace](#namespace)_ |  false  | Namespace is the namespace of the backend. When unspecified, the local<br />namespace is inferred.<br /><br />Note that when a namespace different than the local namespace is specified,<br />a ReferenceGrant object is required in the referent namespace to allow that<br />namespace's owner to accept the reference. See the ReferenceGrant<br />documentation for details.<br /><br />Support: Core |
 | `port` | _[PortNumber](#portnumber)_ |  false  | Port specifies the destination port number to use for this resource.<br />Port is required when the referent is a Kubernetes Service. In this<br />case, the port number is the service port number, not the target port.<br />For other resources, destination port might be derived from the referent<br />resource or this field. |
-| `failover` | _boolean_ |  false  | Failover indicates whether the backend is designated as a failover.<br />Multiple failover backends can be configured.<br />It is highly recommended to configure active or passive health checks to ensure that failover can be detected<br />when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.<br />The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when<br />the health of the active backends falls below 72%. |
+| `fallback` | _boolean_ |  false  | Fallback indicates whether the backend is designated as a fallback.<br />Multiple fallback backends can be configured.<br />It is highly recommended to configure active or passive health checks to ensure that failover can be detected<br />when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.<br />The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when<br />the health of the active backends falls below 72%. |
 
 
 #### BackendSpec
diff --git a/site/content/zh/latest/api/extension_types.md b/site/content/zh/latest/api/extension_types.md
index 39a7e955c..ae48e513e 100644
--- a/site/content/zh/latest/api/extension_types.md
+++ b/site/content/zh/latest/api/extension_types.md
@@ -364,7 +364,7 @@ _Appears in:_
 | `name` | _[ObjectName](#objectname)_ |  true  | Name is the name of the referent. |
 | `namespace` | _[Namespace](#namespace)_ |  false  | Namespace is the namespace of the backend. When unspecified, the local<br />namespace is inferred.<br /><br />Note that when a namespace different than the local namespace is specified,<br />a ReferenceGrant object is required in the referent namespace to allow that<br />namespace's owner to accept the reference. See the ReferenceGrant<br />documentation for details.<br /><br />Support: Core |
 | `port` | _[PortNumber](#portnumber)_ |  false  | Port specifies the destination port number to use for this resource.<br />Port is required when the referent is a Kubernetes Service. In this<br />case, the port number is the service port number, not the target port.<br />For other resources, destination port might be derived from the referent<br />resource or this field. |
-| `failover` | _boolean_ |  false  | Failover indicates whether the backend is designated as a failover.<br />Multiple failover backends can be configured.<br />It is highly recommended to configure active or passive health checks to ensure that failover can be detected<br />when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.<br />The overprovisioning factor is set to 1.4, meaning the failover backends will only start receiving traffic when<br />the health of the active backends falls below 72%. |
+| `fallback` | _boolean_ |  false  | Fallback indicates whether the backend is designated as a fallback.<br />Multiple fallback backends can be configured.<br />It is highly recommended to configure active or passive health checks to ensure that failover can be detected<br />when the active backends become unhealthy and to automatically readjust once the primary backends are healthy again.<br />The overprovisioning factor is set to 1.4, meaning the fallback backends will only start receiving traffic when<br />the health of the active backends falls below 72%. |
 
 
 #### BackendSpec