Amazon ECS
User Guide for AWS Fargate (API Version 2014-11-13)

Service Discovery

Your Amazon ECS service can optionally be configured to use Amazon ECS Service Discovery. Service discovery uses Amazon Route 53 auto naming API actions to manage DNS entries for your service's tasks, making them discoverable within your VPC. For more information, see Using Auto Naming for Service Discovery in the Amazon Route 53 API Reference.

Service discovery is available in the following AWS Regions:

Region Name Region
US East (N. Virginia) us-east-1
US East (Ohio) us-east-2
US West (N. California) us-west-1
US West (Oregon) us-west-2
Asia Pacific (Mumbai) ap-south-1
Asia Pacific (Seoul) ap-northeast-2
Asia Pacific (Singapore) ap-southeast-1
Asia Pacific (Sydney) ap-southeast-2
Asia Pacific (Tokyo) ap-northeast-1
EU (Frankfurt) eu-central-1
EU (Ireland) eu-west-1
EU (London) eu-west-2
EU (Paris) eu-west-3
South America (São Paulo) sa-east-1
Canada (Central) ca-central-1

Service Discovery Concepts

Service discovery consists of the following components:

  • Service discovery namespace: A logical group of services that share the same domain name, such as You need one namespace per Route 53 hosted zone and per VPC. If you are using service discovery from the Amazon ECS console, the workflow creates one private namespace per ECS cluster.

  • Service discovery service: Exists within the service discovery namespace and consists of the service name and DNS configuration for the namespace. It provides the following core component:

    • Service directory: Allows you to look up a service via DNS or Route 53 auto naming API actions and get back one or more available endpoints that can be used to connect to the service.

  • Health checks: Perform periodic container-level health checks. If an endpoint does not pass the health check, it is removed from DNS routing and marked as unhealthy. For more information, see How Amazon Route 53 Checks the Health of Your Resources.

Service Discovery Considerations

The following should be considered when using service discovery:

  • Service discovery is supported for Fargate tasks if you are using platform version v1.1.0 or later. For more information, see AWS Fargate Platform Versions.

  • Public namespaces are supported but you must have an existing public hosted zone registered with Route 53 before creating your service discovery service.

  • The DNS records created for a service discovery service always register with the private IP address for the task, rather than the public IP address, even when public namespaces are used.

  • Service discovery requires that tasks specify either the awsvpc, bridge, or host network mode (none is not supported).

  • If the task definition your service task specifies uses the awsvpc network mode, you can create any combination of A or SRV records for each service task. If you use SRV records, a port is required.

  • If the task definition that your service task specifies uses the bridge or host network mode, an SRV record is the only supported DNS record type. Create an SRV record for each service task. The SRV record must specify a container name and container port combination from the task definition.

  • DNS records for a service discovery service can be queried within your VPC. They use the following format: <service discovery service name>.<service discovery namespace>. For more information, see Step 5: Verify Service Discovery.

  • When doing a DNS query on the service name, A records return a set of IP addresses that correspond to your tasks. SRV records return a set of IP addresses and ports per task.

  • You can configure service discovery for an ECS service that is behind a load balancer, but service discovery traffic is always routed to the task and not the load balancer.

  • Service discovery does not support the use of Classic Load Balancers.

  • When specifying health checks for your service discovery service, you must use either custom health checks managed by Amazon ECS or Route 53 health checks. The two options for health checks cannot be combined.

    • HealthCheckCustomConfig—Amazon ECS manages health checks on your behalf. Amazon ECS uses information from container and Elastic Load Balancing health checks, as well as your task state, to update the health with Route 53. This is specified using the --health-check-custom-config parameter when creating your service discovery service. For more information, see HealthCheckCustomConfig in the Amazon Route 53 API Reference.

    • HealthCheckConfig—Route 53 creates health checks to monitor tasks. This requires the tasks to be publicly available. This is specified using the --health-check-config parameter when creating your service discovery service. For more information, see HealthCheckConfig in the Amazon Route 53 API Reference.

  • If you are using the Amazon ECS console, the workflow creates one service discovery service per ECS service and maps all of the task IP addresses as A records, or task IP addresses and port as SRV records.

  • Service discovery can only be configured when first creating a service. Updating existing services to configure service discovery for the first time or change the current configuration is not supported.

  • The Route 53 resources created when service discovery is used must be cleaned up manually. For more information, see Step 6: Clean Up in the Tutorial: Creating a Service Using Service Discovery topic.

Service Discovery Pricing

Customers using Amazon ECS service discovery are charged for the usage of Route 53 auto naming APIs. This involves costs for creating the hosted zones and queries to the service registry. For more information, see Amazon Route 53 Pricing

Amazon ECS performs container level health checks and exposes this to Route 53 custom health check APIs and this is currently made available to customers at no extra cost. If you configure additional network health checks for publicly exposed tasks, you are charged for those health checks.