Stay organized with collectionsSave and categorize content based on your preferences.
This page describes how to use Cloud DNS to configure a
Google Kubernetes Engine cluster scope.
To configure a GKE cluster-scoped DNS zone using
Cloud DNS, first choose an existing private DNS zone or create a new
private DNS zone to which to attach a specific GKE cluster. Next,
configure the DNS zone to reference the GKE cluster's name.
PROJECT_ID: the ID of the project where you have
created 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_1andGKE_CLUSTER_NAME_2:
the fully qualified resource path of a GKE cluster, such
asprojects/my-project/locations/us-east1a/clusters/my-cluster
Authorize the GKE cluster to query a Cloud DNS private zone
To authorize the GKE
cluster to query an existing Cloud DNS private zone, complete the
following step.
PROJECT_ID: the ID of the project where you have
created the managed zone
NAME: the name of your zone, such asmy-zone
GKE_CLUSTER_NAME_1andGKE_CLUSTER_NAME_2:
the fully qualified resource path of a GKE cluster, such
asprojects/my-project/locations/us-east1a/clusters/my-cluster
Configure the GKE cluster to query a response policy
To configure the GKE
cluster to query a response policy, complete the following step.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-09-04 UTC."],[[["\u003cp\u003eThis guide details the process of configuring a Google Kubernetes Engine (GKE) cluster-scoped DNS zone using Cloud DNS.\u003c/p\u003e\n"],["\u003cp\u003eTo begin, you can either select an existing private DNS zone or establish a new one to be associated with a specific GKE cluster.\u003c/p\u003e\n"],["\u003cp\u003eThe \u003ccode\u003egcloud\u003c/code\u003e command-line tool or API calls can be used to create a new managed private zone and to update or configure it.\u003c/p\u003e\n"],["\u003cp\u003eSpecific permissions and roles, such as \u003ccode\u003edns.managedZones.create\u003c/code\u003e and \u003ccode\u003eroles/dns.admin\u003c/code\u003e, are required to carry out these configurations.\u003c/p\u003e\n"],["\u003cp\u003eA GKE cluster can be configured to query a response policy, which is subject to standard Cloud DNS query billing rates.\u003c/p\u003e\n"]]],[],null,["# Configure a GKE cluster scope\n\nThis page describes how to use Cloud DNS to configure a\nGoogle Kubernetes Engine cluster scope.\n\nTo configure a GKE cluster-scoped DNS zone using\nCloud DNS, first choose an existing private DNS zone or create a new\nprivate DNS zone to which to attach a specific GKE cluster. Next,\nconfigure the DNS zone to reference the GKE cluster's name.\n\nTo learn more about scopes, see [Scopes and hierarchies](/dns/docs/scopes).\n\n#### Permissions required for this task\n\nTo perform this task, you must have been granted the following permissions\n*or* the following IAM roles.\n\n**Permissions**\n\n- `dns.managedZones.create` to create a managed zone\n- `dns.managedZones.list` to list managed zones\n- `dns.gkeClusters.bindPrivateDNSZone` to configure a GKE cluster scope\n- `dns.managedZones.update` to update a managed zone\n- `dns.managedZones.list` to list managed zones\n- `dns.managedZones.patch` to update a managed zone\n\n**Roles**\n\n- `roles/dns.admin`\n\nCreate a private zone for the GKE cluster\n-----------------------------------------\n\nTo create a new managed private zone using Cloud DNS for the\nGKE cluster, complete the following step. \n\n### gcloud\n\nRun the\n[`gcloud dns managed-zones create` command](/sdk/gcloud/reference/dns/managed-zones/create): \n\n```\ngcloud dns managed-zones create NAME \\\n --dns-name=DNS_NAME \\\n --visibility=private \\\n --gkeclusters=GKE_CLUSTER\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: a name for your zone\n- \u003cvar translate=\"no\"\u003eDNS_NAME\u003c/var\u003e: the DNS suffix for your zone, such as `example.private.`\n- \u003cvar translate=\"no\"\u003eGKE_CLUSTER\u003c/var\u003e: the fully qualified resource path of a GKE cluster, such as `projects/my-project/locations/us-east1a/clusters/my-cluster`\n\n### API\n\nSend a `POST` request by using the\n[`managedZones.create` method](/dns/docs/reference/v1/managedZones/create): \n\n```\nPOST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones\n{\n\n\"name\": \"NAME\",\n\"description\": \"DESCRIPTION\",\n\"dnsName\": \"DNS_NAME\",\n\"visibility\": \"private\"\n\"privateVisibilityConfig\": {\n \"kind\": \"dns#managedZonePrivateVisibilityConfig\",\n \"gkeClusters\": [{\n \"kind\": \"dns#managedZonePrivateVisibilityConfigGKEClusters\",\n \"gkeClusterName\": GKE_CLUSTER_NAME_1\n },\n {\n \"kind\": \"dns#managedZonePrivateVisibilityConfigGKEClusters\",\n \"gkeClusterName\": GKE_CLUSTER_NAME_2\n },\n ....\n ]\n }\n}\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of the project where you have created the managed zone\n- \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: a name for your zone\n- \u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e: a description for your zone\n- \u003cvar translate=\"no\"\u003eDNS_NAME\u003c/var\u003e: the DNS suffix for your zone, such as `example.private.`\n- \u003cvar translate=\"no\"\u003eGKE_CLUSTER_NAME_1\u003c/var\u003e and \u003cvar translate=\"no\"\u003eGKE_CLUSTER_NAME_2\u003c/var\u003e: the fully qualified resource path of a GKE cluster, such as `projects/my-project/locations/us-east1a/clusters/my-cluster`\n\nAuthorize the GKE cluster to query a Cloud DNS private zone\n-----------------------------------------------------------\n\nTo authorize the GKE\ncluster to query an existing Cloud DNS private zone, complete the\nfollowing step. \n\n### gcloud\n\nRun the\n[`gcloud dns managed-zones update` command](/sdk/gcloud/reference/beta/dns/managed-zones/update): \n\n```\ngcloud dns managed-zones update NAME \\\n --gkeclusters=GKE_CLUSTER\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: the name of your zone, such as `my-zone`\n- \u003cvar translate=\"no\"\u003eGKE_CLUSTER\u003c/var\u003e: the fully qualified resource path of a GKE cluster, such as `projects/my-project/locations/us-east1a/clusters/my-cluster`\n\n### API\n\nSend a `PATCH` request by using the\n[`managedZones.patch` method](/dns/docs/reference/v1/managedZones/patch): \n\n```\nPATCH https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/managedZones/NAME\n{\n\"privateVisibilityConfig\": {\n \"gkeClusters\": [{\n \"kind\": \"dns#managedZonePrivateVisibilityConfigGKEClusters\",\n \"gkeClusterName\": GKE_CLUSTER_NAME_1\n },\n {\n \"kind\": \"dns#managedZonePrivateVisibilityConfigGKEClusters\",\n \"gkeClusterName\": GKE_CLUSTER_NAME_2\n },\n ....\n ]\n }\n}\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003ePROJECT_ID\u003c/var\u003e: the ID of the project where you have created the managed zone\n- \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: the name of your zone, such as `my-zone`\n- \u003cvar translate=\"no\"\u003eGKE_CLUSTER_NAME_1\u003c/var\u003e and \u003cvar translate=\"no\"\u003eGKE_CLUSTER_NAME_2\u003c/var\u003e: the fully qualified resource path of a GKE cluster, such as `projects/my-project/locations/us-east1a/clusters/my-cluster`\n\nConfigure the GKE cluster to query a response policy\n----------------------------------------------------\n\nTo configure the GKE\ncluster to query a response policy, complete the following step.\n**Note:** DNS queries that reach response policies get billed at the usual Cloud DNS query billing rate. For pricing details, see [Cloud DNS pricing](/dns/pricing). \n\n### gcloud\n\nRun the\n[`gcloud dns response-policies create` command](/sdk/gcloud/reference/dns/response-policies/create): \n\n```\ngcloud dns response-policies create NAME \\\n --description=DESCRIPTION \\\n --gkeclusters=GKE_CLUSTER\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: a name for your response policy, such as `my-response-policy`\n- \u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e: a description for your response policy, such as `\"my-response-policy-for-gke-5\"`\n- \u003cvar translate=\"no\"\u003eGKE_CLUSTER\u003c/var\u003e: the fully qualified resource path of a GKE cluster, such as `projects/my-project/locations/us-east1a/clusters/my-cluster`\n\n### API\n\nSend a `POST` request by using the\n[`responsePolicies.create` method](/dns/docs/reference/v1/responsePolicies/create): \n\n```\nPOST https://dns.googleapis.com/dns/v1/projects/PROJECT_ID/responsePolicies\n{\n \"responsePolicyName\": \"NAME\",\n \"description\": \"DESCRIPTION\",\n \"gkeClusters\": [\n {\n \"kind\": \"dns#responsePolicyGKECluster\",\n \"gkeClusterName\": \"GKE_CLUSTER\"\n },\n ]\n}\n```\n\nReplace the following:\n\n- \u003cvar translate=\"no\"\u003eNAME\u003c/var\u003e: a name for your response policy, such as `my-response-policy`\n- \u003cvar translate=\"no\"\u003eDESCRIPTION\u003c/var\u003e: a description for your response policy, such as `my-response-policy-for-gke-5`\n- \u003cvar translate=\"no\"\u003eGKE_CLUSTER\u003c/var\u003e: the fully qualified resource path of a GKE cluster, such as `projects/my-project/locations/us-east1a/clusters/my-cluster`\n\nWhat's next\n-----------\n\n- To find solutions for common issues that you might encounter when using Cloud DNS, see [Troubleshooting](/dns/docs/troubleshooting).\n- To learn more about Cloud DNS response policies and rules, see [Manage response policies and rules](/dns/docs/zones/manage-response-policies).\n- To display an audit log of operations, see [View operations on managed zones](/dns/docs/zones/operations)."]]
