Menu
Amazon Route 53
API Reference

Using Auto Naming for Service Discovery

Amazon Route 53 auto naming makes it easier to provision instances for microservices by automating DNS configuration. Auto naming lets you automatically create DNS records based on a configuration that you define. You can also optionally create a health check based on the same configuration and associate the health check with all of the new records.

Overview

Here's an overview of how you use Route 53 auto naming:

  1. Create either a public namespace (accessible on the internet) or a private namespace (accessible only in an Amazon VPC). Note the following:

    • A namespace is a logical group of services that share the same domain name, such as example.com.

    • When you create a namespace, you specify a name that matches the name of a domain that you've registered.

    • When you create a namespace, Route 53 automatically creates a public or private hosted zone that has the same name as the namespace.

    • For private namespaces, you can query within your VPC immediately.

    Commands:

    For a list of the endpoints that you can submit HTTPS requests to, see Amazon Route 53 in the "AWS Regions and Endpoints" chapter in the Amazon Web Services General Reference.

  2. If you created a public DNS namespace, perform the following steps:

    1. If you already registered a domain that has the same name as the public DNS namespace, skip to step 2b.

      If you haven't registered a domain that has the same name as the namespace, register a domain. If you want to use Route 53 for domain registration, see Registering a New Domain in the Amazon Route 53 Developer Guide.

    2. Get the names of the name servers that Route 53 assigned to your hosted zone. For more information, see Getting the Name Servers for a Public Hosted Zone.

    3. Change the name servers that are assigned to the domain. If the domain is registered with Route 53, see Adding or Changing Name Servers and Glue Records for a Domain for more information.

  3. Using the OperationId that was returned when you created the namespace, get the namespace ID.

    Command:

  4. Create a service for the namespace, and specify the following values:

    • A name for the service, such as backend or worker. When you register an instance in the next step, Route 53 creates records in the hosted zone that it created automatically in step 1. The record names are a combination of the name of the service and the name of the namespace, for example, backend.example.com or worker.example.com.

    • DNS settings for the applicable records.

    • Optionally, a health check. If you specify settings for a health check, Route 53 assigns the health check to all the records that it creates when you register an instance.

    • The NamespaceId that you got in step 3.

    Command:

  5. Register one or more instances. Specify the ServiceId that Route 53 returned in the response to the CreateService request, an InstanceId to associate your instance with the record, and IP address for the instance.

    Route 53 creates multivalue answer or weighted records based on the settings that you specified in the service. You can see the records that Route 53 creates in the hosted zone, but you can't change or delete them. For more information, see Multivalue Answer Routing and Weighted Routing in the Amazon Route 53 Developer Guide

    Command:

    When Route 53 receives a DNS query for the name of an instance, such as backend.example.com, it responds with the applicable values based on the settings that you specified when you created the service and when you registered instances. If you specified settings for a health check when you created the service, Route 53 returns values only for healthy instances.

  6. When you're ready to remove the DNS records and healthchecks for an instance, you can deregister your instance. Route 53 automatically deletes the corresponding resources. Specify the ServiceId that Route 53 returned in the response to the CreateService request, and specify the InstanceId for the instance that you want to deregister.

    Command:

  7. If you don't need a service and namespace any longer, you can delete them. Note the following:

    • Before you can delete a service, you must deregister all instances that were registered using the service.

    • Before you can delete a namespace, you must delete all services that were created using the namespace.

    Commands:

Using Service Discovery with an Existing Hosted Zone

If you already have a hosted zone for a domain such as example.com, you can continue to use the records in that hosted zone and configure service discovery using the same domain name.

To use service discovery with an existing hosted zone

  1. Create a public namespace (accessible on the internet) or a private namespace (accessible only in an Amazon VPC).

    If you create a public namespace, give it the same name as the existing hosted zone. Route 53 creates another hosted zone that has the same name.

    If you create a private namespace, you must give it a different name than the existing hosted zone.

    Command:

  2. Use the OperationId that was returned when you created the namespace to get the namespace ID.

    Command:

  3. Create one or more services.

    Command:

  4. In the existing hosted zone, create one alias record for each service discovery service that you want to route DNS queries to.

    Note the following:

    • Don't update the configuration for the domain to use different name servers. Continue to use the name servers for the existing hosted zone.

    • Whenever you add another service to the hosted zone that service discovery created, you must add another alias record to the original hosted zone.

    You can't use the Route 53 console to create an alias record in one hosted zone that refers to a record in another hosted zone, so you must create the alias record programmatically. Here's how you do it using the AWS Command Line Interface (AWS CLI) change-resource-record-sets command. For information about installing and configuring the AWS CLI, see the AWS Command Line Interface User Guide.

    1. Create a text file that contains the definition of the new alias record:

      { "Changes": [ { "Action": "UPSERT", "ResourceRecordSet": { "Type":"A", "Name":"record-name-in-existing-hosted-zone", "AliasTarget": { "DNSName":"record-name-in-new-hosted-zone", "HostedZoneId":"service-discovery-hosted-zone-id", "EvaluateTargetHealth":true } } } ] }

      Specify the following values:

      record-name-in-existing-hosted-zone

      The name of the record that you want to create in the existing hosted zone

      record-name-in-new-hosted-zone

      The name of the record that service discovery created in the hosted zone for your namespace, for example, backend.example.com

      Note

      If you created a public DNS namespace in step 1, the record names will be the same. If you created a private namespace, the record names will be different because the hosted zone names are different.

      service-discovery-hosted-zone-id

      The ID of the hosted zone that service discovery created when you created a namespace

    2. Run the following AWS CLI change-resource-record-sets command:

      aws route53 change-resource-record-sets --hosted-zone-id existing-hosted-zone-id --change-batch file://path-to-text-file

      Specify the following values:

      existing-hosted-zone-id

      The ID of the hosted zone that existed before you created a namespace

      path-to-text-file

      The path to the text file that you created in step 4a