Configure Service Directory for GKE

This page provides information about how to configure Service Directory with Google Kubernetes Engine (GKE) and automatically register your GKE clusters with Service Directory. You can configure Service Directory for GKE with Autopilot GKE clusters or Standard GKE clusters. For information about the two modes, see Choose a GKE mode of operation.

To learn more about Service Directory for GKE, see Service Directory for GKE overview.


Service Directory for GKE has the following limitations:

  • You can only register services using the Service Directory-GKE integration. You must register ingresses, gateways, and other resources manually using the Service Directory API.
  • You must register your GKE clusters by using Fleets before you can sync services in those clusters to Service Directory. For details on how to register your GKE clusters, see Registering a cluster.
  • All Service Directory resources are registered in the fleet project, not the project of the cluster.
  • You can not modify the Service Directory entities registered using this integration. You must make all changes to the GKE service resources themselves so that they propagate to Service Directory.

Before you begin

  • You must register your GKE cluster to a fleet. To register your GKE cluster, follow the instructions in Registering a cluster.

Set up the GKE cluster

To set up the GKE cluster, follow these steps.

  • Enable the Service Directory GKE fleet feature.
  • Configure the Service Directory registration policy.
  • Deploy the GKE service.

Enable the Service Directory GKE fleet feature

To enable the Service Directory GKE fleet feature, run the gcloud container hub command.


gcloud alpha container hub service-directory enable

Configure the Service Directory registration policy for the service

The registration policy defines what kinds of services within GKE are automatically imported by Service Directory. The following list shows the configurable options for this policy:

  • resources: the type of GKE resources that are imported. You can specify multiple resource types. Resources are identified by Group and Kind. By default, the Group is core. Only Kind: service is available.
  • selector: a GKE label selector which matches on key:value labels that are applied on the GKE resource. By default, no resources are selected.
  • annotationsToSync: the annotation keys on the resource that are synced to Service Directory. If this list is empty, then resources are synced to Service Directory without annotations.

Each namespace should define a single policy. This policy must have name: "default". The Controller does not allow or reconcile other names.

Configure a ServiceDirectoryRegistrationPolicy.

The following manifest describes a ServiceDirectoryRegistrationPolicy:

kind: ServiceDirectoryRegistrationPolicy
    # Only the name "default" is allowed.
    name: default
    # The ServiceDirectoryRegistrationPolicy is a namespaced resource
    namespace: NAMESPACE
    # Kind specifies the types of Kubernetes resources that can be synced into Service Directory.
    - kind: Service
      # Selector is a label selector for the resource types specified in Kind.
      # annotationsToSync specifies the annotations that are matched and imported.
      # Any annotations that do not match this set of keys will not be imported into Service Directory.

Replace the following:

  • NAMESPACE: the name of the namespace. There can only be one ServiceDirectoryRegistrationPolicy in a namespace. If there are multiple policies in a single namespace, GKE chooses one policy to be the active policy and marks the others as inactive.
  • LABELS: the label selector, such as, sd-import: "true". This value applies to resources specified in kind. By default, no resources are selected.
  • ANNOTATIONS: a list of annotations that are matched and imported, such as, - If a selected GKE resource has one of the annotations in the list, the annotation and its values are synced to Service Directory with the resource. If this list is empty, then resources are synced to Service Directory without annotations.

Save the manifest as registration_policy.yaml.

Apply the manifest to your cluster

To apply the manifest to your cluster, run the kubectl apply -f command:

kubectl apply -f registration_policy.yaml

Deploy the GKE service

Deploy the GKE external passthrough Network Load Balancer service and application in your region's GKE cluster, for example, if your region is us-central1, deploy it in a GKE cluster gke-us-central1.

This imports your GKE service into Service Directory.

Create a YAML file and apply it like any other GKE resource. Here is a manifest for a service of type LoadBalancer:

apiVersion: v1
kind: Service
  name: hello-app-service
    sd-import: "true"
  annotations: "Internal"
  type: LoadBalancer
    app: hello
  - name: tcp-port
    protocol: TCP
    port: 80
    targetPort: 8080

Here is a manifest for a Deployment:

apiVersion: apps/v1
kind: Deployment
    app: hello
  name: hello-app
  replicas: 2
      app: hello
        app: hello
      - image:
        name: hello
        - containerPort: 8080
          protocol: TCP

To verify, run the Service Directory query for your service by using the gcloud service-directory services resolve command:


gcloud beta service-directory services resolve SERVICE_NAME \
  --location=LOCATION \

Replace the following:

  • SERVICE_NAME: the name or fully qualified identifier for the service, for example hello-app-service
  • LOCATION: the name of the region for the service, for example, us-central1
  • NAMESPACE: the name of the namespace for the service, for example, default

Your output shows your service and is similar to the following:

  - address:
    metadata: "Internal"
    name: projects/my-project/locations/us-central1/namespaces/default/services/hello-app-service/endpoints/my-cluster-12345
    port: 80
    network: projects/123456789/locations/global/networks/default
  name: projects/my-project/locations/us-central1/namespaces/default/services/hello-app-service


Service Directory does not charge for resources created by the GKE integration. However, there is a charge for the API calls. For pricing details, see Service Directory pricing.

What's next