Orchestrating SageMaker AI endpoint auto scaling with AWS CDK

🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

AWS CDK의 재사용 가능한 구성 요소와 CloudFormation 사용자 지정 리소스로 SageMaker AI 엔드포인트 업데이트 전후의 오토 스케일링 해제·재등록을 자동화한다.

📌 핵심 요약

• SageMaker AI 엔드포인트 구성을 변경할 때 확장 대상이 등록되어 있으면 업데이트가 거부될 수 있으며, AWS CLI로 수동 해제하면 CloudFormation이 오토 스케일링을 복원하지 않거나 UPDATE_ROLLBACK_FAILED 상태에 빠질 수 있다.
• 제안된 구성 요소는 기본 ScalableTarget·ScalingPolicy 리소스를 사용자 지정 리소스 3개로 대체하고, node.add_dependency로 확장 대상 해제 → 엔드포인트 업데이트 → 확장 대상 등록 → 스케일링 정책 적용 순서를 보장한다.
• 확장 대상 등록은 엔드포인트가 InService에 도달할 때까지, 정책 적용은 확장 대상을 조회할 수 있을 때까지 비동기로 대기한다. 확인 간격은 30초이며 전체 대기 한도는 각각 1시간과 15분이다.
• 엔드포인트와 오토 스케일링 설정을 함께 반영하는 ConfigHash가 설정 변경 시 전체 절차를 다시 실행하게 한다. 배포 결과에는 사용자 지정 리소스 3개, Step Functions 상태 머신 2개, Lambda 함수 12개가 포함된다.
• 예제는 config/config.yaml에서 설정하고 InferenceStack을 배포한 뒤 AWS CLI로 확장 대상과 스케일링 정책을 확인한다. ml.m5.large를 ml.m5.xlarge로 변경해 재배포하는 검증 절차와 기존 CDK 스택에 구성 요소를 통합하는 방법도 제시한다.

🧩 주요 포인트

1. 수동 해제와 CloudFormation의 리소스 추적 사이에 불일치가 발생하므로, 업데이트 성공 여부와 함께 오토 스케일링 복원 여부를 확인해야 한다.
2. 명시적 의존성과 비동기 준비 상태 확인을 결합해, SageMaker AI의 업데이트 제약과 확장 대상·정책의 적용 시점을 배포 절차에 반영한다.
3. ConfigHash로 엔드포인트와 오토 스케일링 변경을 연결하면 단일 배포로 처리할 수 있지만, 실제 배포 자원 검토에는 Lambda 함수 12개와 Step Functions 상태 머신 2개까지 포함해야 한다.

🧠 상세 정리

1. 엔드포인트 변경과 오토 스케일링 등록의 충돌

글은 Amazon SageMaker AI 실시간 엔드포인트의 인스턴스 유형, 인스턴스 수 또는 환경 변수를 변경할 때 AWS CloudFormation이나 AWS CDK 배포가 실패하는 문제에서 출발한다. 핵심 제약은 엔드포인트를 업데이트하기 전에 Application Auto Scaling의 확장 대상 등록을 해제해야 한다는 점이다. 기본 CloudFormation 오토 스케일링 리소스를 사용하는 상태에서 엔드포인트 구성을 바꾸면, CloudFormation은 확장 대상이 여전히 등록된 상태로 업데이트를 시도한다. SageMaker AI는 AllTraffic 변형을 제거하거나 인스턴스 유형을 업데이트하려면 먼저 확장 대상 등록을 해제해야 한다는 오류로 요청을 거부한다. 따라서 CloudFormation이 오토 스케일링 리소스 처리 단계에 도달하기도 전에 엔드포인트 업데이트가 차단되며, 이 순서 문제를 배포 과정에서 해결해야 한다.

2. 수동 등록 해제가 만드는 두 가지 추가 실패

AWS CLI로 확장 대상 등록을 수동 해제하면 최초의 업데이트 차단은 피할 수 있지만, 이후 결과는 템플릿에서 무엇을 바꾸었는지에 따라 달라진다. 엔드포인트 구성만 변경해 재배포하면 배포 자체는 성공하지만, 오토 스케일링 매개변수가 바뀌지 않았으므로 CloudFormation은 확장 대상을 다시 등록하거나 스케일링 정책을 재적용하지 않는다. 이 경우 엔드포인트는 오토 스케일링 없이 실행되며, 문제가 생겼다는 오류도 나타나지 않는다. 반대로 수동 해제 후 오토 스케일링 매개변수까지 바꾸면 CloudFormation은 이미 사라진 AWS::ApplicationAutoScaling::ScalableTarget 리소스를 업데이트하려다 리소스를 찾을 수 없다는 오류를 낸다. 원문은 이 경우 롤백도 실패해 UPDATE_ROLLBACK_FAILED 상태가 되며, CloudFormation 콘솔에서 수동 복구가 필요하다고 설명한다.

3. 사용자 지정 리소스로 배포 순서 제어

해결책은 기본 AWS::ApplicationAutoScaling::ScalableTarget과 AWS::ApplicationAutoScaling::ScalingPolicy를 사용자 지정 리소스 3개로 대체하는 재사용 가능한 CDK 구성 요소다. CDK의 node.add_dependency 호출로 의존성을 명시해, 확장 대상 해제부터 엔드포인트 업데이트와 오토 스케일링 복원까지 순서대로 실행되게 한다. 먼저 Deregister가 확장 대상을 해제하며, 최초 배포처럼 대상이 아직 없는 경우에는 해당 오류를 처리하고 계속 진행한다. 이어 CDK가 엔드포인트 리소스를 정상적으로 업데이트해 새 엔드포인트 구성으로 전환한다. Register Scalable Target은 엔드포인트가 InService가 된 뒤 확장 대상을 등록하고, Attach Scaling Policy는 그 대상을 조회할 수 있을 때 대상 추적 정책을 적용한다. 이 절차를 통해 엔드포인트 구성과 오토 스케일링 매개변수를 수동 개입 없이 한 번의 배포에서 변경하는 것이 글의 목표다.

4. 비동기 대기 방식과 실제 배포 자원

확장 대상 등록과 정책 적용은 CDK 공급자의 비동기 완료 패턴을 사용하며, on_event 처리기는 즉시 반환하고 is_complete 처리기가 준비 상태를 확인한다. 공급자의 대기 로직은 30초마다 is_complete를 다시 호출하며, 전체 대기 한도는 확장 대상 등록에 1시간, 정책 적용에 15분으로 설정된다. 따라서 준비 상태를 기다리는 시간은 개별 Lambda 호출의 제한 시간에 묶이지 않는다. 실제 스택에는 사용자 지정 리소스 3개뿐 아니라 공급자 프레임워크가 생성하는 보조 자원도 포함되어, Step Functions 상태 머신 2개와 Lambda 함수 12개가 배포된다. Lambda 함수 중 5개는 구성 요소의 처리기 코드를 담고, 나머지 7개는 공급자 프레임워크가 생성한다. 이 보조 함수들을 직접 작성하거나 유지보수할 필요는 없지만, 원문은 배포 자원을 검토할 때 그 존재를 고려해야 한다고 설명한다.

5. 실행 전제와 설정 변경을 연결하는 ConfigHash

실습에는 SageMaker AI, Lambda, IAM, Application Auto Scaling, CloudWatch 권한이 있는 AWS 계정과 AWS CDK v2, Python 3.12 이상, Python 의존성 관리 도구 uv가 필요하다. 모델 준비물로는 Amazon S3의 모델 아티팩트와 Amazon ECR의 컨테이너 이미지 또는 SageMaker AI 내장 알고리즘 컨테이너가 제시된다. 저장소를 복제하고 uv sync로 의존성을 설치한 뒤, config/config.yaml에 엔드포인트와 오토 스케일링 값을 함께 정의한다. 예제는 ml.m5.large와 초기 인스턴스 수 1, 최소 용량 1과 최대 용량 10, 목표값 100, 축소 쿨다운 600과 확장 쿨다운 120을 사용한다. 두 설정 영역을 함께 두는 이유는 단일 config_hash가 전체 오토 스케일링 절차를 구동하며, 어느 영역이 바뀌어도 사용자 지정 리소스의 ConfigHash 변경으로 처리기가 다시 호출되기 때문이다. 엔드포인트 설정은 CreateModel·CreateEndpointConfig API에, 오토 스케일링 설정은 RegisterScalableTarget·PutScalingPolicy API에 대응한다.

6. 최초 배포와 업데이트 검증

AWS 환경을 아직 부트스트랩하지 않았다면 uv run cdk bootstrap을 실행하고, 이어 uv run cdk deploy InferenceStack으로 예제 스택을 배포한다. CloudFormation은 SageMaker AI 모델, 엔드포인트 구성, 엔드포인트를 생성하고 사용자 지정 리소스 3개를 순서대로 실행해 오토 스케일링을 등록한다. 배포 후에는 AWS CLI의 describe-scalable-targets로 endpoint/my-model-endpoint/variant/AllTraffic의 확장 대상 등록을 확인하고, describe-scaling-policies로 스케일링 정책 적용을 확인한다. 업데이트 실습에서는 config/config.yaml의 인스턴스 유형을 ml.m5.large에서 ml.m5.xlarge로 바꾼 뒤 동일한 InferenceStack을 다시 배포한다. 배포가 완료되면 확장 대상을 다시 조회해 오토 스케일링이 여전히 등록되어 있고 변경한 값이 반영되었는지 확인한다. 이는 배포 성공만으로는 오토 스케일링 복원을 보장할 수 없다는 앞선 실패 사례와 연결되는 검증 절차다.

7. 기존 CDK 스택에 통합하는 방법

새로 시작하거나 참조 구현이 필요하면 예제 스택을 사용하고, 이미 SageMaker AI 리소스가 있는 CDK 스택에는 구성 요소를 직접 추가할 수 있다. 원문은 sagemaker_autoscaling/constructs/ 디렉터리를 프로젝트에 복사한 뒤 AutoscalingConfig, SagemakerAutoscalingConstruct, SagemakerAutoscalingProps를 가져오는 예를 제공한다. 기존 CfnEndpoint를 endpoint 속성으로 전달하고, 최소·최대 용량과 목표값, 쿨다운을 AutoscalingConfig에 지정해 엔드포인트 리소스 옆에 구성 요소를 배치한다. 이때 config_hash에는 이미지, 모델 데이터 위치, 인스턴스 유형, 초기 인스턴스 수 같은 엔드포인트 값과 오토 스케일링 값을 함께 포함해야 한다. 예제는 두 설정 영역을 json.dumps로 직렬화해 전달하며, 어느 쪽이 변경되어도 오토 스케일링 절차가 실행되게 한다. 따라서 기존 스택 통합에서도 구성 요소 추가뿐 아니라 변경 감지에 필요한 값들을 함께 전달하는 것이 핵심 조건이다.

8. 등록 해제 처리기와 엔드포인트 준비 상태 확인

구현 설명에서 Deregister 처리기는 Create 또는 Update 요청일 때 deregister_scalable_target을 호출하며, 서비스 네임스페이스는 sagemaker, 확장 차원은 sagemaker:variant:DesiredInstanceCount를 사용한다. 최초 배포에서 확장 대상이 없어 발생하는 ObjectNotFoundException은 처리하고 계속 진행하며, PhysicalResourceId를 반환한다. 엔드포인트에 props.endpoint.node.add_dependency(deregister)를 설정해 등록 해제가 엔드포인트 업데이트보다 먼저 실행되도록 한다. Register Scalable Target 설명은 CloudFormation이 엔드포인트 업데이트를 수락한 뒤 리소스를 완료로 취급하더라도, 확장 대상 등록은 엔드포인트가 InService가 되어야 가능하다는 차이를 강조한다. 이를 위해 단일 Lambda 호출을 계속 대기시키는 대신 공급자가 is_complete를 반복 실행하며, 제공된 코드 일부에서는 Delete 요청에 IsComplete를 참으로 반환한다. 제공된 source_body는 describe_endpoint 호출 부분에서 끊기므로, 이후 처리기의 전체 구현은 이 자료만으로 확인할 수 없다.

🧾 핵심 주장 / 시사점

• 배포가 성공했다는 사실과 오토 스케일링이 정상 복원되었다는 사실은 별개다. 수동 등록 해제 후 설정 변경이 없으면 CloudFormation이 복원을 수행하지 않아도 오류가 발생하지 않을 수 있다.
• 이 구성 요소는 실행 순서뿐 아니라 실제 준비 상태까지 배포 조건으로 다룬다. 엔드포인트의 InService 도달과 확장 대상의 조회 가능 여부를 나누어 확인하는 점이 핵심이다.
• 사용자가 관리하는 사용자 지정 리소스는 3개지만 실제 배포 자원은 더 많다. 재사용 가능한 구성 요소를 도입할 때 공급자 프레임워크가 생성하는 함수와 상태 머신까지 파악할 필요가 있다.

✅ 액션 아이템

• config/config.yaml 변경 시 엔드포인트와 오토 스케일링 설정이 ConfigHash에 함께 반영되는지 확인한다.
• InferenceStack 재배포 후 AWS CLI로 확장 대상 등록과 스케일링 정책 적용 상태를 확인한다.
• 기존 CDK 스택 통합 시 사용자 지정 리소스 3개, Lambda 함수 12개, Step Functions 상태 머신 2개를 배포 자원 검토에 포함한다.

❓ 열린 질문

• 현재 CloudFormation 배포에는 수동 해제 이후 오토 스케일링이 복원되지 않은 엔드포인트가 있는가?
• ConfigHash에는 엔드포인트와 오토 스케일링의 변경 대상 설정이 모두 반영되어 있는가?
• 확장 대상 등록의 1시간과 스케일링 정책 적용의 15분 대기 한도는 해당 SageMaker AI 엔드포인트의 업데이트에 충분한가?