Mission Control 설치

Mission Control 설치 (Install Mission Control)

자체호스팅 LangSmith를 Kubernetes에서 모니터링·구성·운영하기 위한 인-클러스터 콘솔인 Mission Control 설치 방법을 설명해요.

출처: Mission Control 설치 (Install Mission Control)

Mission Control은 Kubernetes에서 LangSmith를 모니터링·구성·운영하기 위한 인-클러스터 콘솔입니다. 클러스터 안에서 실행되고 기본적으로 kubectl port-forward로 접근하므로 인그레스가 필요 없어요.

설치 경로는 두 가지입니다.

경로	적합한 경우
빠른 설치	검토된 셸 설치 프로그램을 실행할 수 있고 가장 짧은 설정을 원하는 고객
수동 설치	설치 프로그램 스크립트를 허용하지 않거나 모든 Kubernetes 명령을 검토해야 하는 조직

공개 설치 자산은 다음과 같아요.

install-script.sh: prereqs, namespace, secret, values, install, forward 단계를 각각 분리한 단일 설치 프로그램.
values.yaml: 포트 포워딩 전용 설치를 위한 기본 Helm values.

Mission Control 이미지는 두 개의 Docker Hub 저장소(langchain/mission-control-backend, langchain/mission-control-frontend)에 게시됩니다. 최신 이미지는 다음으로 확인할 수 있어요.

docker pull langchain/mission-control-backend:latest
docker pull langchain/mission-control-frontend:latest

브라우저 검토 링크:

https://github.com/langchain-ai/helm/tree/main/charts/mission-control/install-script.sh
https://github.com/langchain-ai/helm/tree/main/charts/mission-control/values.yaml

아래 명령은 curl이 파일을 직접 내려받을 수 있도록 raw GitHub URL을 사용합니다. 이 파일들을 다른 저장소나 브랜치에서 게시한다면 아래 raw 기본 URL을 바꾸세요.

MC_RAW_BASE=https://raw.githubusercontent.com/langchain-ai/helm/main/charts/mission-control

사전 준비

도구	최소 버전	설치 예
`kubectl`	1.24+	`brew install kubectl`
`helm`	3.x	`brew install helm`
`curl`	최신 버전	보통 사전 설치됨

설치 프로그램은 LangSmith가 설치된(또는 설치될) Kubernetes 클러스터에 대해 실행해야 해요. 계속하기 전에 활성 컨텍스트를 확인하세요.

kubectl config current-context

설치 프로그램 아이덴티티에는 Mission Control 네임스페이스 리소스와 클러스터 범위 RBAC를 만들 권한이 필요합니다.

kubectl auth can-i create clusterrole
kubectl auth can-i create clusterrolebinding
kubectl auth can-i create serviceaccount -n langsmith
kubectl auth can-i create deployment -n langsmith
kubectl auth can-i create secret -n langsmith

다섯 명령 모두 yes를 반환해야 해요. Mission Control에 부여되는 런타임 권한은 Permissions reference를 참고하세요.

빠른 설치

다음 세 명령을 실행하세요.

curl -fsSLO https://raw.githubusercontent.com/langchain-ai/helm/main/charts/mission-control/install-script.sh && chmod +x install-script.sh
curl -fsSL https://raw.githubusercontent.com/langchain-ai/helm/main/charts/mission-control/values.yaml -o values.yaml
./install-script.sh all -f values.yaml

all 단계는 다음을 수행합니다.

필수 도구와 RBAC 검사.
langsmith 네임스페이스 생성.
Mission Control 사용자 이름·비밀번호 입력 요청.
해당 자격 증명을 mission-control-auth Kubernetes Secret에 저장.
values.yaml이 없으면 작성.
로컬 차트 체크아웃이 아닌 경우 공개 Helm 차트 저장소에서 설치.
Helm으로 Mission Control 설치.

RBAC 검사는 다음을 실행합니다.

kubectl auth can-i create clusterrole
kubectl auth can-i create clusterrolebinding
kubectl auth can-i create serviceaccount -n langsmith
kubectl auth can-i create deployment -n langsmith
kubectl auth can-i create secret -n langsmith

조직이 의도적으로 kubectl auth can-i를 차단하지만 Helm 설치는 다른 통제 경로로 승인된다면 다음을 실행하세요.

./install-script.sh all -f values.yaml --skip-rbac-check

UI 접근

설치가 끝나면 로컬 포트 포워딩을 시작해요.

./install-script.sh forward

http://localhost:3000을 열고 입력한 사용자 이름과 비밀번호로 로그인하세요.

스크립트 먼저 검토하기

빠른 설치 경로는 실행 전에 스크립트를 내려받으므로, 세 번째 명령 전에 install-script.sh를 로컬에서 검토할 수 있어요.

설치 전 values 편집

빠른 설치 경로는 설치 프로그램 실행 전에 values.yaml도 내려받습니다. 네임스페이스, 리소스, 인그레스, 기능 플래그, 진단 지속성 등을 바꿔야 한다면 세 번째 명령 전에 그 파일을 검토·편집하세요.

흔한 편집:

설정	언제 바꾸는가
`namespace`	`langsmith`가 아닌 다른 곳에 설치할 때. 스크립트에도 `-n <namespace>`를 전달.
`resources`	네임스페이스에 `ResourceQuota`가 있거나 플랫폼이 특정 requests/limits를 요구할 때.
`ingress.enabled`와 `ingress.host`	포트 포워딩 대신 인그레스 컨트롤러로 Mission Control을 노출하려 할 때.
`config.features.*`	특정 쓰기 권한이나 외부 이그레스 기능을 제거해야 할 때.
`diagnostics.persistence.enabled`	진단 번들이 파드 재시작·Helm 업그레이드를 견디길 원할 때.
`backend.podSecurityContext`와 `frontend.podSecurityContext`	플랫폼이 컨테이너를 `1001` 같은 특정 비root UID로 실행하길 요구할 때.

커스텀 네임스페이스 예:

curl -fsSLO https://raw.githubusercontent.com/langchain-ai/helm/main/charts/mission-control/install-script.sh && chmod +x install-script.sh
curl -fsSL https://raw.githubusercontent.com/langchain-ai/helm/main/charts/mission-control/values.yaml -o values.yaml
./install-script.sh all -n mission-control -f values.yaml

스크립트 명령 레퍼런스

./install-script.sh prereqs
./install-script.sh namespace
./install-script.sh secret
./install-script.sh values
./install-script.sh install
./install-script.sh forward
./install-script.sh all

유용한 플래그:

./install-script.sh all -n langsmith -f values.yaml
./install-script.sh all -u admin
printf '%s\n' 'your-password' | ./install-script.sh secret -u admin --password-stdin
./install-script.sh all -f values.yaml --skip-rbac-check
./install-script.sh install --chart-ref langchain/mission-control
./install-script.sh install --chart-path /path/to/mission-control
./install-script.sh forward --port 3001:3000

수동 설치

설치 프로그램 스크립트가 허용되지 않을 때 이 경로를 사용하세요. 다음 단계는 일반 kubectl, helm, curl 명령만 사용합니다.

1단계. Helm 저장소 추가 및 values 파일 가져오기

LangChain Helm 저장소를 추가해요.

helm repo add langchain https://langchain-ai.github.io/helm
helm repo update langchain

고객 values 파일을 내려받습니다.

curl -fsSL https://raw.githubusercontent.com/langchain-ai/helm/main/charts/mission-control/values.yaml -o values.yaml

설치 전에 values.yaml을 검토하세요. 운영에서는 config.auth.enabled: true를 유지합니다.

플랫폼이 비root 컨테이너를 요구하면 Mission Control을 UID 1001로 실행할 수 있어요. 설치 전에 values.yaml에 다음을 추가하세요.

backend:
  podSecurityContext:
    runAsNonRoot: true
    runAsUser: 1001
    runAsGroup: 1001
    fsGroup: 1001
  securityContext:
    allowPrivilegeEscalation: false
    capabilities:
      drop:
        - ALL
  extraEnv:
    - name: HOME
      value: /tmp
    - name: HELM_CACHE_HOME
      value: /tmp/.cache/helm
    - name: HELM_CONFIG_HOME
      value: /tmp/.config/helm
    - name: HELM_DATA_HOME
      value: /tmp/.local/share/helm

frontend:
  podSecurityContext:
    runAsNonRoot: true
    runAsUser: 1001
    runAsGroup: 1001
  securityContext:
    allowPrivilegeEscalation: false
    capabilities:
      drop:
        - ALL

2단계. 네임스페이스 생성

kubectl create namespace langsmith --dry-run=client -o yaml | kubectl apply -f -

3단계. 인증 자격 증명 Secret 생성

자격 증명은 Kubernetes Secret에 저장됩니다. values.yaml에는 기록되지 않아요.

read -r -p "Username: " MC_USER
read -r -s -p "Password: " MC_PASS; echo

kubectl create secret generic mission-control-auth \
  --namespace=langsmith \
  --from-literal=username="$MC_USER" \
  --from-literal=password="$MC_PASS" \
  --dry-run=client -o yaml | kubectl apply -f -

멀티 레플리카 백엔드 배포에서는 같은 Secret에 공유 JWT 서명 키를 포함하고 values.yaml에 config.auth.jwtSecretKey: jwtSecret을 설정하세요.

JWT_SECRET="$(openssl rand -base64 32)"

kubectl create secret generic mission-control-auth \
  --namespace=langsmith \
  --from-literal=username="$MC_USER" \
  --from-literal=password="$MC_PASS" \
  --from-literal=jwtSecret="$JWT_SECRET" \
  --dry-run=client -o yaml | kubectl apply -f -

4단계. Helm으로 설치

helm upgrade --install mission-control langchain/mission-control \
  --namespace langsmith \
  --create-namespace \
  --values values.yaml \
  --rollback-on-failure

두 워크로드가 준비될 때까지 기다리세요 (백엔드는 StatefulSet, 프론트엔드는 Deployment로 실행):

kubectl rollout status statefulset/mission-control-backend -n langsmith
kubectl rollout status deployment/mission-control-frontend -n langsmith

파드를 직접 확인할 수도 있어요.

kubectl get pods -n langsmith

5단계. UI 접근

kubectl port-forward svc/mission-control-frontend 3000:3000 -n langsmith

http://localhost:3000을 열고 3단계의 자격 증명으로 로그인하세요.

업그레이드

최신 공개 values 파일을 내려받고 필요한 로컬 변경을 병합한 뒤 다음을 실행하세요.

helm repo update langchain

helm upgrade --install mission-control langchain/mission-control \
  --namespace langsmith \
  --values values.yaml \
  --rollback-on-failure

로컬 차트 체크아웃에서 작업한다면:

helm upgrade --install mission-control . \
  --namespace langsmith \
  --values values.yaml \
  --rollback-on-failure

빠른 스크립트로 설치했고 로컬에 유지 중이라면:

./install-script.sh install -f values.yaml

제거

helm uninstall mission-control -n langsmith

이 명령은 Mission Control 릴리스만 제거합니다. 네임스페이스나 관련 없는 LangSmith 리소스는 삭제하지 않아요.

Mission Control이 소유한 Secret의 선택적 정리:

kubectl delete secret -n langsmith \
  mission-control-auth \
  mission-control-draft \
  mission-control-deployed \
  mission-control-backup \
  mission-control-history \
  mission-control-alerts-config \
  mission-control-alerts-log \
  mission-control-alerts-key \
  mission-control-setup-token \
  --ignore-not-found

추가 자료

트러블슈팅

증상	확인할 것
`kubectl auth can-i ...`가 `no` 반환	클러스터 관리자에게 설치용 RBAC 부여를 요청하거나 대신 설치를 수행하도록 한다.
파드가 계속 `Pending`	`kubectl describe pod -n langsmith <pod>`로 네임스페이스 `ResourceQuota`, 노드 용량, PVC/storage class 이벤트를 확인.
이미지 풀 오류	클러스터가 `langchain/mission-control-backend:latest`와 `langchain/mission-control-frontend:latest`를 풀 수 있는지 확인.
로그인 실패	같은 네임스페이스에 `mission-control-auth`가 있고 `username`·`password` 키가 있는지 확인.
브라우저 연결 불가	포트 포워딩 명령이 계속 실행 중이고 다른 로컬 프로세스가 포트 `3000`을 쓰지 않는지 확인.

권한 레퍼런스

Helm 차트는 mission-control이라는 ServiceAccount, ClusterRole, ClusterRoleBinding을 만듭니다. 대부분의 권한은 읽기 전용이에요. 쓰기 동사는 좁고 기능 플래그로 제어됩니다.

설치·업그레이드에는 클러스터 범위 RBAC(ClusterRole, ClusterRoleBinding)를 만드는 능력이 필요하며, 보통 cluster-admin 또는 그에 준하는 커스텀 권한이 필요합니다. 가장 넓은 런타임 권한 집합은 config.features.deploy: true일 때만 사용됩니다. 이 플래그는 기본으로 활성화되어 있어요. 읽기 전용 설치는 false로 설정하세요.

항상 존재하는 읽기 전용 권한

리소스 그룹	리소스	동사
워크로드	pods, pods/log, deployments, statefulsets, replicasets, daemonsets, jobs, cronjobs	get, list, watch
네트워킹	services, endpoints, ingresses, ingressclasses	get, list, watch
저장소	persistentvolumeclaims, storageclasses	get, list, watch
클러스터	nodes, namespaces, events, serviceaccounts, resourcequotas	get, list, watch
구성	configmaps, secrets	get, list
메트릭	metrics.k8s.io pods/nodes	get, list, watch
RBAC	roles, rolebindings, clusterroles, clusterrolebindings	get, list, watch
CRD·확장	customresourcedefinitions, leases, scaledobjects, httproutes, virtualservices, lgps	get, list, watch

기능 게이트 권한

기능 플래그	리소스	추가 동사
`config.features.configSave`	secrets (`mission-control-draft`)	create, update, delete
`config.features.alerts`	secrets (`mission-control-alerts-*`)	create, update, delete
`config.features.fixIssue`	pods	delete
`config.features.adopt`	secrets, configmaps, serviceaccounts, deployments, statefulsets	patch
`config.auth.enabled`	secrets (`mission-control-auth`, setup-token), backend statefulset	create, update, delete, patch
`config.features.valuesOverride`	secrets (`mission-control-values-overrides`)	create, update, delete
`config.features.deploy`	workloads, networking, RBAC, CRDs, Helm release secrets	create, update, patch, delete

values.yaml에서 기능 플래그를 false로 설정하면 해당 쓰기 동사가 제거됩니다. 모든 기능 플래그를 비활성화하면 config.auth.enabled: true의 인증 설정 권한을 제외하고 Mission Control은 실질적으로 읽기 전용이 돼요.

더 알아보기 (Learn more)

자체호스팅 LangSmith 전반은 Self-hosted LangSmith를 참고하세요.
Kubernetes 설정은 Kubernetes setup 가이드를 확인하세요.