Windows 환경에서 AWS CLI로 S3 자동 배포 및 CloudFront 캐시 무효화 처리하기

CloudFront 캐시 무효화까지 함께 처리하는 운영 가이드

AWS S3(Simple Storage Service)와 CloudFront 조합은 정적 웹사이트 운영에서 가장 많이 사용되는 방식 중 하나로 HTML, CSS, JavaScript 파일만으로 구성된 웹사이트뿐 아니라 이미지, 문서, 다운로드 리소스 배포 등 다양한 서비스 환경에서 폭넓게 활용되고 있습니다.

최근에는 기업 홈페이지, 프로모션 페이지 등도 정적 구조 기반으로 운영하는 사례가 늘어나면서 S3와 CloudFront를 이용한 배포 환경 구축 수요 역시 꾸준히 증가하고 있습니다. 다만 실제 운영 단계에서는 파일을 업로드만으로 끝나지 않는 경우가 많습니다.

특히 운영 과정에서는 아래와 같은 문제가 자주 발생합니다.

수정한 파일이 즉시 반영되지 않는 현상
CloudFront 캐시 때문에 이전 화면이 유지되는 문제
삭제된 파일이 S3에 계속 남아있는 문제
수동 업로드 과정에서 파일 누락 발생
Windows CMD 환경에서 명령어 오류 발생

초기에는 AWS 콘솔에서 직접 파일을 업로드하며 운영하는 경우가 많지만, 배포 횟수가 늘어나고 관리 대상 사이트가 많아질수록 반복 작업에 소요되는 시간과 운영 피로도도 함께 증가하게 됩니다. 또한 캐시 처리나 파일 정리 과정이 누락될 경우, 실제 사용자 화면에서는 이전 버전이 계속 노출되거나 일부 리소스만 갱신되는 문제도 발생할 수 있습니다.

이번 글에서는 이러한 반복 작업과 운영 이슈를 줄이기 위해 Windows 환경에서 AWS CLI를 활용하여 S3 업로드와 CloudFront 캐시 무효화 작업을 자동화하는 방법을 정리합니다. 특히 Windows CMD 환경 기준으로 자주 발생하는 오류와 실무 운영 시 고려해야 하는 부분까지 함께 다루어, 정적 웹사이트 운영 자동화를 준비하는 분들에게 도움이 될 수 있도록 구성하였습니다.

AWS CLI 설치

먼저 Windows PC 또는 운영 서버에 AWS CLI(Amazon Web Services Command Line Interface)를 설치합니다.

AWS CLI는 명령어 기반으로 AWS 서비스를 제어할 수 있도록 제공되는 공식 도구이며 S3 업로드, CloudFront 캐시 무효화, EC2 관리, IAM 설정 등 다양한 작업을 콘솔 접속 없이 수행할 수 있습니다. 특히 반복적인 배포 작업을 자동화하거나 배치 파일(.bat)과 함께 운영할 경우 매우 유용하게 활용됩니다.

Windows 환경에서는 GUI 기반으로 파일을 직접 업로드하는 방식보다 AWS CLI를 이용한 자동화 방식이 훨씬 효율적이며, 운영 과정에서 발생할 수 있는 실수도 줄일 수 있습니다.

AWS CLI 공식 다운로드

AWS 공식 사이트에서 Windows용 설치 파일을 다운로드한 뒤 일반 프로그램 설치 방식으로 진행하면 됩니다. 설치가 완료되면 CMD(명령 프롬프트)를 실행한 뒤 아래 명령어를 입력하여 정상 설치 여부를 확인합니다.

aws --version

정상적으로 설치되었다면 다음과 비슷한 형태의 메시지가 출력됩니다.

aws-cli/2.x.x Python/3.x Windows/11 exe/AMD64

출력 결과에는 다음과 같은 정보가 포함됩니다.

설치된 AWS CLI 버전
내부적으로 사용되는 Python 런타임 버전
운영체제 정보
실행 아키텍처(64bit 등)

AWS 인증 정보 등록

AWS CLI를 처음 사용하는 경우 AWS 계정과 연결할 인증 정보를 먼저 등록해야 합니다. AWS CLI는 콘솔 로그인 방식이 아니라 Access Key 기반 인증을 사용하기 때문에 S3 업로드나 CloudFront 제어 같은 작업을 수행할 때 이 인증 정보를 이용하여 AWS 권한을 확인합니다.

CMD(명령 프롬프트)를 실행한 뒤 아래 명령어를 입력합니다.

aws configure

명령 실행 후 아래 항목들을 순서대로 입력하게 됩니다.

AWS Access Key ID
AWS Secret Access Key
Default region name
Default output format

예시:

AWS Access Key ID [None]: AKIAXXXXX
AWS Secret Access Key [None]: xxxxxxxxx
Default region name [None]: ap-northeast-2
Default output format [None]: json

각 항목의 의미는 다음과 같습니다.

AWS Access Key ID → AWS API 접근용 계정 ID
AWS Secret Access Key → Access Key와 함께 사용하는 인증 비밀번호 역할
Default region name → 기본 AWS 리전 설정 대한민국 서울 리전은 일반적으로 ap-northeast-2 를 사용합니다.
Default output format → CLI 결과 출력 형식 일반적으로 json 을 가장 많이 사용합니다.

AWS

S3 업로드 기본 명령

AWS CLI에서 가장 많이 사용하는 명령 중 하나는 sync 입니다. sync 명령은 로컬 폴더와 S3 버킷의 파일 상태를 비교하여 필요한 파일만 업로드하거나 갱신합니다.

aws s3 sync C:\build s3://sample-bucket

예를 들어 위 명령은:

C:\build → 로컬 배포 폴더
s3://sample-bucket → 업로드 대상 S3 버킷을 서로 동기화하는 역할을 수행합니다.

특히 정적 웹사이트 운영 환경에서는 전체 파일을 다시 업로드하는 방식보다 sync 명령을 사용하는 것이 훨씬 효율적이며, 변경된 파일만 전송되기 때문에 배포 시간도 줄일 수 있습니다.

–delete 옵션 함께 사용하기

실제 운영 환경에서는 대부분 --delete 옵션을 함께 사용합니다.

aws s3 sync C:\build s3://sample-bucket --delete

이 옵션은 로컬 폴더에는 존재하지 않지만 S3 버킷에는 남아있는 파일을 자동으로 삭제합니다.

오래된 JavaScript 파일
더 이상 사용하지 않는 CSS 파일
교체된 이미지 리소스

같은 파일이 S3에 계속 남아있으면 브라우저 캐시 또는 CloudFront 캐시와 충돌하여 예상하지 못한 문제가 발생할 수 있습니다. 특히 정적 웹사이트는 파일명이 변경되는 경우가 많기 때문에, 오래된 파일 정리를 함께 수행하는 것이 안정적인 운영에 매우 중요합니다.

CloudFront 캐시 무효화 처리

S3 업로드가 정상적으로 완료되었더라도 사용자 화면에는 이전 버전이 계속 표시되는 경우가 있습니다. 이는 CloudFront가 기존 정적 파일을 캐시하고 있기 때문입니다. 특히 HTML, CSS, JavaScript 파일은 CloudFront 캐시 정책에 따라 일정 시간 동안 이전 데이터를 유지할 수 있으므로, 운영 환경에서는 캐시 무효화(invalidation) 작업을 함께 수행하는 경우가 많습니다.

이 경우 아래 명령어를 사용합니다.

aws cloudfront create-invalidation --distribution-id E123456789 --paths "/*"

각 옵션의 의미는 다음과 같습니다.

distribution-id → CloudFront 배포 ID
–paths → 캐시 제거 대상 경로

Windows CMD에서 자주 발생하는 오류

Windows CMD 환경에서는 Linux나 macOS 터미널처럼 세미콜론(;)으로 명령어를 연결하면 오류가 발생할 수 있습니다.

예를 들어 아래와 같은 방식은 Windows CMD에서 정상 동작하지 않을 수 있습니다.

aws s3 sync C:\build s3://sample-bucket --delete; aws cloudfront create-invalidation --distribution-id EXAMPLE --paths "/*"

실제 운영 과정에서는 아래와 같은 오류 메시지가 출력되는 경우가 많습니다.

Invalid choice: 'public-read;'

이는 Windows CMD가 세미콜론(;)을 Linux 계열 쉘처럼 명령 연결 문자로 처리하지 않기 때문입니다. 특히 AWS CLI 옵션 뒤에 세미콜론이 함께 붙어 전달되면서 예상하지 못한 파라미터 오류가 발생하는 경우가 많습니다.

따라서 Windows CMD 환경에서는 명령 연결 방식에 주의해야 합니다.

Windows에서는 && 사용

Windows CMD 환경에서는 여러 명령을 순차적으로 실행할 때 && 연산자를 사용합니다.

aws s3 sync C:\build s3://sample-bucket --delete && aws cloudfront create-invalidation --distribution-id EXAMPLE --paths "/*"

이 방식은:

- 첫 번째 명령이 정상적으로 성공한 경우에만
- 다음 명령을 이어서 실행하는 구조입니다.

즉, S3 업로드가 실패했는데도 CloudFront 캐시 무효화가 실행되는 상황을 방지할 수 있습니다. 특히 실제 운영 환경에서는 배포 실패 여부를 명확히 구분할 수 있기 때문에 && 방식이 가장 안정적으로 사용됩니다.

Windows 배치 파일(.bat) 자동화에서도 가장 많이 사용하는 방식 중 하나입니다.

배치 파일(.bat)로 자동화하기

반복적으로 수행하는 배포 작업은 .bat 파일로 만들어두면 편리합니다. 매번 CMD에 명령어를 직접 입력하지 않아도 되고 정해진 순서대로 S3 업로드와 CloudFront 캐시 무효화를 실행할 수 있습니다.

@echo off

echo S3 Upload Start...

aws s3 sync C:\build s3://sample-bucket --delete

echo CloudFront Invalidation Start...

aws cloudfront create-invalidation --distribution-id E123456789 --paths "/*"

echo Deploy Complete

pause

위 내용을 예를 들어 아래와 같은 파일명으로 저장합니다.

deploy.bat

이후 해당 파일을 더블클릭하면 배포 명령이 순서대로 실행됩니다.

운영 환경에서는 실제 로컬 폴더 경로, S3 버킷명, CloudFront 배포 ID만 자신의 환경에 맞게 변경하면 됩니다.

운영 시 주의사항

전체 캐시 무효화 남용 주의

CloudFront 캐시 무효화 시 아래처럼 전체 경로를 지정할 수 있습니다.

--paths "/*"

이 방식은 CloudFront에 캐시된 모든 파일을 무효화합니다.

운영 초기나 전체 파일 구조가 크게 변경된 경우에는 유용하지만, 배포할 때마다 전체 캐시를 제거하는 방식은 신중하게 사용해야 합니다. 운영 규모가 커질수록 다음과 같은 문제가 발생할 수 있습니다.

캐시 효율 감소
원본 서버 요청 증가
불필요한 비용 증가

실제 운영에서는 변경 범위에 따라 특정 파일만 무효화하는 방식도 자주 사용합니다.

--paths "/index.html"

정적 파일명이 버전 기반으로 관리되는 구조라면, 전체 무효화보다 주요 진입 파일만 갱신하는 방식이 더 효율적일 수 있습니다.

S3 퍼블릭 접근 정책 확인

CloudFront 없이 S3 URL을 직접 공개하는 경우에는 버킷 정책(Bucket Policy)과 퍼블릭 접근 설정(Public Access Block)을 반드시 확인해야 합니다. 특히 최근 AWS는 보안 강화를 위해 기본적으로 퍼블릭 접근 차단 상태를 권장하고 있으며, 설정에 따라 외부 접근이 제한될 수 있습니다.

정적 웹사이트 공개 목적이라면 아래 사항을 함께 확인하는 것이 중요합니다.

S3 정적 웹사이트 호스팅 활성화 여부
Bucket Policy 설정
Public Access Block 상태

오래된 파일 정리 중요

정적 웹사이트는 빌드 과정에서 파일명이 변경되는 경우가 많습니다.

main_old.js
main_new.js

이처럼 새로운 파일이 생성되더라도 이전 파일이 S3에 그대로 남아있으면 브라우저 또는 CloudFront가 오래된 파일을 참조하는 문제가 발생할 수 있습니다. 특히 CSS나 JavaScript 리소스 충돌로 인해 화면이 깨지거나 일부 기능이 정상 동작하지 않는 사례도 자주 발생합니다.

따라서 배포 시 오래된 파일을 함께 정리하는 것은 운영 안정성 측면에서 매우 중요하며, 이런 이유로 --delete 옵션을 함께 사용하는 경우가 많습니다.

AWS CLI 자동 배포의 장점

Windows 환경에서 AWS CLI 기반 자동 배포 환경을 구성하면 반복적인 운영 작업을 훨씬 효율적으로 관리할 수 있습니다.

특히 정적 웹사이트 운영 과정에서는 파일 업로드, 오래된 파일 정리, CloudFront 캐시 무효화 같은 작업이 반복적으로 발생하는데, 이를 수동으로 처리할 경우 작업 시간 증가와 함께 운영 실수 가능성도 커질 수 있습니다. AWS CLI를 이용한 자동 배포 환경을 구성하면 이러한 과정을 일정한 방식으로 표준화할 수 있으며, 운영 안정성과 유지보수 효율 향상에도 도움이 됩니다.

반복 작업 자동화
수동 업로드 실수 감소
배포 시간 단축
운영 효율 향상
CloudFront 캐시 문제 최소화
다수 사이트 운영 시 관리 편의성 증가

예를 들어 운영자가 직접 AWS 콘솔에 접속하여 파일을 업로드하는 방식에서는 아래와 같은 문제가 발생할 수 있습니다.

특정 파일 업로드 누락
오래된 리소스 미삭제
캐시 무효화 누락
잘못된 폴더 업로드

반면 AWS CLI 기반 자동화 구조에서는 미리 정의된 명령을 기준으로 동일한 절차가 반복 수행되기 때문에 운영 품질을 일정하게 유지하기 쉽습니다. 또한 .bat 파일과 함께 구성하면 운영 담당자마다 다른 방식으로 배포하는 문제를 줄일 수 있으며, 신규 운영 인력이 추가되더라도 비교적 빠르게 동일한 운영 절차를 적용할 수 있습니다.

특히 여러 프로젝트나 다수의 정적 사이트를 동시에 운영하는 환경에서는 CLI 기반 배포 구조가 유지보수 효율과 운영 안정성 측면에서 큰 차이를 만들 수 있습니다.

마무리

AWS S3와 CloudFront를 이용한 정적 웹사이트 운영 구조는 비교적 단순하게 보일 수 있지만, 실제 운영 단계에서는 캐시 관리와 파일 동기화 방식에 따라 서비스 안정성과 운영 효율에 큰 차이가 발생할 수 있습니다. 특히 파일 수정 사항이 즉시 반영되지 않거나 오래된 리소스가 남아있는 문제는 정적 사이트 운영 환경에서 자주 발생하는 대표적인 사례 중 하나입니다.

Windows 환경에서는 Linux 계열 서버와 명령 처리 방식이 다른 부분도 있기 때문에 다음과 같은 요소를 함께 이해하고 운영하는 것이 중요합니다.

CMD 명령 연결 방식
배치 파일(.bat) 자동화 구성
CloudFront invalidation 처리
S3 sync 및 --delete 옵션 활용
오래된 리소스 정리 전략

이러한 구조를 미리 정리해두면 반복적인 배포 작업을 보다 안정적으로 관리할 수 있으며, 운영 과정에서 발생할 수 있는 실수와 관리 부담도 줄일 수 있습니다. 특히 여러 프로젝트 또는 다수의 정적 웹사이트를 운영하는 환경에서는 AWS CLI 기반 자동 배포 환경을 미리 구축해두는 것이 장기적인 운영 효율 측면에서도 도움이 될 수 있습니다.

Keywords
AWS AWSCLI AmazonS3 CloudFront S3자동배포 CloudFrontInvalidation 정적웹사이트 배치파일 CMD AWS배포자동화 S3Sync CloudFront캐시 정적사이트운영 Windows배포 리소스배포 웹사이트배포 AWS가이드

작성자 : (주)리프아이티 ICT사업본부