Manage DNS names for VPC endpoint services
Service providers can configure private DNS names for their endpoint services. Suppose that a service provider makes their service available through a public endpoint and as an endpoint service. If the service provider uses the DNS name of the public endpoint as the private DNS name of the endpoint service, then service consumers can access the public endpoint or the endpoint service using the same client application, without modification. If a request comes from the service consumer VPC, the private DNS servers resolve the DNS name to the IP addresses of the endpoint network interfaces. Otherwise, the public DNS servers resolve the DNS name to the public endpoint.
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.
-
When the consumer creates an interface endpoint to connect to your service, we create a private hosted zone and associate it with the service consumer VPC. We create a CNAME record in the private hosted zone that maps the private DNS name of the endpoint service to the regional DNS name of the VPC endpoint. When a consumer sends a request to the public DNS name of the service, the private DNS servers resolve the request to the IP addresses of the endpoint network interfaces.
-
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. 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.
-
Private DNS names are not supported for Gateway Load Balancer endpoints.
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 AWS 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 AWS 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.
DNS/Hosting provider | Documentation link |
---|---|
GoDaddy |
|
Dreamhost |
|
Cloudflare |
|
HostGator |
|
Namecheap |
|
Names.co.uk |
|
Wix |
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 command, 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
-
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.
-
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
-
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 AWS 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.
-
In the Route 53 console, choose the TXT record that you created when you verified your domain in the first Region.
-
For Value, go to the end of the existing attribute value, and then press Enter.
-
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.
-