Manage DNS names for VPC endpoint services - Amazon Virtual Private Cloud
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Manage DNS names for VPC endpoint services

Service providers can configure private DNS names for their endpoint services. When a service provider uses an existing public DNS name as the private DNS name for their endpoint service, then service consumers don't need to change any applications that use the existing public DNS name. Before you can configure a private DNS name for your endpoint service, you must prove that you own the domain by performing a domain ownership verification check.

Considerations
  • An endpoint service can have only one private DNS name.

  • You must not create an A record for the private DNS name, so that only servers in the service consumer VPC can resolve the private DNS name.

  • Private DNS names are not supported for Gateway Load Balancer endpoints.

  • To verify a domain, you must have a public hostname or a public DNS provider.

  • You can verify the domain of a subdomain. For example, you can verify example.com, instead of a.example.com. As specified in RFC 1034, each DNS label can have up to 63 characters and the whole domain name must not exceed a total length of 255 characters.

    If you add an additional subdomain, you must verify the subdomain, or the domain. For example, let's say you had a.example.com, and verified example.com. You now add b.example.com as a private DNS name. You must verify example.com or b.example.com before service consumers can use the name.

Domain ownership verification

Your domain is associated with a set of domain name service (DNS) records that you manage through your DNS provider. A TXT record is a type of DNS record that provides additional information about your domain. It consists of a name and a value. As part of the verification process, you must add a TXT record to the DNS server for your public domain.

Domain ownership verification is complete when we detect the existence of the TXT record in your domain's DNS settings.

After you add a record, you can check the status of the domain verification process using the Amazon VPC console. In the navigation pane, choose Endpoint services. Select the endpoint service and check the value of Domain verification status in the Details tab. If domain verification is pending, wait a few minutes and refresh the screen. If needed, you can initiate the verification process manually. Choose Actions, Verify domain ownership for private DNS name.

The private DNS name is ready for use by service consumers when the verification status is verified. If the verification status changes, new connection requests are denied but existing connections are not affected.

If the verification status is failed, see Troubleshoot domain verification issues.

Get the name and value

We provide you with the name and value that you use in the TXT record. For example, the information is available in the Amazon Web Services Management Console. Select the endpoint service and see Domain verification name and Domain verification value on the Details tab for the endpoint service. You can also use the following describe-vpc-endpoint-service-configurations Amazon CLI command to retrieve information about the configuration of the private DNS name for the specified endpoint service.

aws ec2 describe-vpc-endpoint-service-configurations \ --service-ids vpce-svc-071afff70666e61e0 \ --query ServiceConfigurations[*].PrivateDnsNameConfiguration

The following is example output. You'll use Value and Name when you create the TXT record.

[ { "State": "pendingVerification", "Type": "TXT", "Value": "vpce:l6p0ERxlTt45jevFwOCp", "Name": "_6e86v84tqgqubxbwii1m" } ]

For example, suppose that your domain name is example.com and that Value and Name are as shown in the preceding example output. The following table is an example of the TXT record settings.

Name Type Value

_6e86v84tqgqubxbwii1m.example.com

TXT

vpce:l6p0ERxlTt45jevFwOCp

We suggest that you use Name as the record subdomain because the base domain name might already be in use. However, if your DNS provider does not allow DNS record names to contain underscores, you can omit the "_6e86v84tqgqubxbwii1m" and simply use "example.com" in the TXT record.

After we verify "_6e86v84tqgqubxbwii1m.example.com", service consumers can use "example.com" or a subdomain (for example, "service.example.com" or "my.service.example.com").

Add a TXT record to your domain's DNS server

The procedure for adding TXT records to your domain's DNS server depends on who provides your DNS service. Your DNS provider might be Amazon Route 53 or another domain name registrar.

Create a record for your public hosted zone. Use the following values:

  • For Record type, choose TXT.

  • For TTL (seconds), enter 1800.

  • For Routing policy, choose Simple routing.

  • For Record name enter the domain or subdomain.

  • For Value/Route traffic to, enter the domain verification value.

For more information, see Create records using the console in the Amazon Route 53 Developer Guide.

Go to the website for your DNS provider and sign in to your account. Find the page to update the DNS records for your domain. Add a TXT record with the name and value that we provided. It can take up to 48 hours for DNS record updates to take effect, but they often take effect much sooner.

For more specific directions, consult the documentation from your DNS provider. The following table provides links to the documentation for several common DNS providers. This list is not intended to be comprehensive, nor is it intended as a recommendation of the products or services provided by these companies.

Check whether the TXT record is published

You can verify that your private DNS name domain ownership verification TXT record is published correctly to your DNS server using the following steps. You'll run the nslookup tool, which is available for Windows and Linux.

You'll query the DNS servers that serve your domain because those servers contain the most up-to-date information for your domain. Your domain information takes time to propagate to other DNS servers.

To verify that your TXT record is published to your DNS server
  1. Find the name servers for your domain using the following command.

    nslookup -type=NS example.com

    The output lists the name servers that serve your domain. You'll query one of these servers in the next step.

  2. Verify that the TXT record is correctly published using the following command, where name_server is one of the name servers that you found in the previous step.

    nslookup -type=TXT _6e86v84tqgqubxbwii1m.example.com name_server
  3. In the output of the previous step, verify that the string that follows text = matches the TXT value.

    In our example, if the record is correctly published, the output includes the following.

    _6e86v84tqgqubxbwii1m.example.com text = "vpce:l6p0ERxlTt45jevFwOCp"

Troubleshoot domain verification issues

If the domain verification process fails, the following information can help you troubleshoot issues.

  • Check whether your DNS provider allows underscores in TXT record names. If your DNS provider does not allow underscores, you can omit the domain verification name (for example, "_6e86v84tqgqubxbwii1m") from the TXT record.

  • Check whether your DNS provider appended the domain name to the end of the TXT record. Some DNS providers automatically append the name of your domain to the attribute name of the TXT record. To avoid this duplication of the domain name, add a period to the end of the domain name when you create the TXT record. This tells your DNS provider that it isn't necessary to append the domain name to the TXT record.

  • Check whether your DNS provider modified the DNS record value to use only lowercase letters. We verify your domain only when there is a verification record with an attribute value that exactly matches the value that we provided. If the DNS provider changed your TXT record values to use only lowercase letters, contact them for assistance.

  • You might need to verify your domain more than once because you're supporting multiple Regions or multiple Amazon Web Services accounts. If your DNS provider doesn't allow you to have more than one TXT record with the same attribute name, check whether your DNS provider allows you to assign multiple attribute values to the same TXT record. For example, if your DNS is managed by Amazon Route 53, you can use the following procedure.

    1. In the Route 53 console, choose the TXT record that you created when you verified your domain in the first Region.

    2. For Value, go to the end of the existing attribute value, and then press Enter.

    3. Add the attribute value for the additional Region, and then save the record set.

    If your DNS provider doesn't allow you to assign multiple values to the same TXT record, you can verify the domain once with the value in the attribute name of the TXT record, and one other time with the value removed from the attribute name. However, you can only verify the same domain two times.