Learn how to use Amazon Cloud Map service discovery with DNS queries and API calls
This tutorial simulates a microservice architecture with two backend services. The first service will be discoverable using a DNS query. The second service will be discoverable using the Amazon Cloud Map API only.
Note
For the purposes of this tutorial, the resource details, like domain names and IP addresses, are for simulation purposes only. They can't be resolved over the internet.
Prerequisites
The following prerequisites must be met to complete this tutorial successfully.
-
Before you begin, complete the steps in Set up to use Amazon Cloud Map.
-
If you have not yet installed the Amazon Command Line Interface, follow the steps at Installing or updating the latest version of the Amazon CLI to install it.
The tutorial requires a command line terminal or shell to run commands. In Linux and macOS, use your preferred shell and package manager.
Note
In Windows, some Bash CLI commands that you commonly use with Lambda (such as
zip
) are not supported by the operating system's built-in terminals. To get a Windows-integrated version of Ubuntu and Bash, install the Windows Subsystem for Linux. The tutorial requires a local environment with the
dig
DNS lookup utility command. For more information about thedig
command, see dig - DNS lookup utility.
Step 1: Create an Amazon Cloud Map namespace
In this step, you create a public Amazon Cloud Map namespace. Amazon Cloud Map creates a Route 53 hosted zone on your behalf with this same name. This gives you the ability to discover the service instances created in this namespace either using public DNS records or by using Amazon Cloud Map API calls.
Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/
. -
Choose Create namespace.
-
For Namespace name, specify
cloudmap-tutorial.com
.Note
If you were going to use this in production, you'd want to ensure that you specified the name of a domain you owned or had access to. But for the purposes of this tuturial, it's not necessary for it to be an actual domain that's being used.
-
(Optional) For Namespace description, specify a description for what you intend to use the namespace for.
-
For Instance discovery, select API calls and public DNS queries.
-
Leave the rest of the default values and choose Create namespace.
Step 2: Create the Amazon Cloud Map services
In this step, you create two services. The first service will be discoverable using public DNS and API calls. The second service will be discoverable using API calls only.
Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/
. -
In the left navigation pane, choose Namespaces to list the namespaces you've created.
-
From the list of namespaces, select the
cloudmap-tutorial.com
namespace and choose View details. -
In the Services section, choose Create service and do the following to create the first service.
-
For Service name, enter
public-service
. The service name will be applied to the DNS records that Amazon Cloud Map creates. The format that is used is
.<service-name>
.<namespace-name>
-
For Service Discovery Configuration, select API and DNS.
-
In the DNS configuration section, for Routing policy, select Multivalue answer routing.
Note
The console will translate this to MULTIVALUE after it is selected. For more information about available routing options, see Choosing a routing policy in the Route 53 Developer Guide.
-
Leave the rest of the default values and choose Create service which will return you to the namespace details page.
-
-
In the Services section, choose Create service and do the following to create the second service.
-
For Service name, enter
backend-service
. -
For Service Discovery Configuration, select API only.
-
Leave the rest of the default values and choose Create service.
-
Step 3: Register the Amazon Cloud Map service instances
In this step, you create two service instances, one for each service in our namespace.
Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/
. -
From the list of namespaces, select the namespace you created in step 1 and choose View details.
-
On the namespace details page, from the list of services, select the
public-service
service and choose View details. -
In the Service instances section, choose Register service instance and do the following to create the first service instance.
-
For Service instance ID, specify
first
. -
For IPv4 address, specify
192.168.2.1
. -
Leave the rest of the default values and choose Register service instance.
-
-
Using the breadcrumb at the top of the page, select cloudmap-tutorial.com to navigate back to the namespace detail page.
-
On the namespace details page, from the list of services, select the backend-service service and choose View details.
-
In the Service instances section, choose Register service instance and do the following to create the second service instance.
-
For Service instance ID, specify
second
to indicate that this is the second service instance. -
For Instance type, select Identifying information for another resource.
-
For Custom attributes, add a key-value pair with
service-name
as the key andbackend
as the value. -
Choose Register service instance.
-
Step 4: Discover the Amazon Cloud Map service instances
Now that the Amazon Cloud Map namespace, services, and service instances are created, you can verify
everything is working by discovering the instances. Use the dig
command to verify
the public DNS settings and the Amazon Cloud Map API to verify the backend service. For more information
about the dig
command, see dig - DNS lookup utility
Sign in to the Amazon Web Services Management Console and open the Route 53 console at https://console.amazonaws.cn/route53/
. -
In the left navigation, choose Hosted zones.
-
Select the cloudmap-tutorial.com hosted zone. This displays the hosted zone details in a separate pane. Take note of the Name servers associated with your hosted zone as we will use those in the next step.
-
Using the dig command and one of the Route 53 name servers for your hosted zone, query the DNS records for your service instance.
dig @
hosted-zone-nameserver
public-service.cloudmap-tutorial.comThe
ANSWER SECTION
in the output should display the IPv4 address you associated with yourpublic-service
service.;; ANSWER SECTION: public-service.cloudmap-tutorial.com. 300 IN A 192.168.2.1
-
Using the Amazon CLI, query the attributes for your second service instances.
aws servicediscovery discover-instances --namespace-name cloudmap-tutorial.com --service-name backend-service --region
region
The output displays the attributes you associated with the service as key-value pairs.
{ "Instances": [ { "InstanceId": "second", "NamespaceName": "cloudmap-tutorial.com", "ServiceName": "backend-service", "HealthStatus": "UNKNOWN", "Attributes": { "service-name": "backend" } } ], "InstancesRevision": 71462688285136850 }
Step 5: Clean up the resources
Once you have completed the tutorial, you can delete the resources. Amazon Cloud Map requires that you clean them up in reverse order, the service instances first, then the services, and finally the namespace. Amazon Cloud Map will clean up the Route 53 resources on your behalf when you go through these steps.
Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/
. -
From the list of namespaces, select the
cloudmap-tutorial.com
namespace and choose View details. -
On the namespace details page, from the list of services, select the
public-service
service and choose View details. -
In the Service instances section, select the
first
instance and choose Deregister. -
Using the breadcrumb at the top of the page, select cloudmap-tutorial.com to navigate back to the namespace detail page.
-
On the namespace details page, from the list of services, select the public-service service and choose Delete.
-
Repeat steps 3-6 for the
backend-service
. -
In the left navigation, choose Namespaces.
-
Select the
cloudmap-tutorial.com
namespace and choose Delete.Note
Although Amazon Cloud Map cleans up the Route 53 resources on your behalf, you can navigate to the Route 53 console to verify that the
cloudmap-tutorial.com
hosted zone is deleted.