How do I configure service discovery with AWS Cloud Map through the AWS CLI?

Last updated: 2019-06-25

How do I create a hosted zone using AWS Cloud Map through the AWS Command Line Interface (AWS CLI)?

Short Description

AWS Cloud Map automates DNS configuration and simplifies the provision of instances for services such as Amazon Elastic Container Service (Amazon ECS), Fargate, and Kubernetes.

You can create a hosted zone with AWS Cloud Map using the AWS SDK or the AWS CLI:

1.    Create a DNS namespace (for which a hosted zone is automatically created) to define your service naming scheme.

2.    Create your service.

3.    Register an instance to your service.


Before proceeding, be sure to install the latest version of the AWS CLI.

Create your DNS namespace

1.    Create the namespace using the AWS CLI, replacing with the domain name you want to use.

Note: You must choose between creating a public or a private namespace. Public namespaces are visible on the internet as long as the domain name is registered. Private namespaces are visible only within the VPC.

To create a public namespace, use the following command:

$ aws servicediscovery create-public-dns-namespace --name

To create a private namespace, use the following command:

$ aws servicediscovery create-private-dns-namespace --name

2.    Note the value of OperationId in the output.

For example:

    "OperationId": "igbkufld72o4vbsbwejfi6eyinfprhc3-jkwmz00b"

3.    Obtain more details about the operation using the command get-operation as follows. Be sure to replace the value for the option --operation-id with the OperationId value you obtained in the previous step.

aws servicediscovery get-operation --operation-id igbkufld72o4vbsbwejfi6eyinfprhc3-jkwmz00b

4.    Note the output.

Verify that the Status value is SUCCESS.

Make note of the NAMESPACE value, which is the namespace ID used to create the service and register the instance.

For example:

    "Operation": {
        "Status": "SUCCESS",
        "CreateDate": 1534428266.699,
        "Id": "igbkufld72o4vbsbwejfi6eyinfprhc3-jkwmz00b",
        "UpdateDate": 1534428267.113,
        "Type": "CREATE_NAMESPACE",
        "Targets": {
            "NAMESPACE": "ns-f2wjnv2p7pqtz5f2"

5.    Open the Route 53 console.

6.    On the navigation pane, choose Hosted zones.

7.    Find your hosted zone in the list of hosted zones in the content pane.

Note: When you create the namespace, Route 53 automatically creates a hosted zone for the domain. The hosted zone's Domain name value is the same domain name as your namespace. The Comment value is Created by Route 53 Auto Naming.

Create your service

1.    Open the AWS CLI.

2.    Create the service using the command servicediscovery create-service in shorthand syntax as follows.

Important: Be sure to replace workers in your command with your preferred service name. Route 53 uses this service name when creating records.

$aws servicediscovery create-service --name workers --dns-config 'NamespaceId="ns-f2wjnv2p7pqtz5f2",DnsRecords=[{Type="A",TTL="300"}]'

3.    Note the output. The Id value is the ID of the service you just created.

Note: The CreatorRequestId is the ID of the request, which you can use to repeat the operation if the API call fails.

For example:

    "Service": {
        "DnsConfig": {
            "NamespaceId": "ns-f2wjnv2p7pqtz5f2",
            "DnsRecords": [
                    "Type": "A",
                    "TTL": 300
        "CreatorRequestId": "93e0a17a-230b-4c58-b986-f03f3217869f",
        "Id": "srv-iy3d7hhlf5cjciph",
        "Arn": "arn:aws:servicediscovery:eu-west-1:356906700443:service/srv-iy3d7hhlf5cjciph",
        "Name": "workers"

Register your instance

1.    Open the AWS CLI.

2.    Register your instance using the command servicediscovery register-instance as follows.

Important: If you don't provide the following parameters, the API call fails:

  • --service-id (the ID of the service you want to use in the settings for the resource record set Route 53 creates)
  • --instance-id (the ID you want to associate with the instance)
  • --attributes (attributes applied to the records defined in your service)

For example:

$ aws servicediscovery register-instance --service-id srv-iy3d7hhlf5cjciph --instance-id i-039444aa1e2932ca3 --attributes=AWS_INSTANCE_IPV4=

You can use the following options in --attributes:

  • Use AWS_ALIAS_DNS_NAME to create alias records to point to AWS resources. Note that service discovery supports only weighted alias records. Also note that you can create alias records to Elastic Load Balancing only when using Route 53 service discovery. If you point to an alias record, Route 53 doesn't associate health checks configured for the service ID with the alias record.
  • Use AWS_INSTANCE_CNAME when the service configuration includes a CNAME record.
  • Use AWS_INSTANCE_IPv4 when the service includes an A record for the IPv4 address you want Route 53 to return in response to DNS queries.
  • Use AWS_INSTANCE_PORT when the service includes an SRV record with the value you want Route 53 to return for that port.

Important: You can only run one request to register an instance (servicediscovery register-instance) with the same --service-id and --instance-id options at a time.

3.    Review the output, which includes the OperationId. For example:

    "OperationId": "z7dfqgeadkvwwid2wa2n5ckicrxs255x-jkwr1x9f"

4.    Open the Route 53 console.

5.    On the navigation pane, choose Hosted zones.

6.    Select the hosted zone you created earlier in the list of hosted zones in the content pane.

7.    Choose Go to Record Sets and verify the record sets are created for the hosted zone.

Note: When you register the instance, Route 53 automatically creates a record with the service name and domain name.

If you're using Amazon ECS and Route 53 service discovery, you can use the Route 53 namespace and service name to configure your services. Route 53 then automatically creates, deletes, or updates records in your hosted zone according to your ECS container settings.

Did this article help you?

Anything we could improve?

Need more help?