CLOUDP-389836 & CLOUDP-386688: Load Balancer Improvements (#912)

# Summary

Two problems with the managed Envoy LB:

1. The Envoy image had three sources: `spec.lb.envoy.image` CRD field,
`MDB_ENVOY_IMAGE` env var, and a hardcoded fallback in the controller.
This didn't match our configuration patterns for the other resources.
2. The main search controller reported Running even if Envoy failed to
deploy, we had no way of easily observe the load balancer status.

Changes:
**Image resolution**: Remove `spec.lb.envoy.image` from the CRD and the
hardcoded fallback from the controller. The Envoy image is now sourced
exclusively from `MDB_ENVOY_IMAGE`. If the env var isn't set, the envoy
controller fails at reconcile time with a clear error.

**LB status**: Add a `status.loadBalancer` substatus (phase + message)
to the MongoDBSearch CR. The envoy controller reports
Pending/Running/Failed into it independently from the main status. The
main controller checks `IsLoadBalancerReady()` before going Running, so
the search resource won't claim Running until Envoy is healthy. A new
`LoadBalancer` print column shows the phase in `kubectl get`.

The Envoy image bump from v1.31 to v1.37 is just for local development
defaults.

## Proof of Work

- Unit tests for `LoadBalancerStatus`, `SearchPartOption`,
`IsLoadBalancerReady`, and the LB status update path.
- `assert_lb_status()` added to all managed and unmanaged LB E2E tests
(RS and sharded) to verify the substatus is present+Running for managed,
absent for unmanaged.

## Checklist

- [x] Have you linked a jira ticket and/or is the ticket in the title?
- [x] Have you checked whether your jira ticket required DOCSP changes?
- [x] Have you added changelog file?
    - use `skip-changelog` label if not needed
- refer to [Changelog files and Release
Notes](https://github.com/mongodb/mongodb-kubernetes/blob/master/CONTRIBUTING.md#changelog-files-and-release-notes)
section in CONTRIBUTING.md for more details

Author: Julien-Ben

api/v1/search/mongodbsearch_types.go

@@ -26,6 +26,7 @@ const (
 	MongotDefaultGrpcPort           int32 = 27028
 	MongotDefaultPrometheusPort     int32 = 9946
 	MongotDefautHealthCheckPort     int32 = 8080
+	EnvoyDefaultProxyPort           int32 = 27028
 	MongotDefaultSyncSourceUsername       = "search-sync-source"
 
 	ForceWireprotoAnnotation = "mongodb.com/v1.force-search-wireproto"
@@ -130,10 +131,6 @@ type LoadBalancerConfig struct {
 
 // EnvoyConfig contains configuration for the operator-managed Envoy load balancer.
 type EnvoyConfig struct {
-	// Image is the container image for the Envoy proxy.
-	// Overrides the operator-level default (MDB_ENVOY_IMAGE env var).
-	// +optional
-	Image string `json:"image,omitempty"`
 	// ResourceRequirements for the Envoy container.
 	// When not set, defaults to requests: {cpu: 100m, memory: 128Mi}, limits: {cpu: 500m, memory: 512Mi}.
 	// When set, replaces the defaults entirely.
@@ -254,10 +251,20 @@ type TLS struct {
 	CertsSecretPrefix string `json:"certsSecretPrefix,omitempty"`
 }
 
+// LoadBalancerStatus reports the state of the operator-managed load balancer (Envoy).
+type LoadBalancerStatus struct {
+	Phase   status.Phase `json:"phase"`
+	Message string       `json:"message,omitempty"`
+}
+
 type MongoDBSearchStatus struct {
 	status.Common `json:",inline"`
 	Version       string           `json:"version,omitempty"`
 	Warnings      []status.Warning `json:"warnings,omitempty"`
+	// LoadBalancer reports the state of the operator-managed load balancer.
+	// Only populated when spec.lb.mode == Managed.
+	// +optional
+	LoadBalancer *LoadBalancerStatus `json:"loadBalancer,omitempty"`
 }
 
 // +k8s:deepcopy-gen=true
@@ -266,6 +273,7 @@ type MongoDBSearchStatus struct {
 // +kubebuilder:subresource:status
 // +kubebuilder:printcolumn:name="Phase",type="string",JSONPath=".status.phase",description="Current state of the MongoDB deployment."
 // +kubebuilder:printcolumn:name="Version",type="string",JSONPath=".status.version",description="MongoDB Search version reconciled by the operator."
+// +kubebuilder:printcolumn:name="LoadBalancer",type="string",JSONPath=".status.loadBalancer.phase",description="Current state of the managed load balancer."
 // +kubebuilder:printcolumn:name="Age",type="date",JSONPath=".metadata.creationTimestamp",description="The time since the MongoDB resource was created."
 // +kubebuilder:resource:path=mongodbsearch,scope=Namespaced,shortName=mdbs
 type MongoDBSearch struct {
@@ -289,11 +297,21 @@ func (s *MongoDBSearch) GetCommonStatus(options ...status.Option) *status.Common
 	return &s.Status.Common
 }
 
-func (s *MongoDBSearch) GetStatus(...status.Option) interface{} {
+func (s *MongoDBSearch) GetStatus(options ...status.Option) interface{} {
+	if partOpt, exists := status.GetOption(options, SearchPartOption{}); exists {
+		if partOpt.(SearchPartOption).Part == SearchPartLoadBalancer {
+			return s.Status.LoadBalancer
+		}
+	}
 	return s.Status
 }
 
-func (s *MongoDBSearch) GetStatusPath(...status.Option) string {
+func (s *MongoDBSearch) GetStatusPath(options ...status.Option) string {
+	if partOpt, exists := status.GetOption(options, SearchPartOption{}); exists {
+		if partOpt.(SearchPartOption).Part == SearchPartLoadBalancer {
+			return "/status/loadBalancer"
+		}
+	}
 	return "/status"
 }
 
@@ -302,6 +320,13 @@ func (s *MongoDBSearch) SetWarnings(warnings []status.Warning, _ ...status.Optio
 }
 
 func (s *MongoDBSearch) UpdateStatus(phase status.Phase, statusOptions ...status.Option) {
+	if partOpt, exists := status.GetOption(statusOptions, SearchPartOption{}); exists {
+		if partOpt.(SearchPartOption).Part == SearchPartLoadBalancer {
+			s.updateLoadBalancerStatus(phase, statusOptions...)
+			return
+		}
+	}
+
 	s.Status.UpdateCommonFields(phase, s.GetGeneration(), statusOptions...)
 	if option, exists := status.GetOption(statusOptions, status.WarningsOption{}); exists {
 		s.Status.Warnings = append(s.Status.Warnings, option.(status.WarningsOption).Warnings...)
@@ -311,6 +336,17 @@ func (s *MongoDBSearch) UpdateStatus(phase status.Phase, statusOptions ...status
 	}
 }
 
+func (s *MongoDBSearch) updateLoadBalancerStatus(phase status.Phase, statusOptions ...status.Option) {
+	if s.Status.LoadBalancer == nil {
+		s.Status.LoadBalancer = &LoadBalancerStatus{}
+	}
+	s.Status.LoadBalancer.Phase = phase
+	s.Status.LoadBalancer.Message = ""
+	if option, exists := status.GetOption(statusOptions, status.MessageOption{}); exists {
+		s.Status.LoadBalancer.Message = option.(status.MessageOption).Message
+	}
+}
+
 func (s *MongoDBSearch) NamespacedName() types.NamespacedName {
 	return types.NamespacedName{Name: s.Name, Namespace: s.Namespace}
 }
@@ -606,6 +642,15 @@ func stripPort(endpoint string) string {
 	return host
 }
 
+// IsLoadBalancerReady returns true if managed LB is not configured,
+// or if it is configured and its status phase is Running.
+func (s *MongoDBSearch) IsLoadBalancerReady() bool {
+	if !s.IsLBModeManaged() {
+		return true
+	}
+	return s.Status.LoadBalancer != nil && s.Status.LoadBalancer.Phase == status.PhaseRunning
+}
+
 // LoadBalancerDeploymentName returns the name of the managed Envoy Deployment for this resource.
 func (s *MongoDBSearch) LoadBalancerDeploymentName() string {
 	return s.Name + "-search-lb"

api/v1/search/mongodbsearch_types_test.go

@@ -0,0 +1,132 @@
+package search
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/mongodb/mongodb-kubernetes/api/v1/status"
+)
+
+func TestUpdateStatus_MainPath(t *testing.T) {
+	s := &MongoDBSearch{}
+	s.UpdateStatus(status.PhaseRunning, NewMongoDBSearchVersionOption("1.0"))
+
+	assert.Equal(t, status.PhaseRunning, s.Status.Phase)
+	assert.Equal(t, "1.0", s.Status.Version)
+	assert.Nil(t, s.Status.LoadBalancer)
+}
+
+func TestUpdateStatus_LoadBalancerPath(t *testing.T) {
+	s := &MongoDBSearch{}
+	partOpt := NewSearchPartOption(SearchPartLoadBalancer)
+	s.UpdateStatus(status.PhaseRunning, partOpt, status.NewMessageOption("Envoy ready"))
+
+	assert.NotNil(t, s.Status.LoadBalancer)
+	assert.Equal(t, status.PhaseRunning, s.Status.LoadBalancer.Phase)
+	assert.Equal(t, "Envoy ready", s.Status.LoadBalancer.Message)
+	// Main status untouched
+	assert.Equal(t, status.Phase(""), s.Status.Phase)
+}
+
+func TestGetStatusPath_Default(t *testing.T) {
+	s := &MongoDBSearch{}
+	assert.Equal(t, "/status", s.GetStatusPath())
+}
+
+func TestGetStatusPath_LoadBalancer(t *testing.T) {
+	s := &MongoDBSearch{}
+	partOpt := NewSearchPartOption(SearchPartLoadBalancer)
+	assert.Equal(t, "/status/loadBalancer", s.GetStatusPath(partOpt))
+}
+
+func TestGetStatus_Default(t *testing.T) {
+	s := &MongoDBSearch{}
+	s.Status.Phase = status.PhaseRunning
+	got := s.GetStatus()
+	assert.Equal(t, s.Status, got)
+}
+
+func TestGetStatus_LoadBalancer(t *testing.T) {
+	s := &MongoDBSearch{}
+	s.Status.LoadBalancer = &LoadBalancerStatus{Phase: status.PhaseRunning, Message: "ok"}
+	partOpt := NewSearchPartOption(SearchPartLoadBalancer)
+	got := s.GetStatus(partOpt)
+	assert.Equal(t, s.Status.LoadBalancer, got)
+}
+
+// nil LB → GetStatus returns nil, used by clearLBStatus to patch null
+func TestGetStatus_LoadBalancerNil(t *testing.T) {
+	s := &MongoDBSearch{}
+	partOpt := NewSearchPartOption(SearchPartLoadBalancer)
+	got := s.GetStatus(partOpt)
+	assert.Nil(t, got)
+}
+
+// Failed→Running transition must not carry over the old error message
+func TestUpdateStatus_LoadBalancerClearsStaleMessage(t *testing.T) {
+	s := &MongoDBSearch{}
+	partOpt := NewSearchPartOption(SearchPartLoadBalancer)
+
+	// Simulate a failure with a message
+	s.UpdateStatus(status.PhaseFailed, partOpt, status.NewMessageOption("missing image"))
+	assert.Equal(t, "missing image", s.Status.LoadBalancer.Message)
+
+	// Transition to Running without a message — old message must be cleared
+	s.UpdateStatus(status.PhaseRunning, partOpt)
+	assert.Equal(t, status.PhaseRunning, s.Status.LoadBalancer.Phase)
+	assert.Equal(t, "", s.Status.LoadBalancer.Message)
+}
+
+func TestIsLoadBalancerReady(t *testing.T) {
+	tests := []struct {
+		name     string
+		search   MongoDBSearch
+		expected bool
+	}{
+		{
+			name:     "no LB configured",
+			search:   MongoDBSearch{},
+			expected: true,
+		},
+		{
+			name: "managed LB, status nil",
+			search: MongoDBSearch{
+				Spec: MongoDBSearchSpec{
+					LoadBalancer: &LoadBalancerConfig{Mode: LBModeManaged},
+				},
+			},
+			expected: false,
+		},
+		{
+			name: "managed LB, status Running",
+			search: MongoDBSearch{
+				Spec: MongoDBSearchSpec{
+					LoadBalancer: &LoadBalancerConfig{Mode: LBModeManaged},
+				},
+				Status: MongoDBSearchStatus{
+					LoadBalancer: &LoadBalancerStatus{Phase: status.PhaseRunning},
+				},
+			},
+			expected: true,
+		},
+		{
+			name: "managed LB, status Pending",
+			search: MongoDBSearch{
+				Spec: MongoDBSearchSpec{
+					LoadBalancer: &LoadBalancerConfig{Mode: LBModeManaged},
+				},
+				Status: MongoDBSearchStatus{
+					LoadBalancer: &LoadBalancerStatus{Phase: status.PhasePending},
+				},
+			},
+			expected: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			assert.Equal(t, tt.expected, tt.search.IsLoadBalancerReady())
+		})
+	}
+}

api/v1/search/status_options.go

@@ -15,3 +15,28 @@ func NewMongoDBSearchVersionOption(version string) MongoDBSearchVersionOption {
 func (o MongoDBSearchVersionOption) Value() interface{} {
 	return o.Version
 }
+
+// SearchPart identifies which sub-status of MongoDBSearch to update.
+// Search-scoped to avoid polluting the shared status.Part enum.
+type SearchPart int
+
+const (
+	// SearchPartLoadBalancer targets status.loadBalancer.
+	SearchPartLoadBalancer SearchPart = iota
+)
+
+// SearchPartOption tells UpdateStatus/GetStatus/GetStatusPath which
+// sub-status to operate on. Analogous to status.OMPartOption.
+type SearchPartOption struct {
+	Part SearchPart
+}
+
+var _ status.Option = SearchPartOption{}
+
+func NewSearchPartOption(part SearchPart) SearchPartOption {
+	return SearchPartOption{Part: part}
+}
+
+func (o SearchPartOption) Value() interface{} {
+	return o.Part
+}

api/v1/search/zz_generated.deepcopy.go

@@ -25,6 +25,10 @@ spec:
       jsonPath: .status.version
       name: Version
       type: string
+    - description: Current state of the managed load balancer.
+      jsonPath: .status.loadBalancer.phase
+      name: LoadBalancer
+      type: string
     - description: The time since the MongoDB resource was created.
       jsonPath: .metadata.creationTimestamp
       name: Age
@@ -127,11 +131,6 @@ spec:
                         required:
                         - spec
                         type: object
-                      image:
-                        description: |-
-                          Image is the container image for the Envoy proxy.
-                          Overrides the operator-level default (MDB_ENVOY_IMAGE env var).
-                        type: string
                       resourceRequirements:
                         description: |-
                           ResourceRequirements for the Envoy container.
@@ -579,6 +578,18 @@ spec:
             properties:
               lastTransition:
                 type: string
+              loadBalancer:
+                description: |-
+                  LoadBalancer reports the state of the operator-managed load balancer.
+                  Only populated when spec.lb.mode == Managed.
+                properties:
+                  message:
+                    type: string
+                  phase:
+                    type: string
+                required:
+                - phase
+                type: object
               message:
                 type: string
               observedGeneration:

config/crd/bases/mongodb.com_mongodbsearch.yaml

@@ -342,15 +342,15 @@ spec:
             - name: RELATED_IMAGE_MDB_SEARCH_IMAGE_f85ffd3e5a
               value: "quay.io/mongodb/mongodb-search:f85ffd3e5a"
             - name: RELATED_IMAGE_MDB_ENVOY_IMAGE
-              value: "envoyproxy/envoy:v1.31-latest"
+              value: "envoyproxy/envoy:v1.37-latest"
             - name: MDB_SEARCH_REPO_URL
               value: "quay.io/mongodb"
             - name: MDB_SEARCH_NAME
               value: "mongodb-search"
             - name: MDB_SEARCH_VERSION
               value: "f85ffd3e5a"
             - name: MDB_ENVOY_IMAGE
-              value: "envoyproxy/envoy:v1.31-latest"
+              value: "envoyproxy/envoy:v1.37-latest"
       volumes:
         - name: webhook-server-dir
           emptyDir: {}