Skip to content

Deploy in a VPC with a custom domain name#

Some organizations follow network patterns which impose a specific domain name for Instances. In that case, the instance's hostname instead of would be

The control plane at needs to be aware of such case in order to properly initialize the Cluster.


This feature is enabled only upon request. If you want this feature to be enable for your account please contact sales

There are multiple ways to use custom domain names in your organization which are beyond the scope of this guide. We assume your cloud/network team has already setup the infrastructure.

If you are using a resolver such as Amazon Route 53, it is advised to update the record sets automatically. See our guide below for more information.

Set cluster domain name#

If this feature is enabled for your account, then in the VPC selection step you will have the option to specify the custom domain name as shown in the figure below.

Custom domain name
VPC with custom domain name

In this case, the hostname of the Instance would be

Hostnames must be resolvable by all Virtual Machines in the cluster. For that reason we suggest, if possible, to automatically register the hostnames with your DNS.

In the following section we present an example of automatic name registration in Amazon Route 53

Auto registration with Amazon Route 53#

It is quite common for organizations in AWS to use Route 53 for DNS or for hosted zones. You can configure a cluster in to execute some custom initialization script before any other action. This script will be executed on all nodes of the cluster.

Since the hostname of the VM is in the form of INSTANCE_ID.DOMAIN_NAME it is easy to automate the zone update. The script below creates an A record in a configured Route 53 hosted zone.


If you want the VM to register itself with Route 53 you must amend the Instance Profile with the following permissions

    "Sid": "Route53RecordSet",
    "Effect": "Allow",
    "Action": [
    "Resource": "arn:aws:route53:::hostedzone/YOUR_HOSTED_ZONE_ID"
    "Sid": "Route53GetChange",
    "Effect": "Allow",
    "Action": [
    "Resource": "arn:aws:route53:::change/*"

The following script will get the instance ID from the EC2 metadata server and add an A record to the hosted zone in Route53. Update the YOUR_HOSTED_ZONE_ID and YOUR_CUSTOM_DOMAIN_NAME to match yours.

#!/usr/bin/env bash
set -e



instance_id=$(curl --silent


local_ip=$(curl --silent

cat << EOC | tee $record_set_file
    "Changes": [
            "Action": "UPSERT",
            "ResourceRecordSet": {
                "Name": "${domain_name}",
                "Type": "A",
                "TTL": 60,
                "ResourceRecords": [
                        "Value": "${local_ip}"

echo "Adding A record ${domain_name} -> ${local_ip} to Hosted Zone ${HOSTED_ZONE_ID}"
change_resource_id=$(aws route53 change-resource-record-sets --hosted-zone-id ${HOSTED_ZONE_ID} --change-batch file://${record_set_file} | jq -r '.ChangeInfo.Id')

echo "Change resource ID: ${change_resource_id}"
aws route53 wait resource-record-sets-changed --id ${change_resource_id}
echo "Added resource record set"

rm -f ${record_set_file}

Set VM initialization script#

As a final step you need to configure the Cluster to use the script above during VM creation with the user init script option.

Paste the script to the text box and make sure you select this script to be executed before anything else on the VM.

Automatic domain name registration
Automatic domain name registration with Route53