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

Endpoint

:   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](https://stedolan.github.io/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.

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.

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](https://docs.cloud.google.com/dns/docs/overview#concepts) 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.