As we are not allowed to specify platform flag for DockerImageAsset, users deploying cdk on x86_64 platform will not be able to bundle lambda.DockerImageFunction for the new arm64 architecture. Similarly, users deploying cdk on arm64 architecture like Mac M1 will not be able to bundle images for AWS Fargate, which is x86_64 only.

With this support, we are allowed to:

• bundle image assets for a specific architecture with the new platform property of DockerImageAsset from aws-ecr-assets.
• bundle arm64 DockerImageFunction from aws-lambda on x86_64.
• bundle x86_64 container images for AWS Fargate from aws-ecs on arm64.

Fixes: #12472

Background

When we bundle and publish the docker container image assets with cdk deploy, it's important we must build images of correct architectures for different services. For AWS Fargate, as it only supports x86_64 at this moment, we must build x86_64(amd64) architecture docker images, while for Lambda Graviton2, the arm64 would be required.

Architecture of the images

Run docker inspect to check the Architecture for local images:

For example:

docker inspect 6aab191c10a7 | grep "Arch"    
        "Architecture": "arm64",

(The image was built for arm64 platform)

How to build images with correct Architecture?

Many docker image registries come with multi-architecture support. Read Introducing multi-architecture container images for Amazon ECR for more details on Amazon ECR. Let's take public.ecr.aws/lambda/python:latest for example. Run docker manifest inspect to check its manifest for architectures:

docker manifest inspect public.ecr.aws/lambda/python:latest                                                                                                                               
{
   "schemaVersion": 2,
   "mediaType": "application/vnd.docker.distribution.manifest.list.v2+json",
   "manifests": [
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 1580,
         "digest": "sha256:fc52f9b4ca941653c109fca35078fb3d589283f61e37ab88bed05101c607de7a",
         "platform": {
            "architecture": "arm64",
            "os": "linux",
            "variant": "v8"
         }
      },
      {
         "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
         "size": 1580,
         "digest": "sha256:68ffef9d11b6de8675b657ecfb5eadf152150c720e627fb9b5ea0c69ef6ac8d0",
         "platform": {
            "architecture": "amd64",
            "os": "linux"
         }
      }
   ]
}

This image supports both linux/arm64 and linux/amd64 from the manifest.

Similarly, if we check python:3.9 from docker hub, we can list all platforms/architectures supported from its manifest data.

docker manifest inspect python:3.9

So how can we ensure to build correct architecture from different desktops like Apple Mac M1 or any x86_64 desktops? Let's take the following Dockerfile for example:

FROM public.ecr.aws/lambda/python:latest

For Apple Mac M1 users, if we docker build with this Dockerfile, under the covers the image layers for arm64 will be pulled because the Apple Mac M1 is arm64 architecture unless:

1. we specify the DOCKER_DEFAULT_PLATFORM env var(see (assets): allow user to pass platform option to Docker builds #12472 (comment))
2. Specify the --platform in the Dockerfile like

FROM --platform=linux/amd64 someBaseImage:someVersion

3. docker build with --platform flag

Let's take M1 for example, if we docker build without passing --platform, we'll build an arm64 image.

However, if we pass --platform='linux/amd64' we'll be able to build amd64 image from exactly the same Dockerfile.

Similarly, for x86_64 desktop users, we'll build amd64 images by default and arm64 images by passing --platform='linux/arm64'.

When we bundle container image assets for AWS Fargate, we must build amd64 images. For Lambda arm64 architecture, we must build arm64 images for Lambda container runtime, no matter which platform you synthesize and deploy the assets. The key is always to pass correct --platform flag with Dockerfile from a base image with multiple-platform support.

However, what if we use python:latest-arm64 as the base image for our Dockerfile? Well, we will lose the advantages of multi-architecture support as this will only build arm64 images.

builder experience with aws-ecr-assets

Specify platform with ARM_64 or AMD_64 from docker image assets with multi-architecture docker base images

import * as assets from '@aws-cdk/aws-ecr-assets';

new assets.DockerImageAsset(stack, 'DockerImage', {
  directory: path.join(__dirname, 'demo-image'),
  platform: DockerPlatform.ARM_64,
});

builder experience with aws-ecs

For Mac M1 users deploying Amazon ECS services on AWS Fargate from local container image assets with multi-architecture docker base images. Specify the platform to ensure the image would be built for AMD_64 architecture.

taskDefinition.addContainer('web', {
  image: ecs.ContainerImage.fromAsset(path.join(__dirname, '../demo-image'), {
    platform: DockerPlatform.AMD_64,
  }),
  portMappings: [{
    containerPort: 8000,
  }],
});

builder experience with aws-lambda

For x86_64 users deploying Lambda functions with container runtime on Lambda Graviton2(arm64) from local container image assets with multi-architecture docker base images. Specify the platform to ensure the image would be built for ARM64 architecture.

new DockerImageFunction(this, 'MyLambda', {
  code: DockerImageCode.fromImageAsset(path.join(__dirname, 'docker-arm64-handler'), {
    platform: DockerPlatform.ARM_64,
  }),
  architectures: [Architecture.ARM_64],
});

builder experience with aws-apprunner

AWS App Runner supports x86_64 architecture only at this moment. For Mac M1 users, use platform to ensure the AMD_64 architecture for the DockerImageAsset.

import * as assets from '@aws-cdk/aws-ecr-assets';
import { Service } from '@aws-cdk/aws-apprunner';

const imageAsset = new assets.DockerImageAsset(stack, 'ImageAssets', {
  directory: path.join(__dirname, './docker.assets'),
  platform: DockerPlatform.AMD_64,
});

new Service(stack, 'Service', {
  source: Source.fromAsset({
    imageConfiguration: { port: 8000 },
    asset: imageAsset,
  }),
});

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license