Amazon ECS 배포 도구 ecspresso에 대해 알아보기

안녕하세요 클래스메소드의 이수재입니다.

Amazon ECS를 운영하다 보면 새로운 컨테이너 이미지를 배포하기 위해 태스크 정의를 등록하고 서비스를 업데이트해야 하는 경우가 많습니다.

AWS 콘솔에서 직접 작업할 수도 있고 AWS CLI로 배포 스크립트를 만들 수도 있지만, 서비스가 늘어나면 현재 설정을 관리하거나 배포 상태를 확인하는 작업도 점점 복잡해집니다.

이런 상황에서 검토해볼 수 있는 도구가 ecspresso입니다. 이번 글에서는 ecspresso가 어떤 도구인지, 주요 기능과 다른 관리 방법의 차이에 대해 알아보겠습니다.

ecspresso?

ecspresso는 KAYAC에서 공개한 Amazon ECS 배포 도구입니다.

이름은 espresso와 동일하게 발음합니다. AWS에서 제공하는 관리형 서비스가 아니라 로컬 환경이나 CI/CD 파이프라인에서 실행하는 오픈소스 CLI입니다.

쉽게 이해하면 ECS 서비스와 태스크 정의를 파일로 관리하고, 배포에 필요한 여러 작업을 하나의 명령으로 실행할 수 있게 해주는 도구입니다.

ecspresso에서는 일반적으로 다음 세 가지 파일을 사용합니다.

서비스와 태스크 정의는 JSON, YAML 또는 Jsonnet으로 관리할 수 있으며, 환경 변수와 Terraform state, CloudFormation Output 등을 템플릿에서 참조하는 것도 가능합니다.

주요 기능

기존 ECS 서비스를 가져올 수 있습니다

ecspresso는 새로운 ECS 환경을 만드는 것보다 이미 실행 중인 서비스를 관리하는 데 편리합니다.

ecspresso init을 실행하면 현재 ECS 서비스와 태스크 정의를 읽어 로컬에 설정 파일을 생성합니다.

ecspresso init \
  --region <region> \
  --cluster <cluster-name> \
  --service <service-name> \
  --config ecspresso.yml

콘솔이나 다른 도구로 만든 ECS 서비스를 코드 관리로 옮기고 싶을 때 비교적 쉽게 시작할 수 있습니다.

자동으로 생성된 파일은 그대로 사용하기보다 불필요한 속성이 없는지, 계정 ID나 비밀 정보처럼 저장소에 포함하면 안 되는 값이 없는지 확인하는 것을 권장합니다.

배포 전에 차이를 확인할 수 있습니다

diff 명령은 로컬에 작성한 서비스·태스크 정의와 현재 ECS에서 실행 중인 설정의 차이를 보여줍니다.

verify 명령으로 설정에서 참조하는 AWS 리소스와 정의를 확인하는 것도 가능합니다.

# ECS 서비스를 변경하지 않고 설정을 확인합니다.
ecspresso diff --config ecspresso.yml
ecspresso verify --config ecspresso.yml

두 명령을 CI/CD의 배포 전 단계에서 실행하면 실제 배포 전에 어떤 내용이 바뀌는지 확인하기 쉽습니다.

배포와 롤백을 하나의 도구에서 처리할 수 있습니다

ecspresso deploy를 실행하면 새로운 태스크 정의를 등록하고 ECS 서비스를 업데이트한 후, 서비스가 안정적인 상태가 될 때까지 기다립니다.

기본적으로 롤링 업데이트를 사용하며 ECS 네이티브 또는 CodeDeploy를 이용한 Blue/Green 배포도 지원합니다.

# 이 명령은 새로운 태스크 정의를 등록하고 ECS 서비스를 실제로 변경합니다.
ecspresso deploy --config ecspresso.yml

배포에 문제가 생겼을 때는 ecspresso rollback으로 이전 태스크 정의 리비전을 다시 적용할 수 있습니다.

이 외에도 서비스 상태 확인, 태스크 목록 조회, 단발성 태스크 실행, 스케일 변경과 ECS Exec 등의 기능을 제공하고 있습니다.

이미지 태그를 템플릿으로 관리하기

ecspresso의 템플릿 기능을 이용하면 CI/CD에서 전달한 이미지 태그를 태스크 정의에 반영할 수 있습니다.

예를 들어 태스크 정의의 이미지 항목을 다음과 같이 작성합니다.

{
  "containerDefinitions": [
    {
      "name": "app",
      "image": "<account-id>.dkr.ecr.ap-northeast-1.amazonaws.com/app:{{ must_env `IMAGE_TAG` }}"
    }
  ]
}

배포할 때는 CI/CD에서 이미지 태그를 환경 변수로 전달합니다.

export IMAGE_TAG=<immutable-image-tag>
ecspresso deploy --config ecspresso.yml

must_env를 사용하면 IMAGE_TAG가 설정되지 않았을 때 실행이 중단됩니다. 값이 비어 있거나 의도하지 않은 기본 태그로 배포되는 것을 방지할 때 유용합니다.

개인적으로는 latest처럼 반복해서 사용하는 태그보다 커밋 SHA처럼 배포한 이미지를 구분할 수 있는 태그를 사용하는 것을 권장합니다. 어떤 이미지가 배포되었는지 확인하거나 이전 버전으로 되돌릴 때도 이해하기 쉽습니다.

다른 방법과 무엇이 다른가?

ECS를 배포하는 방법은 ecspresso 이외에도 AWS CLI, Terraform, CloudFormation 등이 있습니다.

가장 큰 차이는 관리하는 범위입니다.

AWS CLI를 사용하면 register-task-definition, update-service 같은 명령으로 필요한 작업을 직접 구성할 수 있습니다. 자유도가 높은 대신 배포 상태 확인과 실패 처리 등의 흐름도 직접 만들어야 합니다.

Terraform과 CloudFormation은 ECS뿐만 아니라 주변 AWS 리소스까지 하나의 IaC 구성으로 관리할 수 있습니다. 인프라 전체의 생성과 변경, 삭제를 관리하는 것이 목적이라면 이쪽이 더 적합합니다.

ecspresso는 VPC나 IAM 같은 전체 인프라보다 ECS 서비스와 태스크 정의의 배포에 중점을 둡니다. 이미 인프라는 별도로 관리하고 있고 애플리케이션 배포만 단순하게 만들고 싶다면 검토하기 좋은 도구라고 생각합니다.

비슷한 역할의 도구로 AWS Copilot CLI도 있었지만, 2026년 6월 12일 지원이 종료되었고 공식 저장소도 읽기 전용으로 전환되었습니다. 새롭게 도입할 도구를 비교한다면 현재는 같은 선택지로 보기 어렵고, 기존 Copilot 환경을 운영 중인 경우 마이그레이션 관점에서 확인하는 것이 좋습니다.

Terraform과 같이 사용한다면?

ecspresso는 Terraform state의 값이나 CloudFormation Output을 템플릿에서 참조할 수 있습니다. 따라서 다음처럼 역할을 나누어 사용하는 것도 가능합니다.

• Terraform 또는 CloudFormation: VPC, 서브넷, 보안 그룹, ECS 클러스터, IAM 역할과 로드 밸런서
• ecspresso: ECS 서비스, 태스크 정의와 애플리케이션 배포

다만 Terraform과 ecspresso가 같은 ECS 서비스 설정을 동시에 관리하면 주의가 필요합니다.

예를 들어 ecspresso가 새로운 태스크 정의를 배포한 후 Terraform에서도 task_definition 값을 관리하고 있다면, 다음 terraform plan에서 이 변경을 드리프트로 인식할 수 있습니다.

두 도구를 같이 사용할 때는 어떤 리소스와 속성을 어느 쪽에서 관리할지 먼저 정하고, 실제 배포 후 terraform plan 결과도 확인하는 것을 권장합니다.

고려할 점

ecspresso를 도입하기 전에 다음 내용은 확인할 필요가 있습니다.

• VPC, ECS 클러스터, IAM 역할 같은 전체 인프라를 구성하는 도구는 아닙니다.
• CodeDeploy 방식의 Blue/Green 배포를 사용할 경우 CodeDeploy 애플리케이션과 배포 그룹은 별도로 준비해야 합니다.
• rollback은 이전 태스크 정의를 다시 적용하는 기능입니다. 데이터베이스 스키마나 외부 API, 메시지 형식의 변경까지 되돌리지는 않습니다.
• Terraform이나 CloudFormation과 함께 사용한다면 동일한 ECS 설정을 중복해서 관리하지 않는지 확인해야 합니다.

특히 데이터베이스 마이그레이션이 포함된 배포라면 애플리케이션 롤백과 데이터 롤백을 별도로 생각해야 합니다. ecspresso의 롤백만으로 전체 서비스가 이전 상태로 돌아간다고 생각하면 안 됩니다.

실제로 사용해보기

마지막으로 이미 실행 중인 ECS 서비스를 ecspresso로 가져오고, 컨테이너 이미지 태그를 변경해 배포해보겠습니다.

이번 테스트에서는 ecspresso v2.8.5를 사용했습니다. ECS 클러스터와 서비스는 미리 생성해두었으며, AWS 인증도 완료된 환경에서 진행했습니다.

기존 ECS 서비스 가져오기

변경 전 ECS 콘솔에서는 서비스가 태스크 정의의 첫 번째 리비전을 사용하고 있는 것을 확인했습니다.

다음으로 init을 실행해 현재 ECS 서비스 설정을 로컬 파일로 가져옵니다. --config에는 생성할 ecspresso 설정 파일의 경로를 지정합니다.

ecspresso init \
  --region "$TASK_REGION" \
  --cluster "$CLUSTER_NAME" \
  --service "$SERVICE_NAME" \
  --config ecspresso.yml

실행 결과 서비스 정의, 태스크 정의와 ecspresso 설정 파일이 생성되었습니다.

[INFO] saving service definition [path:ecs-service-def.json]
[INFO] saving task definition [path:ecs-task-def.json]
[INFO] saving config [path:ecspresso.yml]

ecs-service-def.json
ecs-task-def.json
ecspresso.yml

ecspresso.yml에는 대상 리전, 클러스터와 서비스 이름, 두 정의 파일의 경로가 저장됩니다. 실제 컨테이너 이미지와 태스크 설정은 ecs-task-def.json, 네트워크와 배포 설정은 ecs-service-def.json에서 관리합니다.

이미지 태그 변경하기

이번에는 동작을 크게 바꾸지 않으면서 배포 과정을 확인할 수 있도록 Apache HTTP Server 이미지의 태그를 2.4에서 구체적인 패치 버전인 2.4.68로 변경했습니다.

-      "image": "public.ecr.aws/docker/library/httpd:2.4"
+      "image": "public.ecr.aws/docker/library/httpd:2.4.68"

먼저 diff로 현재 ECS에 등록된 태스크 정의와 로컬 파일의 차이를 확인합니다.

ecspresso diff \
  --config ecspresso.yml

이어서 정의와 참조하는 AWS 리소스를 확인하고, 실제 변경 없이 배포 과정을 확인했습니다.

ecspresso verify \
  --config ecspresso.yml

2026-09-02T15:33:42.134+09:00 [INFO] ecspresso version [version:v2.8.5]
...
2026-09-02T15:33:44.401+09:00 [INFO] [ecstest-service/ecstest-cluster] Verify OK!

ecspresso deploy \
  --config ecspresso.yml \
  --dry-run

2026-09-02T15:34:03.818+09:00 [INFO] ecspresso version [version:v2.8.5]
2026-09-02T15:34:03.848+09:00 [INFO] [ecstest-service/ecstest-cluster] Starting deploy [dry_run:true]
...
2026-09-02T15:34:04.449+09:00 [INFO] [ecstest-service/ecstest-cluster] DRY RUN OK

diff, verify와 deploy --dry-run까지는 ECS 서비스를 변경하지 않습니다. 결과에 문제가 없는 것을 확인한 후 실제 배포를 실행합니다.

# 이 명령은 새로운 태스크 정의를 등록하고 ECS 서비스를 실제로 변경합니다.
ecspresso deploy \
  --config ecspresso.yml

배포가 시작되면 ecspresso가 새로운 태스크 정의 리비전을 등록하고 ECS 서비스를 업데이트합니다. 이후 새로운 태스크가 실행되고 서비스가 안정적인 상태가 될 때까지 기다립니다.

배포가 완료된 뒤 ECS 콘솔을 확인해보면 서비스가 새로운 태스크 정의 리비전을 사용하고, 실행 중인 태스크도 교체된 것을 확인할 수 있습니다.

직접 사용해보니 기존 ECS 서비스를 파일로 가져오고, 변경점을 확인한 뒤 배포하는 흐름을 몇 개의 명령으로 진행할 수 있었습니다. 특히 실제 배포 전에 diff와 dry-run으로 변경 내용을 확인할 수 있다는 점이 이해하기 쉬웠습니다.

이전 리비전으로 롤백하기

필요하다면 rollback을 실행해 ECS 서비스를 이전 태스크 정의 리비전으로 되돌릴 수 있습니다.

# 이 명령은 ECS 서비스가 사용하는 태스크 정의를 실제로 변경합니다.
ecspresso rollback \
  --config ecspresso.yml

rollback은 로컬의 설정파일을 변경하지 않는다

rollback은 ECS 서비스가 사용하는 태스크 정의를 이전 리비전으로 변경하지만, 로컬의 ecs-task-def.json까지 되돌리지는 않습니다. 그대로 두면 다음 diff에서 차이가 표시되고, 다시 deploy할 때 변경한 이미지가 적용될 수 있습니다.

이번 테스트에서는 변경 전 이미지 태그를 알고 있으므로 로컬 파일도 원래 값으로 되돌렸습니다.

-      "image": "public.ecr.aws/docker/library/httpd:2.4.68"
+      "image": "public.ecr.aws/docker/library/httpd:2.4"

마지막으로 diff를 실행해 롤백한 ECS 서비스와 로컬 정의가 일치하는지 확인합니다.

ecspresso diff \
  --config ecspresso.yml

변경 전 파일을 별도로 보관하지 않았고 원래 값을 알 수 없다면, 롤백 후 init을 다른 디렉터리에서 다시 실행해 현재 ECS 설정을 가져온 뒤 기존 파일과 비교하는 방법도 있습니다. 같은 위치에서 파일을 바로 덮어쓰면 템플릿이나 로컬 수정 사항도 사라질 수 있으므로 먼저 비교하는 것을 권장합니다.

직접 사용해보니 기존 ECS 서비스를 파일로 가져오고, 변경점을 확인한 뒤 배포하는 흐름을 몇 개의 명령으로 진행할 수 있었습니다. 특히 실제 배포 전에 diff와 dry-run으로 변경 내용을 확인할 수 있다는 점이 이해하기 쉬웠습니다.

마무리

ecspresso는 ECS 전체 인프라를 구성하는 도구라기보다, 기존 ECS 서비스와 태스크 정의를 코드로 관리하고 배포 과정을 간단하게 만들어주는 도구입니다.

이미 Terraform이나 CloudFormation으로 인프라를 관리하고 있지만 애플리케이션 배포는 별도로 분리하고 싶거나, 콘솔에서 운영 중인 ECS 서비스를 코드 관리로 전환하고 싶을 때 검토해볼 수 있습니다.

ECS 배포 도구를 검토하고 계신 분들께 도움이 되었으면 합니다.

긴 글 읽어주셔서 감사합니다.

참고 자료

• KAYAC ecspresso 공식 저장소
• AWS CLI ecs update-service
• AWS CloudFormation AWS::ECS::Service
• HashiCorp Terraform terraform plan
• AWS Copilot CLI 공식 저장소 및 지원 종료 안내
• Docker Official Image httpd