Amazon ECS Service Connect configuration overview - Amazon Elastic Container Service

Amazon ECS Service Connect configuration overview

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

Amazon ECS resources that need to be configured for Service Connect
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.

  • Service Connect creates AWS Cloud Map services in your account. Modifying these AWS Cloud Map resources by manually registering/deregistering instances, changing instance attributes, or deleting a service may lead to unexpected behaviour 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 AWS Cloud Map 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 AWS 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. If you specify a namespace name that doesn't exist in the same AWS Region and account, a new HTTP namespace is created.

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 AWS CLI, you must add --include ATTACHMENTS to see them.

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

The following example shows each kind of Service Connect configuration being used together in the same Amazon ECS service. Shell comments are provided, however note that the JSON configuration used to Amazon ECS services doesn't support comments.

{ ... serviceConnectConfiguration: { enabled: true, namespace: "internal", #config for client services can end here, only these two parameters are required. services: [{ portName: "http" }, #minimal client - server service config can end here.portName must match the "name" parameter of a port mapping in the task definition. { discoveryName: "http-second" #name the discoveryName to avoid a Task def port name collision with the minimal config in the same Cloud Map namespace portName: "http" }, { clientAliases: [{ dnsName: "db", port: 81 }] #use when the port in Task def is not the port that client apps use.Client apps can use http: //db:81 to connect discoveryName: "http-three" portName: "http" }, { clientAliases: [{ dnsName: "", port: 81 }] #use when the port in Task def is not the port that client apps use.duplicates are fine as long as the discoveryName is different. discoveryName: "http-four" portName: "http", ingressPortOverride: 99 #If App should also accept traffic directly on Task def port. } ] } }