Route53
5 minute read
Introduction
Route 53 is a highly scalable and reliable domain name system (DNS) web service provided by Amazon Web Services. Route 53 allows you to register domain names, and associate them with IP addresses or other resources. In addition to basic DNS functionality, Route 53 offers advanced features like health checks and DNS failover. Route 53 integrates seamlessly with other AWS services, such as route traffic to CloudFront distributions, S3 buckets configured for static website hosting, EC2 instances, and more.
LocalStack supports Route53 via the Community offering, allowing you to use the Route53 APIs in your local environment to create hosted zones and to manage DNS entries which can then be queried via the built-in DNS server. The supported APIs are available on our API coverage page, which provides information on the extent of Route53’s integration with LocalStack.
Getting started
This guide is designed for users new to Route53 and assumes basic knowledge of the AWS CLI and our awslocal
wrapper script.
Start your LocalStack container using your preferred method. We will demonstrate how to create a hosted zone and query the DNS record with the AWS CLI.
Note
The built-in DNS capabilities requires privileged access for the LocalStack container. TheDNS_ADDRESS
configuration variable can be used to address the port the LocalStack should bind the DNS server on (port 53 tcp/udp). Default is 0.0.0.0
and you can add 0
to disable.Create a hosted zone
You can created a hosted zone for example.com
using the CreateHostedZone
API. Run the following command:
$ zone_id=$(awslocal route53 create-hosted-zone \
--name example.com \
--caller-reference r1 | jq -r '.HostedZone.Id')
$ echo $zone_id
The following output would be retrieved:
/hostedzone/WBCZ6F10CWV9J1G
Change resource record sets
You can now change the resource record sets for the hosted zone example.com
using the ChangeResourceRecordSets
API. Run the following command:
$ awslocal route53 change-resource-record-sets \
--hosted-zone-id $zone_id \
--change-batch 'Changes=[{Action=CREATE,ResourceRecordSet={Name=test.example.com,Type=A,ResourceRecords=[{Value=1.2.3.4}]}}]'
The following output would be retrieved:
{
"ChangeInfo": {
"Id": "/change/C2682N5HXP0BZ4",
"Status": "INSYNC",
"SubmittedAt": "2010-09-10T01:36:41.958000Z"
}
}
Query DNS record
You can query the DNS record using dig
via the built-in DNS server by running the following command:
$ dig @localhost test.example.com
The following output would be retrieved:
;; QUESTION SECTION:
;test.example.com. IN A
;; ANSWER SECTION:
test.example.com. 300 IN A 1.2.3.4
Customizing internal endpoint resolution
The DNS name localhost.localstack.cloud
, along with its subdomains like mybucket.s3.localhost.localstack.cloud
, serves an internal routing purpose within LocalStack. It facilitates communication between a Lambda container and the LocalStack APIs.
For most use-cases, the default configuration of the internal LocalStack DNS name requires no modification. It functions seamlessly in typical scenarios. However, there are instances where adjusting the external resolution of this DNS name becomes necessary. For instance, this might be required when your LocalStack instance operates on a distinct Docker network compared to your application code or even on a separate machine.
Suppose you intend to achieve a scenario in which all subdomains in the format *.localhost.localstack.cloud
resolve to the IP address 5.6.7.8
. This IP signifies the accessibility of your LocalStack instance. This can be accomplished using Route53.
Create a hosted zone for the domain localhost.localstack.cloud
using the CreateHostedZone
API API. Run the following command:
$ zone_id=$(awslocal route53 create-hosted-zone \
--name localhost.localstack.cloud \
--caller-reference r1 | jq -r .HostedZone.Id)
$ echo $zone_id
The following output would be retrieved:
/hostedzone/3NF6SEGOB5EBHS1
You can now use the ChangeResourceRecordSets
API to create a record set for the domain localhost.localstack.cloud
using the zone_id
retrieved in the previous step. Run the following command to accomplish this:
$ awslocal route53 change-resource-record-sets \
--hosted-zone-id $zone_id \
--change-batch '{"Changes":[{"Action":"CREATE","ResourceRecordSet":{"Name":"localhost.localstack.cloud","Type":"A","ResourceRecords":[{"Value":"5.6.7.8"}]}},{"Action":"CREATE","ResourceRecordSet":{"Name":"*.localhost.localstack.cloud","Type":"A","ResourceRecords":[{"Value":"5.6.7.8"}]}}]}'
The following output would be retrieved:
{
"ChangeInfo": {
"Id": "/change/C2682N5HXP0BZ4",
"Status": "INSYNC",
"SubmittedAt": "2010-09-10T01:36:41.958000Z"
}
}
You can now verify that the DNS name localhost.localstack.cloud
and its subdomains resolve to the IP address:
$ dig @127.0.0.1 bucket1.s3.localhost.localstack.cloud
$ dig @127.0.0.1 localhost.localstack.cloud
The following output would be retrieved:
...
;; ANSWER SECTION:
bucket1.s3.localhost.localstack.cloud. 300 IN A 127.0.0.1
bucket1.s3.localhost.localstack.cloud. 300 IN A 5.6.7.8
...
;; QUESTION SECTION:
;localhost.localstack.cloud. IN A
;; ANSWER SECTION:
localhost.localstack.cloud. 300 IN A 5.6.7.8
Resource Browser
The LocalStack Web Application provides a Route53 for creating hosted zones and to manage DNS entries. You can access the Resource Browser by opening the LocalStack Web Application in your browser, navigating to the Resources section, and then clicking on Route53 under the Analytics section.

The Resource Browser allows you to perform the following actions:
- Create Hosted Zone: Create a hosted zone for a domain name by clicking on the Create Hosted Zone button. This will open a modal where you can enter the name, VPC, and other paramteres and click on the Submit button to create the hosted zone.
- View Hosted Zone: View the details of a hosted zone by clicking on the specific hosted zone name. This will open a modal where you can view the hosted zone details.
- Create Record: Click on the Records button on the individual hosted zone page, followed by clicking Create Record to create a record for the hosted zone. This will open a modal where you can enter the name, type, and other paramteres and click on the Submit button to create the record.
- Edit Record: Click on the Records button on the individual hosted zone page, followed by clicking Edit on the specific record to edit the record. This will open a modal where you can edit the record details and click on the Submit button to save the changes.s
- View Records: Click on the Records button on the individual hosted zone page, followed by clicking on the specific record to view the record details. This will open a modal where you can view the record details.
- Delete Hosted Zone: Select the hosted zones you want to delete by clicking on the checkbox next to the hosted zone name, followed by clicking on the Actions button and then clicking on Remove Selected.
- Delete Record: Click on the Records button on the individual hosted zone page, followed by clicking on checkbox next to the specific record, and then clicking on the Actions button and then clicking on Remove Selected.
Examples
The following code snippets and sample applications provide practical examples of how to use Route53 in LocalStack for various use cases: