How do I configure service discovery with AWS Cloud Map through the 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), AWS Fargate, and Amazon Elastic Kubernetes Service (Amazon EKS).

To 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.

Resolution

Note: If you receive errors when running AWS CLI commands, make sure that you’re using the most recent AWS CLI version.

Create your DNS namespace

1.    Create the namespace using the AWS CLI, replacing example.com 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 virtual private cloud (VPC). You must specify the VPC ID when you create a private namespace.

To create a public namespace:

$ aws servicediscovery create-public-dns-namespace --name example.com

To create a private namespace:

$ aws servicediscovery create-private-dns-namespace --name example.com --vpc vpc-0c92f38bf7db24a05

2.    Note the value of OperationId in the output.

For example:

{
    "OperationId": "igbkufld72o4vbsbwejfi6eyinfprhc3-jkwmz00b"
}

3.    Find more details about the operation using the get-operation command. Be sure to replace  <OperationId value> with the OperationId value you found in the previous step.

aws servicediscovery get-operation --operation-id <OperationId value>

4.    In 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"
        }
    }
}

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. To verify the hosted zone:

1.    Open the Route 53 console.

2.    On the navigation pane, choose Hosted zones.

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

Create your service

1.    Create the service using the servicediscovery create-service command in shorthand syntax as follows. Be sure to replace workers 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",RoutingPolicy="WEIGHTED",DnsRecords=[{Type="A",TTL="300"}]'

The default routing policy is "MULTIVALUE".  Supported routing policies are "MULTIVALUE" and "WEIGHTED".

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

Note: The CreatorRequestId is the ID of the request. If the API call fails, use the CreatorRequestId to repeat the operation.

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.    Register your instance using the servicediscovery register-instance command. Be sure to replace the <value> placeholders with your corresponding values. Note that you can run only one request to register an instance with the same service-id and instance-id options at a time.

Important: The API call fails if you don't provide the service-id, instance-id, and attributes parameters. For more details, see "Options" on the register-instance page.

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

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

{
    "OperationId": "z7dfqgeadkvwwid2wa2n5ckicrxs255x-jkwr1x9f"
}

3.    Open the Route 53 console.

4.    On the navigation pane, choose Hosted zones.

5.    Select the hosted zone you created earlier.

6.    Choose Go to Record Sets, and then verify that 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 Amazon ECS container settings.

Related information

Service discovery (Amazon ECS)