서비스 계정을 사용하여 워크플로 자동화

서비스 계정은 팀 내 프로젝트 또는 여러 팀에 걸쳐 일반적인 작업을 자동으로 수행할 수 있는 비인간 사용자 또는 머신 사용자를 나타냅니다. 서비스 계정은 CI/CD 파이프라인, 자동화된 트레이닝 작업, 기타 머신 간 워크플로에 적합합니다. 이 페이지에서는 서비스 계정에 사용 가능한 범위, 생성 및 관리 방법, 프로덕션 자동화에서 안전하게 사용하기 위한 권장사항을 설명합니다. 자동화 시스템의 자격 증명을 프로비저닝하는 조직 및 팀 관리자를 대상으로 합니다.

​

키 이점

서비스 계정의 주요 이점:

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

​

개요

서비스 계정을 사용하면 개인 사용자 자격 증명이나 하드코딩된 자격 증명 없이도 W&B 워크플로를 안전하게 자동화할 수 있습니다. 서비스 계정은 두 가지 범위에서 생성할 수 있습니다.

• 조직 범위: 조직 관리자가 생성하며, 모든 팀에 액세스할 수 있습니다.
• 팀 범위: 팀 관리자가 생성하며, 특정 팀에만 액세스할 수 있습니다.

서비스 계정의 API 키를 사용하면 호출자가 서비스 계정 범위 내의 프로젝트에서 데이터를 조회하거나 쓸 수 있습니다. 이를 통해 W&B Models의 실험 추적이나 W&B Weave의 트레이스 로깅을 위한 자동화된 워크플로를 중앙에서 관리할 수 있습니다. 서비스 계정은 다음과 같은 경우에 유용합니다.

• CI/CD 파이프라인: GitHub Actions, GitLab CI 또는 Jenkins에서 모델 트레이닝 run을 자동으로 로깅합니다.
• 예약된 작업: 야간 모델 재트레이닝, 주기적인 평가 run 또는 데이터 검증 워크플로.
• 프로덕션 모니터링: 프로덕션 시스템의 추론 메트릭과 모델 성능을 로깅합니다.
• Jupyter 노트북: JupyterHub 또는 Google Colab 환경의 공유 노트북.
• Kubernetes 작업: Kubernetes 클러스터에서 실행되는 자동화된 워크플로.
• Airflow/Prefect/Dagster: ML 파이프라인 오케스트레이션 도구.

​

조직 범위 서비스 계정

자동화가 여러 팀의 프로젝트 전반에 걸쳐 조회하거나 쓰기가 필요할 때 조직 범위 서비스 계정을 사용하세요. 조직 범위 서비스 계정은 팀과 관계없이 조직 내 모든 프로젝트에서 조회하고 쓸 수 있는 권한을 가집니다. 단, 제한된 프로젝트는 예외입니다. 조직 범위 서비스 계정이 제한된 프로젝트에 액세스하려면 먼저 해당 프로젝트의 Admin이 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.

​

조직 범위 서비스 계정 생성

조직 범위의 service account와 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. 방금 생성한 service account를 찾아 action () 메뉴를 클릭한 다음 Create API key를 클릭하세요.
7. API 키의 이름을 입력한 다음 Create를 클릭하세요.
8. API 키를 복사하여 안전하게 보관하세요.
9. Done을 클릭하세요.

​

팀 범위 서비스 계정

최소 권한 원칙에 따라 자동화 범위를 단일 팀의 프로젝트로 제한하려면 팀 범위 서비스 계정을 사용하세요. 팀 범위 서비스 계정은 소속 팀의 모든 프로젝트에서 조회 및 쓰기를 할 수 있지만, 해당 팀의 제한된 프로젝트는 예외입니다. 팀 범위 서비스 계정이 제한된 프로젝트에 액세스하려면 먼저 해당 프로젝트의 Admin이 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.

​

팀 범위 서비스 계정 만들기

새로운 팀 범위 서비스 계정과 API 키를 생성하려면:

1. 팀 설정에서 Service Accounts를 클릭합니다.
2. New Team Service Account를 클릭합니다.
3. 서비스 계정의 이름을 입력합니다.
4. Authentication Method를 Generate API key로 설정합니다(기본값). Federated Identity를 선택하면 서비스 계정이 API 키를 소유할 수 없습니다.
5. Create를 클릭합니다.
6. 생성한 서비스 계정을 찾아 action () 메뉴를 클릭한 다음 Create API key를 클릭합니다.
7. API 키의 이름을 입력한 다음 Create를 클릭합니다.
8. API 키를 복사하여 안전하게 보관합니다.
9. Done을 클릭합니다.

​

서비스 계정의 추가 API 키 생성

서비스 계정이 소유하는 API 키를 생성하려면 다음을 수행하세요.

1. 팀 또는 조직 설정에서 Service Accounts 탭으로 이동하세요.
2. 목록에서 해당 서비스 계정을 찾으세요.
3. 액션() 메뉴를 클릭한 다음 Create API key를 클릭하세요.
4. API 키의 이름을 입력한 다음 Create를 클릭하세요.
5. 표시된 API 키를 즉시 복사하여 안전한 곳에 보관하세요.
6. Done을 클릭하세요.

환경이나 워크플로별로 사용할 수 있도록 하나의 서비스 계정에 여러 API 키를 생성할 수 있습니다.

​

서비스 계정 API 키 삭제

조직 또는 팀 서비스 계정이 소유한 API 키를 삭제하려면:

1. Organization settings로 이동한 다음 API Keys를 클릭하세요.
2. API 키를 찾으세요. 목록에는 조직 및 팀 서비스 계정이 소유한 모든 API 키가 포함됩니다. 키 이름이나 ID로 검색하거나 필터링할 수 있으며, 모든 열로 정렬할 수 있습니다.
3. 삭제 버튼을 클릭하세요.

팀 범위 서비스 계정을 사용하는 모델 트레이닝 또는 생성형 AI 앱 환경에서 팀을 설정하지 않으면, 모델 run 또는 Weave 트레이스가 서비스 계정의 상위 팀에 있는 지정된 프로젝트에 로깅됩니다. 이 경우 참조된 사용자가 서비스 계정의 상위 팀에 속하지 않으면 WANDB_USERNAME 또는 WANDB_USER_EMAIL 변수를 통한 사용자 귀속이 작동하지 않습니다.

​

외부 서비스 계정

W&B 기본 API 키를 관리하는 대신 자체 ID 공급자를 통해 자격 증명을 발급하려면 외부 서비스 계정을 사용하세요. W&B는 기본 제공 서비스 계정 외에도 JSON Web Token(JWT)을 발급하는 ID 공급자(IdP)와의 ID 페더레이션을 통해 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
• 사용자 귀속: 여러 팀 구성원이 동일한 자동화 워크플로를 사용하는 경우 WANDB_USERNAME 또는 WANDB_USER_EMAIL을 설정하여 각 run을 누가 트리거했는지 추적하세요.
  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 키가 올바르게 설정되었는지, 서비스 계정이 대상 프로젝트에 액세스할 수 있는지 확인하세요.
• run이 표시되지 않음: WANDB_ENTITY가 올바른 팀 이름으로 설정되었는지 확인하세요.
• 사용자 귀속이 작동하지 않음: WANDB_USERNAME에 지정된 사용자가 팀의 구성원인지 확인하세요.
• 제한된 프로젝트에 대한 액세스 거부: 서비스 계정을 제한된 프로젝트의 액세스 목록에 명시적으로 추가하세요.