Using Amazon Cloud Map - Amazon Cloud Map
Overview of How to Use Amazon Cloud Map
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Using Amazon Cloud Map

Amazon Cloud Map is a managed solution that you can use to map logical names to the resources for an application. It also helps your applications discover resources using one of the Amazon SDKs, RESTful API calls, or DNS queries. Amazon Cloud Map serves only healthy resources, which can be Amazon DynamoDB (DynamoDB) tables, Amazon Simple Queue Service (Amazon SQS) queues, or any higher-level application services that are built using Amazon Elastic Compute Cloud (Amazon EC2) instances or Amazon Elastic Container Service (Amazon ECS) tasks.

Topics

Overview of How to Use Amazon Cloud Map

The following is an overview of how you can use Amazon Cloud Map:

  1. Create a namespace, which is a logical grouping of services. When you create a namespace, you specify the name that you want your applications to use to discover instances. You also specify how you want to discover service instances that you register with Amazon Cloud Map: using API calls or using DNS queries.

    For more information, see the following topics:

    If you create a public or private DNS namespace, Amazon Cloud Map automatically creates an Amazon Route 53 public or private hosted zone that has the same name as the namespace. Even with public and private DNS namespaces, you can still discover instances using Amazon Cloud Map DiscoverInstances requests.

    For a list of the endpoints that you can submit Amazon Cloud Map API requests to, see Amazon Cloud Map in the "Amazon Regions and Endpoints" chapter in the Amazon Web Services General Reference.

  2. If you created a public DNS namespace, perform the following steps to change the name servers for the domain registration to the name servers for the Route 53 hosted zone that Amazon Cloud Map created when you created the namespace:

    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. Then skip to step 3.

    2. Use the OperationId that was returned when you created the namespace to get the namespace ID. For more information, see GetOperation.

      Note

      If you're using a programmatic method to perform these steps, you'll also use the namespace ID later in the process to create a service.

    3. Use the namespace ID that you got in step 2b to get the ID of the Route 53 hosted zone that Amazon Cloud Map created. For more information, see GetNamespace in the Amazon Cloud Map API Reference.

    4. Using the hosted zone ID that you got in step 2c, 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.

    5. 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. Create a service, which contains the service instances that identify how to contact the resources for an application, such as a web server, a DynamoDB table, or an Amazon S3 bucket.

    If you created a public or private DNS namespace in step 1, the name that you specify for the service becomes part of the names of records in the Route 53 public or private hosted zone that Amazon Cloud Map created automatically in step 1. When you register an instance in the next step, Amazon Cloud Map creates records in the hosted zone. The record names are a combination of the name of the service (such as backend) and the name of the namespace (such as example.com): backend.example.com.

    When you create a service, you can also choose whether you want to check the health of the resources that service instances point to:

    • If you choose no health checking, Amazon Cloud Map or Route 53 return service instances regardless of the health of the corresponding resources.

    • If you choose Route 53 health checking (only available for public DNS namespaces), Amazon Cloud Map automatically creates a Route 53 health check and associates it with the corresponding Route 53 record. Route 53 responds to DNS queries only with records for healthy resources.

    • If you choose custom health checking, you use a third-party application to determine the health of your resources. Based on the results of the third-party health checks, you send UpdateInstanceCustomHealthStatus requests to Amazon Cloud Map to update the status of the service instances.

    If you configure health checking, either Amazon Cloud Map or Route 53 returns only service instances for healthy resources in response to DiscoverInstances requests or DNS queries.

    For more information, see the following topics:

  4. Register one or more service instances. Each service instance contains information about how your application can contact one resource for an application.

    For more information, see the following topics:

  5. Write your application to discover instances using either the Amazon Cloud Map DiscoverInstances API action or using DNS queries:

    • If your application uses DiscoverInstances, Amazon Cloud Map returns information about the available instances that meet the specified criteria.

    • If your application uses DNS queries, Route 53 returns one or more records.

    If you specified settings for a health check when you created the service, Amazon Cloud Map or Route 53 returns values only for healthy instances.

  6. When you want to stop using a resource, deregister the corresponding service instance. Amazon Cloud Map automatically deletes the associated Route 53 record and health check, if any.

    For more information, see the following topics:

  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 in the namespace.

    For more information, see the following topics: