Configure a custom domain name for your VPC Lattice service - Amazon VPC Lattice
Associate a custom domain name with your service

Configure a custom domain name for your VPC Lattice service

When you create a new service, VPC Lattice generates a unique Fully Qualified Domain Name (FQDN) for the service with the following syntax.

service_name-service_id.partition_id.vpc-lattice-svcs.region.on.aws

However, the domain names that VPC Lattice provides are not easy for your users to remember. Custom domain names are simpler and more intuitive URLs that you can provide to your users. If you'd prefer to use a custom domain name for your service, such as www.parking.example.com instead of the VPC Lattice generated DNS name, you can configure it when you create a VPC Lattice service. When a client makes a request using your custom domain name, the DNS server resolves it to the VPC Lattice generated domain name. However, this happens only if you map your custom domain name to the VPC Lattice generated domain name with a CNAME record to route queries to your service. For more information, see Associate a custom domain name with your service.

Prerequisites

  • You must have a registered domain name for your service. If you don't already have a registered domain name, you can register one through Amazon Route 53 or any other commercial registrar.

  • To receive HTTPS requests, you must provide your own certificate in AWS Certificate Manager. VPC Lattice doesn't support a default certificate as a fallback. Therefore, if you don't provide an SSL/TLS certificate corresponding to your custom domain name, all HTTPS connections to your custom domain name will fail. For more information, see Bring Your Own Certificate (BYOC) for VPC Lattice.

Limitations and considerations

  • You can’t have more than one custom domain name for a service.

  • You can’t modify the custom domain name after you've created the service.

  • The custom domain name must be unique for a service network. This means that a service can't be created with a custom domain name that already exists (for another service) in the same service network.

To configure a custom domain name for your service using the AWS Management Console

  1. Open the Amazon VPC console at https://console.aws.amazon.com/vpc/.

  2. In the navigation pane, under VPC Lattice, choose Service.

  3. Choose Create Service. You are navigated to Step 1: Create a service.

  4. In the Custom domain configuration section, choose Specify a custom domain configuration.

  5. Enter your custom domain name.

  6. To serve HTTPS requests, select the SSL/TLS certificate matching your custom domain name in Custom SSL/TLS certificate. If you don't have a certificate yet, or don't want to add one now, you can add a certificate when you create your HTTPS listener. However, without a certificate, your custom domain name won't be able to serve HTTPS requests. For more information, see Add an HTTPS listener.

  7. When you have finished adding all other information for creating the service, choose Create.

To configure a custom domain name for your service using the AWS CLI

Use the create-service command.

aws vpc-lattice create-service --name service_name --custom-domain-name your_custom_domain_name --type https --certificate-arn arn:aws:acm:us-east-1:123456789012:certificate/12345678-1234-1234-1234-123456789012

In the above command, for --name, enter a name for your service. For --custom-domain-name, enter your service's domain name such as, parking.example.com. For --certificate-arn enter the ARN of your certificate in ACM. The certificate ARN is available in your account in AWS Certificate Manager.

If you don’t have your own SSL/TLS certificate in AWS Certificate Manager (ACM), you can create or import one before setting up a custom domain name. However, the certificate is required only if you want to serve HTTPS requests using your custom domain name. For more information, see Bring Your Own Certificate (BYOC) for VPC Lattice.

Associate a custom domain name with your service

First, if you haven't already done so, register your custom domain name. The Internet Corporation for Assigned Names and Numbers (ICANN) manages domain names on the internet. You register a domain name using a domain name registrar, an ICANN-accredited organization that manages the registry of domain names. The website for your registrar will provide detailed instructions and pricing information for registering your domain name. For more information, see the following resources:

Next, use your DNS service, such as your domain registrar, to create a CNAME record to route queries to your service. For more information, see the documentation for your DNS service. Alternatively, you can use Route 53 as your DNS service.

If you're using Route 53, you must first create a hosted zone, which contains information about how to route traffic on the internet for your domain. After you create the private or public hosted zone, create a CNAME record such that your custom domain name, for example parking.example.com, is mapped to the VPC Lattice auto-generated domain name, for example, my-service-02031c045478f6ddf1.7d67968.vpc-lattice-svcs.us-west-2.on.aws. Without this mapping, your custom domain name won't work in VPC Lattice. For more information, see Creating records by using the Amazon Route 53 console in the Amazon Route 53 Developer Guide. Additionally, you can refer to the steps below to create a hosted zone and a CNAME record to map your custom domain name to the VPC Lattice endpoint.

To create a private or public hosted zone with a CNAME record using Amazon Route 53 console

  1. Open the Route 53 console at https://console.aws.amazon.com/route53/.

  2. In the navigation pane, choose Hosted zones and then Create hosted zone.

  3. For Domain name, choose the name of the hosted zone that you want to use to route traffic to your VPC Lattice service. For example, If your custom domain name is parking.example.com (http://parking.example.com/), then the domain name for your hosted zone will be example.com (http://example.com/), also known as the apex domain name. You can then create a CNAME record for this hosted zone to route traffic to your VPC Lattice service. Note: You can't change the name of a hosted zone after you create it.

  4. For Type, choose Private Hosted Zone or Public Hosted Zone as required.

  5. Choose your Region and select the VPC ID for a VPC that you want to associate with this hosted zone.

  6. Add tags if necessary, and choose Create hosted zone. After creation, your hosted zone is listed under Hosted Zones.

  7. To create a CNAME record in the hosted zone that you just created, select the hosted zone, then select Create record.

  8. Specify the following values under Create record:

    1. For Record name, enter the name that you want to use as your custom domain name. If you want to use parking.example.com (http://acme.example.com/) as your custom domain name, enter parking*. This means that you would enter the subdomain name parking but without the hosted zone domain name example.com (http://example.com/).

    2. For Record type, choose CNAME.

    3. Keep Alias turned off.

    4. For Value, enter the VPC Lattice generated the domain name for your service (for example, my-service-02031c045478f6ddf1.7d67968.vpc-lattice-svcs.us-west-2.on.aws). You will find this auto-generated domain name in the VPC Lattice console on your service page. If using the AWS CLI, the output of the create-service or list-services commands will return this auto-generated domain name.

    5. For TTL (seconds), accept the default value of 300.

    6. For Routing policy, choose the applicable routing policy. For more information, see Choosing a routing policy in the Amazon Route 53 Developer Guide.

  9. Choose Create records.

    Changes generally propagate to all Route 53 servers within 60 seconds. When propagation is done, you'll be able to route traffic to your service by using the custom domain name.

To create an alias record in your hosted zone using the AWS CLI

  1. Obtain the VPC Lattice generated domain name for your service (for example, my-service-02031c045478f6ddf1.7d67968.vpc-lattice-svcs.us-west-2.on.aws) and the hosted zone ID by running the get-service command.

  2. To set the alias, use following command.

    aws route53 change-resource-record-sets --hosted-zone-id hosted-zone-id-for-your-service-domain --change-batch file://~/Desktop/change-set.json

    For the change-set.json file, create a JSON file with the content in the following JSON example, and save it on your local machine. Replace file://~/Desktop/change-set.json in the above command with the path of the JSON file saved in your local machine. Note that "Type" in the following JSON can be an A or AAAA record type.

    {
    "Comment": "my-service-domain.com alias",
    "Changes": [
        {
            "Action": "CREATE",
            "ResourceRecordSet": {
                "Name": "my-custom-domain-name.com",
                "Type": "alias-record-type",
                "AliasTarget": {
                    "HostedZoneId": "hosted-zone-id-for-your-service-domain",
                    "DNSName": "lattice-generated-domain-name",
                    "EvaluateTargetHealth": true
                }
            }   
        }
    ] 
}