이 기사에서 알 수 있는 것

Snowflake Notebooks 및 Container Runtime 상의 ML Jobs에 자체 Docker 이미지를 도입하고 싶은 분들을 위한 기사입니다.

"Snowflake 표준 런타임에서는 목적에 맞는 패키지를 사용할 수 없다", "사내 보안 정책상 승인된 이미지만 이용할 수 있다"라는 과제를 Custom Runtime Environment (CRE)가 해결합니다.

Image Repository 생성부터 CRE 등록 및 참조까지, Preview 단계에서의 제약을 포함하여 일련의 절차를 정리합니다.

공식 릴리스 노트: Snowflake Documentation

Snowflake 표준 런타임이 "벽"이 되는 3가지 상황

Snowflake Notebooks나 ML Jobs에서 모델 개발을 진행하다 보면 피할 수 없는 제약에 부딪히는 상황이 있습니다.

CRE가 "자체 컨테이너를 Snowflake에서 실행"하는 것을 실현

Snowflake는 2026년 5월 19일, Custom Runtime Environments (CRE)를 Preview로 공개했습니다.

CRE를 사용하면 직접 빌드한 Docker 이미지를 Snowflake의 Image Repository에 등록하고, Notebooks나 ML Jobs의 실행 환경으로서 이름으로 지정할 수 있습니다.

앞서 언급한 3가지 과제에 대한 답을 정리합니다.

패키지의 완전 제어: Dockerfile에 임의의 Python 패키지를 고정 버전으로 기술하여, 그대로 Snowflake의 실행 환경으로 만들 수 있습니다.

컴플라이언스 대응: 사내 승인을 받은 베이스 이미지로부터 구축한 컨테이너를 Snowflake 상에서도 이용할 수 있으며, 이미지의 출처를 사내에서 관리할 수 있습니다.

환경의 고정: 이미지 태그를 고정하면, 몇 번을 실행해도 동일한 패키지 버전이 보장됩니다.

CRE는 계정 레벨의 오브젝트이며, 스키마에는 속하지 않습니다.

한 번 등록하면 여러 Notebook이나 ML Job에서 공유하여 참조할 수 있으며, 버전 관리는 Image Repository 측에서 일원화할 수 있습니다.

Before / After로 보는 런타임 지정의 변화

CRE 도입 전후로 실행 환경의 지정이 어떻게 변하는지 대조합니다.

Before: Snowflake 관리 런타임 (패키지 추가는 매번 pip 사용)

-- 런타임 지정 없음. Snowflake가 관리하는 기본 환경에서 동작
EXECUTE NOTEBOOK mydb.myschema.analysis_notebook;

Notebook 셀 내에서는 다음과 같은 일시적인 설치가 필요했습니다.

# 재시작할 때마다 사라지므로 재현성 제로
!pip install lightgbm==4.3.0 shap==0.45.0

After: CRE로 커스텀 컨테이너를 지정

-- RUNTIME 파라미터로 CRE를 이름으로 지정하기만 하면 됨
EXECUTE NOTEBOOK PROJECT mydb.myschema.analysis_notebook
RUNTIME = 'cre@ml_lightgbm_env';

이미지 측에 lightgbm==4.3.0과 shap==0.45.0

포함되어 있기 때문에, 셀에는 순수한 분석 코드만 남게 됩니다.

cre@

접두사(Prefix)는 CRE 참조를 나타내는 구문으로, 환경 이름만 변경하면 서로 다른 이미지로 전환할 수 있습니다.

실제로 작동시켜 보기

전체 흐름은 다음과 같습니다.

• Image Repository를 생성하고, 레지스트리(Registry) URL을 확인한다
• 로컬에서 Docker 이미지를 빌드하여 푸시(Push)한다
• CRE를 등록한다
• Notebooks / ML Jobs에서 CRE를 참조한다

단계 1: Image Repository 생성하기

DB·스키마·Image Repository 생성 DDL

-- 데이터베이스와 스키마를 생성
CREATE DATABASE IF NOT EXISTS cre_demo_db;
CREATE SCHEMA IF NOT EXISTS cre_demo_db.ml_schema;
...

-- 레지스트리 URL을 확인한다
SHOW IMAGE REPOSITORIES IN SCHEMA cre_demo_db.ml_schema;

실행 결과:

name | repository_url
------------------+-------------------------------------------------------------------------------------------
MY_IMAGE_REPO | myorg-myacc.registry.snowflakecomputing.com/cre_demo_db/ml_schema/my_image_repo

이 URL이 docker push의 대상이 됩니다.

myorg-myacc 부분은 계정마다 다르므로, 반드시 SHOW 명령어로 확인하십시오.

단계 2: Docker 이미지 빌드 및 푸시하기

Snowflake가 제공하는 베이스 이미지(Base Image)를 확장한 Dockerfile을 준비합니다.

# Snowflake 제공 ML 런타임 베이스 이미지를 확장
FROM nvcr.io/snowflake/runtime:latest
# 필요한 패키지를 고정 버전으로 추가
...

터미널에서 빌드와 푸시를 실행합니다.

# Snowflake 레지스트리에 로그인
docker login myorg-myacc.registry.snowflakecomputing.com
# 빌드 및 푸시 (태그에 버전을 명시)
...

푸시가 완료되었음을 확인한 후 다음 단계로 진행하십시오.

푸시하기 전에 CRE를 생성하려고 하면, 서버 사이드(Server-side)의 이미지 존재 확인 과정에서 에러가 발생합니다 (단계 3에서 상세 설명).

단계 3: CRE 등록하기

-- CRE는 계정 수준의 오브젝트 (DB·스키마 지정 불필요)
CREATE CUSTOM RUNTIME ENVIRONMENT ml_lightgbm_env
IMAGE_PATH = 'cre_demo_db/ml_schema/my_image_repo/ml_lightgbm_env:v1.0'
...

중요한 주의 사항으로, 이미지가 존재하지 않는 상태에서 실행하면 IMAGE_PATH를 찾을 수 없다는 에러가 반환됩니다.

이는 DDL 구문의 문제가 아니라, Snowflake가 서버 사이드에서 이미지의 실재 여부를 확인하기 때문입니다.

Docker 푸시 후에 다시 실행하면 CRE가 정상적으로 생성됩니다.

단계 4: CRE 목록 확인하기

-- 계정 내 CRE 목록 (스키마 지정 없음)
SHOW CUSTOM RUNTIME ENVIRONMENTS;

CRE가 생성되면 name, base_image_type, image_path의 각 열을 가진 행이 반환됩니다.

스키마를 넘나들며 여러 개의 CRE를 등록한 경우에도, 이 명령어 하나로 계정 전체의 목록을 확인할 수 있습니다.

단계 5: 액세스 권한 부여하기

-- 데이터 사이언티스트 역할(Role)에 Image Repository에 대한 읽기 권한 부여
GRANT READ ON IMAGE REPOSITORY cre_demo_db.ml_schema.my_image_repo
TO ROLE data_scientist_role;
...

단계 6: CRE를 지정하여 Notebook 실행하기

-- RUNTIME 파라미터로 CRE 참조
EXECUTE NOTEBOOK PROJECT mydb.myschema.analysis_notebook
RUNTIME = 'cre@ml_lightgbm_env';

cre@ml_lightgbm_env에서 cre@ 부분이 CRE 참조를 나타내는 접두사(Prefix)입니다.

CRE 이름만 변경하면 실행 환경을 전환할 수 있으므로, 실험마다 이미지를 구분하여 사용하는 것도 용이합니다.

운영 도입 전 알아두어야 할 포인트

1. CRE 생성은 「이미지 푸시(Image Push) 후」가 필수

CREATE CUSTOM RUNTIME ENVIRONMENT는 실행 시 서버 사이드(Server-side)에서 이미지의 존재 여부를 확인합니다.

docker push가 완료되지 않은 상태에서는 IMAGE_PATH 부재 에러가 반환되므로, 처리 순서는 「push → CREATE CRE」로 고정됩니다.

Terraform과 같은 IaC(Infrastructure as Code) 도구로 리소스를 관리하는 경우, Image Repository와 Docker 푸시 단계를 CRE 생성의 의존성(Dependency)으로 명시적으로 설정해야 합니다.

요약

Custom Runtime Environment (CRE)는 Snowflake의 ML 실행 환경에 자체 Docker 컨테이너를 가져올 수 있는 수단을 공식적으로 제공하는 것입니다.

「패키지 제약 해소」, 「컴플라이언스(Compliance) 대응」, 「환경의 재현성」이라는 세 가지 과제를 RUNTIME = 'cre@<이름>'이라는 단 하나의 파라미터로 해결할 수 있다는 점이 큰 특징입니다.

상세한 구문과 최신 제약 사항은 공식 문서(Custom runtime images)에서 확인하시기 바랍니다.

참고 링크

Discussion