환경 구성 · 심화

SageMaker Conda 환경 & 커널 영속성

재시작해도 환경이 살아있도록 — ~/SageMaker/ 안에 Miniconda를 설치하는 방법

Conda 커널 영속성 — 심화 가이드

재시작해도 환경이 살아있도록 — ~/SageMaker/ 안에 Miniconda를 설치하는 방법

"분명히 어제 만들었는데, 노트북 재시작하니 커널이 사라졌어요."

왜 이게 필요한가?

SageMaker Notebook Instance는 두 종류의 스토리지가 있습니다.

경로	유형	재시작 후
`/home/ec2-user/` (홈 디렉토리)	임시 스토리지	😰 초기화됨
`/home/ec2-user/SageMaker/`	EBS 영구 볼륨	✅ 유지됨

기본 conda create 명령어는 /home/ec2-user/anaconda3/envs/에 환경을 만듭니다. 이 경로는 재시작 시 초기화되므로 환경이 사라집니다.

✅ 해결책: Miniconda와 모든 conda 환경을 ~/SageMaker/.myenv/ 안에 설치합니다.

/home/ec2-user/SageMaker/
└── .myenv/                            ← EBS에 있으므로 재시작해도 유지
    └── miniconda/
        └── envs/
            ├── boilerplate312/        ← 내 conda 환경들
            ├── tabular312/
            └── streamlit314/

전체 흐름 한눈에 보기

최초 1회

create_env.sh

Miniconda 설치 + 환경 생성

→

재시작마다

start.sh

Lifecycle Auto-run

→

결과

커널 자동복원

JupyterLab에서 선택 가능

ℹ️ Lifecycle Configuration: SageMaker Notebook 설정에서 on-start 스크립트를 등록하면 인스턴스가 시작될 때마다 자동으로 실행됩니다. start.sh를 여기에 등록하면 재시작 후에도 커널이 자동 복원됩니다.

Step 1: 실습 repo 클론 (~/SageMaker 안에)

SageMaker Notebook Terminal에서 실행합니다.

📋 복사해서 붙여넣기

# SageMaker 영구 볼륨 안에 repo 클론
cd ~/SageMaker
git clone https://github.com/hakmink/gs-ds-env
ls gs-ds-env/

예상 결과:

bin  boilerplate312  lightgbm311  streamlit314  tabular312  tsai

⚠️ ~/SageMaker/ 안에 클론해야 합니다. 홈 디렉토리(~)에 클론하면 재시작 시 사라집니다.

Step 2: Swap 메모리 설정

Conda 환경 생성과 패키지 설치 중 메모리 부족으로 프로세스가 죽는 것을 방지합니다.

📋 복사해서 붙여넣기

cd ~/SageMaker/gs-ds-env/bin/
./increase_swap_size.sh

📋 복사해서 붙여넣기

# Swap 설정 확인
free -h

예상 결과:

              total        used        free      shared  buff/cache   available
Mem:           15Gi       2.1Gi        11Gi       ...
Swap:         4.0Gi          0B       4.0Gi   ← Swap 4G 활성화

free -h 에서 Swap이 4.0Gi로 표시되는가?

Step 3: 환경 생성 — `create_env.sh`

환경을 처음 만들 때 이 스크립트를 실행합니다.

스크립트 동작 순서 (6단계)

[1/6] Miniconda 설치  →  ~/SageMaker/.myenv/miniconda/
[2/6] conda 환경 생성  →  ~/SageMaker/.myenv/miniconda/envs/<env_name>/
[3/6] 환경 활성화
[4/6] uv로 requirements.txt 패키지 설치
[5/6] ipykernel 설치 + Jupyter 커널 등록  →  커널 이름: conda_<env_name>
[6/6] envs_dirs 등록 + 확인

사용법

📋 복사해서 붙여넣기

cd ~/SageMaker/gs-ds-env/bin/

# Usage: ./create_env.sh <env_name> <requirements_path> <python_version>
./create_env.sh boilerplate312 \
    /home/ec2-user/SageMaker/gs-ds-env/boilerplate312/kernel/requirements.txt \
    3.12

파라미터	예시	의미
`env_name`	`boilerplate312`	conda 환경 이름
`requirements_path`	`.../kernel/requirements.txt`	설치할 패키지 목록
`python_version`	`3.12`	Python 버전

완료 후 확인

📋 복사해서 붙여넣기

# 환경 목록 확인
source ~/SageMaker/.myenv/miniconda/etc/profile.d/conda.sh
conda env list

# 커널 등록 확인
jupyter kernelspec list

예상 결과:

# conda env list
base        *  /home/ec2-user/SageMaker/.myenv/miniconda
boilerplate312  /home/ec2-user/SageMaker/.myenv/miniconda/envs/boilerplate312

# jupyter kernelspec list
Available kernels:
  conda_boilerplate312    /home/ec2-user/.local/share/jupyter/kernels/conda_boilerplate312
  python3                 /usr/local/share/jupyter/kernels/python3

conda env list에 내 환경이 ~/SageMaker/.myenv/... 경로로 표시되는가?
jupyter kernelspec list에 conda_boilerplate312가 있는가?
JupyterLab에서 커널 선택 시 conda_boilerplate312가 보이는가?

Step 4: 재시작 후 자동 복원 — `start.sh`

인스턴스를 재시작하면 커널 등록이 사라집니다. start.sh가 이를 자동으로 복원합니다.

start.sh가 하는 일

1. 한국어 로케일 설정
2. git 자격증명 복원 (~/SageMaker/.git-credentials → ~/.git-credentials)
3. Swap 메모리 설정 (increase_swap_size.sh)
4. ~/SageMaker/.myenv/miniconda/envs/ 에서 환경 자동 감지
5. 각 환경에 대해:
   - ~/.bashrc에 alias 등록
   - start_env.sh 실행 → 커널 Jupyter에 재등록

Lifecycle Configuration에 등록하기

🌐 AWS 콘솔: SageMaker → Notebook instances → 해당 인스턴스 → Lifecycle configuration

📋 복사해서 붙여넣기 (Lifecycle on-start 스크립트)

#!/bin/bash
set -e

# gs-ds-env가 SageMaker 볼륨에 있어야 함
cd /home/ec2-user/SageMaker/gs-ds-env/bin/

# start.sh 실행
./start.sh >> /tmp/start.log 2>&1

echo "Lifecycle start.sh 완료"

⚠️ Lifecycle Configuration 스크립트는 root 권한으로 실행됩니다. 스크립트 내부에서 ec2-user로 전환이 필요한 경우 sudo -u ec2-user bash -c "..." 형식을 사용하세요.

SageMaker Studio 사용자를 위한 uv venv 방식

SageMaker Studio (사용자: sagemaker-user)에서는 conda 대신 uv venv 방식을 사용합니다.

환경	유저	환경 경로
Notebook Instance	`ec2-user`	`~/SageMaker/.myenv/miniconda/envs/<env>/`
Studio	`sagemaker-user`	`~/.myenv/<theme>/kernel/.venv/`

📋 복사해서 붙여넣기

# Usage: ./gs-env-create-kernel-smus.sh <theme> <python_version> [kernel_name]
./gs-env-create-kernel-smus.sh boilerplate 3.12

ℹ️ Studio에서는 ~/.myenv/가 영구 EFS 볼륨에 마운트되어 있어, 별도의 Lifecycle Configuration 없이도 재시작 후 환경이 유지됩니다.

트러블슈팅

커널이 JupyterLab에 안 보여요

📋 복사해서 붙여넣기

# 커널 목록 확인
jupyter kernelspec list

# 커널이 없으면 수동 재등록
source ~/SageMaker/.myenv/miniconda/etc/profile.d/conda.sh
conda activate ~/SageMaker/.myenv/miniconda/envs/boilerplate312
python -m ipykernel install --user --name=conda_boilerplate312

# JupyterLab 커널 서버 재시작 (콘솔에서)
sudo initctl restart jupyter-server --no-wait

conda 명령어를 찾을 수 없어요

📋 복사해서 붙여넣기

# conda 초기화
source ~/SageMaker/.myenv/miniconda/etc/profile.d/conda.sh
conda init bash
source ~/.bashrc

# 확인
conda --version

패키지 설치 중 "Killed" 에러

메모리 부족으로 프로세스가 죽은 것입니다.

📋 복사해서 붙여넣기

# Swap 재설정
cd ~/SageMaker/gs-ds-env/bin/
./increase_swap_size.sh

# 확인
free -h

전체 설정 체크리스트

☐	단계	확인 방법
☐	`~/SageMaker/gs-ds-env/` repo가 클론됐는가?	`ls ~/SageMaker/gs-ds-env/bin/`
☐	Swap 4G가 활성화됐는가?	`free -h` → Swap 4.0Gi
☐	`create_env.sh` 실행 후 환경이 `~/SageMaker/.myenv/...` 경로에 있는가?	`conda env list`
☐	커널이 `conda_boilerplate312` 이름으로 등록됐는가?	`jupyter kernelspec list`
☐	JupyterLab 커널 선택 메뉴에 보이는가?	JupyterLab UI
☐	Lifecycle Configuration에 `start.sh`가 등록됐는가?	SageMaker 콘솔
☐	인스턴스 재시작 후에도 커널이 살아있는가?	재시작 후 `jupyter kernelspec list`

✅ 영속성의 핵심 원칙: 환경, 코드, 자격증명 모두 ~/SageMaker/ 안에 두세요. 이 경로만 인스턴스 재시작 후에도 살아남습니다.

SageMaker Conda 환경 & 커널 영속성

Conda 커널 영속성 — 심화 가이드

왜 이게 필요한가?

전체 흐름 한눈에 보기

Step 1: 실습 repo 클론 (~/SageMaker 안에)

Step 2: Swap 메모리 설정

Step 3: 환경 생성 — create_env.sh

스크립트 동작 순서 (6단계)

사용법

완료 후 확인

Step 4: 재시작 후 자동 복원 — start.sh

start.sh가 하는 일

Lifecycle Configuration에 등록하기

SageMaker Studio 사용자를 위한 uv venv 방식

트러블슈팅

커널이 JupyterLab에 안 보여요

conda 명령어를 찾을 수 없어요

패키지 설치 중 "Killed" 에러

전체 설정 체크리스트

Step 3: 환경 생성 — `create_env.sh`

Step 4: 재시작 후 자동 복원 — `start.sh`