제어 평면과 함께 배포하기

제어 평면과 함께 배포하기 (Deploy with control plane)

자체호스팅 LangSmith 인스턴스에 Docker 이미지를 빌드하고 제어 평면 UI로 애플리케이션을 배포하는 방법을 설명해요.

출처: 제어 평면과 함께 배포하기 (Deploy with control plane)

안내 — 이 가이드는 인스턴스에서 LangSmith Deployment를 활성화한 자체호스팅 LangSmith 고객을 위한 것입니다. Cloud 고객은 Deploy on Cloud를, 제어 평면 없이 독립형 Agent Server를 원하는 분은 Self-host standalone servers를 보세요.

제어 평면이 있는 자체호스팅 LangSmith 인스턴스로 애플리케이션을 배포하는 방법이에요. 제어 평면이 있으면 Docker 이미지를 로컬에서 빌드하고, Kubernetes 클러스터가 접근할 수 있는 레지스트리에 푸시한 뒤, LangSmith UI로 배포할 수 있습니다.

토폴로지

기존 자체호스팅 LangSmith 인스턴스에서 LangSmith Deployment를 활성화하면 클러스터에 Agent Server를 프로비저닝하는 제어 평면, 데이터 평면 리스너, 오퍼레이터가 추가됩니다. 기본 LangSmith 플랫폼은 옵저버빌리티·평가·프롬프트를 계속 처리하고, 배포된 Agent Server는 트레이스를 그쪽으로 다시 보내요.

LangSmith Deployment 활성화로 추가되는 컴포넌트에 대한 자세한 내용은 Enable LangSmith Deployment를 보세요.

개요

제어 평면이 있는 자체호스팅 LangSmith 인스턴스에 배포되는 애플리케이션은 Docker 이미지를 사용합니다. 이 가이드의 배포 워크플로는 이렇게 진행돼요.

langgraph dev 또는 Studio로 애플리케이션을 로컬에서 테스트해요.
langgraph build 명령으로 Docker 이미지를 빌드합니다.
인프라가 접근할 수 있는 컨테이너 레지스트리에 이미지를 푸시해요.
이미지 URL을 지정해 제어 평면 UI에서 배포합니다.

사전 준비

자체호스팅 LangSmith 인스턴스에서 LangSmith Deployment 활성화
LangSmith Deployment가 활성화된 LangSmith UI 접근 권한
Kubernetes 클러스터가 접근 가능한 컨테이너 레지스트리. 인증이 필요한 프라이빗 레지스트리를 쓰면 인프라 설정의 일부로 이미지 풀 시크릿(image pull secrets)을 구성해야 해요. Private registry authentication 참고.

1단계. 로컬에서 테스트

배포 전에 애플리케이션을 로컬에서 테스트하세요. LangGraph CLI로 개발 모드의 Agent 서버를 실행할 수 있어요.

langgraph dev

로컬 테스트 전체 가이드는 Local server quickstart를 참고해요.

2단계. Docker 이미지 빌드

langgraph build 명령으로 애플리케이션의 Docker 이미지를 빌드합니다.

langgraph build -t my-image

빌드 명령 옵션은 다음과 같아요.

옵션	기본값	설명
`-t, --tag TEXT`	필수	Docker 이미지 태그
`--platform TEXT`		빌드할 대상 플랫폼 (예: `linux/amd64,linux/arm64`)
`--pull / --no-pull`	`--pull`	최신 원격 Docker 이미지로 빌드
`-c, --config FILE`	`langgraph.json`	설정 파일 경로

플랫폼 지정 예시:

langgraph build --platform linux/amd64 -t my-image:v1.0.0

자세한 내용은 CLI reference를 참고하세요.

3단계. 컨테이너 레지스트리에 푸시

Kubernetes 클러스터가 접근할 수 있는 컨테이너 레지스트리에 이미지를 푸시하세요. 구체적인 명령은 레지스트리 제공자에 따라 달라져요.

참고 — 롤백을 쉽게 하려면 이미지에 버전 정보를 태그하세요 (예: my-registry.com/my-app:v1.0.0).

4단계. 제어 평면 UI로 배포

제어 평면 UI는 배포를 만들고·관리하고, 로그와 메트릭을 보고, 구성을 업데이트할 수 있게 해줍니다. LangSmith UI에서 새 배포를 만드는 방법:

왼쪽 내비게이션 패널에서 Deployments를 선택해요.
오른쪽 상단에서 + New Deployment를 선택합니다.
배포 구성 패널에서 다음을 입력하세요.
- Image URL: 3단계에서 푸시한 전체 이미지 URL.
- Listener/Compute ID: 인프라에 대해 구성된 리스너 선택.
- Namespace: 배포할 Kubernetes 네임스페이스.
- Environment variables: 필요한 구성(API 키 등).
- 필요에 따라 기타 배포 설정.
Submit을 선택합니다.

제어 평면은 데이터 평면 리스너와 조율해 애플리케이션을 배포해요.

배포를 만든 뒤 인프라는 비동기적으로 프로비저닝됩니다. 배포는 몇 분까지 걸릴 수 있고, 첫 배포는 데이터베이스 생성 때문에 더 오래 걸려요.

제어 평면 UI에서 빌드 로그, 서버 로그, 그리고 CPU/메모리 사용량·레플리카·API 성능 등 배포 메트릭을 볼 수 있어요. 자세한 내용은 control plane monitoring 문서를 참고하세요.

참고 — 각 배포마다 배포와 같은 이름의 LangSmith Observability 트레이싱 프로젝트가 자동으로 생성됩니다. 트레이싱 환경 변수는 제어 평면이 자동으로 설정해요.

배포 업데이트

새 버전의 애플리케이션을 배포하려면 새 리비전을 만드세요.

LangSmith UI에서:

왼쪽 내비게이션 패널에서 Deployments를 선택해요.
기존 배포를 선택합니다.
Deployment 뷰에서 오른쪽 상단의 + New Revision을 선택해요.
구성을 업데이트합니다.
- Image URL을 새 이미지 버전으로 업데이트.
- 필요하면 환경 변수 업데이트.
- 필요에 따라 다른 설정 조정.
Submit을 선택합니다.

프라이빗 레지스트리 인증

컨테이너 레지스트리가 인증을 요구하면(예: AWS ECR, Azure ACR, GCP Artifact Registry, 프라이빗 Docker 레지스트리), 애플리케이션 배포 전에 Kubernetes 이미지 풀 시크릿을 구성해야 해요. 이는 일회성 인프라 구성입니다.

참고 — 이 구성은 배포별이 아니라 인프라 수준에서 이루어집니다. 한 번 구성하면 모든 배포가 자동으로 레지스트리 자격 증명을 상속받아요.

LangSmith Helm 차트의 values.yaml에서 imagePullSecrets를 구성하세요. 자세한 단계는 Enable LangSmith Deployment 가이드를 참고해요.

레지스트리 제공자별 이미지 풀 시크릿 생성에 대한 자세한 단계는 Kubernetes의 프라이빗 레지스트리 이미지 풀 문서를 참고하세요.

다음 단계

제어 평면 — 제어 평면 기능 자세히.
데이터 평면 — 데이터 평면 아키텍처 이해.
옵저버빌리티 — 자동 트레이싱으로 배포 모니터링.
Studio — 배포된 애플리케이션 테스트·디버깅.
LangGraph CLI — CLI 전체 레퍼런스.

더 알아보기 (Learn more)

제어 평면 없이 가장 가벼운 배포를 원한다면 Self-host standalone servers를 확인하세요.
자체호스팅 전반은 Deploy to self-hosted를 참고하세요.