Key terms

Stay organized with collections Save and categorize content based on your preferences.

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.