Prerequisites

• A domain registered with or managed through AWS Route 53
• Your Tunnelwise unique URL (e.g., your-tunnel.tunnelwise.io)
• AWS account with appropriate IAM permissions for Route 53
• Access to the AWS Management Console or AWS CLI

Step-by-Step Instructions

1. Access AWS Route 53

• Log in to the AWS Management Console
• Navigate to Route 53 service (search for it in the services search bar)
• Click on Hosted zones in the left sidebar

2. Select Your Hosted Zone

• Find and click on your domain name from the list of hosted zones
• You'll see all existing DNS records for this domain
• Note the Hosted zone ID for reference

3. Create a New CNAME Record

• Click the Create record button
• Choose Simple routing if prompted for routing policy
• Configure the record with the following settings:

Important: Don't include the domain name in the Record name field

• Route 53 automatically appends your domain
• The value must be a fully qualified domain name (FQDN)

4. Review and Create

• Click Define simple record
• Review your settings in the preview
• Click Create records
• You'll see a success notification

Verification

DNS Propagation

Route 53 changes typically propagate within 60 seconds to AWS's global DNS servers, but full global propagation can take up to 48 hours. You can check the propagation status using:

# Check if your CNAME is resolving correctly
dig your-subdomain.yourdomain.com CNAME

# Or using nslookup
nslookup your-subdomain.yourdomain.com

Testing Your Custom Domain

Once DNS has propagated:

1. Open Tunnelwise
2. Start a tunnel with your custom domain
3. Visit https://your-subdomain.yourdomain.com in your browser
4. You should see your local application

Troubleshooting

Common Issues

1. Record Set Already Exists

Problem: Error saying record set already exists

Solution:

• Check for existing records with the same name
• Delete or update the existing record
• Use the AWS Console to view all records for conflicts

2. Invalid Resource Record

Problem: Error about invalid resource record format

Solution:

• Ensure the CNAME value ends with a period (.) if entering via JSON/CLI
• Don't add a period when using the AWS Console
• Verify the target domain is a valid FQDN

AWS-Specific Settings

Health Checks

Route 53 health checks are not recommended for Tunnelwise tunnels:

• Tunnels may be intermittent during development
• Health checks incur additional AWS charges
• Can cause false-positive alerts

Traffic Policies

For simple tunnel setups, avoid complex routing:

• Use Simple routing policy
• Weighted, Latency, or Geolocation routing not needed
• Failover routing only if you have backup tunnels

Still Need Help?

If you encounter issues not covered in this guide:

1. Check the Tunnelwise Documentation
2. Review existing and closed issues on Github. If you can't find a related issue, feel free to open one
3. Visit the Route 53 Documentation