Envoy image - AWS App Mesh

Envoy image

AWS App Mesh is a service mesh based on the Envoy proxy.

You must add an Envoy proxy to the Amazon ECS task, Kubernetes pod, or Amazon EC2 instance represented by your App Mesh endpoint, such as a virtual node or virtual gateway. App Mesh vends an Envoy proxy Docker container image and validate that this container image is patched with the latest vulnerability and performance patches. App Mesh tests a new Envoy proxy release against the App Mesh feature set before making a new container image available to you.

You can choose either a Regional image from the list below or an image from our public repository named aws-appmesh-envoy.

  • Starting from June 30, 2023, only envoy image v1.17.2.0-prod or later is compatible for use with App Mesh. For current customers using Envoy image before v1.17.2.0, although existing envoys will continue to be compatible, we strongly recommend migrating to the latest version.

  • As a best practice, upgrading the Envoy version to the latest version on a regular basis is highly recommended. Only the latest envoy version is officially supported with security patches, feature release, performance improvements, etc.

  • Version 1.17 was a significant update to Envoy. See Updating/migrating to Envoy 1.17 for more details.

  • Version or later is ARM64 compatible.

  • For IPv6 support, Envoy version 1.20 or later is required.

  • All supported Regions other than me-south-1, ap-east-1, ap-southeast-3, eu-south-1, il-central-1, and af-south-1. You can replace Region-code with any Region other than me-south-1, ap-east-1, ap-southeast-3, eu-south-1, il-central-1, and af-south-1.

  • me-south-1 Region:

  • ap-east-1 Region:

  • ap-southeast-3 Region:

  • eu-south-1 Region:

  • il-central-1 Region:

  • af-south-1 Region:

  • Public repository


We recommend allocating 512 CPU units and at least 64 MiB of memory to the Envoy container. On Fargate the lowest amount of memory that you can set is 1024 MiB of memory. Resource allocation to the Envoy container can be increased if container insights or other metrics indicate insufficient resources due to higher load.


All aws-appmesh-envoy image release versions starting from v1.22.0.0 are built as a distroless Docker image. We made this change so that we could reduce the image size and reduce our vulnerability exposure in unused packages present in the image. If you are building on top of aws-appmesh-envoy image and are relying on some of the AL2 base packages (e.g. yum) and functionalities, then we suggest you copy the binaries from inside an aws-appmesh-envoy image to build a new Docker image with AL2 base.

Run this script to generate a custom docker image with the tag aws-appmesh-envoy:v1.22.0.0-prod-al2:

cat << EOF > Dockerfile FROM public.ecr.aws/appmesh/aws-appmesh-envoy:v1.22.0.0-prod as envoy FROM public.ecr.aws/amazonlinux/amazonlinux:2 RUN yum -y update && \ yum clean all && \ rm -rf /var/cache/yum COPY --from=envoy /usr/bin/envoy /usr/bin/envoy COPY --from=envoy /usr/bin/agent /usr/bin/agent COPY --from=envoy /aws_appmesh_aggregate_stats.wasm /aws_appmesh_aggregate_stats.wasm CMD [ "/usr/bin/agent" ] EOF docker build -f Dockerfile -t aws-appmesh-envoy:v1.22.0.0-prod-al2 .

Access to this container image in Amazon ECR is controlled by AWS Identity and Access Management (IAM). As a result, you must use IAM to verify that you have read access to Amazon ECR. For example, when using Amazon ECS, you can assign an appropriate task execution role to an Amazon ECS task. If you use IAM policies that limit access to specific Amazon ECR resources, make sure to verify that you allow access to the Region specific Amazon Resource Name (ARN) that identifies the aws-appmesh-envoy repository. For example, in the us-west-2 Region, you allow access to the following resource: arn:aws:ecr:us-west-2:840364872350:repository/aws-appmesh-envoy. For more information, see Amazon ECR Managed Policies. If you're using Docker on an Amazon EC2 instance, then authenticate Docker to the repository. For more information, see Registry authentication.

We occasionally release new App Mesh features that depend on Envoy changes that have not been merged to the upstream Envoy images yet. To use these new App Mesh features before the Envoy changes are merged upstream, you must use the App Mesh-vended Envoy container image. For a list of changes, see the App Mesh GitHub roadmap issues with the Envoy Upstream label. We recommend that you use the App Mesh Envoy container image as the best supported option.