Configure Service Directory

This page shows how to set up a Service Directory namespace, register a service in the namespace, and add endpoints to a service. You can create a namespace when you're registering a service or before registering a service.

Before running the commands listed on this page, familiarize yourself with the concepts in the Service Directory overview and key terms related to Service Directory.

Set up your project

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Service Directory API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

    Enable the API

  5. Install the Google Cloud CLI.

  6. If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

  7. To initialize the gcloud CLI, run the following command: 

    gcloud init

To populate Service Directory with services, create a namespace and register your service in the namespace.

Configure a namespace

For your project, create a namespace in your region. This region doesn't have to be where all your services and endpoints are running but must be close, if possible.

You can register your services in any Service Directory region; they are still globally resolvable. Within a region, projects can have multiple namespaces, and those namespaces can be in different regions. A single namespace can't span multiple regions.

Console

  1. In the Google Cloud console, go to the Service Directory namespaces page.

    Go to Service Directory namespaces

  2. Click Create namespace.
  3. In the Region list, select a region for your namespace.
  4. In the Namespace name field, give the namespace a name.
  5. Click Create.

gcloud

To use Service Directory on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

  1. Create a namespace

    gcloud service-directory namespaces create NAMESPACE \
   --location REGION

    Replace the following:

    • NAMESPACE: the name of the namespace that you are creating.
    • REGION: the Google Cloud region that contains the namespace.

  2. Optional: Set an IAM policy on your namespace. This gives the specified user or group the specified role for this namespace and all services that belong to the namespace.

    gcloud service-directory namespaces add-iam-policy-binding NAMESPACE \
--member user:someone@example.com \
--role ROLE \
--location REGION

    Replace the following:

    • NAMESPACE: the name of the namespace that you created.
    • ROLE: the role that you are granting.
    • REGION: the Google Cloud region that contains the namespace.

C#

To run this code, first set up a C# development environment and install the Service Directory C# SDK.

Go

To run this code, first set up a Go development environment and install the Service Directory Go SDK.

Java

To run this code, first set up a Java development environment and install the Service Directory Java SDK.

Node.js

To run this code, first set up a Node.js development environment and install the Service Directory Node.js SDK.

PHP

To run this code, first set up a PHP development environment and install the Service Directory PHP SDK.

Python

To run this code, first set up a Python development environment and install the Service Directory Python SDK.

Ruby

To run this code, first set up a Ruby development environment and install the Service Directory Ruby SDK.

Configure a service

Create a service in the namespace. A service consists of a name and optional service-related annotations. There are some restrictions on the format of service names:

  • Service names must be unique within a namespace.
  • Service names must follow the naming convention for DNS labels.

To create a Private Service Connect forwarding rule and register it as a service with Service Directory, see Register a Private Service Connect endpoint with Service Directory.

To register a standard service with Service Directory, follow these steps:

Console

  1. In the Google Cloud console, go to the Service Directory page.

    Go to Service Directory

  2. Click Register Service.
  3. Click Standard, and then click Next.
  4. Choose a Region to register your service in.
  5. Choose a Namespace to register your service in. If you don't have a namespace, follow these steps to create one:
    1. In the Namespace box, click Create namespace.
    2. Enter a Namespace name.
    3. Click Create.
  6. Enter a Service name.
  7. Optional: If you want to add annotations to the service, do the following:
    1. Click Add annotation.
    2. Add a Key and Value.
    3. To add more annotations, click Add annotation again.
  8. Click Create.

gcloud

To use Service Directory on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

  1. Create a service in a namespace.

    gcloud service-directory services create SERVICE \
   --annotations KEY_1=VALUE_1,KEY_2=VALUE_2 \
   --namespace NAMESPACE \
   --location REGION

    Replace the following:

    • SERVICE: the name of the service that you are creating.
    • NAMESPACE: the name of the namespace that contains your service.
    • REGION: the Google Cloud region that contains the namespace.
    • KEY_1,VALUE_1,KEY_2, VALUE_2: key and value string set in pairs.

  2. Optional: Set an IAM policy on your service. This gives the specified user or group the specified role for this service and all endpoints that belong to the service.

    gcloud service-directory services add-iam-policy-binding SERVICE \
--member user:someone@example.com \
--role ROLE \
--namespace NAMESPACE \
--location REGION

    Replace the following:

    • SERVICE: the name that you gave your service.
    • NAMESPACE: the name of the namespace that contains your service
    • ROLE: the role that you are granting.
    • REGION: the Google Cloud region that contains the namespace.

C#

To run this code, first set up a C# development environment and install the Service Directory C# SDK.

Go

To run this code, first set up a Go development environment and install the Service Directory Go SDK.

Java

To run this code, first set up a Java development environment and install the Service Directory Java SDK.

Node.js

To run this code, first set up a Node.js development environment and install the Service Directory Node.js SDK.

PHP

To run this code, first set up a PHP development environment and install the Service Directory PHP SDK.

Python

To run this code, first set up a Python development environment and install the Service Directory Python SDK.

Ruby

To run this code, first set up a Ruby development environment and install the Service Directory Ruby SDK.

Configure an endpoint

After you have registered the service, add some endpoints. An endpoint consists of a unique name, an optional IP address and a port, and key-value annotations. The IP address, if specified, must be a valid IPv4 or IPv6 address.

Console

  1. In the Google Cloud console, go to the Service Directory page.

    Go to Service Directory

  2. Click a service.
  3. Click Add endpoint.
  4. Provide an Endpoint name.
  5. Enter an IPv4 or IPv6 IP address.
  6. Enter a Port number.
  7. Optional: If you want to add annotations to the endpoint, do the following:
    1. Under Annotations, click Add annotation.
    2. Add a Key and Value.
    3. To add more annotations, click Add annotation again.
  8. Click Create.

gcloud

To use Service Directory on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

Once the service is registered, add some endpoints.

gcloud service-directory endpoints create ENDPOINT \
   --address IP_ADDRESS \
   --port PORT_NUMBER \
   --annotations KEY_1=VALUE_1,KEY_2=VALUE_2 \
   --service SERVICE \
   --namespace NAMESPACE \
   --location REGION

gcloud service-directory endpoints create ENDPOINT2 \
   --address IP_ADDRESS2 \
   --port PORT_NUMBER2 \
   --service SERVICE \
   --namespace NAMESPACE \
   --location REGION

Replace the following:

  • ENDPOINT and ENDPOINT2: the names of the endpoints that you are creating in your service.
  • IP_ADDRESS and IP_ADDRESS2: the IPv6 and IPv4 addresses of the endpoints, respectively.
  • PORT_NUMBER and PORT_NUMBER2: the ports that the endpoints are running on.
  • SERVICE: the name of the service that contains your endpoint.
  • NAMESPACE: the name of the namespace that contains your service.
  • REGION: the Google Cloud region that contains the namespace.
  • KEY_1,VALUE_1,KEY_2, VALUE_2: key and value string set in pairs.

C#

To run this code, first set up a C# development environment and install the Service Directory C# SDK.

Go

To run this code, first set up a Go development environment and install the Service Directory Go SDK.

Java

To run this code, first set up a Java development environment and install the Service Directory Java SDK.

Node.js

To run this code, first set up a Node.js development environment and install the Service Directory Node.js SDK.

PHP

To run this code, first set up a PHP development environment and install the Service Directory PHP SDK.

Python

To run this code, first set up a Python development environment and install the Service Directory Python SDK.

Ruby

To run this code, first set up a Ruby development environment and install the Service Directory Ruby SDK.

Resolve a service

Service Directory lets clients resolve services by using DNS, HTTP, and gRPC. Resolving the service returns all properties of the service, all endpoints, and all annotations.

Delete resources

If you don't need a resource, you can delete it from Service Directory.

Delete an endpoint from a service

Console

  1. In the Google Cloud console, go to the Service Directory page.

    Go to Service Directory

  2. Click the service that you want to delete the endpoint from.
  3. Select the checkbox next to the endpoint that you want to delete.
  4. Click Delete.
  5. In the confirmation dialog, click Delete again.

gcloud

To use Service Directory on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

gcloud service-directory endpoints delete ENDPOINT \
    --service=SERVICE \
    --namespace=NAMESPACE \
    --location=REGION

Replace the following:

  • ENDPOINT: the name of the endpoint that you are deleting.
  • SERVICE: the name of the service that contains your endpoint.
  • NAMESPACE: the name of the namespace that contains your service.
  • REGION: the Google Cloud region that contains the namespace.

C#

To run this code, first set up a C# development environment and install the Service Directory C# SDK.

Go

To run this code, first set up a Go development environment and install the Service Directory Go SDK.

Java

To run this code, first set up a Java development environment and install the Service Directory Java SDK.

Node.js

To run this code, first set up a Node.js development environment and install the Service Directory Node.js SDK.

PHP

To run this code, first set up a PHP development environment and install the Service Directory PHP SDK.

Python

To run this code, first set up a Python development environment and install the Service Directory Python SDK.

Ruby

To run this code, first set up a Ruby development environment and install the Service Directory Ruby SDK.

Delete a service from a namespace

You can delete a service that has endpoints. When a service is deleted, all of its endpoints are deleted as well.

You can delete a service that has a Service Directory zone pointing to it. Any further DNS queries for that service return NXDOMAIN.

Console

  1. In the Google Cloud console, go to the Service Directory page.

    Go to Service Directory

  2. Select the checkbox next to the service that you want to delete.
  3. Click Delete.
  4. In the confirmation dialog, click Delete again.

gcloud

To use Service Directory on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

gcloud service-directory services delete SERVICE \
    --namespace=NAMESPACE \
    --location=REGION

Replace the following:

  • SERVICE: the name of the service that you are deleting.
  • NAMESPACE: the name of the namespace that contains your service.
  • REGION: the Google Cloud region that contains the namespace.

C#

To run this code, first set up a C# development environment and install the Service Directory C# SDK.

Go

To run this code, first set up a Go development environment and install the Service Directory Go SDK.

Java

To run this code, first set up a Java development environment and install the Service Directory Java SDK.

Node.js

To run this code, first set up a Node.js development environment and install the Service Directory Node.js SDK.

PHP

To run this code, first set up a PHP development environment and install the Service Directory PHP SDK.

Python

To run this code, first set up a Python development environment and install the Service Directory Python SDK.

Ruby

To run this code, first set up a Ruby development environment and install the Service Directory Ruby SDK.

Delete a namespace

You can delete a namespace that has services and endpoints. When a namespace is deleted, all of its services and endpoints are deleted as well.

You can delete a namespace that has a Service Directory zone pointing to it. Any further DNS queries (not including SOA/NS requests for the zone origin) return NXDOMAIN.

Console

  1. In the Google Cloud console, go to the Service Directory namespaces page.

    Go to Service Directory namespaces

  2. Select the checkbox next to the namespace that you want to delete.
  3. Click Delete.
  4. In the confirmation dialog, click Delete again.

gcloud

To use Service Directory on the command line, first Install or upgrade to the latest version of Google Cloud CLI.

gcloud service-directory namespaces delete NAMESPACE \
    --location=REGION

Replace the following:

  • NAMESPACE: the name of the namespace that you are deleting.
  • REGION: the Google Cloud region that contains the namespace.

C#

To run this code, first set up a C# development environment and install the Service Directory C# SDK.

Go

To run this code, first set up a Go development environment and install the Service Directory Go SDK.

Java

To run this code, first set up a Java development environment and install the Service Directory Java SDK.

Node.js

To run this code, first set up a Node.js development environment and install the Service Directory Node.js SDK.

PHP

To run this code, first set up a PHP development environment and install the Service Directory PHP SDK.

Python

To run this code, first set up a Python development environment and install the Service Directory Python SDK.

Ruby

To run this code, first set up a Ruby development environment and install the Service Directory Ruby SDK.

What's next

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2026-02-19 UTC.