메인 콘텐츠로 건너뛰기
서비스 계정은 팀 내 여러 프로젝트나 여러 팀에 걸쳐 반복적인 작업을 자동으로 수행하는 사람이 아닌 머신 사용자 계정입니다. 서비스 계정은 CI/CD 파이프라인, 자동화된 트레이닝 작업, 기타 머신 간 워크플로에 특히 적합합니다.

​
주요 이점

서비스 계정의 주요 이점:
  • 라이선스 소모 없음: 서비스 계정은 사용자 좌석이나 라이선스를 소모하지 않습니다.
  • 전용 API 키: 자동화 워크플로를 위한 보안 자격 증명.
  • 사용자 귀속: 자동화된 run을 특정 사람 사용자에게 선택적으로 연결할 수 있습니다.
  • 엔터프라이즈 준비 완료: 대규모 프로덕션 자동화를 위해 설계되었습니다.
  • 위임된 작업: 서비스 계정은 이를 생성한 사용자 또는 조직을 대신해 작업을 수행합니다.

​
개요

서비스 계정은 개인 사용자 자격 증명이나 하드코딩된 자격 증명을 사용하지 않고도 W&B 워크플로를 자동화할 수 있는 안전한 방법을 제공합니다. 서비스 계정은 두 가지 범위에서 생성할 수 있습니다:
  • 조직 범위(Organization-scoped): 조직 관리자가 생성하며, 모든 팀에 대한 접근 권한을 가집니다.
  • 팀 범위(Team-scoped): 팀 관리자가 생성하며, 특정 팀으로 접근이 제한됩니다.
서비스 계정의 API 키를 사용하면 호출자는 서비스 계정의 범위 내에서 프로젝트를 읽거나 쓸 수 있습니다. 이를 통해 W&B Models에서 실험 추적을 위한 자동화 워크플로를 중앙에서 관리하거나 W&B Weave에서 트레이스를 기록할 수 있습니다. 서비스 계정은 다음과 같은 경우에 특히 유용합니다:
  • CI/CD 파이프라인: GitHub Actions, GitLab CI, Jenkins에서 모델 트레이닝 run을 자동으로 기록
  • 스케줄된 작업: 야간 모델 재트레이닝, 주기적인 평가 run, 데이터 검증 워크플로
  • 프로덕션 모니터링: 프로덕션 시스템에서 추론 메트릭과 모델 성능을 기록
  • Jupyter 노트북: JupyterHub 또는 Google Colab 환경에서 공유 노트북
  • Kubernetes 작업: K8s 클러스터에서 실행되는 자동화 워크플로
  • Airflow/Prefect/Dagster: ML 파이프라인 오케스트레이션 도구
서비스 계정은 Dedicated Cloud, 엔터프라이즈 라이선스를 사용하는 Self-Managed 인스턴스, 그리고 Multi-tenant Cloud의 엔터프라이즈 계정에서 사용할 수 있습니다.

​
조직 범위 서비스 계정

조직 범위 서비스 계정은 팀과 관계없이 조직 내 모든 프로젝트에 대해, 제한된 프로젝트를 제외하고 읽기 및 쓰기 권한을 가집니다. 조직 범위 서비스 계정이 제한된 프로젝트에 액세스하려면 해당 프로젝트의 관리자가 서비스 계정을 해당 프로젝트에 명시적으로 추가해야 합니다.

​
조직 범위의 서비스 계정 생성

조직 범위의 새 서비스 계정과 API 키를 생성하려면 다음 단계를 따르세요.
  1. W&B에 로그인하고 사용자 프로필 아이콘을 클릭한 다음:
    • Dedicated Cloud 또는 Self-Managed: Organization Dashboard를 클릭한 후 Service Accounts를 클릭합니다.
    • Multi-tenant Cloud: Service Accounts를 클릭합니다.
  2. Create service account를 클릭합니다.
  3. 이름을 입력하고 기본 팀을 선택합니다.
  4. Create를 클릭합니다.
  5. 방금 생성한 서비스 계정을 찾습니다.
  6. 작업 메뉴(...)를 클릭한 다음 Create API key를 클릭합니다.
  7. API 키 이름을 입력한 후 Create를 클릭합니다.
  8. API 키를 복사하여 안전한 위치에 보관합니다.
  9. Done을 클릭합니다.
전체 API 키는 생성할 때만 한 번 표시됩니다. 대화 상자를 닫으면 전체 API 키를 다시 볼 수 없습니다. 설정에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 생성해야 합니다.
조직 범위 서비스 계정은 조직 내 모든 팀이 소유한, 제한이 없는 프로젝트에 액세스할 수 있지만 기본 팀이 반드시 필요합니다. 이는 모델 트레이닝이나 생성형 AI 앱을 위해 환경에 WANDB_ENTITY 변수가 설정되어 있지 않더라도 워크로드가 실패하지 않도록 하기 위함입니다. 다른 팀의 프로젝트에 대해 조직 범위 서비스 계정을 사용하려면 해당 팀을 가리키도록 WANDB_ENTITY 환경 변수를 설정해야 합니다.

​
팀 범위 서비스 계정

팀 범위 서비스 계정은 소속 팀 내의 모든 프로젝트에서, 해당 팀의 제한된 프로젝트를 제외하고 읽기 및 쓰기 작업을 수행할 수 있습니다. 팀 범위 서비스 계정이 제한된 프로젝트에 액세스하려면, 해당 프로젝트의 관리자가 서비스 계정을 그 프로젝트에 명시적으로 추가해야 합니다.

​
Team 범위 서비스 계정 생성

팀 단위의 새 서비스 계정과 API 키를 생성하려면:
  1. 팀 설정에서 Service Accounts를 클릭합니다.
  2. New Team Service Account를 클릭합니다.
  3. 서비스 계정 이름을 입력합니다.
  4. Authentication Method를 기본값인 Generate API key로 설정합니다. Federated Identity를 선택하면 이 서비스 계정은 API 키를 소유할 수 없습니다.
  5. Create를 클릭합니다.
  6. 방금 생성한 서비스 계정을 찾습니다.
  7. 작업 메뉴(...)를 클릭한 다음 Create API key를 클릭합니다.
  8. API 키 이름을 입력하고 Create를 클릭합니다.
  9. API 키를 복사하여 안전한 위치에 보관합니다.
  10. Done을 클릭합니다.
전체 API 키는 생성할 때만 한 번 표시됩니다. 대화 상자를 닫으면 전체 API 키를 다시 볼 수 없습니다. 설정에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 생성해야 합니다.

​
서비스 계정에 대한 추가 API 키 생성

서비스 계정 소유의 API 키를 생성하려면:
  1. 팀이나 조직 설정에서 Service Accounts 탭으로 이동합니다.
  2. 목록에서 서비스 계정을 찾습니다.
  3. 작업 메뉴(...)를 클릭한 다음 Create API key를 클릭합니다.
  4. API 키 이름을 입력한 후 Create를 클릭합니다.
  5. 표시된 API 키를 바로 복사하여 안전하게 보관합니다.
  6. Done을 클릭합니다.
하나의 서비스 계정에 대해 여러 개의 API 키를 생성하여 서로 다른 환경이나 워크플로에 사용할 수 있습니다.
전체 API 키는 생성할 때만 한 번 표시됩니다. 대화 상자를 닫으면 전체 API 키를 다시 볼 수 없습니다. 설정에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 생성해야 합니다.

​
서비스 계정 API 키 삭제

조직 또는 팀 서비스 계정이 소유한 API 키를 삭제하려면 다음 단계를 따르세요:
  1. Organization settings으로 이동한 후 API Keys를 클릭합니다.
  2. API 키를 찾습니다. 이 목록에는 조직 및 팀 서비스 계정이 소유한 모든 API 키가 포함됩니다. 키 이름이나 ID로 검색하거나 필터링할 수 있으며, 원하는 열을 기준으로 정렬할 수 있습니다.
  3. 삭제 버튼을 클릭합니다.
팀 범위 서비스 계정을 사용하는 모델 트레이닝 또는 생성형 AI 앱 환경에서 팀을 설정하지 않으면, 모델 run 또는 Weave trace는 서비스 계정의 상위 팀 내 지정된 프로젝트에 기록됩니다. 이러한 상황에서는 참조된 사용자가 서비스 계정 상위 팀의 구성원이 아닌 이상, WANDB_USERNAME 또는 WANDB_USER_EMAIL 변수를 사용한 사용자 귀속은 동작하지 않습니다.
팀 범위 서비스 계정은 상위 팀과 다른 팀에 속한 팀 또는 제한 범위 프로젝트에는 run을 기록할 수 없지만, 다른 팀의 공개 가시성 프로젝트에는 run을 기록할 수 있습니다.

​
외부 서비스 계정

내장 서비스 계정 외에도 W&B는 JSON Web Token(JWT)을 발급할 수 있는 IdP(Identity Provider)와의 Identity federation을 통해 W&B SDK와 CLI에서 팀 범위 외부 서비스 계정도 지원합니다.

​
모범 사례

조직에서 서비스 계정을 안전하고 효율적으로 사용하려면 다음 권장 사항을 따르세요:
  • 시크릿 관리 도구 사용: 서비스 계정 API 키는 일반 텍스트 설정 파일에 두지 말고, (예: AWS Secrets Manager, HashiCorp Vault, Azure Key Vault 같은) 안전한 시크릿 관리 시스템에 저장하세요.
  • 최소 권한 원칙: 필요한 프로젝트에만 액세스를 제한할 수 있도록, 가능하면 조직 범위 계정이 아니라 팀 범위 서비스 계정을 생성하세요.
  • 사용 사례별 고유 서비스 계정: 감사를 용이하게 하고 세분화된 액세스 제어를 가능하게 하기 위해, 서로 다른 자동화 워크플로(예: 하나는 CI/CD용, 다른 하나는 정기적인 재트레이닝용)에 대해 별도의 서비스 계정을 생성하세요.
  • 정기 감사: 활성 서비스 계정을 주기적으로 검토하고 더 이상 사용하지 않는 계정은 제거하세요. 감사 로그를 확인하여 서비스 계정 활동을 모니터링하세요.
  • API 키 안전하게 처리:
    • API 키를 절대 버전 관리 시스템에 커밋하지 마세요
    • 애플리케이션에 키를 전달할 때는 환경 변수를 사용하세요
    • 키가 실수로 노출된 경우 키를 로테이션하세요
  • 네이밍 규칙: 서비스 계정의 목적을 나타내는 설명적인 이름을 사용하세요:
    • 권장: ci-model-training, nightly-eval-pipeline, prod-inference-monitor
    • 피해야 할 예: service-account-1, test-sa, temp
  • 사용자 추적: 여러 팀원이 동일한 자동화 워크플로를 사용하는 경우, 각 run이 누가 트리거했는지 추적할 수 있도록 WANDB_USERNAME 또는 WANDB_USER_EMAIL을 설정하세요: 
    export WANDB_API_KEY="<service_account_key>"
export WANDB_USERNAME="john.doe@company.com"
  • 환경 설정: 팀 범위 서비스 계정의 경우, run이 올바른 팀에 로깅되도록 항상 WANDB_ENTITY를 설정하세요: 
    export WANDB_ENTITY="ml-team"
export WANDB_PROJECT="production-models"
  • 오류 처리: 서비스 계정 자격 증명 관련 문제를 신속히 파악할 수 있도록, 인증 실패에 대한 적절한 오류 처리와 알림을 구현하세요.
  • 문서화: 다음 내용을 문서로 관리하세요:
    • 어떤 서비스 계정이 존재하는지와 각 계정의 목적
    • 각 서비스 계정을 사용하는 시스템/워크플로
    • 각 계정을 담당하는 팀의 연락처 정보

​
문제 해결

일반적인 문제와 해결 방법:
  • “Unauthorized” 오류: API 키가 올바르게 설정되어 있고 서비스 계정에 대상 프로젝트에 대한 액세스 권한이 있는지 확인하세요.
  • Runs가 표시되지 않음: WANDB_ENTITY가 올바른 팀 이름으로 설정되어 있는지 확인하세요.
  • 사용자 연결이 작동하지 않음: WANDB_USERNAME에 지정된 사용자가 해당 팀의 구성원인지 확인하세요.
  • 제한된 프로젝트에 대한 액세스가 거부됨: 서비스 계정을 해당 제한된 프로젝트의 액세스 목록에 명시적으로 추가하세요.