This page shows how to set up a Service Directory namespace, add a service to the namespace, and add endpoints to a service. Before running the commands on this page, familiarize yourself with the concepts in the Service Directory overview and key terms related to Service Directory.
Set up your project
- 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.
-
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.
-
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
- Enable the Service Directory API.
- Install and initialize the Cloud SDK.
Configuring Service Directory resources
Configuring a namespace
Create a namespace for your project for your chosen region. This region does not need to be where all your services and endpoints are running, but should be close, if possible. You can register your services in any Service Directory region; they are still globally resolvable. Projects can have multiple namespaces within a region, and multiple regions can have namespaces. A single namespace cannot span regions.
Console
- Go to the Service Directory namespaces page in the Google Cloud Console.
Go to the Service Directory namespaces page - Click Create namespace.
- In the Region pull-down menu, select a region for your namespace.
- In the Namespace name field, give the namespace a name.
- Click Create.
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
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.
(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.
Configuring a service
Create a service in the namespace. A service consists of a name and optional service-related metadata. 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.
Console
- Go to the Service Directory namespaces page in the Google Cloud Console.
Go to the Service Directory namespaces page - Click a namespace.
- Click Add service.
- Enter a Service name.
- Optional If you want to add metadata to the service, do the following:
- Click Service metadata.
- Click Add metadata.
- Add a Key and Value.
- To add more metadata pairs, click Add metadata again.
- Click Create.
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
Create a service in a namespace.
gcloud service-directory services create SERVICE \ --metadata 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 that you gave the namespace containing 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.
(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 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.
Configuring an endpoint
Once the service is registered, add some endpoints. An endpoint consists of a unique name and the optional fields of address, port, and key/value metadata. The address, if specified, must be a valid IPv4 or IPv6 address.
Console
- Go to the Service Directory namespaces page in the Google Cloud Console.
Go to the Service Directory namespaces page - Click a namespace.
- Click a service.
- Click Add endpoint.
- Provide an Endpoint name.
- Enter an IPv4 or IPv6 IP address.
- Enter a Port number.
- Optional If you want to add metadata to the endpoint, do the following:
- Click Endpoint metadata.
- Click Add metadata.
- Add a Key and Value.
- To add more metadata pairs, click Add metadata again.
- Click Create.
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
Once the service is registered, add some endpoints.
gcloud service-directory endpoints create ENDPOINT \ --address IP_ADDRESS \ --port PORT_NUMBER \ --metadata 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 values:
ENDPOINT
andENDPOINT2
: the names of the endpoints that you are creating in your service.IP_ADDRESS
andIP_ADDRESS2
: the IPv6 and IPv4 addresses of the endpoints, respectively.PORT_NUMBER
andPORT_NUMBER2
: the ports that the endpoints are running on.SERVICE
: the name of the service that you are creating.NAMESPACE
: the name that you gave the namespace containing 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.
Resolving a service
Service Directory lets clients resolve services using DNS, HTTP, and gRPC. Resolving the service returns all properties of the service as well as all endpoints and metadata.
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
gcloud service-directory services resolve SERVICE \ --namespace NAMESPACE \ --location REGION
Replace the following:
SERVICE
: the name of the service that you are creating.NAMESPACE
: the name that you gave 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.
Deleting resources
Deleting an endpoint from a service
Console
- Go to the Service Directory namespaces page in the Google Cloud Console.
Go to the Service Directory namespaces page - Click the namespace that you want to delete the endpoint from.
- Click the service that you want to delete the endpoint from.
- Click the checkbox next to the endpoint that you want to delete.
- Click Delete.
- In the confirmation dialog box, click Delete again .
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
gcloud service-directory endpoints delete ENDPOINT \ --service=SERVICE \ --namespace=NAMESPACE \ --location=REGION
Replace the following:
SERVICE
: the name of the service that you are creating.NAMESPACE
: the name that you gave the namespace containing 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.
Deleting 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
- Go to the Service Directory namespaces page in the Google Cloud Console.
Go to the Service Directory namespaces page - Click the namespace you want to delete the service from.
- Click the checkbox next to the service you want to delete.
- Click Delete.
- Click Delete again in the confirmation dialog box.
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
gcloud service-directory services delete SERVICE \ --namespace=NAMESPACE \ --location=REGION
Replace the following:
SERVICE
: the name of the service that you are creating.NAMESPACE
: the name that you gave the namespace containing 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.
Deleting 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
- Go to the Service Directory namespaces page in the Google Cloud Console.
Go to the Service Directory namespaces page - Click the checkbox next to the namespace you want to delete.
- Click Delete.
- In the confirmation dialog box, click Delete again.
gcloud
To use Service Directory on the command line, first Install or upgrade to the latest version of Cloud SDK.
gcloud service-directory namespaces delete NAMESPACE \ --location=REGION
Replace the following:
NAMESPACE
: the name that you gave the namespace containing 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.
What's next
- To configure a Service Directory zone so that you can query your service using DNS, see Service Directory zone.
- To get an overview of Service Directory, see the Service Directory overview.
- To find solutions for common issues that you might encounter when using Service Directory, see Troubleshooting.