> ## Documentation Index > Fetch the complete documentation index at: https://wb-21fd5541-mintlify-8476678c.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > 조직 및 팀 범위의 서비스 계정을 사용하여 자동화 또는 비대화형 워크플로를 관리합니다 # 서비스 계정을 사용해 워크플로 자동화하기 서비스 계정은 사람이 아닌 사용자 또는 머신 사용자를 의미하며, 팀 내 여러 프로젝트나 여러 팀에 걸쳐 공통 작업을 자동으로 수행할 수 있습니다. 서비스 계정은 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 작업**: Kubernetes 클러스터에서 실행되는 자동화 워크플로입니다. * **Airflow/Prefect/Dagster**: ML 파이프라인 오케스트레이션 도구입니다. 서비스 계정은 [Dedicated Cloud](/ko/platform/hosting/hosting-options/dedicated-cloud), 엔터프라이즈 라이선스가 있는 [Self-Managed instances](/ko/platform/hosting/hosting-options/self-managed), 그리고 [Multi-tenant Cloud](/ko/platform/hosting/hosting-options/multi_tenant_cloud)의 엔터프라이즈 계정에서 사용할 수 있습니다.
## 조직 범위 서비스 계정
자동화에서 여러 팀의 프로젝트 전반에 걸쳐 조회하거나 써야 하는 경우 조직 범위 서비스 계정을 사용하세요. 조직 범위 서비스 계정은 [제한된 프로젝트](/ko/platform/hosting/iam/access-management/restricted-projects/#visibility-scopes)를 제외하고, 팀과 관계없이 해당 조직의 모든 프로젝트에 대해 조회 및 쓰기 권한을 가집니다. 조직 범위 서비스 계정이 제한된 프로젝트에 액세스하려면, 해당 프로젝트의 관리자가 먼저 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.
### 조직 범위 서비스 계정 생성
새 조직 범위의 서비스 계정과 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` 환경 변수를 해당 팀으로 설정해야 합니다.
## 팀 범위 서비스 계정
최소 권한 원칙에 따라 자동화를 단일 팀의 프로젝트로 제한하려는 경우 팀 범위 서비스 계정을 사용하세요. 팀 범위 서비스 계정은 해당 팀의 [제한된 프로젝트](/ko/platform/hosting/iam/access-management/restricted-projects/#visibility-scopes)를 제외한 모든 프로젝트에서 조회 및 쓰기가 가능합니다. 팀 범위 서비스 계정이 제한된 프로젝트에 액세스하려면 해당 프로젝트의 관리자가 서비스 계정을 프로젝트에 명시적으로 추가해야 합니다.
### 팀 범위 서비스 계정 생성하기
새 팀 범위 서비스 계정과 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. [조직 설정](https://wandb.ai/account-settings/)으로 이동한 다음 **API Keys**를 클릭합니다. 2. API 키를 찾습니다. 목록에는 조직 및 팀 서비스 계정이 소유한 모든 API 키가 포함됩니다. 키 이름 또는 ID로 검색하거나 필터링하고, 모든 열을 기준으로 정렬합니다. 3. 삭제 버튼을 클릭합니다. 팀 범위 서비스 계정을 사용하는 모델 트레이닝 또는 생성형 AI 앱 환경에서 팀을 설정하지 않으면, 모델 run 또는 Weave 트레이스가 서비스 계정의 상위 팀 내에서 지정한 프로젝트에 기록됩니다. 이런 경우 `WANDB_USERNAME` 또는 `WANDB_USER_EMAIL` 변수를 사용하는 사용자 귀속은, 참조된 사용자가 서비스 계정의 상위 팀에 속해 있지 않으면 *작동하지 않습니다*. 팀 범위 서비스 계정은 상위 팀과 다른 팀에 있는 [팀 범위 또는 제한 범위 프로젝트](/ko/platform/hosting/iam/access-management/restricted-projects/#visibility-scopes)에 run을 기록할 수 없지만, 다른 팀 내의 open visibility 프로젝트에는 run을 기록할 수 있습니다.
### 외부 서비스 계정
W\&B 기본 API 키를 직접 관리하는 대신 자체 ID 공급자를 통해 자격 증명을 발급하려면 외부 서비스 계정을 사용하세요. 기본 제공 서비스 계정 외에도, W\&B는 JSON Web Token(JWT)을 발급할 수 있는 ID 공급자(IdP)의 [Identity federation](./identity_federation#external-service-accounts)을 사용해 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`을 설정하세요. ```bash theme={null} export WANDB_API_KEY="[SERVICE_ACCOUNT_KEY]" export WANDB_USERNAME="john.doe@company.com" ``` * **환경 설정**: 팀 범위 서비스 계정의 경우, run이 올바른 팀에 기록되도록 항상 `WANDB_ENTITY`를 설정하세요. ```bash theme={null} export WANDB_ENTITY="ml-team" export WANDB_PROJECT="production-models" ``` * **오류 처리**: 서비스 계정 자격 증명 관련 문제를 신속하게 파악할 수 있도록 인증 실패에 대한 적절한 오류 처리와 알림을 구현하세요. * **문서화**: 다음 내용을 문서로 관리하세요. * 어떤 서비스 계정이 존재하며 각 계정의 용도가 무엇인지 * 각 서비스 계정을 어떤 시스템 또는 워크플로에서 사용하는지 * 각 계정을 담당하는 팀의 연락처 정보
## 문제 해결
서비스 계정이 예상대로 작동하지 않는 경우, 다음의 일반적인 문제와 해결 방법을 확인하세요: * **"Unauthorized" 오류**: API 키가 올바르게 설정되어 있고 서비스 계정에 대상 프로젝트에 대한 접근 권한이 있는지 확인합니다. * **Runs가 표시되지 않음**: `WANDB_ENTITY`가 올바른 팀 이름으로 설정되어 있는지 확인합니다. * **사용자 귀속이 작동하지 않음**: `WANDB_USERNAME`에 지정된 사용자가 해당 팀의 멤버인지 확인합니다. * **제한된 프로젝트에 대한 접근 거부**: 서비스 계정을 제한된 프로젝트의 접근 목록에 명시적으로 추가합니다.