Creating an Amazon Cloud Map service - 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).

Creating an Amazon Cloud Map service

To create a service, perform the following procedure.

Amazon Web Services Management Console
  1. Sign in to the Amazon Web Services Management Console and open the Amazon Cloud Map console at https://console.amazonaws.cn/cloudmap/.

  2. In the navigation pane, choose Namespaces.

  3. On the Namespaces page, choose the namespace that you want to add the service to.

  4. On the Namespace: namespace-name page, choose Create service.

  5. On the Create service page, enter the applicable values. For more information, see Values that you specify when you create services.

  6. Choose Create service.

Amazon CLI
  • Create a service with the create-service command (replace the red value with your own).

    aws servicediscovery create-service \ --name service-name \ --namespace-id ns-xxxxxxxxxxx \ --dns-config "NamespaceId=ns-xxxxxxxxxxx,RoutingPolicy=MULTIVALUE,DnsRecords=[{Type=A,TTL=60}]"

    Output:

    { "Service": { "Id": "srv-xxxxxxxxxxx", "Arn": "arn:aws-cn:servicediscovery:us-west-2:123456789012:service/srv-xxxxxxxxxxx", "Name": "service-name", "NamespaceId": "ns-xxxxxxxxxxx", "DnsConfig": { "NamespaceId": "ns-xxxxxxxxxxx", "RoutingPolicy": "MULTIVALUE", "DnsRecords": [ { "Type": "A", "TTL": 60 } ] }, "CreateDate": 1587081768.334, "CreatorRequestId": "567c1193-6b00-4308-bd57-ad38a8822d25" } }
Amazon SDK for Python (Boto3)
  1. If you don't already have Boto3 installed, you can find instructions for installing, configuring, and using Boto3 here.

  2. Import Boto3 and use servicediscovery as your service.

    import boto3 client = boto3.client('servicediscovery')
  3. Create a service with create_service() (replace the red value with your own).

    response = client.create_service( DnsConfig={ 'DnsRecords': [ { 'TTL': 60, 'Type': 'A', }, ], 'NamespaceId': 'ns-xxxxxxxxxxx', 'RoutingPolicy': 'MULTIVALUE', }, Name='service-name', NamespaceId='ns-xxxxxxxxxxx', )

    Example response output

    { 'Service': { 'Arn': 'arn:aws-cn:servicediscovery:us-west-2:123456789012:service/srv-xxxxxxxxxxx', 'CreateDate': 1587081768.334, 'DnsConfig': { 'DnsRecords': [ { 'TTL': 60, 'Type': 'A', }, ], 'NamespaceId': 'ns-xxxxxxxxxxx', 'RoutingPolicy': 'MULTIVALUE', }, 'Id': 'srv-xxxxxxxxxxx', 'Name': 'service-name', 'NamespaceId': 'ns-xxxxxxxxxxx', }, 'ResponseMetadata': { '...': '...', }, }
Note

For services that are accessible by DNS queries, you cannot create multiple services with names that differ only by case (such as EXAMPLE and example). Otherwise, these services will have the same DNS name. If you use a namespace that's only accessible by API calls, then you can create services that with names that differ only by case.

Values that you specify when you create services

When you create an Amazon Cloud Map service, you specify the following values.

Note

You can only change tags in a service after you create it.

Values

Service name

Enter a name that describes the instances that you register when using this service. The value is used to discover Amazon Cloud Map service instances either in API calls or in DNS queries. This depends on the instance discovery method that you chose when you created the namespace. You can use one of the following methods:

  • API calls – When your application calls DiscoverInstances, the API call includes the namespace and service names.

  • API calls and DNS queries in VPCs or API calls and public DNS queries – When you register service instances and create the namespace, Amazon Cloud Map creates an Amazon Route 53 private or public hosted zone. It also create DNS records in that hosted zone. The names of the records are in the following format:

    service-name.namespace-name

    When your application submits a DNS query to discover service instances, the query is for a record that includes the name of the service in the record name.

Note

When creating a service in a namespace that supports DNS queries, you can choose to have the service instances for that service discoverable only with calls to the DiscoverInstances API operation and not DNS queries. See Service discovery configuration.

If you want Amazon Cloud Map to create an SRV record when you register an instance and you're using a system that requires a specific SRV format (such as HAProxy), specify the following for Service name:

  • Start the name with an underscore (_), for example _exampleservice.

  • End the name with ._protocol, for example ._tcp.

When you register an instance, Amazon Cloud Map creates an SRV record and assigns a name by concatenating the service name and the namespace name, for example:

_exampleservice._tcp.example.com

Note

For services that are discoverable by DNS queries, you can't create multiple services with names that differ only by case (such as EXAMPLE and example). Otherwise, these services have the same DNS name and can't be distinguished.

Service description

Enter a description for the service. The value that you enter here appears on the Services page and on the detail page for each service.

Service discovery configuration

If the namespace supports DNS queries, Amazon Cloud Map supports the following service discovery options:

API and DNS

Amazon Cloud Map will create SRV records when you register an instance for the service. Service instances can also be discovered using the DiscoverInstances API operation.

API only

Amazon Cloud Map will not create SRV records for instance for the service. Service instances can be discovered only using the DiscoverInstances API operation.

Routing policy (public and private DNS namespaces only)

If you're using a public or private DNS namespace to create the service, choose the Amazon Route 53 routing policy for the DNS records that Amazon Cloud Map creates when you register instances. (Public DNS namespaces have a value of API calls and public DNS queries for Instance discovery, and private DNS namespaces have a value of API calls and DNS queries in VPCs.)

Note

You can't use the console to configure Amazon Cloud Map to create a Route 53 alias record when you register an instance. If you want Amazon Cloud Map to create alias records for Elastic Load Balancing load balancer when you register instances programmatically, choose Weighted routing for Routing policy.

Amazon Cloud Map supports the following Route 53 routing policies:

Weighted routing

Route 53 returns the applicable value from one randomly selected instance from among the instances that you registered using the same service. All records have the same weight, so you can't route more or less traffic to any instances.

For example, suppose the service includes configurations for one A record and a health check, and you use the service to register 10 instances. Route 53 responds to DNS queries with the IP address for one randomly selected instance from among the healthy instances. If no instances are healthy, Route 53 responds to DNS queries as if all the instances were healthy.

If you don't define a health check for the service, Route 53 assumes that all instances are healthy and returns the applicable value for one randomly selected instance.

For more information, see Weighted Routing in the Amazon Route 53 Developer Guide.

Multivalue answer routing

If you define a health check for the service and the result of the health check is healthy, Route 53 returns the applicable value for up to eight instances.

For example, suppose that the service includes configurations for one A record and a health check. You use the service to register 10 instances. Route 53 responds to DNS queries with IP addresses for only a maximum of eight healthy instances. If fewer than eight instances are healthy, Route 53 responds to every DNS query with the IP addresses for all the healthy instances.

If you don't define a health check for the service, Route 53 assumes that all instances are healthy and returns the values for up to eight instances.

For more information, see Multivalue Answer Routing in the Amazon Route 53 Developer Guide.

Record type (public and private DNS namespaces only)

If you're using a public or private DNS namespace to create the service, choose the DNS record type for the records that Amazon Cloud Map creates when you register instances. Amazon Route 53 returns the applicable value in response to DNS queries for registered instances.

The following record types are supported:

A

When you register an instance, you specify the IP address of the resource in IPv4 format, such as 192.0.2.44.

AAAA

When you register an instance, you specify the IP address of the resource in IPv6 format, such as 2001:0db8:85a3:0000:0000:abcd:0001:2345.

CNAME

When you register an instance, you specify the domain name of the resource (such as www.example.com). Note the following:

  • If you want to choose CNAME, you must choose Weighted routing for Routing policy.

  • If you choose CNAME, you can't choose Route 53 health check for Health check options.

SRV

The value for an SRV record uses the following values:

priority weight port service-hostname

Note the following about the values:

  • The values of priority and weight are both set to 1 and can't be changed.

  • For port, Amazon Cloud Map uses the value that you specify for Port when you register an instance.

  • The value of service-hostname is a concatenation of the following values:

    • The value that you specify for Service instance ID when you register an instance

    • The name of the service

    • The name of the namespace

    For example, suppose you specify test for Service instance ID when you register an instance. The name of the service is backend and the name of the namespace is example.com. Amazon Cloud Map assigns the following value to the service-hostname attribute in the SRV record:

    test.backend.example.com

If you specify settings for an SRV record, note the following:

  • If you specify values for IPv4 address, IPv6 address, or both, Amazon Cloud Map automatically creates A and/or AAAA records that have the same name as the value of service-hostname in the SRV record.

  • If you're using a system that requires a specific SRV format, such as HAProxy, see service name for information about how to specify the correct name format.

You can specify record types in the following combinations:

  • A

  • AAAA

  • A and AAAA

  • CNAME

  • SRV

If you specify A and AAAA record types, you can specify an IPv4 IP address, an IPv6 IP address, or both when you register an instance.

TTL (public and private DNS namespaces only)

If you're using a public or private DNS namespace to create the service, enter a value for TTL, or time to live. The value of TTL determines how long DNS resolvers cache information for this record before the resolvers forward another DNS query to Amazon Route 53 to get updated settings.

Health check options

No health check

If you don't configure a health check, traffic is routed to service instances regardless of whether they're healthy.

Route 53 health check (not supported for private DNS namespaces)

If you specify settings for an Amazon Route 53 health check, Amazon Cloud Map creates a Route 53 health check whenever you register an instance and deletes the health check when you deregister the instance.

For public DNS namespaces, Amazon Cloud Map associates the health check with the Route 53 record that Amazon Cloud Map creates when you register an instance.

For namespaces that you use API calls to discover instances for, Amazon Cloud Map creates a Route 53 health check. However, there's no DNS record for Amazon Cloud Map to associate the health check with. To determine whether a health check is healthy, you can configure monitoring using either the Route 53 console or using Amazon CloudWatch. For more information about using the Route 53 console, see Get Notified When a Health Check Fails in the Amazon Route 53 Developer Guide. For more information about using CloudWatch, see PutMetricAlarm in the Amazon CloudWatch API Reference.

For information about the charges for Route 53 health checks, see Route 53 Pricing.

Custom health check

If you configure Amazon Cloud Map to use a custom health check when you register an instance, you must use a third-party health checker to evaluate the health of your resources. Custom health checks are useful in the following circumstances:

  • You can't use a Route 53 health check because the resource isn't available over the internet. For example, suppose that you have an instance that's located in an Amazon VPC. You can use a custom health check for this instance. However, for the health check to work,your health checker must also be in the same VPC as your instance.

  • You want to use a third-party health checker regardless of where your resources are.

Failure threshold (Route 53 health check only)

The number of consecutive Route 53 health checks that a resource must pass or fail for Amazon Route 53 to change the current status of the resource from healthy to unhealthy or the opposite situation. For more information, see How Amazon Route 53 Determines Whether a Health Check Is Healthy Amazon Route 53 Developer Guide.

Health check protocol (Route 53 health check only)

The method that you want Amazon Route 53 to use to check the health of your resource:

HTTP

Route 53 tries to establish a TCP connection. If successful, Route 53 submits an HTTP request and waits for an HTTP status code of a 2xx or 3xx format.

HTTPS

Route 53 tries to establish a TCP connection. If successful, Route 53 submits an HTTPS request and waits for an HTTP status code of a 2xx or 3xx format.

Important

If you choose HTTPS, the resource must support TLS v1.0 or later.

If you choose HTTPS for the value of Health check protocol, additional charges apply. For more information, see Route 53 Pricing.

TCP

Route 53 tries to establish a TCP connection.

For more information, see How Amazon Route 53 Determines Whether a Health Check Is Healthy.

Health check path (Route 53 HTTP and HTTPS health checks only)

The path that you want Amazon Route 53 to request when performing health checks. The path can be any value such as the file /docs/route53-health-check.html. When the resource is healthy, the returned value is an HTTP status code of a 2xx or 3xx format. You can also include query string parameters, for example, /welcome.html?language=jp&login=y. The Amazon Cloud Map console automatically adds a leading slash (/) character.

Tags

You can specify one or more tags to add to your service. A tag is an optional label that you can assign to an Amazon resource. Each tag consists of a key and a value. For example, you can define a tag with Key = Environment and Value = Production. Using tags to categorize Amazon resources can make managing those resources easier.

After your tags are created, you can always update or remove tags on your namespaces. For more information, see Tagging your Amazon Cloud Map resources.