Mac에서 AWS ECS, EKS, Fargate, Lambda용 로컬 개발

각 구성 요소의 실행 위치

ECS와 Fargate 작업을 Compose 프로젝트로 실행

ECS 작업 정의는 이미지, 환경, 포트 매핑, 상태 확인, 시작 순서를 지정한 컨테이너 목록입니다. Compose도 같은 내용을 정의하므로 컨테이너 정의 하나를 서비스 하나로 직접 대응시킬 수 있습니다.

services:
  api:
    image: ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0
    platform: linux/amd64          # match the task's cpuArchitecture
    environment:
      DATABASE_URL: postgres://postgres:dev@db:5432/app
    ports: ["8080:8080"]
    depends_on:
      db:
        condition: service_healthy
  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_PASSWORD: dev
      POSTGRES_DB: app
    healthcheck:
      test: ["CMD", "pg_isready", "-U", "postgres"]
      interval: 2s
      retries: 30

docker compose up -d --wait     # returns when db is healthy and api has started
curl localhost:8080/health
docker compose down -v

Oxcart에서 Postgres 17과 service_healthy 조건을 기다리는 nginx 서비스로 이 방식을 검증했습니다. up --wait가 반환되었을 때 두 서비스 모두 정상 상태였고 게시된 포트가 localhost에서 응답했습니다. Mac에서 빌드한 amd64 이미지는 실행할 때도 같은 플랫폼을 전달하세요. 로컬에서 빌드한 amd64 전용 이미지는 --platform linux/amd64(Compose에서는 platform:)를 설정해야만 검색됩니다.

Lambda 컨테이너 이미지를 로컬에서 실행하고 호출

1. 핸들러를 작성하세요. app.py를 만들고 {"statusCode": 200, "body": "hello"} 같은 딕셔너리를 반환하는 handler(event, context) 함수를 작성하세요.
2. Dockerfile을 작성하세요. Runtime Interface Emulator를 포함하는 AWS Lambda 기본 이미지로 시작합니다. FROM public.ecr.aws/lambda/python:3.13 다음에 COPY app.py ${LAMBDA_TASK_ROOT}/와 CMD ["app.handler"]를 추가하세요.
3. 이미지를 빌드하세요. docker build -t my-lambda .를 실행합니다. 함수가 x86_64로 설정되어 있다면 --platform linux/amd64를 추가하세요.
4. 실행하세요. docker run -d -p 9000:8080 my-lambda를 실행합니다. 에뮬레이터는 컨테이너 내부의 포트 8080에서 수신합니다.
5. 호출하세요. curl -XPOST localhost:9000/2015-03-31/functions/function/invocations -d '{}'를 실행합니다. 응답은 핸들러의 반환값이며, docker logs에 실행 시간이 포함된 Lambda REPORT 줄이 표시됩니다.

실행 결과 함수가 {"statusCode": 200, "body": "hello from lambda on aarch64"}를 반환했으며, 컨테이너 로그의 Lambda REPORT 줄에 19 ms가 표시되었습니다. 이 에뮬레이터는 AWS가 제공하는 'Lambda Runtime 및 Extensions API의 프록시'로, /2015-03-31/functions/function/invocations 엔드포인트를 제공합니다.

LocalStack으로 AWS API 사용

LocalStack은 포트 4566의 단일 컨테이너에서 AWS API를 에뮬레이션합니다. Oxcart에서 4.9 이미지를 실행하고 S3를 처음부터 끝까지 검증했습니다.

docker run -d --name localstack -p 4566:4566 localstack/localstack:4.9
curl -s localhost:4566/_localstack/health          # s3, lambda, dynamodb… "available"
curl -X PUT localhost:4566/my-bucket               # create a bucket
curl -X PUT --data-binary hello localhost:4566/my-bucket/hello.txt
curl localhost:4566/my-bucket/hello.txt            # hello

기반으로 사용하기 전에 라이선스 조건을 확인하세요. 2026년 3월 23일부터 최신 LocalStack 릴리스는 LocalStack 계정과 인증 토큰이 필요합니다. LOCALSTACK_AUTH_TOKEN이 없으면 최신 이미지는 "License activation failed"로 종료됩니다. 무료 Hobby 요금제는 비상업적 사용용이며, ECS는 Base 요금제부터, EKS는 Ultimate 요금제부터 제공됩니다.

ECR로 푸시하고 배포

aws ecr get-login-password --region us-east-1 \
  | docker login --username AWS --password-stdin ACCOUNT.dkr.ecr.us-east-1.amazonaws.com
docker buildx build --platform linux/amd64 --load -t ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0 .
docker push ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/api:1.4.0

Oxcart는 레지스트리 암호를 ~/.docker/config.json이 아닌 macOS 키체인에 보관합니다. Oxcart에서 다중 플랫폼 이미지를 푸시하는 기능은 지원되지 않습니다. 아키텍처별 태그를 푸시하거나 CI에서 다중 아키텍처 매니페스트를 게시하세요.

Mac에서 EKS 사용

aws eks update-kubeconfig --name my-cluster로 클러스터를 kubeconfig에 추가하면 macOS에서 kubectl과 k9s를 사용할 수 있습니다. Oxcart로 서비스를 로컬에서 개발하고 테스트한 뒤 같은 이미지를 EKS에 배포하세요. 로컬 매니페스트 및 컨트롤러 테스트에는 kwok이 실제 Kubernetes API 서버와 시뮬레이션된 노드를 제공합니다. 워크플로를 함께 활용하는 방법은 Mac의 Kubernetes 가이드에서 설명합니다.

로컬 반복 작업의 가치

변경 사항을 로컬에서 테스트할 때마다 푸시, 배포, 로그 검색을 생략할 수 있습니다. Oxcart는 이 반복을 짧게 만듭니다. docker run --rm은 42 ms, 컨테이너 20개 생성 및 시작은 0.69 s, 중지 및 삭제는 77 ms로 테스트한 세 런타임 중 가장 빨랐습니다. 컨테이너의 아웃바운드 연결은 Mac에서 열기 때문에 AWS 네트워크로 향하는 VPN도 적용됩니다.

자주 묻는 질문

Mac에서 ECS 또는 Fargate 작업을 어떻게 로컬 테스트하나요?

Docker Compose로 작업의 컨테이너를 실행하세요. 컨테이너 정의마다 서비스 하나를 만들고 같은 이미지, 환경, 포트 매핑, 상태 확인, 종속성을 사용합니다. docker compose up -d --wait는 상태 확인이 설정된 모든 서비스가 정상 상태가 되면 반환됩니다. Oxcart는 상태 확인 종속성과 게시된 포트를 갖춘 스택을 실행하므로 배포 전에 서비스를 함께 검증할 수 있습니다.

Apple Silicon에서 AWS Lambda 컨테이너 이미지를 로컬로 실행할 수 있나요?

네. AWS Lambda 기본 이미지는 Runtime Interface Emulator를 포함합니다. Oxcart에서 public.ecr.aws/lambda/python:3.13을 기반으로 Python 3.13 함수를 빌드하고, -p 9000:8080으로 실행한 뒤 curl로 호출했습니다. arm64에서 네이티브로 실행되어 HTTP 200을 반환했습니다.

LocalStack은 Oxcart에서 작동하나요?

네, 컨테이너로 실행됩니다. LocalStack 4.9 이미지로 localhost:4566에서 S3 버킷 생성, put, get, list를 검증했습니다. 현재 LocalStack 릴리스는 계정과 인증 토큰이 필요하며 LOCALSTACK_AUTH_TOKEN으로 설정합니다. 없으면 최신 이미지는 종료됩니다. LocalStack 문서에 따르면 ECS는 Base 요금제부터, EKS는 Ultimate 요금제부터 제공됩니다.

Mac에서 Amazon ECR로 이미지를 어떻게 푸시하나요?

aws ecr get-login-password --region REGION | docker login --username AWS --password-stdin ACCOUNT.dkr.ecr.REGION.amazonaws.com으로 로그인한 뒤 태그를 붙이고 docker push하세요. Oxcart에서 docker login은 암호를 macOS 키체인에 저장합니다.

Fargate용으로 amd64와 arm64 중 어떤 이미지를 빌드해야 하나요?

작업 정의의 런타임 플랫폼에 맞추세요. ARM64라면 Mac에서 네이티브 arm64 이미지를 빌드하고, X86_64라면 --platform linux/amd64로 빌드하세요. Oxcart는 amd64 이미지를 로컬에서 Rosetta로 실행하므로 배포할 이미지와 정확히 같은 이미지를 테스트할 수 있습니다.

Mac에서 EKS용으로 어떻게 개발하나요?

Oxcart로 앱과 종속성을 로컬에서 빌드하고 테스트한 뒤 ECR에 이미지를 푸시하세요. Mac에서 kubectl과 k9s로 EKS 클러스터를 사용하고, Oxcart의 kwok으로 로컬 Kubernetes API에서 매니페스트를 확인하세요. Mac의 Kubernetes 가이드를 확인하세요.

출처와 측정 방법

• 예제는 2026-10-10에 Oxcart 0.1.2, Mac17,14, macOS 27.2에서 테스트했습니다(Compose, 에뮬레이터가 포함된 Lambda 기본 이미지, LocalStack 4.9 S3, Buildx).
• LocalStack 인증: https://blog.localstack.cloud/localstack-single-image-next-steps/; 요금제: https://localstack.cloud/pricing/; ECS: https://docs.localstack.cloud/aws/services/ecs/; EKS: https://docs.localstack.cloud/aws/services/eks/.
• Lambda Runtime Interface Emulator: https://github.com/aws/aws-lambda-runtime-interface-emulator. AWS SAM CLI 및 Docker: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-docker.html. ECS Local Container Endpoints: https://github.com/awslabs/amazon-ecs-local-container-endpoints. 2026-10-10 확인.
• 컨테이너 속도: Oxcart 0.1.2, 2026-10-10, Apple M5 Max, CPU 8개 및 12 GiB, 5회 표본의 중앙값. 다른 런타임은 같은 날 앞서 동일한 Mac과 테스트 하네스에서 docker 29.4 클라이언트로 측정했습니다.