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

org 및 team 범위의 서비스 계정을 사용하여 자동화된 또는 비대화형 워크플로우 를 관리하세요

서비스 계정은 팀 내의 여러 Projects 또는 여러 Teams 간에 일반적인 작업을 자동으로 수행할 수 있는 비인적(non-human) 또는 머신 사용자를 나타냅니다. 서비스 계정은 CI/CD 파이프라인, 자동화된 트레이닝 잡 및 기타 머신 간 워크플로우에 적합합니다.

​

주요 이점

Key benefits of service accounts:

• No license consumption: Service accounts do not consume user seats or licenses
• Dedicated API keys: Secure credentials for automated workflows
• User attribution: Optionally attribute automated runs to human users
• Enterprise-ready: Built for production automation at scale
• Delegated operations: Service accounts operate on behalf of the user or organization that creates them

​

개요

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

• 조직 범위(Organization-scoped): 조직 관리자가 생성하며, 모든 Teams에 대한 엑세스 권한을 가집니다.
• 팀 범위(Team-scoped): 팀 관리자가 생성하며, 특정 팀으로 엑세스가 제한됩니다.

서비스 계정의 API 키를 사용하면 서비스 계정 범위 내의 Projects를 읽거나 쓸 수 있습니다. 이를 통해 W&B Models의 실험 추적이나 W&B Weave의 트레이스 로깅을 위한 자동화된 워크플로우를 중앙 집중식으로 관리할 수 있습니다.

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

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

서비스 계정은 Dedicated Cloud, 엔터프라이즈 라이선스가 포함된 Self-Managed 인스턴스, 그리고 SaaS Cloud의 엔터프라이즈 계정에서 사용할 수 있습니다.

​

조직 범위 서비스 계정

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

​

조직 범위 서비스 계정 생성하기

To create a new organization-scoped service account and API key:

1. Log in to W&B, click your user profile icon, then:
   • Dedicated Cloud or Self-Managed: Click Organization Dashboard, then click Service Accounts.
   • Multi-tenant Cloud: Click Service Accounts.
2. Click Create service account.
3. Provide a name and select a default team.
4. Click Create.
5. Find the service account you just created.
6. Click the action menu (...), then click Create API key.
7. Provide a name for the API key, then click Create.
8. Copy the API key and store it securely.
9. Click Done.

The full API key is only shown once at creation time. After you close the dialog, you cannot view the full API key again. Only the key ID (first part of the key) is visible in your settings. If you lose the full API key, you must create a new API key.

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

​

팀 범위 서비스 계정

팀 범위 서비스 계정은 해당 팀 내의 제한된 프로젝트(restricted projects)를 제외한 모든 Projects에서 읽고 쓸 수 있습니다. 팀 범위 서비스 계정이 제한된 프로젝트에 엑세스하려면, 해당 프로젝트의 관리자가 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.

​

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

To create a new team-scoped service account and API key:

1. In your team’s settings, click Service Accounts.
2. Click New Team Service Account.
3. Provide a name for the service account.
4. Set Authentication Method to Generate API key (default). If you select Federated Identity, the service account cannot own API keys.
5. Click Create.
6. Find the service account you just created.
7. Click the action menu (...), then click Create API key.
8. Provide a name for the API key, then click Create.
9. Copy the API key and store it securely.
10. Click Done.

The full API key is only shown once at creation time. After you close the dialog, you cannot view the full API key again. Only the key ID (first part of the key) is visible in your settings. If you lose the full API key, you must create a new API key.

​

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

To create an API key owned by a service account:

1. Navigate to the Service Accounts tab in your team or organization settings.
2. Find the service account in the list.
3. Click the action menu (...), then click Create API key.
4. Provide a name for the API key, then click Create.
5. Copy the displayed API key immediately and store it securely.
6. Click Done.

You can create multiple API keys for a single service account to support different environments or workflows.

The full API key is only shown once at creation time. After you close the dialog, you cannot view the full API key again. Only the key ID (first part of the key) is visible in your settings. If you lose the full API key, you must create a new API key.

​

서비스 계정 API 키 삭제하기

To delete an API key owned by an organization or team service account:

1. Go to Organization settings, then click API Keys.
2. Find the API key. The list includes all API keys owned by organization and team service accounts. You can search or filter by key name or ID, and you can sort by any column.
3. Click the delete button.

팀 범위 서비스 계정을 사용하는 모델 트레이닝 또는 생성형 AI 앱 환경에서 팀을 설정하지 않으면, 모델 Runs 또는 Weave 트레이스는 서비스 계정의 상위 팀 내의 지정된 프로젝트로 로그를 남깁니다. 이러한 시나리오에서는 참조된 사용자가 서비스 계정의 상위 팀에 속해 있지 않는 한 WANDB_USERNAME 또는 WANDB_USER_EMAIL 변수를 사용한 사용자 속성(attribution) 기능이 작동하지 않습니다.

팀 범위 서비스 계정은 상위 팀이 아닌 다른 팀의 팀 또는 제한된 범위 프로젝트(team or restricted-scoped project)에는 Runs를 로깅할 수 없지만, 다른 팀 내의 공개 가시성 프로젝트(open visibility project)에는 Runs를 로깅할 수 있습니다.

​

외부 서비스 계정

기본 제공 서비스 계정 외에도, W&B는 JSON Web Tokens(JWT)을 발행할 수 있는 ID 공급자(IdP)와 ID 연동(Identity federation)을 사용하여 W&B SDK 및 CLI에서 팀 범위의 외부 서비스 계정을 지원합니다.

​

모범 사례

조직에서 서비스 계정을 안전하고 효율적으로 사용하려면 다음 권장 사항을 따르세요.

• 비밀 관리자(Secrets manager) 사용: 서비스 계정 API 키를 일반 텍스트 설정 파일 대신 보안 비밀 관리 시스템(예: AWS Secrets Manager, HashiCorp Vault, Azure Key Vault)에 저장하세요.

• 최소 권한 원칙: 가능한 경우 조직 범위 계정 대신 팀 범위 서비스 계정을 생성하여 필요한 Projects로만 엑세스를 제한하세요.

• 유스 케이스별 고유 서비스 계정: 감사 가능성을 높이고 세부적인 엑세스 제어를 가능하게 하려면 다양한 자동화 워크플로우(예: CI/CD용, 정기 재트레이닝용 등)에 대해 별도의 서비스 계정을 생성하세요.

• 정기 감사: 활성 서비스 계정을 주기적으로 검토하고 더 이상 사용하지 않는 계정은 제거하세요. 감사 로그를 확인하여 서비스 계정 활동을 모니터링하세요.

• 안전한 API 키 처리:

  • API 키를 버전 관리 시스템에 절대 커밋하지 마세요.
  • 환경 변수를 사용하여 애플리케이션에 키를 전달하세요.
  • 키가 실수로 노출된 경우 키를 교체(Rotate)하세요.

• 명명 규칙: 서비스 계정의 목적을 나타내는 설명적인 이름을 사용하세요.

  • 권장: ci-model-training, nightly-eval-pipeline, prod-inference-monitor
  • 지양: service-account-1, test-sa, temp

• 사용자 속성(User attribution): 여러 팀 멤버가 동일한 자동화 워크플로우를 사용하는 경우, 각 Run을 누가 트리거했는지 추적하기 위해 WANDB_USERNAME 또는 WANDB_USER_EMAIL을 설정하세요.

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

• 환경 설정: 팀 범위 서비스 계정의 경우, Runs가 올바른 팀으로 로깅되도록 항상 WANDB_ENTITY를 설정하세요.

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

• 오류 처리: 서비스 계정 자격 증명 문제를 신속하게 식별할 수 있도록 인증 실패에 대한 적절한 오류 처리 및 알림을 구현하세요.

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

  • 존재하는 서비스 계정 및 해당 용도
  • 각 서비스 계정을 사용하는 시스템/워크플로우
  • 각 계정을 담당하는 팀의 연락처 정보

​

문제 해결

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

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