Amazon ECS Service Connect configuration overview - Amazon Elastic Container Service
Cluster configurationService configuration
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).

Amazon ECS Service Connect configuration overview

When you use Service Connect, there are parameters you need to configure in your resources.

The following table describes the configuration parameters for the Amazon ECS resources.

Parameter location App type Description Required
Task definition Client There are no changes available for Service Connect in client task definitions. N/A
Task definition Client-server Servers must add name fields to ports in the portMappings of containers. For more information, see portMappings Yes
Task definition Client-server Servers can optionally provide an application protocol (for example, HTTP) to receive protocol-specific metrics for their server applications (for example, HTTP 5xx). No
Service definition Client Client services must add a serviceConnectConfiguration to configure the namespace to join. This namespace must contain all of the server services that this service needs to discover. For more information, see serviceConnectConfiguration. Yes
Service definition Client-server Server services must add a serviceConnectConfiguration to configure the DNS names, port numbers, and namespace that the service is available from. For more information, see serviceConnectConfiguration. Yes
Cluster Client Clusters can add a default Service Connect namespace. New services in the cluster inherit the namespace when Service Connect is configured in a service. No
Cluster Client-server There are no changes available for Service Connect in clusters that apply to server services. Server task definitions and services must set the respective configuration. N/A
Overview of steps to configure Service Connect

The following steps provide an overview of how to configure Service Connect.

Important

  • Service Connect creates Amazon Cloud Map services in your account. Modifying these Amazon Cloud Map resources by manually registering/deregistering instances, changing instance attributes, or deleting a service may lead to unexpected behavior for your application traffic or subsequent deployments.

  • Service Connect doesn't support links in the task definition.

  1. Add port names to the port mappings in your task definitions. Additionally, you can identify the layer 7 protocol of the application, to get additional metrics.

  2. Create a cluster with a Amazon Cloud Map namespace, use a shared namespace, or create the namespace separately. For simple organization, create a cluster with the name that you want for the namespace and specify the identical name for the namespace. In this case, Amazon ECS creates a new HTTP namespace with the necessary configuration. Service Connect doesn't use or create DNS hosted zones in Amazon Route 53.

  3. Configure services to create Service Connect endpoints within the namespace.

  4. Deploy services to create the endpoints. Amazon ECS adds a Service Connect proxy container to each task, and creates the Service Connect endpoints in Amazon Cloud Map. This container isn't configured in the task definition, and the task definition can be reused without modification to create multiple services in the same namespace or in multiple namespaces.

  5. Deploy client apps as services to connect to the endpoints. Amazon ECS connects them to the Service Connect endpoints through the Service Connect proxy in each task.

    Applications only use the proxy to connect to Service Connect endpoints. There is no additional configuration to use the proxy. The proxy performs round-robin load balancing, outlier detection, and retries. For more information about the proxy, see Service Connect proxy.

  6. Monitor traffic through the Service Connect proxy in Amazon CloudWatch.

Cluster configuration

You can set a default namespace for Service Connect when you create or update the cluster. The namespace name that you specify as a default can either be in the same Amazon Web Services Region and account, or in the same Amazon Web Services Region and shared by another Amazon Web Services account using Amazon Resource Access Manager.

If you create a cluster and specify a default Service Connect namespace, the cluster waits in the PROVISIONING status while Amazon ECS creates the namespace. You can see an attachment in the status of the cluster that shows the status of the namespace. Attachments aren't displayed by default in the Amazon CLI, you must add --include ATTACHMENTS to see them.

If you want to use a namespace that is shared with your Amazon Web Services account using Amazon RAM, specify the Amazon Resource Name (ARN) of the namespace in the cluster configuration. For more information about shared Amazon Cloud Map namespaces, see Amazon ECS Service Connect with shared Amazon Cloud Map namespaces.

Service configuration

Service Connect is designed to require the minimum configuration. You need to set a name for each port mapping that you would like to use with Service Connect in the task definition. In the service, you need to turn on Service Connect and select either a namespace in your Amazon Web Services account or a shared namespace to make a client service. To make a client-server service, you need to add a single Service Connect service configuration that matches the name of one of the port mappings. Amazon ECS reuses the port number and port name from the task definition to define the Service Connect service and endpoint. To override those values, you can use the other parameters Discovery, DNS, and Port in the console, or discoveryName and clientAliases, respectively in the Amazon ECS API.