Key terms

This page provides key terminology that applies to Service Directory. Review these terms to better understand how Service Directory works.


An endpoint is an individual IP/port pair fronting a service that can handle requests. Any given service can have zero or more endpoints. The endpoint can be a VM, container, load balancer, or other entity capable of handling the requests. An example would be a cluster of user-managed Redis servers.

Endpoints can have optional annotations, in the form of key:value pairs, that clients can use. For example, a Redis service might have an annotation like replica:server. Annotations can be used to store URLs. You can use a tool such as jq to pull the new URL out of the response.

For Service Directory, an endpoint can only exist within a service and is identified with an endpoint name that is a string identifier that is unique to that service.


A service is a collection of endpoints (IP/ports) that provide a set of behaviors. Clients look up a service by its name and then connect to the endpoints that provide that service. Services can also have optional annotations (key-value pairs) associated with them (for example, use_https:true).

A service must belong to a namespace. Each service name must be unique within that namespace.


A namespace holds a set of service names along with their endpoint information. A namespace is a means of grouping services together for easier management.

Namespaces are regional resources and belong to a project. The name of a namespace must be unique for that project and region.

Although a namespace is a regional resource, the services that belong to that namespace can exist anywhere and be queried from anywhere. We recommend customers choose a region that maps to where their endpoints are running.

HTTP/gRPC clients

Service Directory supports look up of service names using HTTP/gRPC. There are no requirements that the service and client be on the same network.

Lookup operations over gRPC are controlled by IAM.

Service Directory zone

A Service Directory zone is a specific type of Cloud DNS private zone whose complete and authoritative source of information is a Service Directory namespace. It allows you to look up Service Directory data using DNS requests.

If a namespace is attached to a Service Directory zone, then all services in that namespace are visible to all networks that are allowed to query the zone.