envoyproxy / envoyproxy/gateway
Backend: add a KubernetesService type so Backend features apply to Service endpoints (EDS) instead of a DNS cluster
- Dominant language
- Go
- Stars
- 3k
- Forks
- 864
- Avg merge
- 2d 2h
- Merged PRs (30d)
- 140
Description
**Description:**
Today, the only way to reference an in-cluster Kubernetes Service from a `Backend` is via an FQDN endpoint:
```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
name: foo-mtls
namespace: foo
spec:
endpoints:
- fqdn:
hostname: foo-svc.foo.svc.cluster.local
port: 5001
tls:
clientCertificateRef: ...
caCertificateRefs: ...
```
This produces a DNS cluster (STRICT_DNS-equivalent) that resolves to the ClusterIP, so Envoy sends traffic to kube-proxy rather than to the pod endpoints. That loses everything that a plain `Service` backendRef gets from EndpointSlices:
- Session persistence sticks to the ClusterIP, not a pod (#8816).
- Load balancing policies (consistent hash, least request, zone-aware routing via Service `trafficDistribution`) see a single endpoint.
- Active health checking and outlier detection have only the ClusterIP to act on, so they cannot route around an unhealthy pod.
- EndpointSlice draining (`Serving`/`Terminating`) and zone information are not used.
The headless-Service workaround (`clusterIP: None`) gets pod IPs back through DNS, but it forces users to maintain a second Service for the same workload, relies on DNS TTLs instead of EDS pushes, and loses the `Serving`/`Terminating` draining signal, zone, and `trafficDistribution`.
The proposal is a new `Backend` type that references a Kubernetes Service directly, so the Backend-only enhancements (mTLS client cert, custom CA / `insecureSkipVerify`, `appProtocols`, `fallback`, and any future per-backend settings) can be layered on top of the same EDS cluster that a `Service` backendRef would produce:
```yaml
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
name: foo-mtls
namespace: foo
spec:
type: KubernetesService
kubernetesService:
name: foo-svc
port: 5001
tls:
clientCertificateRef: ...
caCertificateRefs: ...
```
Expected semantics:
- Endpoint discovery is identical to an HTTPRoute `backendRef` pointing at `foo-svc:5001`: EndpointSlices are watched and translated to EDS, with the same draining, zone, and `routingType` (EnvoyProxy / BackendTrafficPolicy) handling as a Service backendRef.
- `name` is resolved in the Backend's own namespace. Cross-namespace references could follow later via `namespace` plus a ReferenceGrant, but a same-namespace-only first cut keeps the initial scope small.
- `port` is the Service port, matched to `targetPort` the same way a Service backendRef is today.
- The existing CEL rules extend naturally: `KubernetesService` cannot set `endpoints`, and `kubernetesService` is required when `type: KubernetesService`.
- `appProtocols` on the Backend takes precedence over the Service's `appProtocol`, and `BackendTLSPolicy` targeting the Backend should behave as it does for the other types.
This closes the gap where users must choose between "Service semantics" and "Backend enhancements", and turns `Backend` into a superset of a Service backendRef rather than a parallel path.
**Relevant Links:**
- #8816 (session persistence with Backend mTLS and a Service FQDN), where `kubernetesService` was suggested and got +1s from maintainers
- `api/v1alpha1/backend_types.go` (`BackendType`, `BackendEndpoint`)
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with api/v1alpha1/backend_types.go, then trace how Service backendRefs watch EndpointSlices and produce EDS clusters. Define the KubernetesService type and same-namespace Service port semantics while preserving the stated TLS and Backend policy behavior. Done means the API validation rules are covered and EndpointSlice draining, zone, and routing behavior matches a Service backendRef.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go, kubernetes
- Domain
- backend-api-design, networking
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100