# Interconnect Amazon ECS services Interconnect services Applications that run in Amazon ECS tasks often need to receive connections from the internet or to connect to other applications that run in Amazon ECS services. If you need external connections from the internet, we recommend using Elastic Load Balancing. For more information about integrated load balancing, see [Use load balancing to distribute Amazon ECS service traffic](service-load-balancing.md). If you need an application to connect to other applications that run in Amazon ECS services, Amazon ECS provides the following ways to do this without a load balancer: + *Amazon ECS Service Connect* We recommend Service Connect, which provides Amazon ECS configuration for service discovery, connectivity, and traffic monitoring. With Service Connect, your applications can use short names and standard ports to connect to Amazon ECS services in the same cluster, other clusters, including across VPCs in the same AWS Region. When you use Service Connect, Amazon ECS manages all of the parts of service discovery: creating the names that can be discovered, dynamically managing entries for each task as the tasks start and stop, running an agent in each task that is configured to discover the names. Your application can look up the names by using the standard functionality for DNS names and making connections. If your application does this already, you don't need to modify your application to use Service Connect. You provide the complete configuration inside each service and task definition. Amazon ECS manages changes to this configuration in each service deployment, to ensure that all tasks in a deployment behave in the same way. For example, a common problem with DNS as service discovery is controlling a migration. If you change a DNS name to point to the new replacement IP addresses, it might take the maximum TTL time before all the clients begin using the new service. With Service Connect, the client deployment updates the configuration by replacing the client tasks. You can configure the deployment circuit breaker and other deployment configuration to affect Service Connect changes in the same way as any other deployment. For more information, see [Use Service Connect to connect Amazon ECS services with short names](service-connect.md). + *Amazon ECS service discovery* Another approach for service-to-service communication is direct communication using service discovery. In this approach, you can use the AWS Cloud Map service discovery integration with Amazon ECS. Using service discovery, Amazon ECS syncs the list of launched tasks to AWS Cloud Map, which maintains a DNS hostname that resolves to the internal IP addresses of one or more tasks from that particular service. Other services in the Amazon VPC can use this DNS hostname to send traffic directly to another container using its internal IP address. This approach to service-to-service communication provides low latency. There are no extra components between the containers. Traffic travels directly from one container to the other container. This approach is suitable when using the `awsvpc` network mode, where each task has its own unique IP address. Most software only supports the use of DNS `A` records, which resolve directly to IP addresses. When using the `awsvpc` network mode, the IP address for each task are an `A` record. However, if you're using `bridge` network mode, multiple containers could be sharing the same IP address. Additionally, dynamic port mappings cause the containers to be randomly assigned port numbers on that single IP address. At this point, an `A` record is no longer enough for service discovery. You must also use an `SRV` record. This type of record can keep track of both IP addresses and port numbers but requires that you configure applications appropriately. Some prebuilt applications that you use might not support `SRV` records. Another advantage of the `awsvpc` network mode is that you have a unique security group for each service. You can configure this security group to allow incoming connections from only the specific upstream services that need to talk to that service. The main disadvantage of direct service-to-service communication using service discovery is that you must implement extra logic to have retries and deal with connection failures. DNS records have a time-to-live (TTL) period that controls how long they are cached for. It takes some time for the DNS record to be updated and for the cache to expire so that your applications can pick up the latest version of the DNS record. So, your application might end up resolving the DNS record to point at another container that's no longer there. Your application needs to handle retries and have logic to ignore bad backends. For more information, see [Use service discovery to connect Amazon ECS services with DNS names](service-discovery.md) + *Amazon VPC Lattice * Amazon VPC Lattice is a managed application networking service that Amazon ECS customers use to observe, secure, and monitor applications built across AWS compute services, VPCs, and accounts without having to modify their code. VPC Lattice uses target groups, which are a collection of compute resources. These targets run your application or service and can be Amazon EC2 instances, IP addresses, Lambda functions, and Application Load Balancers. By associating their Amazon ECS services with a VPC Lattice target group, customers can now enable Amazon ECS tasks as IP targets in VPC Lattice. Amazon ECS automatically registers tasks to the VPC Lattice target group when tasks for the registered service are launched. For more information, see [Use Amazon VPC Lattice to connect, observe, and secure your Amazon ECS services](ecs-vpc-lattice.md). ## Network mode compatibility table The following table covers the compatibility between these options and the task network modes. In the table, "client" refers to the application that's making the connections from inside an Amazon ECS task. **** | Interconnection Options | Bridged | `awsvpc` | Host | | --- | --- | --- | --- | | Service discovery | yes, but requires clients be aware of SRV records in DNS without hostPort. | yes | yes, but requires clients be aware of SRV records in DNS without hostPort. | | Service Connect | yes | yes | no | | VPC Lattice | yes | yes | yes | # Use Service Connect to connect Amazon ECS services with short names Service Connect Amazon ECS Service Connect provides management of service-to-service communication as Amazon ECS configuration. It builds both service discovery and a service mesh in Amazon ECS. This provides the complete configuration inside each service that you manage by service deployments, a unified way to refer to your services within namespaces that doesn't depend on the VPC DNS configuration, and standardized metrics and logs to monitor all of your applications. Service Connect only interconnects services. The following diagram shows an example Service Connect network with 2 subnets in the VPC and 2 services. A client service that runs WordPress with 1 task in each subnets. A server service that runs MySQL with 1 task in each subnet. Both services are highly available and resilient to task and Availability Zone issues because each service runs multiple tasks that are spread out over 2 subnets. The solid arrows show a connection from WordPress to MySQL. For example, a `mysql --host=mysql` CLI command that is run from inside the WordPress container in the task with the IP address `172.31.16.1`. The command uses the short name `mysql` on the default port for MySQL. This name and port connects to the Service Connect proxy in the same task. The proxy in the WordPress task uses round-robin load balancing and any previous failure information in outlier detection to pick which MySQL task to connect to. As shown by the solid arrows in the diagram, the proxy connects to the second proxy in the MySQL task with the IP Address `172.31.16.2`. The second proxy connects to the local MySQL server in the same task. Both proxies report connection performance that is visible in graphs in the Amazon ECS and Amazon CloudWatch consoles so that you can get performance metrics from all kinds of applications in the same way. ![\[Example Service Connect network showing minimal HA services\]](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/images/serviceconnect.png) The following terms are used with Service Connect. **port name** The Amazon ECS task definition configuration that assigns a name to a particular port mapping. This configuration is only used by Amazon ECS Service Connect. **client alias** The Amazon ECS service configuration that assigns the port number that is used in the endpoint. Additionally, the client alias can assign the DNS name of the endpoint, overriding the discovery name. If a discovery name isn't provided in the Amazon ECS service, the client alias name overrides the port name as the endpoint name. For endpoint examples, see the definition of *endpoint*. Multiple client aliases can be assigned to an Amazon ECS service. This configuration is only used by Amazon ECS Service Connect. **discovery name** The optional, intermediate name that you can create for a specified port from the task definition. This name is used to create a AWS Cloud Map service. If this name isn't provided, the port name from the task definition is used. Multiple discovery names can be assigned to a specific port an Amazon ECS service. This configuration is only used by Amazon ECS Service Connect. AWS Cloud Map service names must be unique within a namespace. Because of this limitation, you can have only one Service Connect configuration without a discovery name for a particular task definition in each namespace. **endpoint** The URL to connect to an API or website. The URL contains the protocol, a DNS name, and the port. For more information about endpoints in general, see [endpoint](https://docs.aws.amazon.com/glossary/latest/reference/glos-chap.html#endpoint) in the *AWS glossary* in the Amazon Web Services General Reference. Service Connect creates endpoints that connect to Amazon ECS services and configures the tasks in Amazon ECS services to connect to the endpoints. The URL contains the protocol, a DNS name, and the port. You select the protocol and port name in the task definition, as the port must match the application that is inside the container image. In the service, you select each port by name and can assign the DNS name. If you don't specify a DNS name in the Amazon ECS service configuration, the port name from the task definition is used by default. For example, a Service Connect endpoint could be `http://blog:80`, `grpc://checkout:8080`, or `http://_db.production.internal:99`. **Service Connect service** The configuration of a single endpoint in an Amazon ECS service. This is a part of the Service Connect configuration, consisting of a single row in the **Service Connect and discovery name configuration** in the console, or one object in the `services` list in the JSON configuration of an Amazon ECS service. This configuration is only used by Amazon ECS Service Connect. For more information, see [ServiceConnectService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ServiceConnectService.html) in the Amazon Elastic Container Service API Reference. **namespace** The short name or full Amazon Resource Name (ARN) of the AWS Cloud Map namespace for use with Service Connect. The namespace must be in the same AWS Region as the Amazon ECS service and cluster. The type of namespace in AWS Cloud Map doesn't affect Service Connect. The namespace can be one that is shared with your AWS account using AWS Resource Access Manager (AWS RAM) in AWS Regions that AWS RAM is available in. For more information about shared namespaces, see [Cross-account AWS Cloud Map namespace sharing](https://docs.aws.amazon.com/cloud-map/latest/dg/sharing-namespaces.html) in the *AWS Cloud Map Developer Guide*. Service Connect uses the AWS Cloud Map namespace as a logical grouping of Amazon ECS tasks that talk to one another. Each Amazon ECS service can belong to only one namespace. The services within a namespace can be spread across different Amazon ECS clusters within the same AWS Region. If the namespace is a shared namespace, the services can be spread across the namespace owner and namespace consumer AWS accounts. You can freely organize services by any criteria. **client service** A service that runs a network client application. This service must have a namespace configured. Each task in the service can discover and connect to all of the endpoints in the namespace through a Service Connect proxy container. If any of your containers in the task need to connect to an endpoint from a service in a namespace, choose a client service. If a frontend, reverse proxy, or load balancer application receives external traffic through other methods such as from Elastic Load Balancing, it could use this type of Service Connect configuration. **client-server service** An Amazon ECS service that runs a network or web service application. This service must have a namespace and at least one endpoint configured. Each task in the service is reachable by using the endpoints. The Service Connect proxy container listens on the endpoint name and port to direct traffic to the app containers in the task. If any of the containers expose and listen on a port for network traffic, choose a client-server service. These applications don't need to connect to other client-server services in the same namespace, but the client configuration is needed. A backend, middleware, business tier, or most microservices can use this type of Service Connect configuration. If you want a frontend, reverse proxy, or load balancer application to receive traffic from other services configured with Service Connect in the same namespace, these services should use this type of Service Connect configuration. The Service Connect feature creates a virtual network of related services. The same service configuration can be used across multiple different namespaces to run independent yet identical sets of applications. Service Connect defines the proxy container in the Amazon ECS service. This way, the same task definition can be used to run identical applications in different namespaces with different Service Connect configurations. Each task that the service makes runs a proxy container in the task. Service Connect is suitable for connections between Amazon ECS services within the same namespace. For the following applications, you need to use an additional interconnection method to connect to an Amazon ECS service that is configured with Service Connect: + Tasks that are configured in other namespaces + Tasks that aren’t configured for Service Connect + Other applications outside of Amazon ECS These applications can connect through the Service Connect proxy but can’t resolve Service Connect endpoint names. For these applications to resolve the IP addresses of Amazon ECS tasks, you need to use another interconnection method. **Topics** + [ ## Pricing ](#service-connect-pricing) + [ # Amazon ECS Service Connect components ](service-connect-concepts-deploy.md) + [ # Amazon ECS Service Connect configuration overview ](service-connect-concepts.md) + [ # Amazon ECS Service Connect with shared AWS Cloud Map namespaces ](service-connect-shared-namespaces.md) + [ # Amazon ECS Service Connect access logs ](service-connect-envoy-access-logs.md) + [ # Encrypt Amazon ECS Service Connect traffic ](service-connect-tls.md) + [ # Configuring Amazon ECS Service Connect with the AWS CLI ](create-service-connect.md) ## Pricing + Amazon ECS Service Connect pricing depends on whether you use AWS Fargate or Amazon EC2 infrastructure to host your containerized workloads. When using Amazon ECS on AWS Outposts, the pricing follows the same model that's used when you use Amazon EC2 directly. For more information, see [Amazon ECS Pricing](https://aws.amazon.com/ecs/pricing). + There is no additional charge for using Amazon ECS Service Connect. + There is no additional charge for AWS Cloud Map usage when used by Service Connect. + Customers pay for compute resources used by Amazon ECS Service Connect, including vCPU and Memory. As the Amazon ECS Service Connect agent runs inside a customer task, there is no additional charge for running it. The task resources are shared between the customer workload and the Amazon ECS Service Connect agent. + When using Amazon ECS Service Connect traffic encryption functionality with AWS Private CA, customers pay for the private certificate authority they create and for each TLS certificate issued. For more details, see [AWS Private Certificate Authority pricing](https://aws.amazon.com/private-ca/pricing/). To estimate the monthly cost of TLS certificates, customers need to know the number of Amazon ECS services that have TLS enabled, multiply it by the certificate cost, and then multiply it by six. As Amazon ECS Service Connect automatically rotates TLS certificates every five days, there are six certificates issued per Amazon ECS service, per month, on average. # Amazon ECS Service Connect components Service Connect components When you use Amazon ECS Service Connect, you configure each Amazon ECS service to run a server application that receives network requests (client-server service) or to run a client application that makes the requests (client service). When you prepare to start using Service Connect, start with a client-server service. You can add a Service Connect configuration to a new service or an existing service. Amazon ECS creates a Service Connect endpoint in the namespace. Additionally, Amazon ECS creates a new deployment in the service to replace the tasks that are currently running. Existing tasks and other applications can continue to connect to existing endpoints, and external applications. If a client-server service adds tasks by scaling out, new connections from clients will be balanced between all of the tasks. If a client-server service is updated, new connections from clients will be balanced between the tasks of the new version. Existing tasks can't resolve and connect to the new endpoint. Only new tasks with a Service Connect configuration in the same namespace and that start running after this deployment can resolve and connect to this endpoint. This means that the operator of the client application determines when the configuration of their app changes, even though the operator of the server application can change their configuration at any time. The list of endpoints in the namespace can change every time that any service in the namespace is deployed. Existing tasks and replacement tasks continue to behave the same as they did after the most recent deployment. Consider the following examples. First, assume that you are creating an application that is available to the public internet in a single AWS CloudFormation template and single CloudFormation stack. The public discovery and reachability should be created last by CloudFormation, including the frontend client service. The services need to be created in this order to prevent an time period when the frontend client service is running and available the public, but a backend isn't. This eliminates error messages from being sent to the public during that time period. In AWS CloudFormation, you must use the `dependsOn` to indicate to CloudFormation that multiple Amazon ECS services can't be made in parallel or simultaneously. You should add the `dependsOn` to the frontend client service for each backend client-server service that the client tasks connect to. Second, assume that a frontend service exists without Service Connect configuration. The tasks are connecting to an existing backend service. Add a client-server Service Connect configuration to the backend service first, using the same name in the **DNS** or `clientAlias` that the frontend uses. This creates a new deployment, so all the deployment rollback detection or AWS Management Console, AWS CLI, AWS SDKs and other methods to roll back and revert the backend service to the previous deployment and configuration. If you are satisfied with the performance and behavior of the backend service, add a client or client-server Service Connect configuration to the frontend service. Only the tasks in the new deployment use the Service Connect proxy that is added to those new tasks. If you have issues with this configuration, you can roll back and revert to your previous configuration by using the deployment rollback detection or AWS Management Console, AWS CLI, AWS SDKs and other methods to roll back and revert the backend service to the previous deployment and configuration. If you use another service discovery system that is based on DNS instead of Service Connect, any frontend or client applications begin using new endpoints and changed endpoint configuration after the local DNS cache expires, commonly taking multiple hours. ## Networking By default, the Service Connect proxy listens on the `containerPort` from the task definition port mapping. Your security group rules must allow incoming (ingress) traffic to this port from the subnets where clients will run. Even if you set a port number in the Service Connect service configuration, this doesn't change the port for the client-server service that the Service Connect proxy listens on. When you set this port number, Amazon ECS changes the port of the endpoint that the client services connect to, on the Service Connect proxy inside those tasks. The proxy in the client service connects to the proxy in the client-server service using the `containerPort`. If you want to change the port that the Service Connect proxy listens on, change the `ingressPortOverride` in the Service Connect configuration of the client-server service. If you change this port number, you must allow inbound traffic on this port that is used by traffic to this service. Traffic that your applications send to Amazon ECS services configured for Service Connect require that the Amazon VPC and subnets have route table rules and network ACL rules that allow the `containerPort` and `ingressPortOverride` port numbers that you are using. You can use Service Connect to send traffic between VPCs. The same requirements for the route table rules, network ACLs, and security groups apply to both VPCs. For example, two clusters create tasks in different VPCs. A service in each cluster is configured to use the same namespace. The applications in these two services can resolve every endpoint in the namespace without any VPC DNS configuration. However, the proxies can't connect unless the VPC peering, VPC, or subnet route tables, and VPC network ACLs allow the traffic on the `containerPort` and `ingressPortOverride` port numbers. For tasks that use the `bridge` networking mode, you must create a security group with an inbound rule that allows traffic on the upper dynamic port range. Then, assign the security group to all the EC2 instances in the Service Connect cluster. ## Service Connect proxy If you create or update a service with Service Connect configuration, Amazon ECS adds a new container to each new task as it is started. This pattern of using a separate container is called a `sidecar`. This container isn't present in the task definition and you can't configure it. Amazon ECS manages the Container configuration in the service. This allows you to reuse the same task definitions between multiple services, namespaces, and tasks without Service Connect. **Proxy resources** + For task definitions, you must set the CPU and memory parameters. We recommend adding an additional 256 CPU units and at least 64 MiB of memory to your task CPU and memory for the Service Connect proxy container. On AWS Fargate, the lowest amount of memory that you can set is 512 MiB of memory. On Amazon EC2, task definition memory is required. + For the service, you set the log configuration in the Service Connect configuration. + If you expect tasks in this service to receive more than 500 requests per second at their peak load, we recommend adding 512 CPU units to your task CPU in this task definition for the Service Connect proxy container. + If you expect to create more than 100 Service Connect services in the namespace or 2000 tasks in total across all Amazon ECS services within the namespace, we recommend adding 128 MiB of memory to your task memory for the Service Connect proxy container. You should do this in every task definition that is used by all of the Amazon ECS services in the namespace. **Proxy configuration** Your applications connect to the proxy in the sidecar container in the same task as the application is in. Amazon ECS configures the task and containers so that applications only connect to the proxy when the application is connected to the endpoint names in the same namespace. All other traffic doesn't use the proxy. The other traffic includes IP addresses in the same VPC, AWS service endpoints, and external traffic. **Load balancing** Service Connect configures the proxy to use the round-robin strategy for load balancing between the tasks in a Service Connect endpoint. The local proxy that is in the task where the connection comes from, picks one of the tasks in the client-server service that provides the endpoint. For example, consider a task that runs WordPress in a service that is configured as a *client service* in a namespace called *local*. There is another service with 2 tasks that run the MySQL database. This service is configured to provide an endpoint called `mysql` through Service Connect in the same namespace. In the WordPress task, the WordPress application connects to the database using the endpoint name. Connections to this name go to the proxy that runs in a sidecar container in the same task. Then, the proxy can connect to either of the MySQL tasks using the round-robin strategy. Load balancing strategies: round-robin **Outlier detection** This feature uses data that the proxy has about prior failed connections to avoid sending new connections to the hosts that had the failed connections. Service Connect configures the outlier detection feature of the proxy to provide passive health checks. Using the previous example, the proxy can connect to either of the MySQL tasks. If the proxy made multiple connections to a specific MySQL task, and 5 or more of the connections failed in the last 30 seconds, then the proxy avoids that MySQL task for 30 to 300 seconds. **Retries** Service Connect configures the proxy to retry connection that pass through the proxy and fail, and the second attempt avoids using the host from the previous connection. This ensures that each connection through Service Connect doesn't fail for one-off reasons. Number of retries: 2 **Timeout** Service Connect configures the proxy to wait a maximum time for your client-server applications to respond. The default timeout value is 15 seconds, but it can be updated. Optional parameters: **idleTimeout** ‐ The amount of time in seconds a connection stays active while idle. A value of `0` disables `idleTimeout`. The `idleTimeout` default for `HTTP`/`HTTP2`/`GRPC` is 5 minutes. The `idleTimeout` default for `TCP` is 1 hour. **perRequestTimeout** ‐ The amount of time waiting for the upstream to respond with a complete response per request. A value of `0` turns off `perRequestTimeout`. This can only be set when the `appProtocol` for application container is `HTTP`/`HTTP2`/`GRPC`. The default is 15 seconds. If `idleTimeout` is set to a time that is less than `perRequestTimeout`, the connection will close when the `idleTimeout` is reached and not the `perRequestTimeout`. ## Considerations Consider the following when using Service Connect: + Tasks that run in Fargate must use the Fargate Linux platform version `1.4.0` or higher to use Service Connect. + The Amazon ECS agent version on the container instance must be `1.67.2` or higher. + Container instances must run the Amazon ECS-optimized Amazon Linux 2023 AMI version `20230428` or later, or Amazon ECS-optimized Amazon Linux 2 AMI version `2.0.20221115` to use Service Connect. These versions have the Service Connect agent in addition to the Amazon ECS container agent. For more information about the Service Connect agent, see [Amazon ECS Service Connect Agent](https://github.com/aws/amazon-ecs-service-connect-agent) on GitHub. + Container instances must have the `ecs:Poll` permission for the resource `arn:aws:ecs:region:0123456789012:task-set/cluster/*`. If you are using the `ecsInstanceRole`, you don't need to add additional permissions. The `AmazonEC2ContainerServiceforEC2Role` managed policy has the necessary permissions. For more information, see [Amazon ECS container instance IAM role](instance_IAM_role.md). + Tasks that use the `bridge` network mode and use Service Connect don't support the `hostname` container definition parameter. + Task definitions must set the task memory limit to use Service Connect. For more information, see [Service Connect proxy](#service-connect-concepts-proxy). + Task definitions that set container memory limits aren't supported. You can set container memory limits on your containers, but you must set the task memory limit to a number greater than the sum of the container memory limits. The additional CPU and memory in the task limits that aren't allocated in the container limits are used by the Service Connect proxy container and other containers that don't set container limits. For more information, see [Service Connect proxy](#service-connect-concepts-proxy). + You can configure Service Connect to use any AWS Cloud Map namespace in the same Region that are either in the same AWS account or are shared with your AWS account using AWS Resource Access Manager. For more information about using shared namespaces, see [Amazon ECS Service Connect with shared AWS Cloud Map namespaces](service-connect-shared-namespaces.md). + Each service can belong to only one namespace. + Only the tasks that services create are supported. + All endpoints must be unique within a namespace. + All discovery names must be unique within a namespace. + You must redeploy existing services before the applications can resolve new endpoints. New endpoints that are added to the namespace after the most recent deployment won't be added to the task configuration. For more information, see [Amazon ECS Service Connect components](#service-connect-concepts-deploy). + Service Connect doesn't delete namespaces when clusters are deleted. You must delete namespaces in AWS Cloud Map. + Application Load Balancer traffic defaults to routing through the Service Connect agent in `awsvpc` network mode. If you want non-service traffic to bypass the Service Connect agent, use the `[ingressPortOverride](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ServiceConnectService.html)` parameter in your Service Connect service configuration. + Service Connect with TLS does not support `bridge` networking mode. Only `awsvpc` networking mode is supported. + In `awsvpc` mode, the Service Connect proxy forwards traffic to the IPv4 localhost `127.0.0.1` for services in IPv4-only and dualstack configurations. For services in IPv6-only configuration, the proxy forwards traffic to the IPv6 localhost `::1`. We recommend configuring your applications to listen to both localhosts for a seamless experience when a service is updated from IPv4-only or dualstack configuration to IPv6-only. For more information, see [Amazon ECS task networking options for EC2](task-networking.md) and [Amazon ECS task networking options for Fargate](fargate-task-networking.md). **Service Connect doesn't support the following:** + Windows containers + HTTP 1.0 + Standalone tasks + Services that use the blue/green powered by CodeDeploy and external deployment types + `External` container instance for Amazon ECS Anywhere aren't supported with Service Connect. + PPv2 + FIPS mode # Amazon ECS Service Connect configuration overview 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](task_definition_parameters.md#ContainerDefinition-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](service_definition_parameters.md#Service-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](service_definition_parameters.md#Service-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 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 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. 1. Create a cluster with a AWS 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. 1. Configure services to create Service Connect endpoints within the namespace. 1. 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. 1. 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](service-connect-concepts-deploy.md#service-connect-concepts-proxy). 1. 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 AWS Region and account, or in the same AWS Region and shared by another AWS account using AWS 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 AWS CLI, you must add `--include ATTACHMENTS` to see them. If you want to use a namespace that is shared with your AWS account using AWS RAM, specify the Amazon Resource Name (ARN) of the namespace in the cluster configuration. For more information about shared AWS Cloud Map namespaces, see [Amazon ECS Service Connect with shared AWS Cloud Map namespaces](service-connect-shared-namespaces.md). ## 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 AWS 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. ## Initial Health Check configuration Service Connect ensures tasks are healthy before routing traffic to them. When a task launches (during deployments, scaling, or replacements), Service Connect monitors the health of your task to ensure it is ready to accept traffic. You must define health checks for the essential container in your task definition to enable this behavior. The behavior of the initial health check accounts for potential delays with reaching the state when a task is ready to accept traffic: + If a task is `HEALTHY`, it's immediately available for traffic. + If a task's health is `UNKNOWN`, Service Connect follows the container health check configuration (see [Health check](task_definition_parameters.md#container_definition_healthcheck)) of the task's essential containers to calculate a timeout, up to `8 minutes`, before making it available to traffic, even if it remains `UNKNOWN`. + If a task is `UNHEALTHY`, Amazon ECS may launch replacement tasks. If no healthy tasks are available, your deployment might be rolled back based on your service's configuration. For all ongoing traffic, Service Connect uses passive health checks based on outlier detection to route traffic efficiently. # Amazon ECS Service Connect with shared AWS Cloud Map namespaces Service Connect with shared namespaces Amazon ECS Service Connect supports using shared AWS Cloud Map namespaces across multiple AWS accounts within the same AWS Region. This capability enables you to create distributed applications where services running in different AWS accounts can discover and communicate with each other through Service Connect. Shared namespaces are managed using AWS Resource Access Manager (AWS RAM), which allows secure cross-account resource sharing. For more information about shared namespaces, see [Cross-account AWS Cloud Map namespace sharing](https://docs.aws.amazon.com/cloud-map/latest/dg/sharing-namespaces.html) in the *AWS Cloud Map Developer Guide*. **Important** You must use the `AWSRAMPermissionCloudMapECSFullPermission` managed permission to share the namespace for Service Connect to work properly with the namespace. When you use shared AWS Cloud Map namespaces with Service Connect, services from multiple AWS accounts can participate in the same service namespace. This is particularly useful for organizations with multiple AWS accounts that need to maintain service-to-service communication across account boundaries while preserving security and isolation. **Note** To communicate with services that are in different VPCs, you will need to configure inter-VPC connectivity. This can be achieved using a VPC Peering connection. For more information, see [Create or delete a VPC Peering connection](https://docs.aws.amazon.com/vpc/latest/peering/create-vpc-peering-connection.html) in the *Amazon Virtual Private Cloud VPC Peering guide*. # Using shared AWS Cloud Map namespaces with Amazon ECS Service Connect Using shared AWS Cloud Map namespaces Setting up shared AWS Cloud Map namespaces for Service Connect involves the following steps: Namespace owner creating the namespace, owner sharing it through AWS Resource Access Manager (AWS RAM), consumer accepting the resource share, and consumer configuring Service Connect to use the shared namespace. ## Step 1: Create the AWS Cloud Map namespace The namespace owner creates a AWS Cloud Map namespace that will be shared with other accounts. **To create a namespace for sharing using the AWS Management Console** 1. Open the AWS Cloud Map console at [https://console.aws.amazon.com/cloudmap/](https://console.aws.amazon.com/cloudmap/). 1. Choose **Create namespace**. 1. Enter a **Namespace name**. This name will be used by services across all participating accounts. 1. For **Namespace type**, choose the appropriate type for your use case: + **API calls** ‐ HTTP namespaces for service discovery without DNS functionality. + **API calls and DNS queries in VPCs** ‐ Private DNS namespaces for service discovery with private DNS queries in a VPC. + **API calls and public DNS queries** ‐ Public DNS namespaces for service discovery with public DNS queries. 1. Choose **Create namespace**. ## Step 2: Share the namespace using AWS RAM The namespace owner uses AWS RAM to share the namespace with other AWS accounts. **To share a namespace using the AWS RAM console** 1. Open the AWS RAM console at [https://console.aws.amazon.com/ram/](https://console.aws.amazon.com/ram/). 1. Choose **Create resource share**. 1. For **Name**, enter a descriptive name for the resource share. 1. In the **Resources** section: 1. For **Resource type**, choose **Cloud Map Namespaces**. 1. Select the namespace you created in the previous step. 1. In the **Managed permissions** section, specify **AWSRAMPermissionCloudMapECSFullPermission**. **Important** You must use the `AWSRAMPermissionCloudMapECSFullPermission` managed permission to share the namespace for Service Connect to work properly with the namespace. 1. In the **Principals** section, specify the AWS accounts you want to share the namespace with. You can enter account IDs or organizational unit IDs. 1. Choose **Create resource share**. ## Step 3: Accept the resource share Namespace consumer accounts must accept the resource share invitation to use the shared namespace. **To accept a resource share invitation using the AWS RAM console** 1. In the consumer account, open the AWS RAM console at [https://console.aws.amazon.com/ram/](https://console.aws.amazon.com/ram/). 1. In the navigation pane, choose **Shared with me**, then choose **Resource shares**. 1. Select the resource share invitation and choose **Accept resource share**. 1. After accepting, note the shared namespace ARN from the resource details. You'll use this ARN when configuring Service Connect services. ## Step 4: Configure an Amazon ECS service with the shared namespace After accepting the shared namespace, the namespace consumer can configure Amazon ECS services to use the shared namespace. The configuration is similar to using a regular namespace, but you must specify the namespace ARN instead of the name. For a detailed service creation procedure, see [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md). **To create a service with a shared namespace using the AWS Management Console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster that you want to create the service in. 1. Under **Services**, choose **Create**. 1. After filling in other details depending on your workload, in the **Service Connect** section, choose **Use Service Connect**. 1. For **Namespace**, enter the full ARN of the shared namespace. The ARN format is: `arn:aws:servicediscovery:region:account-id:namespace/namespace-id` 1. Configure the remaining Service Connect settings as needed for your service type (client or client-server). 1. Complete the service creation process. You can also configure services using the AWS CLI or AWS SDKs by specifying the shared namespace ARN in the `namespace` parameter of the `serviceConnectConfiguration`. ``` aws ecs create-service \ --cluster my-cluster \ --service-name my-service \ --task-definition my-task-def \ --service-connect-configuration '{ "enabled": true, "namespace": "arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-abcdef1234567890", "services": [{ "portName": "web", "discoveryName": "my-service", "clientAliases": [{ "port": 80, "dnsName": "my-service" }] }] }' ``` ## Considerations Consider the following when using shared AWS Cloud Map namespaces with Service Connect: + AWS RAM must be available in the AWS Region where you want to use the shared namespace. + The shared namespace must be in the same AWS Region as your Amazon ECS services and clusters. + You must use the namespace ARN, not the ID, when configuring Service Connect with a shared namespace. + All namespace types are supported: HTTP, Private DNS, and Public DNS namespaces. + If access to a shared namespace is revoked, Amazon ECS operations that require interaction with the namespace (such as `CreateService`, `UpdateService`, and `ListServicesByNamespace`) will fail. For more information about troubleshooting permissions issues with shared namespaces, see [Troubleshooting Amazon ECS Service Connect with shared AWS Cloud Map namespaces](service-connect-shared-namespaces-troubleshooting.md). + For service discovery using DNS queries in a shared private DNS namespace: + The namespace owner will need to call `create-vpc-association-authorization` with the ID of the private hosted zone associated with the namespace, and the consumer's VPC. ``` aws route53 create-vpc-association-authorization --hosted-zone-id Z1234567890ABC --vpc VPCRegion=us-east-1,VPCId=vpc-12345678 ``` + The namespace consumer will need to call `associate-vpc-with-hosted-zone` with the ID of the private hosted zone. ``` aws route53 associate-vpc-with-hosted-zone --hosted-zone-id Z1234567890ABC --vpc VPCRegion=us-east-1,VPCId=vpc-12345678 ``` + Only the namespace owner can manage the resource share. + Namespace consumers can create and manage services within the shared namespace but cannot modify the namespace itself. + Discovery names must be unique within the shared namespace, regardless of which account creates the service. + Services in the shared namespace can discover and connect to services from other AWS accounts that have access to the namespace. + When enabling TLS for Service Connect and using a shared namespace, the AWS Private CA Certificate Authority (CA) is scoped to the namespace. When access to the shared namespace is revoked, access to the CA is stopped. + When working with a shared namespace, namespace owners and consumers don't have access to cross-account Amazon CloudWatch metrics by default. Target metrics are published only to accounts that own client services. An account that owns client services doesn't have access to metrics received by an account owning client-server services, and the other way around. To allow for cross-account access to metrics, set up CloudWatch cross-account observability. For more information about configuring cross-account observability, see [CloudWatch cross-account observabilty](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Unified-Cross-Account.html) in the *Amazon CloudWatch User Guide*. For more information about the CloudWatch metrics for Service Connect, see [Amazon ECS CloudWatch metrics](available-metrics.md). # Troubleshooting Amazon ECS Service Connect with shared AWS Cloud Map namespaces Troubleshooting shared namespaces Use the following information to troubleshoot issues with shared AWS Cloud Map namespaces and Service Connect. For more information on locating error messages, see [Amazon ECS troubleshooting](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/troubleshooting.html). Error messages related to permissions issues appear due to missing permissions, or if access to the namespace is revoked. **Important** You must use the `AWSRAMPermissionCloudMapECSFullPermission` managed permission to share the namespace for Service Connect to work properly with the namespace. Error message appears in one of the following formats: An error occurred (ClientException) when calling the operation: User: arn:aws:iam:::user/ is not authorized to perform: on resource: because no resource-based policy allows the action The following scenarios can result in an error message in this format: **Cluster creation or update failure** These issues occur when Amazon ECS operations such as `CreateCluster` or `UpdateCluster` fail due to missing AWS Cloud Map permissions. The operations require permissions for the following AWS Cloud Map actions: + `servicediscovery:GetNamespace` Ensure that the resource share invitation has been accepted in the consumer account and that the correct namespace ARN is being used in the Service Connect configuration. **Service creation or update failure** These issues occur when Amazon ECS operations such as `CreateService` or `UpdateService` fail due to missing AWS Cloud Map permissions. The operations require permissions for the following AWS Cloud Map actions: + `servicediscovery:CreateService` + `servicediscovery:GetNamespace` + `servicediscovery:GetOperation` (for creating a new AWS Cloud Map service) + `servicediscovery:GetService` (for when a AWS Cloud Map service already exists) Ensure that the resource share invitation has been accepted in the consumer account and that the correct namespace ARN is being used in the Service Connect configuration. **`ListServicesByNamespace` operation fails** This issue occurs when the Amazon ECS `ListServicesByNamespace` operation fails. The operation requires permissions for the following AWS Cloud Map actions: + `servicediscovery:GetNamespace` To resolve this issue: + Verify that the consumer account has the `servicediscovery:GetNamespace` permission. + Use the namespace ARN when calling the API, not the name. + Ensure the resource share is active and the invitation has been accepted. User: is not authorized to perform: on resource: with an explicit deny in an identity-based policy. The following scenarios can result in an error message in this format: **Service deletion fails and gets stuck in `DRAINING` state** This issue occurs when Amazon ECS `DeleteService` operations fail due to the missing `servicediscovery:DeleteService` permission when access to the namespace is revoked. The service may appear to delete successfully initially but will get stuck in the `DRAINING` state. The error message appears as an Amazon ECS service event. To resolve this issue, the namespace owner must share the namespace with the consumer account to allow service deletion to complete. **Tasks in service fail to run** This issue occurs when tasks fail to start due to missing permissions. The error message is surfaced as a stopped task error. For more information, see [Resolve Amazon ECS stopped task errors](resolve-stopped-errors.md). The following AWS Cloud Map actions are required for running a task: + `servicediscovery:GetOperation` + `servicediscovery:RegisterInstance` Ensure that the consumer account has the required permissions and that the shared namespace is accessible. **Tasks fail to stop cleanly or get stuck in `DEACTIVATING` or `DEPROVISIONING` state** This issue occurs when tasks fail to deregister from the AWS Cloud Map service during shutdown due to missing permissions. The error is surfaced as a `statusReason` in the task attachment that can be retreived using the `DescribeTasks` API. For more information, see [DescribeTasks](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_DescribeTasks.html) in the *Amazon Elastic Container Service API Reference*. The following AWS Cloud Map actions are required to stop a task: + `servicediscovery:DeregisterInstance` + `servicediscovery:GetOperation` If access to the shared namespace is revoked, tasks may remain in a `DEACTIVATING` or `DEPROVISIONING` state until namespace access is restored. Request the namespace owner to restore access to the namespace. # Amazon ECS Service Connect access logs Service Connect access logs Amazon ECS Service Connect supports access logs to provide detailed telemetry about individual requests processed by the Service Connect proxy. Access logs complement existing application logs by capturing per-request traffic metadata such as HTTP methods, paths, response codes, flags, and timing information. This enables deeper observability into request-level traffic patterns and service interactions for effective troubleshooting and monitoring. To enable access logs, specify both the `logConfiguration` and `accessLogConfiguration` objects in the `serviceConnectConfiguration` object. You can configure the format of the logs and whether the logs should include query parameters in the `accessLogConfiguration`. The logs are delivered to the destination log group by the log driver specificied in the `logConfiguration`. ``` { "serviceConnectConfiguration": { "enabled": true, "namespace": "myapp.namespace", "services": [ ... ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "my-envoy-log-group", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "myapp-envoy-logs" } }, "accessLogConfiguration": { "format": "TEXT", "includeQueryParameters": "ENABLED" } } } ``` ## Considerations Consider the following when you enable access to access logs + Access logs and application logs are both written to `/dev/stdout`. To separate access logs from application logs, we recommend using the `awsfirelens` log driver with a custom Fluent Bit or Fluentd configuration. + We recommend using the `awslogs` log driver to send application and access logs to the same CloudWatch destination. + access logs are supported on Fargate services that use platform version `1.4.0` and higher. + Query parameters such as request ids and tokens are excluded from access logs by default. To include query parameters in access logs, set `includeQueryParameters` to `"ENABLED"`. ## Access log formats access logs can be formatted in either JSON format dictionaries or Text format strings, with differences in supported command operators for different types of access logs. ### HTTP access logs The following command operators are included by default for HTTP logs: ------ #### [ Text ] ``` [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"\n ``` ------ #### [ JSON ] ``` { "start_time": "%START_TIME%", "method": "%REQ(:METHOD)%", "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%", "protocol": "%PROTOCOL%", "response_code": "%RESPONSE_CODE%", "bytes_received": "%BYTES_RECEIVED%", "bytes_sent": "%BYTES_SENT%", "duration_ms": "%DURATION%", "upstream_service_time": "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%", "forwarded_for": "%REQ(X-FORWARDED-FOR)%", "user_agent": "%REQ(USER-AGENT)%", "request_id": "%REQ(X-REQUEST-ID)%", "authority": "%REQ(:AUTHORITY)%", "upstream_host": "%UPSTREAM_HOST%" } ``` ------ ### HTTP2 access logs In addition to the command operators included for HTTP logs, HTTP2 logs include the `%STREAM_ID%` operator by default. ------ #### [ Text ] ``` [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%" "%STREAM_ID%"\n ``` ------ #### [ JSON ] ``` { "start_time": "%START_TIME%", "method": "%REQ(:METHOD)%", "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%", "protocol": "%PROTOCOL%", "response_code": "%RESPONSE_CODE%", "bytes_received": "%BYTES_RECEIVED%", "bytes_sent": "%BYTES_SENT%", "duration": "%DURATION%", "upstream_service_time": "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%", "forwarded_for": "%REQ(X-FORWARDED-FOR)%", "user_agent": "%REQ(USER-AGENT)%", "request_id": "%REQ(X-REQUEST-ID)%", "authority": "%REQ(:AUTHORITY)%", "upstream_host": "%UPSTREAM_HOST%", "stream_id": "%STREAM_ID%" } ``` ------ ### gRPC access logs In addition to the command operators included for HTTP logs, gRPC access logs include the `%STREAM_ID%` and `%GRPC_STATUS()%`operator by default. ------ #### [ Text ] ``` [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %GRPC_STATUS()% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%" "%STREAM_ID%"\n ``` ------ #### [ JSON ] ``` { "start_time": "%START_TIME%", "method": "%REQ(:METHOD)%", "path": "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%", "protocol": "%PROTOCOL%", "response_code": "%RESPONSE_CODE%", "grpc_status": "%GRPC_STATUS()%", "bytes_received": "%BYTES_RECEIVED%", "bytes_sent": "%BYTES_SENT%", "duration": "%DURATION%", "upstream_service_time": "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%", "forwarded_for": "%REQ(X-FORWARDED-FOR)%", "user_agent": "%REQ(USER-AGENT)%", "request_id": "%REQ(X-REQUEST-ID)%", "authority": "%REQ(:AUTHORITY)%", "upstream_host": "%UPSTREAM_HOST%", "stream_id": "%STREAM_ID%" } ``` ------ ### TCP access logs The following command operators are included by default in TCP access logs: ------ #### [ Text ] ``` [%START_TIME%] %DOWNSTREAM_REMOTE_ADDRESS% %DOWNSTREAM_REMOTE_PORT% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %CONNECTION_TERMINATION_DETAILS% %CONNECTION_ID%\n ``` ------ #### [ JSON ] ``` { "start_time": "%START_TIME%", "downstream_remote_address": "%DOWNSTREAM_REMOTE_ADDRESS%", "downstream_remote_port": "%DOWNSTREAM_REMOTE_PORT%",s "bytes_received": "%BYTES_RECEIVED%", "bytes_sent": "%BYTES_SENT%", "duration": "%DURATION%", "connection_termination_details": "%CONNECTION_TERMINATION_DETAILS%", "connection_id": %CONNECTION_ID% } ``` ------ For more information about these command operators, see [Command Operators](https://www.envoyproxy.io/docs/envoy/latest/configuration/observability/access_log/usage#command-operators) in the Envoy documentation. # Enabling access logs for Amazon ECS Service Connect Enabling access logs Access logs are not enabled by default for Amazon ECS services that use Service Connect. You can enable access logs in the following ways. ## Enable access logs using the AWS CLI The following command shows how you can enable access logs for an Amazon ECS service using the AWS CLI by specifying a `accessLogConfiguration` when you create the service: ``` aws ecs create-service \ --cluster my-cluster \ --service-name my-service \ --task-definition my-task-def \ --service-connect-configuration '{ "enabled": true, "namespace": "arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-abcdef1234567890", "services": [{ "portName": "web", "discoveryName": "my-service", "clientAliases": [{ "port": 80, "dnsName": "my-service" }] }], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "my-envoy-log-group", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "myapp-envoy-logs" } }, "accessLogConfiguration": { "format": "TEXT", "includeQueryParameters": "ENABLED" } }' ``` ## Enable access logs using the console For a detailed service creation procedure, see [Creating an Amazon ECS rolling update deployment](create-service-console-v2.md). **To create a service with a shared namespace using the AWS Management Console** 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. On the **Clusters** page, choose the cluster that you want to create the service in. 1. Under **Services**, choose **Create**. 1. After filling in other details depending on your workload, in the **Service Connect** section, choose **Use Service Connect**. 1. Configure Service Connect settings as needed for your service type (client or client-server). 1. Expand **Access log configuration**. For **Format**, choose either **JSON** or `TEXT`. 1. To include query parameters in access logs, select **Include query parameters**. 1. Complete the service creation process. # Encrypt Amazon ECS Service Connect traffic Encrypt Service Connect traffic Amazon ECS Service Connect supports automatic traffic encryption with Transport Layer Security (TLS) certificates for Amazon ECS services. When you point your Amazon ECS services toward an [AWS Private Certificate Authority (AWS Private CA)](https://docs.aws.amazon.com/privateca/latest/userguide/PcaWelcome.html), Amazon ECS automatically provisions TLS certificates to encrypt traffic between your Amazon ECS Service Connect services. Amazon ECS generates, rotates, and distributes TLS certificates used for traffic encryption. Automatic traffic encryption with Service Connect uses industry-leading encryption capabilities to secure your inter-service communication that helps you meet your security requirements. It supports AWS Private Certificate Authority TLS certificates with `256-bit ECDSA` and `2048-bit RSA` encryption. You also have full control over private certificates and signing keys to help you meet compliance requirements. By default, TLS 1.3 is supported, but TLS 1.0 - 1.2 are not supported. Service Connect supports TLS 1.3 with the following ciphers: + `TLS_AES_128_GCM_SHA256` + `TLS_AES_256_GCM_SHA384` + `TLS_CHACHA20_POLY1305_SHA256` **Note** In order to use TLS 1.3, you must enable it on the listener on the target. Only inbound and outbound traffic passing though the Amazon ECS agent is encrypted. ## Service Connect and Application Load Balancer health checks You can use Service Connect with Application Load Balancer health checks and TLS 1.3 encryption. ### Application Load Balancer configuration Configure the Application Load Balancer with the following settings: + Configure a TLS listener with a TLS 1.3 security policy (such as `ELBSecurityPolicy-TLS13-1-2-2021-06`). For more information, see [Security policies for your Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/describe-ssl-policies.html). + Create a target group with the following settings: + Set the protocol to HTTPS + Attach the target group to the TLS listener + Configure the health check port to match your Service Connect service's container port ### Service Connect configuration Configure a service with the following settings: + Configure the service to use `awsvpc` network mode, as `bridge` network mode is not supported. + Enable Service Connect for the service. + Set up the load balancer configuration with the following settings: + Specify the target group you configured for your Application Load Balancer + Set the container port to match the Service Connect TLS service's container port + Avoid setting `ingressPortOverride` for the service. For more information, see [ServiceConnectService](https://docs.aws.amazon.com/AmazonECS/latest/APIReference/API_ServiceConnectService.html) in the *Amazon Elastic Container Service API Reference*. ### Considerations Consider the following when using Application Load Balancer, TLS and Service Connect: + Use `awsvpc` network mode instead of `bridge` network mode for HTTPS health checks when using Service Connect with TLS encryption. HTTP health checks will continue to work with `bridge` mode. + Configure the target group health check port to match the Service Connect service's container port, not the default HTTPS port (443). ## AWS Private Certificate Authority certificates and Service Connect You need to have the infrastructure IAM role. For more information about this role, see [Amazon ECS infrastructure IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/infrastructure_IAM_role.html ). **AWS Private Certificate Authority modes for Service Connect** AWS Private Certificate Authority can run in two modes: general purpose and short-lived. + General purpose ‐ Certificates that can be configured with any expiration date. + Short-lived ‐ Certificates with a maximum validity of seven days. While Amazon ECS supports both modes, we recommend using short-lived certificates. By default, certificates rotate every five days, and running in short-lived mode offers significant cost savings over general purpose. Service Connect doesn't support certificate revocation and instead leverages short-lived certificates with frequent certificate rotation. You have the authority to modify the rotation frequency, disable, or delete the secrets using [managed rotation](https://docs.aws.amazon.com/secretsmanager/latest/userguide/rotate-secrets_managed.html) in [Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html), but doing so can come with the following possible consequences. + Shorter Rotation Frequency ‐ A shorter rotation frequency incurs higher costs due to AWS Private CA, AWS KMS and Secrets Manager, and Auto Scaling experiencing an increased workload for rotation. + Longer Rotation Frequency ‐ Your applications’ communications fail if the rotation frequency exceeds **seven** days. + Deletion of Secret ‐ Deleting the secret results in rotation failure and impacts customer application communications. In the event of your secret rotation failing, a `RotationFailed` event is published in [AWS CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-user-guide.html). You can also set up a [CloudWatch Alarm](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/AlarmThatSendsEmail.html) for `RotationFailed`. **Important** Don't add replica Regions to secrets. Doing so prevents Amazon ECS from deleting the secret, because Amazon ECS doesn't have permission to remove Regions from replication. If you already added the replication, run the following command. ``` aws secretsmanager remove-regions-from-replication \ --secret-id SecretId \ --remove-replica-regions region-name ``` **Subordinate Certificate Authorities** You can bring any AWS Private CA, root or subordinate, to Service Connect TLS to issue end-entity certificates for the services. The provided issuer is treated as the signer and root of trust everywhere. You can issue end-entity certificates for different parts of your application from different subordinate CAs. When using the AWS CLI, provide the Amazon Resource Name (ARN) of the CA to establish the trust chain. **On-premises Certificate Authorities** To use your on-premises CA, you create and configure a subordinate CA in AWS Private Certificate Authority. This ensures all TLS certificates issued for your Amazon ECS workloads share the trust chain with the workloads you run on premises and are able to securely connect. **Important** Add the **required** tag `AmazonECSManaged : true` in your AWS Private CA. **Infrastructure as code** When using Service Connect TLS with Infrastructure as Code (IaC) tools, it's important to configure your dependencies correctly to avoid issues, such as services stuck in draining. Your AWS KMS key, if provided, IAM role, and AWS Private CA dependencies should be deleted after your Amazon ECS service. If the namespace used for Service Connect is a shared namespace, you can choose to use a shared AWS Private CA resource. For more information, see [Attach a policy for cross-account access](https://docs.aws.amazon.com/privateca/latest/userguide/pca-ram.html) in the *AWS Private Certificate Authority User Guide*. ## Service Connect and Secrets Manager **When using Amazon ECS Service Connect with TLS encryption, the service interacts with Secrets Manager in the following ways:** Service Connect utilizes the infrastructure role provided to create secrets within Secrets Manager. These secrets are used to store the associated private keys for your TLS certificates for encrypting traffic between your Service Connect services. **Warning** The automatic creation and management of these secrets by Service Connect streamlines the process of implementing TLS encryption for your services. However, it's important to be aware of potential security implications. Other IAM roles that have read access to Secrets Manager may be able to access these automatically created secrets. This could expose sensitive cryptographic material to unauthorized parties, if access controls are not properly configured. To mitigate this risk, follow these best practices: Carefully manage and restrict access to Secrets Manager, especially for secrets created by Service Connect. Regularly audit IAM roles and their permissions to ensure the principle of least privilege is maintained. When granting read access to Secrets Manager, consider excluding the TLS private keys created by Service Connect. You can do this by using a condition in your IAM policies to exclude secrets with ARNs that match the pattern: ``` "arn:aws:secretsmanager:::secret:ecs-sc!" ``` An example IAM policy that denies the `GetSecretValue` action to all secrets with the `ecs-sc!` prefix: ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Effect": "Deny", "Action": "secretsmanager:GetSecretValue", "Resource": "arn:aws:secretsmanager:*:*:secret:ecs-sc!*" } ] } ``` ------ **Note** This is a general example and may need to be adjusted based on your specific use case and AWS account configuration. Always test your IAM policies thoroughly to ensure they provide the intended access while maintaining security. By understanding how Service Connect interacts with Secrets Manager, you can better manage the security of your Amazon ECS services while leveraging the benefits of automatic TLS encryption. ## Service Connect and AWS Key Management Service You can use [AWS Key Management Service](https://docs.aws.amazon.com/kms/latest/developerguide/overview.html) to encrypt and decrypt your Service Connect resources. AWS KMS is a service managed by AWS where you can make and manage cryptographic keys that protect your data. When using AWS KMS with Service Connect, you can either choose to use an AWS owned key that AWS manages for you, or you can choose an existing AWS KMS key. You can also [create a new AWS KMS key](https://docs.aws.amazon.com/kms/latest/developerguide/create-keys.html#create-symmetric-cmk) to use. **Providing your own encryption key** You can provide your own key materials, or you can use an external key store through AWS Key Management Service Import your own key into AWS KMS, and then specify the Amazon Resource Name (ARN) of that key in Amazon ECS Service Connect. The following is an example AWS KMS policy. Replace the *user input* values with your own. ------ #### [ JSON ] **** ``` { "Version":"2012-10-17", "Statement": [ { "Sid": "id", "Effect": "Allow", "Principal": { "AWS": "arn:aws:iam::111122223333:role/role-name" }, "Action": [ "kms:Encrypt", "kms:Decrypt", "kms:GenerateDataKey", "kms:GenerateDataKeyPair" ], "Resource": "*" } ] } ``` ------ For more information about key policies, see [Creating a key policy](https://docs.aws.amazon.com/kms/latest/developerguide/key-policy-overview.html) in the *AWS Key Management Service Developer Guide*. **Note** Service Connect supports only symmetric encryption AWS KMS keys. You can't use any other type of AWS KMS key to encrypt your Service Connect resources. For help determining whether a AWS KMS key is a symmetric encryption key, see [Identify asymmetric KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/identify-key-types.html#identify-asymm-keys). For more information on AWS Key Management Service symmetric encryption keys, see [Symmetric encryption AWS KMS keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#symmetric-cmks) in the *AWS Key Management Service Developer Guide*. # Enabling TLS for Amazon ECS Service Connect Enabling TLS for Service Connect You enable traffic encryption when you create or update a Service Connect service. **To enable traffic encryption for a service in an existing namespace using the AWS Management Console** 1. You need to have the infrastructure IAM role. For more information about this role, see [Amazon ECS infrastructure IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/infrastructure_IAM_role.html ). 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation pane, choose **Namespaces**. 1. Choose the **Namespace** with the **Service** you'd like to enable traffic encryption for. 1. Choose the **Service** you'd like to enable traffic encryption for. 1. Choose **Update Service** in the top right corner and scroll down to the Service Connect section. 1. Choose **Turn on traffic encryption** under your service information to enable TLS. 1. For **Service Connect TLS role**, choose an existing infrastructure IAM role or create a new one. 1. For **Signer certificate authority**, choose an existing certificate authority or create a new one. For more information, see see [AWS Private Certificate Authority certificates and Service Connect](service-connect-tls.md#service-connect-tls-certificates). 1. For **Choose an AWS KMS key**, choose an AWS owned and managed key or you can choose a different key. You can also choose to create a new one. For an example of using the AWS CLI to configure TLS for your service, [Configuring Amazon ECS Service Connect with the AWS CLI](create-service-connect.md). # Verifying TLS is enabled for Amazon ECS Service Connect Verifying TLS is enabled for Service Connect Service Connect initiates TLS at the Service Connect agent and terminates it at the destination agent. As a result, the application code never sees TLS interactions. Use the following steps to verify that TLS is enabled. 1. Include the `openssl` CLI in your application image. 1. Enable [ECS Exec](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html) on your services to connect to your tasks via SSM. Alternately, you can launch an Amazon EC2 instance in the same Amazon VPC as the service. 1. Retrieve the IP and port of a task from a service that you want to verify. You can retrieve the task IP address in the AWS Cloud Map console. The information is on the service details page for the namespace. 1. Log on to any of your tasks using `execute-command` like in the following example. Alternately, log on to the Amazon EC2 instance created in **Step 2**. ``` $ aws ecs execute-command --cluster cluster-name \ --task task-id \ --container container-name \ --interactive \ --command "/bin/sh" ``` **Note** Calling the DNS name directly does not reveal the certificate. 1. In the connected shell, use the `openssl` CLI to verify and view the certificate attached to the task. Example: ``` openssl s_client -connect 10.0.147.43:6379 < /dev/null 2> /dev/null \ | openssl x509 -noout -text ``` Example response: ``` Certificate: Data: Version: 3 (0x2) Serial Number: Signature Algorithm: ecdsa-with-SHA256 Issuer: Validity Not Before: Jan 23 21:38:12 2024 GMT Not After : Jan 30 22:38:12 2024 GMT Subject: Subject Public Key Info: Public Key Algorithm: id-ecPublicKey Public-Key: (256 bit) pub: ASN1 OID: prime256v1 NIST CURVE: P-256 X509v3 extensions: X509v3 Subject Alternative Name: DNS:redis.yelb-cftc X509v3 Basic Constraints: CA:FALSE X509v3 Authority Key Identifier: keyid: X509v3 Subject Key Identifier: 1D: X509v3 Key Usage: critical Digital Signature, Key Encipherment X509v3 Extended Key Usage: TLS Web Server Authentication, TLS Web Client Authentication Signature Algorithm: ecdsa-with-SHA256 ``` # Configuring Amazon ECS Service Connect with the AWS CLI Configuring Service Connect with the AWS CLI You can create an Amazon ECS service for a Fargate task that uses Service Connect with the AWS CLI. **Note** You can use dual-stack service endpoints to interact with Amazon ECS from the AWS CLI, SDKs, and the Amazon ECS API over both IPv4 and IPv6. For more information, see [Using Amazon ECS dual-stack endpoints](dual-stack-endpoint.md). ## Prerequisites The following are Service Connect prerequisites: + Verify that the latest version of the AWS CLI is installed and configured. For more information, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + Your IAM user has the required permissions specified in the [AmazonECS\$1FullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonECS_FullAccess) IAM policy example. + You have a VPC, subnet, route table, and security group created to use. For more information, see [Create a virtual private cloud](get-set-up-for-amazon-ecs.md#create-a-vpc). + You have a task execution role with the name `ecsTaskExecutionRole` and the `AmazonECSTaskExecutionRolePolicy` managed policy is attached to the role. This role allows Fargate to write the NGINX application logs and Service Connect proxy logs to Amazon CloudWatch Logs. For more information, see [Creating the task execution role](task_execution_IAM_role.md#create-task-execution-role). ## Step 1: Create the cluster Use the following steps to create your Amazon ECS cluster and namespace. **To create the Amazon ECS cluster and AWS Cloud Map namespace** 1. Create an Amazon ECS cluster named `tutorial` to use. The parameter `--service-connect-defaults` sets the default namespace of the cluster. In the example output, a AWS Cloud Map namespace of the name `service-connect` doesn't exist in this account and AWS Region, so the namespace is created by Amazon ECS. The namespace is made in AWS Cloud Map in the account, and is visible with all of the other namespaces, so use a name that indicates the purpose. ``` aws ecs create-cluster --cluster-name tutorial --service-connect-defaults namespace=service-connect ``` Output: ``` { "cluster": { "clusterArn": "arn:aws:ecs:us-west-2:123456789012:cluster/tutorial", "clusterName": "tutorial", "serviceConnectDefaults": { "namespace": "arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-EXAMPLE" }, "status": "PROVISIONING", "registeredContainerInstancesCount": 0, "runningTasksCount": 0, "pendingTasksCount": 0, "activeServicesCount": 0, "statistics": [], "tags": [], "settings": [ { "name": "containerInsights", "value": "disabled" } ], "capacityProviders": [], "defaultCapacityProviderStrategy": [], "attachments": [ { "id": "a1b2c3d4-5678-90ab-cdef-EXAMPLE11111", "type": "sc", "status": "ATTACHING", "details": [] } ], "attachmentsStatus": "UPDATE_IN_PROGRESS" } } } ``` 1. Verify that the cluster is created: ``` aws ecs describe-clusters --clusters tutorial ``` Output: ``` { "clusters": [ { "clusterArn": "arn:aws:ecs:us-west-2:123456789012:cluster/tutorial", "clusterName": "tutorial", "serviceConnectDefaults": { "namespace": "arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-EXAMPLE" }, "status": "ACTIVE", "registeredContainerInstancesCount": 0, "runningTasksCount": 0, "pendingTasksCount": 0, "activeServicesCount": 0, "statistics": [], "tags": [], "settings": [], "capacityProviders": [], "defaultCapacityProviderStrategy": [] } ], "failures": [] } ``` 1. (Optional) Verify that the namespace is created in AWS Cloud Map. You can use the AWS Management Console or the normal AWS CLI configuration as this is created in AWS Cloud Map. For example, use the AWS CLI: ``` aws servicediscovery get-namespace --id ns-EXAMPLE ``` Output: ``` { "Namespace": { "Id": "ns-EXAMPLE", "Arn": "arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-EXAMPLE", "Name": "service-connect", "Type": "HTTP", "Properties": { "DnsProperties": { "SOA": {} }, "HttpProperties": { "HttpName": "service-connect" } }, "CreateDate": 1661749852.422, "CreatorRequestId": "service-connect" } } ``` ## Step 2: Create the service for the server Step 2: Create the server service The Service Connect feature is intended for interconnecting multiple applications on Amazon ECS. At least one of those applications needs to provide a web service to connect to. In this step, you create: + The task definition that uses the unmodified official NGINX container image and includes Service Connect configuration. + The Amazon ECS service definition that configures Service Connect to provide service discovery and service mesh proxy for traffic to this service. The configuration reuses the default namespace from the cluster configuration to reduce the amount of service configuration that you make for each service. + The Amazon ECS service. It runs one task using the task definition, and inserts an additional container for the Service Connect proxy. The proxy listens on the port from the container port mapping of the task definition. In a client application running in Amazon ECS, the proxy in the client task listens for outbound connections to the task definition port name, service discovery name or service client alias name, and the port number from the client alias. **To create the web service with Service Connect** 1. Register a task definition that's compatible with Fargate and uses the `awsvpc` network mode. Follow these steps: 1. Create a file that's named `service-connect-nginx.json` with the contents of the following task definition. This task definition configures Service Connect by adding `name` and `appProtocol` parameters to the port mapping. The port name makes this port more identifiable in the service configuration when multiple ports are used. The port name is also used by default as the discoverable name for use by other applications in the namespace. The task definition contains the task IAM role because the service has ECS Exec enabled. **Important** This task definition uses a `logConfiguration` to send the nginx output from `stdout` and `stderr` to Amazon CloudWatch Logs. This task execution role doesn't have the extra permissions required to make the CloudWatch Logs log group. Create the log group in CloudWatch Logs using the AWS Management Console or AWS CLI. If you don't want to send the nginx logs to CloudWatch Logs you can remove the `logConfiguration`. Replace the AWS account id in the task execution role with your AWS account id. ``` { "family": "service-connect-nginx", "executionRoleArn": "arn:aws:iam::123456789012:role/ecsTaskExecutionRole", "taskRoleArn": "arn:aws:iam::123456789012:role/ecsTaskRole", "networkMode": "awsvpc", "containerDefinitions": [ { "name": "webserver", "image": "public.ecr.aws/docker/library/nginx:latest", "cpu": 100, "portMappings": [ { "name": "nginx", "containerPort": 80, "protocol": "tcp", "appProtocol": "http" } ], "essential": true, "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/service-connect-nginx", "awslogs-region": "region", "awslogs-stream-prefix": "nginx" } } } ], "cpu": "256", "memory": "512" } ``` 1. Register the task definition using the `service-connect-nginx.json` file: ``` aws ecs register-task-definition --cli-input-json file://service-connect-nginx.json ``` 1. Create a service: 1. Create a file that's named `service-connect-nginx-service.json` with the contents of the Amazon ECS service that you're creating. This example uses the task definition that was created in the previous step. An `awsvpcConfiguration` is required because the example task definition uses the `awsvpc` network mode. When you create the ECS service, specify Fargate, and the `LATEST` platform version that supports Service Connect. The `securityGroups` and `subnets` must belong to a VPC that has the requirements for using Amazon ECS. You can obtain the security group and subnet IDs from the Amazon VPC Console. This service configures Service Connect by adding the `serviceConnectConfiguration` parameter. The namespace is not required because the cluster has a default namespace configured. Client applications running in ECS in the namespace connect to this service by using the `portName` and the port in the `clientAliases`. For example, this service is reachable using `http://nginx:80/`, as nginx provides a welcome page in the root location `/`. External applications that are not running in Amazon ECS or are not in the same namespace can reach this application through the Service Connect proxy by using the IP address of the task and the port number from the task definition. For your `tls` configuration, add the certificate `arn` for your `awsPcaAuthorityArn`, your `kmsKey`, and `roleArn` of your IAM role. This service uses a `logConfiguration` to send the service connect proxy output from `stdout` and `stderr` to Amazon CloudWatch Logs. This task execution role doesn't have the extra permissions required to make the CloudWatch Logs log group. Create the log group in CloudWatch Logs using the AWS Management Console or AWS CLI. We recommend that you create this log group and store the proxy logs in CloudWatch Logs. If you don't want to send the proxy logs to CloudWatch Logs you can remove the `logConfiguration`. ``` { "cluster": "tutorial", "deploymentConfiguration": { "maximumPercent": 200, "minimumHealthyPercent": 0 }, "deploymentController": { "type": "ECS" }, "desiredCount": 1, "enableECSManagedTags": true, "enableExecuteCommand": true, "launchType": "FARGATE", "networkConfiguration": { "awsvpcConfiguration": { "assignPublicIp": "ENABLED", "securityGroups": [ "sg-EXAMPLE" ], "subnets": [ "subnet-EXAMPLE", "subnet-EXAMPLE", "subnet-EXAMPLE" ] } }, "platformVersion": "LATEST", "propagateTags": "SERVICE", "serviceName": "service-connect-nginx-service", "serviceConnectConfiguration": { "enabled": true, "services": [ { "portName": "nginx", "clientAliases": [ { "port": 80 } ], "tls": { "issuerCertificateAuthority": { "awsPcaAuthorityArn": "certificateArn" }, "kmsKey": "kmsKey", "roleArn": "iamRoleArn" } } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/service-connect-proxy", "awslogs-region": "region", "awslogs-stream-prefix": "service-connect-proxy" } } }, "taskDefinition": "service-connect-nginx" } ``` 1. Create a service using the `service-connect-nginx-service.json` file: ``` aws ecs create-service --cluster tutorial --cli-input-json file://service-connect-nginx-service.json ``` Output: ``` { "service": { "serviceArn": "arn:aws:ecs:us-west-2:123456789012:service/tutorial/service-connect-nginx-service", "serviceName": "service-connect-nginx-service", "clusterArn": "arn:aws:ecs:us-west-2:123456789012:cluster/tutorial", "loadBalancers": [], "serviceRegistries": [], "status": "ACTIVE", "desiredCount": 1, "runningCount": 0, "pendingCount": 0, "launchType": "FARGATE", "platformVersion": "LATEST", "platformFamily": "Linux", "taskDefinition": "arn:aws:ecs:us-west-2:123456789012:task-definition/service-connect-nginx:1", "deploymentConfiguration": { "deploymentCircuitBreaker": { "enable": false, "rollback": false }, "maximumPercent": 200, "minimumHealthyPercent": 0 }, "deployments": [ { "id": "ecs-svc/3763308422771520962", "status": "PRIMARY", "taskDefinition": "arn:aws:ecs:us-west-2:123456789012:task-definition/service-connect-nginx:1", "desiredCount": 1, "pendingCount": 0, "runningCount": 0, "failedTasks": 0, "createdAt": 1661210032.602, "updatedAt": 1661210032.602, "launchType": "FARGATE", "platformVersion": "1.4.0", "platformFamily": "Linux", "networkConfiguration": { "awsvpcConfiguration": { "assignPublicIp": "ENABLED", "securityGroups": [ "sg-EXAMPLE" ], "subnets": [ "subnet-EXAMPLEf", "subnet-EXAMPLE", "subnet-EXAMPLE" ] } }, "rolloutState": "IN_PROGRESS", "rolloutStateReason": "ECS deployment ecs-svc/3763308422771520962 in progress.", "failedLaunchTaskCount": 0, "replacedTaskCount": 0, "serviceConnectConfiguration": { "enabled": true, "namespace": "service-connect", "services": [ { "portName": "nginx", "clientAliases": [ { "port": 80 } ] } ], "logConfiguration": { "logDriver": "awslogs", "options": { "awslogs-group": "/ecs/service-connect-proxy", "awslogs-region": "us-west-2", "awslogs-stream-prefix": "service-connect-proxy" }, "secretOptions": [] } }, "serviceConnectResources": [ { "discoveryName": "nginx", "discoveryArn": "arn:aws:servicediscovery:us-west-2:123456789012:service/srv-EXAMPLE" } ] } ], "roleArn": "arn:aws:iam::123456789012:role/aws-service-role/ecs.amazonaws.com/AWSServiceRoleForECS", "version": 0, "events": [], "createdAt": 1661210032.602, "placementConstraints": [], "placementStrategy": [], "networkConfiguration": { "awsvpcConfiguration": { "assignPublicIp": "ENABLED", "securityGroups": [ "sg-EXAMPLE" ], "subnets": [ "subnet-EXAMPLE", "subnet-EXAMPLE", "subnet-EXAMPLE" ] } }, "schedulingStrategy": "REPLICA", "enableECSManagedTags": true, "propagateTags": "SERVICE", "enableExecuteCommand": true } } ``` The `serviceConnectConfiguration` that you provided appears inside the first *deployment* of the output. As you make changes to the ECS service in ways that need to make changes to tasks, a new deployment is created by Amazon ECS. ## Step 3: Verify that you can connect To verify that Service Connect is configured and working, follow these steps to connect to the web service from an external application. Then, see the additional metrics in CloudWatch the Service Connect proxy creates. **To connect to the web service from an external application** + Connect to the task IP address and container port using the task IP address Use the AWS CLI to get the task ID, using the `aws ecs list-tasks --cluster tutorial`. If your subnets and security group permit traffic from the public internet on the port from the task definition, you can connect to the public IP from your computer. The public IP isn't available from `describe-tasks` however, so the steps involve going to the Amazon EC2 AWS Management Console or AWS CLI to get the details of the elastic network interface. In this example, an Amazon EC2 instance in the same VPC uses the private IP of the task. The application is nginx, but the `server: envoy` header shows that the Service Connect proxy is used. The Service Connect proxy is listening on the container port from the task definition. ``` $ curl -v 10.0.19.50:80/ * Trying 10.0.19.50:80... * Connected to 10.0.19.50 (10.0.19.50) port 80 (#0) > GET / HTTP/1.1 > Host: 10.0.19.50 > User-Agent: curl/7.79.1 > Accept: */* > * Mark bundle as not supporting multiuse < HTTP/1.1 200 OK < server: envoy < date: Tue, 23 Aug 2022 03:53:06 GMT < content-type: text/html < content-length: 612 < last-modified: Tue, 16 Apr 2019 13:08:19 GMT < etag: "5cb5d3c3-264" < accept-ranges: bytes < x-envoy-upstream-service-time: 0 < Welcome to nginx!

Welcome to nginx!

If you see this page, the nginx web server is successfully installed and working. Further configuration is required.

For online documentation and support please refer to nginx.org.
Commercial support is available at nginx.com.

Thank you for using nginx.

``` **To view Service Connect metrics** The Service Connect proxy creates application (HTTP, HTTP2, gRPC, or TCP connection) metrics in CloudWatch metrics. When you use the CloudWatch console, see the additional metric dimensions of **DiscoveryName**, (**DiscoveryName, ServiceName, ClusterName**), **TargetDiscoveryName**, and (**TargetDiscoveryName, ServiceName, ClusterName**) under the Amazon ECS namespace. For more information about these metrics and the dimensions, see [View Available Metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/viewing_metrics_with_cloudwatch.html) in the Amazon CloudWatch Logs User Guide. # Use service discovery to connect Amazon ECS services with DNS names Service discovery Your Amazon ECS service can optionally be configured to use Amazon ECS service discovery. Service discovery uses AWS Cloud Map API actions to manage HTTP and DNS namespaces for your Amazon ECS services. For more information, see [What Is AWS Cloud Map](https://docs.aws.amazon.com/cloud-map/latest/dg/Welcome.html) in the *AWS Cloud Map Developer Guide*. 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 | | Africa (Cape Town) | af-south-1 | | Asia Pacific (Hong Kong) | ap-east-1 | | Asia Pacific (Taipei) | ap-east-2 | | Asia Pacific (Mumbai) | ap-south-1 | | Asia Pacific (Hyderabad) | ap-south-2 | | Asia Pacific (Tokyo) | ap-northeast-1 | | Asia Pacific (Seoul) | ap-northeast-2 | | Asia Pacific (Osaka) | ap-northeast-3 | | Asia Pacific (Singapore) | ap-southeast-1 | | Asia Pacific (Sydney) | ap-southeast-2 | | Asia Pacific (Jakarta) | ap-southeast-3 | | Asia Pacific (Melbourne) | ap-southeast-4 | | Asia Pacific (Malaysia) | ap-southeast-5 | | Asia Pacific (New Zealand) | ap-southeast-6 | | Asia Pacific (Thailand) | ap-southeast-7 | | Canada (Central) | ca-central-1 | | Canada West (Calgary) | ca-west-1 | | China (Beijing) | cn-north-1 | | China (Ningxia) | cn-northwest-1 | | Europe (Frankfurt) | eu-central-1 | | Europe (Zurich) | eu-central-2 | | Europe (Ireland) | eu-west-1 | | Europe (London) | eu-west-2 | | Europe (Paris) | eu-west-3 | | Europe (Milan) | eu-south-1 | | Europe (Stockholm) | eu-north-1 | | Israel (Tel Aviv) | il-central-1 | | Europe (Spain) | eu-south-2 | | Middle East (UAE) | me-central-1 | | Mexico (Central) | mx-central-1 | | Middle East (Bahrain) | me-south-1 | | South America (São Paulo) | sa-east-1 | | AWS GovCloud (US-East) | us-gov-east-1 | | AWS GovCloud (US-West) | us-gov-west-1 | ## Service Discovery concepts Service discovery consists of the following components: + **Service discovery namespace**: A logical group of service discovery services that share the same domain name, such as `example.com`, which is where you want to route traffic. You can create a namespace with a call to the `aws servicediscovery create-private-dns-namespace` command or in the Amazon ECS console. You can use the `aws servicediscovery list-namespaces` command to view the summary information about the namespaces that were created by the current account. For more information about the service discovery commands, see `[create-private-dns-namespace](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/create-private-dns-namespace.html)` and `[list-namespaces](https://docs.aws.amazon.com/cli/latest/reference/servicediscovery/list-namespaces.html)` in the *AWS Cloud Map (service discovery) AWS CLI Reference Guide*. + **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 registry**: Allows you to look up a service via DNS or AWS Cloud Map API actions and get back one or more available endpoints that can be used to connect to the service. + **Service discovery instance**: Exists within the service discovery service and consists of the attributes associated with each Amazon ECS service in the service directory. + **Instance attributes**: The following metadata is added as custom attributes for each Amazon ECS service that is configured to use service discovery: + **`AWS_INSTANCE_IPV4`** – For an `A` record, the IPv4 address that Route 53 returns in response to DNS queries and AWS Cloud Map returns when discovering instance details, for example, `192.0.2.44`. + **`AWS_INSTANCE_IPV6`**– For an `AAAA` record, the IPv6 address that Route 53 returns in response to DNS queries and AWS Cloud Map returns when discovering instance details, for example, ` 2001:0db8:85a3:0000:0000:abcd:0001:2345`. Both `AWS_INSTANCE_IPv4` and `AWS_INSTANCE_IPv6` are added for Amazon ECS dualstack services. Only `AWS_INSTANCE_IPv6` is added for Amazon ECS IPv6-only services. + **`AWS_INSTANCE_PORT`** – The port value associated with the service discovery service. + **`AVAILABILITY_ZONE`** – The Availability Zone into which the task was launched. For tasks using EC2, this is the Availability Zone in which the container instance exists. For tasks using Fargate, this is the Availability Zone in which the elastic network interface exists. + **`REGION`** – The Region in which the task exists. + **`ECS_SERVICE_NAME`** – The name of the Amazon ECS service to which the task belongs. + **`ECS_CLUSTER_NAME`** – The name of the Amazon ECS cluster to which the task belongs. + **`EC2_INSTANCE_ID`** – The ID of the container instance the task was placed on. This custom attribute is not added if the task is using Fargate. + **`ECS_TASK_DEFINITION_FAMILY`** – The task definition family that the task is using. + **`ECS_TASK_SET_EXTERNAL_ID`** – If a task set is created for an external deployment and is associated with a service discovery registry, then the `ECS_TASK_SET_EXTERNAL_ID` attribute will contain the external ID of the task set. + **Amazon ECS health checks**: Amazon ECS performs periodic container-level health checks. If an endpoint does not pass the health check, it is removed from DNS routing and marked as unhealthy. ## Service discovery considerations The following should be considered when using service discovery: + Service discovery is supported for tasks on Fargate that use platform version 1.1.0 or later. For more information, see [Fargate platform versions for Amazon ECS](platform-fargate.md). + Services configured to use service discovery have a limit of 1,000 tasks per service. This is due to a Route 53 service quota. + The Create Service workflow in the Amazon ECS console only supports registering services into private DNS namespaces. When an AWS Cloud Map private DNS namespace is created, a Route 53 private hosted zone will be created automatically. + The VPC DNS attributes must be configured for successful DNS resolution. For information about how to configure the attributes, see [DNS support in your VPC](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-dns.html#vpc-dns-support) in the *Amazon VPC User Guide*. + Amazon ECS does not support registering services into shared AWS Cloud Map namespaces. + 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 service task definition 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. You can additionally create `AAAA` records if the service uses dualstack subnets. If the service uses IPv6-only subnets, you can't create `A` records. + If the service task definition uses the `bridge` or `host` network mode, the SRV record is the only supported DNS record type. Create a 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: `.`. + When doing a DNS query on the service name, `A` and `AAAA` records return a set of IP addresses that correspond to your tasks. `SRV` records return a set of IP addresses and ports for each task. + If you have eight or fewer healthy records, Route 53 responds to all DNS queries with all of the healthy records. + When all records are unhealthy, Route 53 responds to DNS queries with up to eight unhealthy records. + You can configure service discovery for a service that's behind a load balancer, but service discovery traffic is always routed to the task and not the load balancer. + Service discovery doesn't support the use of Classic Load Balancers. + We recommend you use container-level health checks managed by Amazon ECS for your service discovery service. + **HealthCheckCustomConfig**—Amazon ECS manages health checks on your behalf. Amazon ECS uses information from container and health checks, and your task state, to update the health with AWS Cloud Map. This is specified using the `--health-check-custom-config` parameter when creating your service discovery service. For more information, see [HealthCheckCustomConfig](https://docs.aws.amazon.com/cloud-map/latest/api/API_HealthCheckCustomConfig.html) in the *AWS Cloud Map API Reference*. + The AWS Cloud Map resources created when service discovery is used must be cleaned up manually. + Tasks and instances are registered as `UNHEALTHY` until the container health checks return a value. If the health checks pass, the status is updated to `HEALTHY`. If the container health checks fail, the service discovery instance is deregistered. ## Service discovery pricing Customers using Amazon ECS service discovery are charged for Route 53 resources and AWS Cloud Map discovery API operations. This involves costs for creating the Route 53 hosted zones and queries to the service registry. For more information, see [AWS Cloud Map Pricing](https://docs.aws.amazon.com/cloud-map/latest/dg/cloud-map-pricing.html) in the *AWS Cloud Map Developer Guide*. Amazon ECS performs container level health checks and exposes them to AWS Cloud Map custom health check API operations. This is currently made available to customers at no extra cost. If you configure additional network health checks for publicly exposed tasks, you're charged for those health checks. # Creating an Amazon ECS service that uses Service Discovery Creating a service that uses Service Discovery Learn how to create a service containing a Fargate task that uses service discovery with the AWS CLI. For a list of AWS Regions that support service discovery, see [Use service discovery to connect Amazon ECS services with DNS names](service-discovery.md). For information about the Regions that support Fargate, see [Supported Regions for Amazon ECS on AWS Fargate](AWS_Fargate-Regions.md). **Note** You can use dual-stack service endpoints to interact with Amazon ECS from the AWS CLI, SDKs, and the Amazon ECS API over both IPv4 and IPv6. For more information, see [Using Amazon ECS dual-stack endpoints](dual-stack-endpoint.md). ## Prerequisites Before you start this tutorial, make sure that the following prerequisites are met: + The latest version of the AWS CLI is installed and configured. For more information, see [Installing or updating to the latest version of the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + The steps described in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) are complete. + Your IAM user has the required permissions specified in the [AmazonECS\$1FullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonECS_FullAccess) IAM policy example. + You have created at least one VPC and one security group. For more information, see [Create a virtual private cloud](get-set-up-for-amazon-ecs.md#create-a-vpc). ## Step 1: Create the Service Discovery resources in AWS Cloud Map Follow these steps to create your service discovery namespace and service discovery service: 1. Create a private Cloud Map service discovery namespace. This example creates a namespace that's called `tutorial`. Replace *vpc-abcd1234* with the ID of one of your existing VPCs. ``` aws servicediscovery create-private-dns-namespace \ --name tutorial \ --vpc vpc-abcd1234 ``` The output of this command is as follows. ``` { "OperationId": "h2qe3s6dxftvvt7riu6lfy2f6c3jlhf4-je6chs2e" } ``` 1. Using the `OperationId` from the output of the previous step, verify that the private namespace was created successfully. Make note of the namespace ID because you use it in subsequent commands. ``` aws servicediscovery get-operation \ --operation-id h2qe3s6dxftvvt7riu6lfy2f6c3jlhf4-je6chs2e ``` The output is as follows. ``` { "Operation": { "Id": "h2qe3s6dxftvvt7riu6lfy2f6c3jlhf4-je6chs2e", "Type": "CREATE_NAMESPACE", "Status": "SUCCESS", "CreateDate": 1519777852.502, "UpdateDate": 1519777856.086, "Targets": { "NAMESPACE": "ns-uejictsjen2i4eeg" } } } ``` 1. Using the `NAMESPACE` ID from the output of the previous step, create a service discovery service. This example creates a service named `myapplication`. Make note of the service ID and ARN because you use them in subsequent commands. ``` aws servicediscovery create-service \ --name myapplication \ --dns-config "NamespaceId="ns-uejictsjen2i4eeg",DnsRecords=[{Type="A",TTL="300"}]" \ --health-check-custom-config FailureThreshold=1 ``` The output is as follows. ``` { "Service": { "Id": "srv-utcrh6wavdkggqtk", "Arn": "arn:aws:servicediscovery:region:aws_account_id:service/srv-utcrh6wavdkggqtk", "Name": "myapplication", "DnsConfig": { "NamespaceId": "ns-uejictsjen2i4eeg", "DnsRecords": [ { "Type": "A", "TTL": 300 } ] }, "HealthCheckCustomConfig": { "FailureThreshold": 1 }, "CreatorRequestId": "e49a8797-b735-481b-a657-b74d1d6734eb" } } ``` ## Step 2: Create the Amazon ECS resources Follow these steps to create your Amazon ECS cluster, task definition, and service: 1. Create an Amazon ECS cluster. This example creates a cluster that's named `tutorial`. ``` aws ecs create-cluster \ --cluster-name tutorial ``` 1. Register a task definition that's compatible with Fargate and uses the `awsvpc` network mode. Follow these steps: 1. Create a file that's named `fargate-task.json` with the contents of the following task definition. ``` { "family": "tutorial-task-def", "networkMode": "awsvpc", "containerDefinitions": [ { "name": "sample-app", "image": "public.ecr.aws/docker/library/httpd:2.4", "portMappings": [ { "containerPort": 80, "hostPort": 80, "protocol": "tcp" } ], "essential": true, "entryPoint": [ "sh", "-c" ], "command": [ "/bin/sh -c \"echo ' Amazon ECS Sample App

Amazon ECS Sample App

Congratulations!

Your application is now running on a container in Amazon ECS.

' > /usr/local/apache2/htdocs/index.html && httpd-foreground\"" ] } ], "requiresCompatibilities": [ "FARGATE" ], "cpu": "256", "memory": "512" } ``` 1. Register the task definition using `fargate-task.json`. ``` aws ecs register-task-definition \ --cli-input-json file://fargate-task.json ``` 1. Create an ECS service by following these steps: 1. Create a file that's named `ecs-service-discovery.json` with the contents of the ECS service that you're creating. This example uses the task definition that was created in the previous step. An `awsvpcConfiguration` is required because the example task definition uses the `awsvpc` network mode. When you create the ECS service, specify Fargate and the `LATEST` platform version that supports service discovery. When the service discovery service is created in AWS Cloud Map , `registryArn` is the ARN returned. The `securityGroups` and `subnets` must belong to the VPC that's used to create the Cloud Map namespace. You can obtain the security group and subnet IDs from the Amazon VPC Console. ``` { "cluster": "tutorial", "serviceName": "ecs-service-discovery", "taskDefinition": "tutorial-task-def", "serviceRegistries": [ { "registryArn": "arn:aws:servicediscovery:region:aws_account_id:service/srv-utcrh6wavdkggqtk" } ], "launchType": "FARGATE", "platformVersion": "LATEST", "networkConfiguration": { "awsvpcConfiguration": { "assignPublicIp": "ENABLED", "securityGroups": [ "sg-abcd1234" ], "subnets": [ "subnet-abcd1234" ] } }, "desiredCount": 1 } ``` 1. Create your ECS service using `ecs-service-discovery.json`. ``` aws ecs create-service \ --cli-input-json file://ecs-service-discovery.json ``` ## Step 3: Verify Service Discovery in AWS Cloud Map You can verify that everything is created properly by querying your service discovery information. After service discovery is configured, you can either use AWS Cloud Map API operations, or call `dig` from an instance within your VPC. Follow these steps: 1. Using the service discovery service ID, list the service discovery instances. Make note of the instance ID (marked in bold) for resource cleanup. ``` aws servicediscovery list-instances \ --service-id srv-utcrh6wavdkggqtk ``` The output is as follows. ``` { "Instances": [ { "Id": "16becc26-8558-4af1-9fbd-f81be062a266", "Attributes": { "AWS_INSTANCE_IPV4": "172.31.87.2" "AWS_INSTANCE_PORT": "80", "AVAILABILITY_ZONE": "us-east-1a", "REGION": "us-east-1", "ECS_SERVICE_NAME": "ecs-service-discovery", "ECS_CLUSTER_NAME": "tutorial", "ECS_TASK_DEFINITION_FAMILY": "tutorial-task-def" } } ] } ``` 1. Use the service discovery namespace, service, and additional parameters such as ECS cluster name to query details about the service discovery instances. ``` aws servicediscovery discover-instances \ --namespace-name tutorial \ --service-name myapplication \ --query-parameters ECS_CLUSTER_NAME=tutorial ``` 1. The DNS records that are created in the Route 53 hosted zone for the service discovery service can be queried with the following AWS CLI commands: 1. Using the namespace ID, get information about the namespace, which includes the Route 53 hosted zone ID. ``` aws servicediscovery \ get-namespace --id ns-uejictsjen2i4eeg ``` The output is as follows. ``` { "Namespace": { "Id": "ns-uejictsjen2i4eeg", "Arn": "arn:aws:servicediscovery:region:aws_account_id:namespace/ns-uejictsjen2i4eeg", "Name": "tutorial", "Type": "DNS_PRIVATE", "Properties": { "DnsProperties": { "HostedZoneId": "Z35JQ4ZFDRYPLV" } }, "CreateDate": 1519777852.502, "CreatorRequestId": "9049a1d5-25e4-4115-8625-96dbda9a6093" } } ``` 1. Using the Route 53 hosted zone ID from the previous step (see the text in bold), get the resource record set for the hosted zone. ``` aws route53 list-resource-record-sets \ --hosted-zone-id Z35JQ4ZFDRYPLV ``` 1. You can also query the DNS from an instance within your VPC using `dig`. ``` dig +short myapplication.tutorial ``` ## Step 4: Clean up When you're finished with this tutorial, clean up the associated resources to avoid incurring charges for unused resources. Follow these steps: 1. Deregister the service discovery service instances using the service ID and instance ID that you noted previously. ``` aws servicediscovery deregister-instance \ --service-id srv-utcrh6wavdkggqtk \ --instance-id 16becc26-8558-4af1-9fbd-f81be062a266 ``` The output is as follows. ``` { "OperationId": "xhu73bsertlyffhm3faqi7kumsmx274n-jh0zimzv" } ``` 1. Using the `OperationId` from the output of the previous step, verify that the service discovery service instances were deregistered successfully. ``` aws servicediscovery get-operation \ --operation-id xhu73bsertlyffhm3faqi7kumsmx274n-jh0zimzv ``` ``` { "Operation": { "Id": "xhu73bsertlyffhm3faqi7kumsmx274n-jh0zimzv", "Type": "DEREGISTER_INSTANCE", "Status": "SUCCESS", "CreateDate": 1525984073.707, "UpdateDate": 1525984076.426, "Targets": { "INSTANCE": "16becc26-8558-4af1-9fbd-f81be062a266", "ROUTE_53_CHANGE_ID": "C5NSRG1J4I1FH", "SERVICE": "srv-utcrh6wavdkggqtk" } } } ``` 1. Delete the service discovery service using the service ID. ``` aws servicediscovery delete-service \ --id srv-utcrh6wavdkggqtk ``` 1. Delete the service discovery namespace using the namespace ID. ``` aws servicediscovery delete-namespace \ --id ns-uejictsjen2i4eeg ``` The output is as follows. ``` { "OperationId": "c3ncqglftesw4ibgj5baz6ktaoh6cg4t-jh0ztysj" } ``` 1. Using the `OperationId` from the output of the previous step, verify that the service discovery namespace was deleted successfully. ``` aws servicediscovery get-operation \ --operation-id c3ncqglftesw4ibgj5baz6ktaoh6cg4t-jh0ztysj ``` The output is as follows. ``` { "Operation": { "Id": "c3ncqglftesw4ibgj5baz6ktaoh6cg4t-jh0ztysj", "Type": "DELETE_NAMESPACE", "Status": "SUCCESS", "CreateDate": 1525984602.211, "UpdateDate": 1525984602.558, "Targets": { "NAMESPACE": "ns-rymlehshst7hhukh", "ROUTE_53_CHANGE_ID": "CJP2A2M86XW3O" } } } ``` 1. Update the desired count for the Amazon ECS service to `0`. You must do this to delete the service in the next step. ``` aws ecs update-service \ --cluster tutorial \ --service ecs-service-discovery \ --desired-count 0 ``` 1. Delete the Amazon ECS service. ``` aws ecs delete-service \ --cluster tutorial \ --service ecs-service-discovery ``` 1. Delete the Amazon ECS cluster. ``` aws ecs delete-cluster \ --cluster tutorial ``` # Use Amazon VPC Lattice to connect, observe, and secure your Amazon ECS services Amazon VPC Lattice Amazon VPC Lattice is a fully managed application networking service that enables Amazon ECS customers to observe, secure, and monitor applications built across AWS compute services, VPCs, and accounts—without requiring any code changes. VPC Lattice uses target groups, which are a collection of compute resources. These targets run your application or service and can be Amazon EC2 instances, IP addresses, Lambda functions, and Application Load Balancers. By associating their Amazon ECS services with a VPC Lattice target group, customers can now enable Amazon ECS tasks as IP targets in VPC Lattice. Amazon ECS automatically registers tasks to the VPC Lattice target group when tasks for the registered service are launched. **Note** When using five VPC Lattice configurations, your deployment time may be slightly longer than when using fewer configurations. A listener rule is used to forward traffic to a specified target group when the conditions are met. A listener checks for connection requests using the protocol on the port you configured. A service routes requests to it's registered targets based on the rules that you define when you configured your listener. Amazon ECS also automatically replaces a task if it becomes unhealthy according to VPC Lattice health checks. Once associated with VPC Lattice, Amazon ECS customers can also take advantage of many other cross-compute connectivity, security, and observability features in VPC Lattice like connecting to services across clusters, VPCs, and accounts with AWS Resource Access Manager, IAM integration for authorization and authentication, and advanced traffic management features. Amazon ECS customers can benefit from VPC Lattice in the following ways. + Increased developer productivity ‐ VPC Lattice boosts developer productivity by letting you focus on building features, while VPC Lattice handles networking, security and observability challenges in a uniform way across all compute platforms. + Better security posture ‐ VPC Lattice enables your developers to easily authenticate and secure communication across applications and compute platforms, enforce encryption in transit, and apply granular access controls with VPC Lattice Auth policies. This allows you to adopt a stronger security posture that meets industry leading regulatory and compliance requirements. + Improved application scalability and resilience ‐ VPC Lattice lets you create a network of deployed applications with features like path, header, and method-based routing, authentication, authorization, and monitoring. These benefits are provided with no resource overhead on workloads and can support multi-cluster deployments that generate millions of requests per second without adding significant latency. + Deployment flexibility with heterogeneous infrastructure ‐ VPC Lattice provides consistent features across all compute services like Amazon ECS, Fargate, Amazon EC2, Amazon EKS, and Lambda and allows your organization the flexibility to choose suitable infrastructure for each application. ## How VPC Lattice works with other Amazon ECS services VPC Lattice and other Amazon ECS services Using VPC Lattice with Amazon ECS may change the way you use other Amazon ECS services, while others stay the same. **Application Load Balancers** You no longer need to create a specific Application Load Balancer to use with the Application Load Balancer target group type in VPC Lattice that then links to the Amazon ECS service. You only need to configure your Amazon ECS service with a VPC Lattice target group instead. You can also still choose to use Application Load Balancer with Amazon ECS at the same time. **Amazon ECS rolling deployments** Only Amazon ECS rolling deployments work with VPC Lattice, and Amazon ECS safely brings tasks into and removes them from services during deployment. Code deploy and Blue/Green deployments aren't supported. To learn more about VPC Lattice, see the [Amazon VPC Lattice User Guide](https://docs.aws.amazon.com/vpc-lattice/latest/ug/what-is-vpc-lattice.html). # Create a service that uses VPC Lattice Create a service with Amazon VPC Lattice You can use either the AWS Management Console or the AWS CLI to create a service with VPC Lattice. ## Prerequisites Before you start this tutorial, make sure that the following prerequisites are met: + The latest version of the AWS CLI is installed and configured. For more information, see [Installing the AWS Command Line Interface](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html). **Note** You can use dual-stack service endpoints to interact with Amazon ECS from the AWS CLI, SDKs, and the Amazon ECS API over both IPv4 and IPv6. For more information, see [Using Amazon ECS dual-stack endpoints](dual-stack-endpoint.md). + The steps described in [Set up to use Amazon ECS](get-set-up-for-amazon-ecs.md) are complete. + Your IAM user has the required permissions specified in the [AmazonECS\$1FullAccess](security-iam-awsmanpol.md#security-iam-awsmanpol-AmazonECS_FullAccess) IAM policy example. ## Create a service that uses VPC Lattice with the AWS Management Console Create a service with Amazon VPC Lattice (AWS Management Console) Follow these steps to create a service with VPC Lattice using the AWS Management Console. 1. Open the console at [https://console.aws.amazon.com/ecs/v2](https://console.aws.amazon.com/ecs/v2). 1. In the navigation page, choose **Clusters**. 1. On the **Clusters** page, choose the cluster to create the service in. 1. From the **Services** tab, choose **Create**. If you've never created a service before, follow the steps found in [Creating an Amazon ECS service using the console](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/create-service-console-v2.html), then continue with these steps when you reach the VPC Lattice section. 1. Choose to **Turn on VPC Lattice** by checking the button. 1. To use an existing role, for **ECS infrastructure role for Amazon ECS**, choose one that you've already created to use when creating the VPC Lattice target group. To create a new role, **Create ECS infrastructure role**. 1. Choose the **VPC**. The **VPC** depends on the networking mode you selected when you registered your task definition. If you use the `host` or `network` mode with EC2, choose your VPC. For the `awsvpc` mode, the VPC is automatically selected based on the VPC you chose under **Networking** and can't be changed. 1. Under **Target Groups** choose the target group or groups. You need to choose at least one target group and can have a maximum of five. Choose **Add target group** to add additional target groups. Choose the **Port name**, **Protocol**, and **Port** for each target group you chose. To delete a target group, choose **Remove**. **Note** If you want to add existing target groups, you need use the AWS CLI. For instructions on how to add target groups using the AWS CLI, see [register-targets ](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/register-targets.html) in the* AWS Command Line Interface Reference*. While a VPC Lattice service can have multiple target groups, each target group can only be added to one service. To create a service in an IPv6-only configuration, choose target groups with an IP address type of `IPv6`. 1. At this point, you navigate to the VPC Lattice console to continue setting up. This is where you include your new target groups in the listener default action or in the rules of an existing VPC Lattice service. For more information, see [Listener rules for your VPC Lattice service](https://docs.aws.amazon.com/vpc-lattice/latest/ug/listener-rules.html). **Important** You need to allow the inbound rule `vpc-lattice` prefix to your security group or tasks and health checks can fail. ## Create a service that uses VPC Lattice with the AWS CLI Create a service with Amazon VPC Lattice Use the AWS CLI to create a service with VPC Lattice. Replace each *user input placeholder* with your own information. 1. Create a target group configuration file. The following example is named `tg-config.json` ``` { "ipAddressType": "IPV4", "port": 443, "protocol": "HTTPS", "protocolVersion": "HTTP1", "vpcIdentifier": "vpc-f1663d9868EXAMPLE" } ``` 1. Use the following command to create a VPC Lattice target group. ``` aws vpc-lattice create-target-group \ --name my-lattice-target-group-ip \ --type IP \ --config file://tg-config.json ``` **Note** To create a service in an IPv6-only configuration, create target groups with an IP address type of `IPv6`. For more information, see [create-target-group](https://docs.aws.amazon.com/cli/latest/reference/vpc-lattice/create-target-group.html) in the *AWS CLI Command Reference*. Example output: ``` { "arn": "arn:aws:vpc-lattice:us-east-2:123456789012:targetgroup/tg-0eaa4b9ab4EXAMPLE", "config": { "healthCheck": { "enabled": true, "healthCheckIntervalSeconds": 30, "healthCheckTimeoutSeconds": 5, "healthyThresholdCount": 5, "matcher": { "httpCode": "200" }, "path": "/", "protocol": "HTTPS", "protocolVersion": "HTTP1", "unhealthyThresholdCount": 2 }, "ipAddressType": "IPV4", "port": 443, "protocol": "HTTPS", "protocolVersion": "HTTP1", "vpcIdentifier": "vpc-f1663d9868EXAMPLE" }, "id": "tg-0eaa4b9ab4EXAMPLE", "name": "my-lattice-target-group-ip", "status": "CREATE_IN_PROGRESS", "type": "IP" } ``` 1. The following JSON file named *ecs-service-vpc-lattice.json* is an example used to attach an Amazon ECS service to a VPC Lattice target group. The `portName` in the example below is the same one you defined in your task definition's `portMappings` property's `name` field. ``` { "serviceName": "ecs-service-vpc-lattice", "taskDefinition": "ecs-task-def", "vpcLatticeConfigurations": [ { "targetGroupArn": "arn:aws:vpc-lattice:us-west-2:123456789012:targetgroup/tg-0eaa4b9ab4EXAMPLE", "portName": "testvpclattice", "roleArn": "arn:aws:iam::123456789012:role/ecsInfrastructureRoleVpcLattice" } ], "desiredCount": 5, "role": "ecsServiceRole" } ``` Use the following command to create an Amazon ECS service and attach it to the VPC Lattice target group using the json example above. ``` aws ecs create-service \ --cluster clusterName \ --serviceName ecs-service-vpc-lattice \ --cli-input-json file://ecs-service-vpc-lattice.json ``` **Note** VPC Lattice isn't supported on Amazon ECS Anywhere.