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

조직 및 팀 범위의 서비스 계정을 사용하여 자동화 또는 비대화형 워크플로를 관리합니다

서비스 계정은 사람이 아닌 사용자 또는 머신 사용자를 의미하며, 팀 내 여러 프로젝트나 여러 팀에 걸쳐 공통 작업을 자동으로 수행할 수 있습니다. 서비스 계정은 CI/CD 파이프라인, 자동화된 트레이닝 작업, 기타 머신 간 워크플로에 적합합니다.

​

주요 이점

서비스 계정의 주요 이점:

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

​

Overview

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

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

서비스 계정의 API 키를 사용하면 호출자가 서비스 계정 범위 내의 프로젝트에 대해 조회 또는 쓰기 작업을 할 수 있습니다. 이를 통해 W&B Models의 실험 추적이나 W&B Weave의 트레이스 로깅을 위한 자동화 워크플로를 중앙에서 관리할 수 있습니다.

서비스 계정은 특히 다음과 같은 경우에 유용합니다:

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

서비스 계정은 Dedicated Cloud, 엔터프라이즈 라이선스가 있는 Self-Managed instances, 그리고 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 키를 다시 볼 수 없습니다. Settings에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 만들어야 합니다.

조직 범위 서비스 계정은 조직 내 모든 팀이 소유한 Restricted가 아닌 프로젝트에 액세스할 수 있더라도 기본 팀이 필요합니다. 이렇게 하면 모델 트레이닝 또는 생성형 AI 앱의 환경에서 WANDB_ENTITY 변수가 설정되지 않았을 때 워크로드가 실패하는 상황을 방지하는 데 도움이 됩니다. 다른 팀의 프로젝트에 조직 범위 서비스 계정을 사용하려면 WANDB_ENTITY 환경 변수를 해당 팀으로 설정해야 합니다.

​

팀 범위 서비스 계정

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

​

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

새 팀 범위 서비스 계정과 API 키를 만들려면 다음 단계를 따르세요.

1. 팀의 Settings에서 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 키를 다시 볼 수 없습니다. Settings에서는 키 ID(키의 첫 부분)만 확인할 수 있습니다. 전체 API 키를 분실한 경우 새 API 키를 만들어야 합니다.

​

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

서비스 계정 소유의 API 키를 생성하려면 다음 단계를 따르세요.

1. 팀 또는 조직 설정의 Service Accounts 탭으로 이동합니다.
2. 목록에서 서비스 계정을 찾습니다.
3. 작업 () 메뉴를 클릭한 다음 Create API key를 클릭합니다.
4. API 키 이름을 지정한 다음 Create를 클릭합니다.
5. 표시된 API 키를 즉시 복사해 안전한 곳에 저장합니다.
6. Done을 클릭합니다.

서로 다른 환경이나 워크플로를 지원하기 위해 하나의 서비스 계정에 여러 API 키를 생성할 수 있습니다.

전체 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는 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을 설정하세요.

  export WANDB_API_KEY="<service_account_key>"
  export WANDB_USERNAME="[e-mail]"
  

• 환경 설정: 팀 범위 서비스 계정의 경우, run이 올바른 팀에 기록되도록 항상 WANDB_ENTITY를 설정하세요.

  export WANDB_ENTITY="ml-team"
  export WANDB_PROJECT="production-models"
  

• 오류 처리: 인증 실패에 대한 적절한 오류 처리와 알림을 구현하여 서비스 계정 자격 증명 관련 문제를 신속하게 파악하세요.

• 문서화: 다음 사항에 대한 문서를 유지하세요.

  • 어떤 서비스 계정이 존재하는지와 그 목적
  • 각 서비스 계정을 사용하는 시스템/워크플로
  • 각 계정을 담당하는 팀의 연락처 정보

​

문제 해결

일반적인 문제와 해결 방법:

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