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.

Limitations

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

  • 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.

    Go to project selector

  • Make sure that billing is enabled for your Google Cloud project.

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

    Go to project selector

  • Make sure that billing is enabled for your Google Cloud project.

  • 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 

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:

apiVersion: networking.gke.io/v1alpha1
kind: ServiceDirectoryRegistrationPolicy
metadata:
    # Only the name "default" is allowed.
    name: default
    # The ServiceDirectoryRegistrationPolicy is a namespaced resource
    namespace: NAMESPACE
spec:
  resources:
    # 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.
      selector:
        matchLabels:
          LABELS
      # 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.
      annotationsToSync:
      - ANNOTATIONS

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, - cloud.google.com/load-balancer-type 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
metadata:
  name: hello-app-service
  labels:
    sd-import: "true"
  annotations:
    cloud.google.com/load-balancer-type: "Internal"
spec:
  type: LoadBalancer
  selector:
    app: hello
  ports:
  - name: tcp-port
    protocol: TCP
    port: 80
    targetPort: 8080

Here is a manifest for a Deployment:

apiVersion: apps/v1
kind: Deployment
metadata:
  labels:
    app: hello
  name: hello-app
spec:
  replicas: 2
  selector:
    matchLabels:
      app: hello
  template:
    metadata:
      labels:
        app: hello
    spec:
      containers:
      - image: gcr.io/google-samples/hello-app:1.0
        name: hello
        ports:
        - containerPort: 8080
          protocol: TCP

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

gcloud 

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

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:

service:
  endpoints:
  - address: 10.140.0.5
    metadata:
      cloud.google.com/load-balancer-type: "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

Billing

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