Managing response policies and rules

This page provides information about how to manage response policies and response policy rules.

Cloud DNS private zones let you create a single response policy per network that modifies resolver behavior according to the policy created. You can also create rules as part of response policies.

You can create a single response policy rule per network that can do the following:

Alter results for selected query names (including wildcards) by providing specific resource records.
Trigger passthru behavior that bypasses the response policy, exempting names that would otherwise match. For example, for wildcard responses, this lets private DNS query matching continue as if it never encountered a wildcard.

For information about how VPC Service Controls lets customers enforce controls on API access from their private VPC networks, see Setting up private connectivity to Google APIs and services.

Managing response policies

Creating a response policy

To create a new response policy, follow these steps.

gcloud

Run the gcloud beta dns response-policies create command:

gcloud beta dns response-policies create RESPONSE_POLICY_NAME \
     --networks=NETWORK \
    [--description=DESCRIPTION]

Replace the following:

RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to create, such as myresponsepolicy
NETWORK: a comma-separated list of network names to associate with the response policy, such as network1, network2
DESCRIPTION: a description of the response policy, such as My new response policy

API

Send a POST request by using the responsePolicies.create method:

POST https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies

Replace PROJECT_ID with the name or ID of the project that you want to create the response policy in.

Viewing response policies

To view the list of all response policies in a given project, or to view the description of a specific response policy, follow these steps.

gcloud

To see the list of all response policies in a project, run the gcloud beta dns response-policies list command:
```
gcloud beta dns response-policies list
```
You can limit the number of response policies by using the --limit flag. For example, to see a list of the first ten response policies, run the following command:
```
gcloud beta dns response-policies list \
  --limit=10
```
To see a detailed description of a response policy, run the gcloud beta dns response-policies describe command:
```
gcloud beta dns response-policies describe RESPONSE_POLICY_NAME
```
Replace RESPONSE_POLICY_NAME with the name or ID of the response policy that you want to view the description for.

API

To see the detailed description of a response policy, send a GET request by using the responsePolicies.get method:

GET https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME

Replace the following:

PROJECT_ID: the ID of the project where you have created the response policy
RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to see the description for, such as myresponsepolicy

Updating a response policy

To update a response policy, follow these steps.

gcloud

Run the gcloud beta dns response-policies update command:

gcloud beta dns response-policies update RESPONSE_POLICY_NAME

Replace RESPONSE_POLICY_NAME with the name or ID of the response policy that you want to update, such as myresponsepolicy.

Use the same syntax as the create command for any updated fields.

API

To apply a partial update to a response policy, send a PATCH request by using the responsePolicies.patch method:
```
PATCH https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to update, such as myresponsepolicy
To update a response policy, send an UPDATE request by using the responsePolicies.update method:
```
UPDATE https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to update, such as myresponsepolicy

Deleting a response policy

To delete a response policy, follow these steps.

gcloud

Run the gcloud beta dns response-policies delete command:

gcloud beta dns response-policies delete RESPONSE_POLICY_NAME

Replace RESPONSE_POLICY_NAME with the name or ID of the response policy that you want to delete.

API

Send a DELETE request by using the responsePolicies.delete method:

DELETE https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME

Replace the following:

PROJECT_ID: the ID of the project where you have created the response policy
RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to delete, such as myresponsepolicy

Managing response policy rules

A site's DNS response policy consists of rules that a DNS resolver consults during lookups. If a rule in the response policy affects the incoming query, it is processed; otherwise, the lookup proceeds normally.

To manage rules, follow these steps.

gcloud

To alter behavior for selected query names, run the gcloud beta dns response-policies rules create command, and specify the --type flag:
```
gcloud beta dns response-policies rules create RESPONSE_POLICY_RULE_NAME \
   --response-policy=RESPONSE_POLICY_NAME \
   --dns-name=DNS_NAME \
   --local-data=name="DNS_NAME.",type="RRTYPE",ttl=TTL,rrdatas="RRDATA"
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy
- DNS_NAME: the DNS or domain name, such as www.googleapis.com
- TTL: time to live for the response policy, such as 21600
- RRTYPE: the resource record type, such as A
- RRDATA: the resource record data, such as 1.2.3.4. Separate multiple entries with |, such as 1.2.3.4|5.6.7.8.
To create a bypass rule, run the gcloud beta dns response-policies rules create command, and set the --behavior flag to bypassResponsePolicy:
```
gcloud beta dns response-policies rules create RESPONSE_POLICY_RULE_NAME \
   --response-policy=RESPONSE_POLICY_NAME \
   --dns-name=DNS_NAME \
   --behavior=bypassResponsePolicy
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy
- DNS_NAME: the DNS or domain name, such as www.googleapis.com
To view details about a response policy rule, run the gcloud beta dns response-policies rules describe command:
```
gcloud beta dns response-policies rules describe RESPONSE_POLICY_RULE_NAME \
  --response-policy=RESPONSE_POLICY_NAME
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy
To view the list of Cloud DNS response policy rules within a response policy, use the gcloud beta dns response-policies rules list command:
```
gcloud beta dns response-policies rules list RESPONSE_POLICY_NAME
```
Replace RESPONSE_POLICY_NAME with the name of the response policy, such as myresponsepolicy.
To update a new Cloud DNS response policy rule, use the gcloud beta dns response-policies rules update command:
```
gcloud beta dns response-policies rules update RESPONSE_POLICY_RULE_NAME \
   --response-policy=RESPONSE_POLICY_NAME
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy
Use the same syntax as the create command for any updated fields.
To delete a Cloud DNS response policy rule, use the gcloud beta dns response-policies rules delete command:
```
gcloud beta dns response-policies rules delete RESPONSE_POLICY_RULE_NAME \
  --response-policy=RESPONSE_POLICY_NAME
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy

API

To create a new response policy rule, send a POST request by using the responsePolicyRules.create method:
```
POST https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME/rules
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to create a rule for, such as myresponsepolicy
To see the detailed description of a rule in a response policy, send a GET request by using the responsePolicyRules.get method:
```
GET https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME/rules/RESPONSE_POLICY_RULE
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to create a rule for, such as myresponsepolicy
- RESPONSE_POLICY_RULE: the response policy rule that you want to see the details of
To apply a partial update to a response policy rule, send a PATCH request by using the responsePolicyRules.patch method:
```
PATCH https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME/rules/RESPONSE_POLICY_RULE
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to update the rule for, such as myresponsepolicy
- RESPONSE_POLICY_RULE: the response policy rule that you want to update
To update a response policy rule, send an UPDATE request by using the responsePolicyRules.update method:
```
UPDATE https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME/rules/RESPONSE_POLICY_RULE
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to update the rule for, such as myresponsepolicy
- RESPONSE_POLICY_RULE: the response policy rule that you want to update
To delete a response policy rule, send a DELETE request by using the responsePolicyRules.delete method:
```
DELETE https://dns.googleapis.com/dns/v1beta2/projects/PROJECT_ID/responsePolicies/RESPONSE_POLICY_NAME/rules/RESPONSE_POLICY_RULE
```
Replace the following:
- PROJECT_ID: the ID of the project where you have created the response policy
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to delete the rule from, such as myresponsepolicy
- RESPONSE_POLICY_RULE: the response policy rule that you want to delete

Use cases

This section provides example use cases to configure rules for response policies.

Directing specific names to restricted VIP addresses

You can configure a response policy that has local CNAME data for each zone to translate Google API requests to restricted Google APIs. Names that aren't specified continue to be resolved by using regular DNS.

For example, you can create a response policy for pubsub.googleapis.com, which has local CNAME data for a zone, to translate Google API requests to restricted.googleapis.com. In the meantime, www.googleapis.com, which is unspecified, continues to be resolved by using regular DNS.

In the following example configuration, you create a policy and apply it to a specific VPC network.

gcloud

To create a response policy, run the gcloud beta dns response-policies create command:
```
gcloud beta dns response-policies create RESPONSE_POLICY_NAME \
    --networks=NETWORK \
    --description=DESCRIPTION
```
Replace the following:
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to create, such as myresponsepolicy
- NETWORK: a comma-separated list of network names to associate with the response policy, such as network1,network2
- DESCRIPTION: a description of the response policy, such as My new response policy
To add a rule to the policy, run the gcloud beta dns response-policies rules create command:
```
gcloud beta dns response-policies rules create RESPONSE_POLICY_RULE_NAME \
    --response-policy=RESPONSE_POLICY_NAME \
    --dns-name=pubsub.googleapis.com. \
    --local-data=name="pubsub.googleapis.com.",type="A",ttl=300,rrdatas="199.36.153.4|199.36.153.5|199.36.153.6|199.36.153.7"
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy

API

Create a response policy by URL:
```
{
  kind: "dns#responsePolicy",
  response_policy_name: RESPONSE_POLICY_NAME,
  description: RESPONSE_POLICY_DESCRIPTION,
  networks: [
    {
      network_url: URL_TO_NETWORK;
    }
  ]
}
```
Replace the following:
- RESPONSE_POLICY_NAME: a name for the response policy
- RESPONSE_POLICY_DESCRIPTION: a description of the response policy
- URL_TO_NETWORK: the URL for which you're creating the response policy
  
  Note: It is not necessary to refer to the parent response policy in the JSON. The parent response policy is inferred from the URL that you use.

Add a rule to the policy:

{
  kind: "dns#responsePolicyRules",
  rule_name: RULE_NAME,
  dns_name: DNS_NAME,
  local_data: [
    {
      name: "pubsub.googleapis.com.",
      type: "A",
      ttl: 300,
      rrdata: ["199.36.153.4", "199.36.153.5", "199.36.153.6", "199.36.153.7"]
    }
  ]
}

Replace the following:

RULE_NAME: a name for the rule that you are creating, such as pubsub
DNS_NAME: the DNS name for which you are creating the rule, such as pubsub.googleapis.com.; note the trailing dot

Directing all names except some to restricted VIP addresses

You can set rules to exempt some DNS responses from a policy rule that covers an entire domain or a large IP address block. This concept is called passthru behavior. By using passthru behavior, you can let names that lack support for service controls be allowed past the wildcard name.

For example, you can let www.googleapis.com be allowed past the wildcard name in the example *.googleapis.com. The exact match for www takes precedence over the wildcard *.

In the following example configuration, you create a policy with a specified name and apply it to a specific VPC network. The rule allows www.googleapis.com to bypass the wildcard *.googleapis.com.

gcloud

To create a response policy, run the gcloud beta dns response-policies create command:
```
gcloud beta dns response-policies create RESPONSE_POLICY_NAME \
    --networks=NETWORK \
    --description=DESCRIPTION
```
Replace the following:
- RESPONSE_POLICY_NAME: the name or ID of the response policy that you want to create, such as myresponsepolicy
- NETWORK: a comma-separated list of network names to associate with the response policy, such as network1,network2
- DESCRIPTION: a description of the response policy, such as My new response policy
To add a bypass rule to the policy, run the gcloud beta dns response-policies rules create command, and set the --behavior flag to bypassResponsePolicy:
```
gcloud beta dns response-policies rules create RESPONSE_POLICY_RULE_NAME \
    --response-policy=RESPONSE_POLICY_NAME \
    --dns-name=DNS_NAME \
    --behavior=bypassResponsePolicy
```
Replace the following:
- RESPONSE_POLICY_RULE_NAME: a name for the response policy rule that you want to create, such as myresponsepolicyrule
- RESPONSE_POLICY_NAME: the name of the response policy, such as myresponsepolicy
- DNS_NAME: the DNS or domain name, such as www.googleapis.com

API

Create a response policy:
```
{
  kind: "dns#responsePolicy",
  response_policy_name: RESPONSE_POLICY_NAME,
  description: RESPONSE_POLICY_DESCRIPTION,
  networks: [
    {
      network_url: URL_TO_NETWORK;
    }
  ]
}
```
Replace the following:
- RESPONSE_POLICY_NAME: a name for the response policy, such as my-response-policy
- RESPONSE_POLICY_DESCRIPTION: a description of the response policy, such as my response policy
- URL_TO_NETWORK: the URL for which you're creating the response policy

Add a rule to the policy:

{
  kind: "dns#responsePolicyRules",
  rule_name: RULE_NAME,
  dns_name: DNS_NAME,
  local_data: [
    {
      name: "*.googleapis.com.",
      type: "A",
      ttl: 300,
      rrdata: ["restricted.googleapis.com."]
    }
  ]
}
{
  kind: "dns#responsePolicyRules",
  rule_name: "www-passthru",
  dns_name: "www.googleapis.com.",
  behavior: BYPASS_RESPONSE_POLICY
}

Replace the following:

RULE_NAME: a name for the rule that you are creating, such as googleapis
DNS_NAME: the wildcard DNS name for which you are creating the rule, such as *.googleapis.com.; note the trailing dot

What's next

To create, update, list, and delete managed zones, see Managing zones.
To find solutions for common issues that you might encounter when using Cloud DNS, see Troubleshooting.
To get an overview of Cloud DNS, see Cloud DNS overview.