Skip to main content
서비스 계정은 사람이 아닌 사용자 또는 머신 사용자를 의미하며, 팀 내 여러 프로젝트나 여러 팀에 걸쳐 공통 작업을 자동으로 수행할 수 있습니다. 서비스 계정은 CI/CD 파이프라인, 자동화된 트레이닝 작업, 기타 머신 간 워크플로에 적합합니다. 이 페이지에서는 서비스 계정에 사용 가능한 범위를 설명하고, 서비스 계정을 생성하고 관리하는 방법을 단계별로 안내하며, 프로덕션 자동화에서 이를 안전하게 사용하기 위한 모범 사례를 간략히 설명합니다. 이 내용은 자동화된 시스템에 대한 자격 증명을 프로비저닝하는 조직 및 팀 관리자를 대상으로 합니다.

​
주요 이점

서비스 계정의 주요 이점:
  • 라이선스 소모 없음: 서비스 계정은 사용자 시트나 라이선스를 소모하지 않습니다.
  • 전용 API 키: 자동화된 워크플로를 위한 안전한 인증 정보.
  • 사용자 귀속: 자동화된 run을 필요에 따라 실제 사용자에게 귀속할 수 있습니다.
  • 엔터프라이즈 환경에 적합: 대규모 프로덕션 자동화를 위해 설계되었습니다.
  • 위임된 오퍼레이션: 서비스 계정은 이를 생성한 사용자 또는 조직을 대신해 오퍼레이션을 수행합니다.

​
Overview

서비스 계정은 개인 사용자 자격 증명이나 하드코딩된 자격 증명을 사용하지 않고도 W&B 워크플로를 안전하게 자동화할 수 있는 방법입니다. 서비스 계정은 다음 두 범위에서 만들 수 있습니다:
  • 조직 범위: 조직 관리자가 생성하며, 모든 팀에 액세스할 수 있습니다.
  • 팀 범위: 팀 관리자가 생성하며, 특정 팀으로 액세스가 제한됩니다.
조직 범위 서비스 계정은 조직 API 키와 다릅니다. 서비스 계정은 자체 키를 보유하는 사람이 아닌 ID입니다. 조직 API 키는 개인에게 속하며 단일 조직 내에서 해당 개인을 인증합니다.
서비스 계정의 API 키를 사용하면 호출자가 서비스 계정 범위 내의 프로젝트에 대해 조회 또는 쓰기 작업을 할 수 있습니다. 이를 통해 W&B Models의 실험 추적이나 W&B Weave의 트레이스 로깅을 위한 자동화 워크플로를 중앙에서 관리할 수 있습니다. 서비스 계정은 다음과 같은 경우에 유용합니다:
  • CI/CD 파이프라인: GitHub Actions, GitLab CI 또는 Jenkins에서 모델 트레이닝 run을 자동으로 기록합니다.
  • 예약 작업: 야간 모델 재트레이닝, 정기적인 Evaluation run, 또는 데이터 검증 워크플로입니다.
  • 프로덕션 모니터링: 프로덕션 시스템에서 Inference 메트릭과 모델 성능을 기록합니다.
  • Jupyter 노트북: JupyterHub 또는 Google Colab 환경의 공유 노트북입니다.
  • Kubernetes 작업: Kubernetes 클러스터에서 실행되는 자동화 워크플로입니다.
  • Airflow/Prefect/Dagster: ML 파이프라인 오케스트레이션 도구입니다.
서비스 계정은 Dedicated Cloud, 엔터프라이즈 라이선스가 있는 Self-Managed instances, 그리고 Multi-tenant Cloud의 엔터프라이즈 계정에서 사용할 수 있습니다.

​
조직 범위 서비스 계정

자동화에서 여러 팀의 프로젝트 전반에 걸쳐 조회하거나 써야 하는 경우 조직 범위 서비스 계정을 사용하세요. 조직 범위 서비스 계정은 제한된 프로젝트를 제외하고, 팀과 관계없이 해당 조직의 모든 프로젝트에 대해 조회 및 쓰기 권한을 가집니다. 조직 범위 서비스 계정이 제한된 프로젝트에 액세스하려면, 해당 프로젝트의 관리자가 먼저 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.

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

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

​
팀 범위 서비스 계정

최소 권한 원칙에 따라 자동화를 단일 팀의 프로젝트로 제한하려는 경우 팀 범위 서비스 계정을 사용하세요. 팀 범위 서비스 계정은 해당 팀의 제한된 프로젝트를 제외한 모든 프로젝트에서 조회 및 쓰기가 가능합니다. 팀 범위 서비스 계정이 제한된 프로젝트에 액세스하려면 해당 프로젝트의 관리자가 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.
Dedicated Cloud 및 Self-Managed v0.83.0+에서는 관리자가 인스턴스에서 GORILLA_DISABLE_TEAM_SERVICE_ACCOUNT_CREATION 환경 변수를 true로 설정하여 팀 범위 서비스 계정 생성을 방지할 수 있습니다. 고급 IAM 설정을 참조하세요.

​
팀 범위 서비스 계정 생성하기

새 팀 범위 서비스 계정과 API 키를 만들려면 다음 단계를 따르세요.
  1. 팀의 Settings에서 Service Accounts를 클릭합니다.
  2. New Team Service Account를 클릭합니다.
  3. 서비스 계정 이름을 입력합니다.
  4. Authentication Method를 Generate API key(기본값)로 설정합니다. Federated Identity를 선택하면 서비스 계정은 API 키를 보유할 수 없습니다.
  5. Create를 클릭합니다.
  6. 만든 서비스 계정을 찾은 다음 해당 액션 () 메뉴를 클릭하고 Create API key를 클릭합니다.
  7. API 키 이름을 입력한 다음 Create를 클릭합니다.
  8. API 키를 복사해 안전한 곳에 저장합니다.
  9. Done을 클릭합니다.
W&B는 전체 API 키를 생성 시점에 한 번만 표시합니다. 대화 상자를 닫으면 전체 API 키를 다시 볼 수 없습니다. Settings에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 만들어야 합니다.

​
서비스 계정용 추가 API 키 만들기

서비스 계정 소유의 API 키를 생성하려면 다음 단계를 따르세요.
  1. 팀 또는 조직 설정에서 Service Accounts 탭으로 이동합니다.
  2. 목록에서 서비스 계정을 찾습니다.
  3. 작업 () 메뉴를 클릭한 다음 Create API key를 클릭합니다.
  4. API 키 이름을 지정한 다음 Create를 클릭합니다.
  5. 표시된 API 키를 즉시 복사해 안전한 곳에 저장합니다.
  6. Done을 클릭합니다.
서로 다른 환경이나 워크플로를 지원하기 위해 하나의 서비스 계정에 여러 API 키를 생성할 수 있습니다.
W&B는 전체 API 키를 생성 시점에 한 번만 표시합니다. 대화 상자를 닫으면 전체 API 키를 다시 볼 수 없습니다. Settings에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 만들어야 합니다.

​
서비스 계정 API 키 삭제

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

​
외부 서비스 계정

W&B 기본 API 키를 직접 관리하는 대신 자체 ID 공급자를 통해 자격 증명을 발급하려면 외부 서비스 계정을 사용하세요. 기본 제공 서비스 계정 외에도, W&B는 JSON Web Token(JWT)을 발급할 수 있는 ID 공급자(IdP)의 Identity federation을 사용해 W&B SDK 및 CLI에서 팀 범위의 외부 서비스 계정을 지원합니다.

​
모범 사례

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

​
문제 해결

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