x/gateway/discovery Primer
x/gateway/discovery Primer
Section titled “x/gateway/discovery Primer”Experimental — API compatibility is not frozen. Evaluate before adopting in production. Check Release Posture for current maturity status.
Open this page after x/gateway Primer when the change is narrowly about service instance resolution: adding a discovery backend adapter, implementing a resolver helper, or consuming discovered instances from the gateway load balancer.
x/gateway/discovery is a subordinate package within the x/gateway family. Start service discovery work in x/gateway before opening this package directly. The gateway surface is the canonical app-facing entrypoint; x/gateway/discovery provides the resolver layer underneath it.
Start here when
Section titled “Start here when”- you are adding a discovery backend adapter (Consul, Kubernetes, etcd, or static list)
- you are implementing or modifying instance resolver helpers (
discovery.go) - you are integrating a new service registry that the gateway load balancer will consume
- you are testing discovery resolution behavior for a specific backend (
consul_test.go,kubernetes_test.go,etcd_test.go,static_test.go)
Do not start here when
Section titled “Do not start here when”- the work is about reverse proxying, path rewriting, or load balancing strategy — start from x/gateway Primer
- the change introduces core bootstrap ownership or stable root entrypoints
- the work is tenant-specific backend routing or per-tenant service selection — coordinate with
x/tenantandx/gateway - the change is application-level service configuration rather than a discovery adapter
First files to read in the current repository
Section titled “First files to read in the current repository”x/gateway/discovery/module.yamlx/gateway/discovery/discovery.gox/gateway/discovery/static.gox/gateway/discovery/consul.gox/gateway/discovery/kubernetes.gox/gateway/discovery/etcd.go
Concrete ownership examples
Section titled “Concrete ownership examples”Keep it in x/gateway/discovery when the work is about | Move out when the work becomes |
|---|---|
static.go: fixed instance list resolver for local development or simple deployments | application-level service configuration or environment variable wiring |
consul.go: Consul health-check-based instance discovery and polling | Consul ACL policy or Consul agent configuration |
kubernetes.go: Kubernetes endpoints-based service discovery | Kubernetes RBAC or cluster network policy |
etcd.go: etcd watch-based instance registry and TTL management | etcd cluster administration or etcd auth configuration |
| Resolver interface implementations that the gateway balancer consumes | gateway-level load balancing strategy or proxy handler construction |
Why this primer exists
Section titled “Why this primer exists”Service discovery is a subordinate concern within gateway edge transport, not a standalone capability. Keeping x/gateway/discovery subordinate to x/gateway preserves the invariant that app-facing gateway work flows through one entrypoint rather than scattering discovery, balancing, and proxying across separate import chains. Transport concerns stay out of discovery — resolvers return instances, not HTTP handlers.