Configure a GKE cluster scope

This page describes how to use Cloud DNS to configure aGoogle Kubernetes Engine cluster scope.

To configure a GKE cluster-scoped DNS zone usingCloud DNS, create or choose a private DNS zone in the same project asthe GKE cluster that will use the DNS zone and thenconfigure the DNS zone to reference the cluster's name.

To learn more about scopes, seeScopes and hierarchies.

Permissions required for this task

To perform this task, you must have been granted the following permissionsor the following IAM roles.

Permissions

  • dns.managedZones.create to create a managed zone
  • dns.managedZones.list to list managed zones
  • dns.gkeClusters.bindPrivateDNSZone to configure a GKE cluster scope
  • dns.managedZones.update to update a managed zone
  • dns.managedZones.list to list managed zones
  • dns.managedZones.patch to update a managed zone

Roles

  • roles/dns.admin

Create a private zone for the GKE cluster

To create a new managed private zone using Cloud DNS for theGKE cluster, complete the following step.

gcloud

Run thegcloud dns managed-zones create command:

gcloud dns managed-zones createNAME \    --dns-name=DNS_NAME \    --visibility=private \    --gkeclusters=GKE_CLUSTER

Replace the following:

  • NAME: a name for your zone
  • DNS_NAME: the DNS suffix for your zone, such asexample.private.
  • GKE_CLUSTER: the fully qualified resource path of aGKE cluster,such asprojects/my-project/locations/us-east1a/clusters/my-cluster

API

Send aPOST request by using themanagedZones.create method:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones{"name": "NAME","description": "DESCRIPTION","dnsName": "DNS_NAME","visibility": "private""privateVisibilityConfig": {    "kind": "dns#managedZonePrivateVisibilityConfig",    "gkeClusters": [{            "kind": "dns#managedZonePrivateVisibilityConfigGKEClusters",            "gkeClusterName":GKE_CLUSTER_NAME_1        },        {            "kind": "dns#managedZonePrivateVisibilityConfigGKEClusters",            "gkeClusterName":GKE_CLUSTER_NAME_2        },        ....    ]  }}

Replace the following:

  • PROJECT_ID: the ID of the project where you havecreated the managed zone
  • NAME: a name for your zone
  • DESCRIPTION: a description for your zone
  • DNS_NAME: the DNS suffix for your zone, such asexample.private.
  • GKE_CLUSTER_NAME_1 andGKE_CLUSTER_NAME_2:the fully qualified resource path of a GKE cluster, suchasprojects/my-project/locations/us-east1a/clusters/my-cluster

Authorize the GKE cluster to query a Cloud DNS private zone

To authorize the GKEcluster to query an existing Cloud DNS private zone, complete thefollowing step.

gcloud

Run thegcloud dns managed-zones update command:

gcloud dns managed-zones updateNAME \    --gkeclusters=GKE_CLUSTER

Replace the following:

  • NAME: the name of your zone, such asmy-zone
  • GKE_CLUSTER: the fully qualified resource path of aGKE cluster, such asprojects/my-project/locations/us-east1a/clusters/my-cluster

API

Send aPATCH request by using themanagedZones.patch method:

PATCH https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/NAME{"privateVisibilityConfig": {    "gkeClusters": [{            "kind": "dns#managedZonePrivateVisibilityConfigGKEClusters",            "gkeClusterName":GKE_CLUSTER_NAME_1        },        {            "kind": "dns#managedZonePrivateVisibilityConfigGKEClusters",            "gkeClusterName":GKE_CLUSTER_NAME_2        },        ....    ]  }}

Replace the following:

  • PROJECT_ID: the ID of the project where you havecreated the managed zone
  • NAME: the name of your zone, such asmy-zone
  • GKE_CLUSTER_NAME_1 andGKE_CLUSTER_NAME_2:the fully qualified resource path of a GKE cluster, suchasprojects/my-project/locations/us-east1a/clusters/my-cluster

Configure the GKE cluster to query a response policy

To configure the GKEcluster to query a response policy, complete the following step.

Note: DNS queries that reach response policies get billed at the usualCloud DNS query billing rate. For pricing details, seeCloud DNS pricing.

gcloud

Run thegcloud dns response-policies create command:

gcloud dns response-policies createNAME \    --description=DESCRIPTION \    --gkeclusters=GKE_CLUSTER

Replace the following:

  • NAME: a name for your response policy, such asmy-response-policy
  • DESCRIPTION: a description for your response policy,such as"my-response-policy-for-gke-5"
  • GKE_CLUSTER: the fully qualified resource path of aGKE cluster, such asprojects/my-project/locations/us-east1a/clusters/my-cluster

API

Send aPOST request by using theresponsePolicies.create method:

POST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/responsePolicies{  "responsePolicyName": "NAME",  "description": "DESCRIPTION",  "gkeClusters": [    {      "kind": "dns#responsePolicyGKECluster",      "gkeClusterName": "GKE_CLUSTER"    },  ]}

Replace the following:

  • NAME: a name for your response policy, such asmy-response-policy
  • DESCRIPTION: a description for your response policy,such asmy-response-policy-for-gke-5
  • GKE_CLUSTER: the fully qualified resource path of aGKE cluster, such asprojects/my-project/locations/us-east1a/clusters/my-cluster

What's next

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

Last updated 2026-02-19 UTC.