feat(api): per-route backend overrides on NebariApp routes

Adds an optional Backend field on RouteMatch so a single NebariApp can
fan out by path to multiple backend services under one hostname. Routes
without a per-route Backend continue to forward to spec.service, so all
existing NebariApp manifests behave identically.

Tightens the same-namespace contract by removing
ServiceReference.Namespace. The field was a half-feature: the operator
emitted a cross-namespace BackendObjectReference on the HTTPRoute, but
never created the Gateway API ReferenceGrant the gateway needs in the
target namespace, so traffic would silently fail. The new contract is
"backends live in the NebariApp's own namespace"; workloads that need
cross-namespace communication should use in-cluster DNS rather than the
public HTTPRoute.

Reconciler changes:
- buildHTTPRouteRules now emits one HTTPRouteRule per RouteMatch when
  routes are configured, each with its own resolved backend. The
  "no routes" case still emits a single rule with empty matches so
  Gateway API's "/" default applies (unchanged behavior).
- buildPublicHTTPRoute applies the same shape so per-route backends
  also work on routing.publicRoutes[].
- ValidateService now walks every backend the NebariApp references
  (spec.service plus any per-route backend in routes[] and
  publicRoutes[]) and confirms each exists in the NebariApp's
  namespace with the requested port exposed.

Design rationale: docs/design/multi-backend-routes.md.

Author: viniciusdc

api/v1/nebariapp_types.go

@@ -25,6 +25,12 @@ type NebariAppSpec struct {
 	// Hostname is the fully qualified domain name where the application should be accessible.
 	// This will be used to generate HTTPRoute.
 	// Example: "myapp.nebari.local" or "api.example.com"
+	//
+	// Each NebariApp exposes exactly one public hostname. Packs that need to expose
+	// multiple hostnames must be split into multiple NebariApps. This is an intentional
+	// boundary so a NebariApp's TLS, auth, landing-page card, and routing concerns all
+	// scope to a single user-visible URL. To fan out by path under one hostname to
+	// multiple backend services, use routing.routes[].backend.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
 	// +kubebuilder:validation:Pattern=`^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$`
@@ -63,9 +69,14 @@ type NebariAppSpec struct {
 	LandingPage *LandingPageConfig `json:"landingPage,omitempty"`
 }
 
-// ServiceReference identifies the Kubernetes Service that backs this application.
+// ServiceReference identifies a Kubernetes Service in the NebariApp's own
+// namespace. Cross-namespace backends are not supported: the operator-generated
+// HTTPRoute would require a Gateway API ReferenceGrant in the target namespace
+// to actually carry traffic, and the operator does not create one. Workloads
+// that need to talk across namespaces should do so via in-cluster DNS rather
+// than via the public HTTPRoute.
 type ServiceReference struct {
-	// Name is the name of the Kubernetes Service in the same namespace.
+	// Name is the name of the Kubernetes Service in the NebariApp's namespace.
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:MinLength=1
 	Name string `json:"name"`
@@ -75,14 +86,6 @@ type ServiceReference struct {
 	// +kubebuilder:validation:Minimum=1
 	// +kubebuilder:validation:Maximum=65535
 	Port int32 `json:"port"`
-
-	// Namespace is the namespace of the Service (if different from the NebariApp).
-	// If not specified, defaults to the NebariApp's namespace.
-	// This allows referencing services in other namespaces for centralized service architectures.
-	// Note: The operator has cluster-scoped permissions to read Services across all namespaces.
-	// +optional
-	// +kubebuilder:validation:MinLength=1
-	Namespace string `json:"namespace,omitempty"`
 }
 
 // RoutingConfig configures routing behavior for the application.
@@ -125,7 +128,7 @@ type RoutingConfig struct {
 // RouteMatch defines a path-based routing rule.
 type RouteMatch struct {
 	// PathPrefix specifies the path prefix to match for routing.
-	// Traffic matching this prefix will be routed to the service.
+	// Traffic matching this prefix will be routed to the backend.
 	// Must start with "/". Example: "/app-1", "/api/v1"
 	// +kubebuilder:validation:Required
 	// +kubebuilder:validation:Pattern=`^/.*`
@@ -140,6 +143,18 @@ type RouteMatch struct {
 	// +kubebuilder:validation:Enum=PathPrefix;Exact
 	// +optional
 	PathType string `json:"pathType,omitempty"`
+
+	// Backend optionally overrides the default backend (spec.service) for
+	// this route. When set, traffic matching this route is forwarded to the
+	// referenced Service instead of spec.service. The referenced Service must
+	// exist in the NebariApp's own namespace; cross-namespace backends are
+	// not supported (see ServiceReference).
+	//
+	// When omitted, the route falls back to spec.service. This allows a single
+	// NebariApp to fan out by path to multiple backend services under one
+	// hostname (e.g. "/api" → api-service, "/" → frontend-service).
+	// +optional
+	Backend *ServiceReference `json:"backend,omitempty"`
 }
 
 // RoutingTLSConfig controls TLS termination for the HTTPRoute.

api/v1/zz_generated.deepcopy.go

@@ -325,6 +325,12 @@ spec:
                   Hostname is the fully qualified domain name where the application should be accessible.
                   This will be used to generate HTTPRoute.
                   Example: "myapp.nebari.local" or "api.example.com"
+
+                  Each NebariApp exposes exactly one public hostname. Packs that need to expose
+                  multiple hostnames must be split into multiple NebariApps. This is an intentional
+                  boundary so a NebariApp's TLS, auth, landing-page card, and routing concerns all
+                  scope to a single user-visible URL. To fan out by path under one hostname to
+                  multiple backend services, use routing.routes[].backend.
                 minLength: 1
                 pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
                 type: string
@@ -442,10 +448,38 @@ spec:
                     items:
                       description: RouteMatch defines a path-based routing rule.
                       properties:
+                        backend:
+                          description: |-
+                            Backend optionally overrides the default backend (spec.service) for
+                            this route. When set, traffic matching this route is forwarded to the
+                            referenced Service instead of spec.service. The referenced Service must
+                            exist in the NebariApp's own namespace; cross-namespace backends are
+                            not supported (see ServiceReference).
+
+                            When omitted, the route falls back to spec.service. This allows a single
+                            NebariApp to fan out by path to multiple backend services under one
+                            hostname (e.g. "/api" → api-service, "/" → frontend-service).
+                          properties:
+                            name:
+                              description: Name is the name of the Kubernetes Service
+                                in the NebariApp's namespace.
+                              minLength: 1
+                              type: string
+                            port:
+                              description: Port is the port number on the Service
+                                to route traffic to.
+                              format: int32
+                              maximum: 65535
+                              minimum: 1
+                              type: integer
+                          required:
+                          - name
+                          - port
+                          type: object
                         pathPrefix:
                           description: |-
                             PathPrefix specifies the path prefix to match for routing.
-                            Traffic matching this prefix will be routed to the service.
+                            Traffic matching this prefix will be routed to the backend.
                             Must start with "/". Example: "/app-1", "/api/v1"
                           pattern: ^/.*
                           type: string
@@ -474,10 +508,38 @@ spec:
                     items:
                       description: RouteMatch defines a path-based routing rule.
                       properties:
+                        backend:
+                          description: |-
+                            Backend optionally overrides the default backend (spec.service) for
+                            this route. When set, traffic matching this route is forwarded to the
+                            referenced Service instead of spec.service. The referenced Service must
+                            exist in the NebariApp's own namespace; cross-namespace backends are
+                            not supported (see ServiceReference).
+
+                            When omitted, the route falls back to spec.service. This allows a single
+                            NebariApp to fan out by path to multiple backend services under one
+                            hostname (e.g. "/api" → api-service, "/" → frontend-service).
+                          properties:
+                            name:
+                              description: Name is the name of the Kubernetes Service
+                                in the NebariApp's namespace.
+                              minLength: 1
+                              type: string
+                            port:
+                              description: Port is the port number on the Service
+                                to route traffic to.
+                              format: int32
+                              maximum: 65535
+                              minimum: 1
+                              type: integer
+                          required:
+                          - name
+                          - port
+                          type: object
                         pathPrefix:
                           description: |-
                             PathPrefix specifies the path prefix to match for routing.
-                            Traffic matching this prefix will be routed to the service.
+                            Traffic matching this prefix will be routed to the backend.
                             Must start with "/". Example: "/app-1", "/api/v1"
                           pattern: ^/.*
                           type: string
@@ -519,15 +581,7 @@ spec:
                 properties:
                   name:
                     description: Name is the name of the Kubernetes Service in the
-                      same namespace.
-                    minLength: 1
-                    type: string
-                  namespace:
-                    description: |-
-                      Namespace is the namespace of the Service (if different from the NebariApp).
-                      If not specified, defaults to the NebariApp's namespace.
-                      This allows referencing services in other namespaces for centralized service architectures.
-                      Note: The operator has cluster-scoped permissions to read Services across all namespaces.
+                      NebariApp's namespace.
                     minLength: 1
                     type: string
                   port:

config/crd/bases/reconcilers.nebari.dev_nebariapps.yaml

@@ -232,7 +232,7 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `hostname` _string_ | Hostname is the fully qualified domain name where the application should be accessible.<br />This will be used to generate HTTPRoute.<br />Example: "myapp.nebari.local" or "api.example.com" |  | MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$` <br />Required: \{\} <br /> |
+| `hostname` _string_ | Hostname is the fully qualified domain name where the application should be accessible.<br />This will be used to generate HTTPRoute.<br />Example: "myapp.nebari.local" or "api.example.com"<br />Each NebariApp exposes exactly one public hostname. Packs that need to expose<br />multiple hostnames must be split into multiple NebariApps. This is an intentional<br />boundary so a NebariApp's TLS, auth, landing-page card, and routing concerns all<br />scope to a single user-visible URL. To fan out by path under one hostname to<br />multiple backend services, use routing.routes[].backend. |  | MinLength: 1 <br />Pattern: `^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$` <br />Required: \{\} <br /> |
 | `service` _[ServiceReference](#servicereference)_ | Service defines the backend Kubernetes Service that should receive traffic. |  | Required: \{\} <br /> |
 | `routing` _[RoutingConfig](#routingconfig)_ | Routing configures routing behavior including path-based rules and TLS. |  | Optional: \{\} <br /> |
 | `auth` _[AuthConfig](#authconfig)_ | Auth configures authentication/authorization for the application.<br />When enabled, the application will require OIDC authentication via supporting OIDC Provider. |  | Optional: \{\} <br /> |
@@ -287,8 +287,9 @@ _Appears in:_
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `pathPrefix` _string_ | PathPrefix specifies the path prefix to match for routing.<br />Traffic matching this prefix will be routed to the service.<br />Must start with "/". Example: "/app-1", "/api/v1" |  | Pattern: `^/.*` <br />Required: \{\} <br /> |
+| `pathPrefix` _string_ | PathPrefix specifies the path prefix to match for routing.<br />Traffic matching this prefix will be routed to the backend.<br />Must start with "/". Example: "/app-1", "/api/v1" |  | Pattern: `^/.*` <br />Required: \{\} <br /> |
 | `pathType` _string_ | PathType specifies how the path should be matched.<br />Valid values:<br />  - "PathPrefix": Match requests with the specified path prefix<br />  - "Exact": Match requests with the exact path<br />When used in routing.routes, defaults to "PathPrefix".<br />When used in routing.publicRoutes, defaults to "Exact" (safer for auth bypass). |  | Enum: [PathPrefix Exact] <br />Optional: \{\} <br /> |
+| `backend` _[ServiceReference](#servicereference)_ | Backend optionally overrides the default backend (spec.service) for<br />this route. When set, traffic matching this route is forwarded to the<br />referenced Service instead of spec.service. The referenced Service must<br />exist in the NebariApp's own namespace; cross-namespace backends are<br />not supported (see ServiceReference).<br />When omitted, the route falls back to spec.service. This allows a single<br />NebariApp to fan out by path to multiple backend services under one<br />hostname (e.g. "/api" → api-service, "/" → frontend-service). |  | Optional: \{\} <br /> |
 
 
 ---
@@ -373,16 +374,21 @@ _Appears in:_
 
 #### ServiceReference
 
-ServiceReference identifies the Kubernetes Service that backs this application.
+ServiceReference identifies a Kubernetes Service in the NebariApp's own
+namespace. Cross-namespace backends are not supported: the operator-generated
+HTTPRoute would require a Gateway API ReferenceGrant in the target namespace
+to actually carry traffic, and the operator does not create one. Workloads
+that need to talk across namespaces should do so via in-cluster DNS rather
+than via the public HTTPRoute.
 
 _Appears in:_
 - [NebariAppSpec](#nebariappspec)
+- [RouteMatch](#routematch)
 
 | Field | Description | Default | Validation |
 | --- | --- | --- | --- |
-| `name` _string_ | Name is the name of the Kubernetes Service in the same namespace. |  | MinLength: 1 <br />Required: \{\} <br /> |
+| `name` _string_ | Name is the name of the Kubernetes Service in the NebariApp's namespace. |  | MinLength: 1 <br />Required: \{\} <br /> |
 | `port` _integer_ | Port is the port number on the Service to route traffic to. |  | Maximum: 65535 <br />Minimum: 1 <br />Required: \{\} <br /> |
-| `namespace` _string_ | Namespace is the namespace of the Service (if different from the NebariApp).<br />If not specified, defaults to the NebariApp's namespace.<br />This allows referencing services in other namespaces for centralized service architectures.<br />Note: The operator has cluster-scoped permissions to read Services across all namespaces. |  | MinLength: 1 <br />Optional: \{\} <br /> |
 
 
 ---

docs/api-reference.md

@@ -115,43 +115,60 @@ func ValidateNamespaceOptIn(ctx context.Context, c client.Client, nebariApp *app
 	return nil
 }
 
-// ValidateService checks if the referenced service exists in the namespace and has the specified port.
-// Returns an error if the service doesn't exist or the port is not exposed.
+// ValidateService checks that every Service the NebariApp references exists in
+// the NebariApp's namespace and exposes the requested port. This covers
+// spec.service (the default backend) as well as any per-route backend
+// overrides declared in routing.routes[].backend and routing.publicRoutes[].backend.
 func ValidateService(ctx context.Context, c client.Client, nebariApp *appsv1.NebariApp) error {
-	service := &corev1.Service{}
+	if err := validateBackend(ctx, c, nebariApp.Namespace, &nebariApp.Spec.Service); err != nil {
+		return err
+	}
+
+	if nebariApp.Spec.Routing == nil {
+		return nil
+	}
 
-	// Use specified service namespace, or default to NebariApp's namespace
-	serviceNamespace := nebariApp.Spec.Service.Namespace
-	if serviceNamespace == "" {
-		serviceNamespace = nebariApp.Namespace
+	for _, route := range nebariApp.Spec.Routing.Routes {
+		if route.Backend == nil {
+			continue
+		}
+		if err := validateBackend(ctx, c, nebariApp.Namespace, route.Backend); err != nil {
+			return fmt.Errorf("route %q: %w", route.PathPrefix, err)
+		}
+	}
+	for _, route := range nebariApp.Spec.Routing.PublicRoutes {
+		if route.Backend == nil {
+			continue
+		}
+		if err := validateBackend(ctx, c, nebariApp.Namespace, route.Backend); err != nil {
+			return fmt.Errorf("public route %q: %w", route.PathPrefix, err)
+		}
 	}
 
+	return nil
+}
+
+// validateBackend checks that the referenced Service exists in the given
+// namespace and exposes the requested port. The namespace is always the
+// NebariApp's own namespace — cross-namespace backends are not supported.
+func validateBackend(ctx context.Context, c client.Client, namespace string, backend *appsv1.ServiceReference) error {
+	service := &corev1.Service{}
 	serviceKey := client.ObjectKey{
-		Name:      nebariApp.Spec.Service.Name,
-		Namespace: serviceNamespace,
+		Name:      backend.Name,
+		Namespace: namespace,
 	}
 
 	if err := c.Get(ctx, serviceKey, service); err != nil {
 		if errors.IsNotFound(err) {
-			return fmt.Errorf("service %s not found in namespace %s",
-				nebariApp.Spec.Service.Name, serviceNamespace)
+			return fmt.Errorf("service %s not found in namespace %s", backend.Name, namespace)
 		}
 		return fmt.Errorf("failed to get service: %w", err)
 	}
 
-	// Validate that the specified port exists on the service
-	portFound := false
 	for _, port := range service.Spec.Ports {
-		if port.Port == nebariApp.Spec.Service.Port {
-			portFound = true
-			break
+		if port.Port == backend.Port {
+			return nil
 		}
 	}
-
-	if !portFound {
-		return fmt.Errorf("service %s does not expose port %d",
-			nebariApp.Spec.Service.Name, nebariApp.Spec.Service.Port)
-	}
-
-	return nil
+	return fmt.Errorf("service %s does not expose port %d", backend.Name, backend.Port)
 }

internal/controller/reconcilers/core/reconciler.go

@@ -184,11 +184,11 @@ func TestValidateService(t *testing.T) {
 			expectError: true,
 		},
 		{
-			name: "Cross-namespace service reference",
+			name: "Per-route backend missing in NebariApp namespace",
 			service: &corev1.Service{
 				ObjectMeta: metav1.ObjectMeta{
-					Name:      "external-service",
-					Namespace: "other-namespace",
+					Name:      "test-service",
+					Namespace: "default",
 				},
 				Spec: corev1.ServiceSpec{
 					Ports: []corev1.ServicePort{
@@ -203,13 +203,23 @@ func TestValidateService(t *testing.T) {
 				},
 				Spec: appsv1.NebariAppSpec{
 					Service: appsv1.ServiceReference{
-						Name:      "external-service",
-						Namespace: "other-namespace",
-						Port:      8080,
+						Name: "test-service",
+						Port: 8080,
+					},
+					Routing: &appsv1.RoutingConfig{
+						Routes: []appsv1.RouteMatch{
+							{
+								PathPrefix: "/api",
+								Backend: &appsv1.ServiceReference{
+									Name: "missing-backend",
+									Port: 8080,
+								},
+							},
+						},
 					},
 				},
 			},
-			expectError: false,
+			expectError: true,
 		},
 	}