envoyproxy / envoyproxy/gateway

Backend: add a KubernetesService type so Backend features apply to Service endpoints (EDS) instead of a DNS cluster

Open
#10,002 0 comments 0 reactions 0 assignees View on GitHub
kind/feature
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.