조직의 고급 접근 제어: Resource Groups

조직의 고급 접근 제어: Resource Groups

Hugging Face 조직에서 Resource Groups를 사용해 특정 리포지토리에 접근할 멤버를 제어할 수 있어요. Team & Enterprise 플랜 전용 기능입니다.

출처: 문서

본문

[!WARNING] 이 기능은 Team & Enterprise 플랜에 포함됩니다.

Hugging Face 조직에서 Resource Groups를 사용해 특정 리포지토리에 어떤 멤버가 접근할지 제어할 수 있어요.

어떻게 동작하나? (How does it work?)

Resource Groups는 조직 관리자가 관련 리포지토리를 함께 그룹화할 수 있게 해줍니다. 조직의 서로 다른 팀이 독립적인 리포지토리 집합에서 작업할 수 있게 하죠.

  • 리소스 (Resources): 그룹의 리포지토리와 컬렉션. 각 리소스는 하나의 Resource Group에만 속할 수 있으며, 적절한 권한을 가진 멤버가 그룹 간에 이동시킬 수 있어요.
  • 멤버 (Members): 조직 멤버는 리포지토리에 접근하려면 Resource Group에 추가되어야 합니다. 멤버는 여러 Resource Group에 속할 수 있습니다.

멤버는 각 Resource Group에서 그 그룹 리포지토리에 대한 권한을 결정하는 역할(role) 을 배정받습니다. Resource Groups에는 네 가지 역할이 있습니다:

  • read: Resource Group 안의 리포지토리에 대한 읽기 접근을 부여합니다.
  • contributor: 사용자가 만든 리포지토리로 제한된 쓰기 권한을 제공합니다(즉 사용자는 repo를 만들고 그 repo만 수정). 'Write' 역할과 비슷하지만 사용자가 만든 repo로 제한됩니다.
  • write: Resource Group의 모든 리포지토리에 대한 쓰기 접근을 제공합니다. 사용자는 Resource Group에서 어떤 리포지토리든 만들고, 삭제하고, 이름을 바꿀 수 있어요.
  • admin: 리포지토리에 대한 쓰기 권한에 더해, admin 멤버는 Resource Group을 관리할 수 있습니다: 다른 멤버 추가·제거·역할 변경. 기존 리포지토리를 Resource Group에서 관리할 수도 있어요.

또한 조직 admin은 조직 안의 모든 resource groups를 관리할 수 있습니다. 여기에는 어떤 Resource Group으로든 리포지토리를 이동하는 것이 포함됩니다.

Resource Groups는 조직 내 비공개 리포지토리의 가시성에도 영향을 줍니다:

  • Resource Group의 일부인 private 리포지토리는 그 Resource Group의 멤버에게만 보입니다.
  • Public 리포지토리는 조직 안팎의 모든 사람에게 보입니다.
  • 동일한 가시성 규칙이 Resource Group에 속한 비공개 컬렉션에도 적용됩니다.

시작하기 (Getting started)

조직 설정으로 가서 왼쪽 메뉴의 "Resource Groups" 항목으로 이동하세요. 페이지는 두 탭으로 나뉩니다: Resource Groups(그룹 자체를 나열·관리)와 Access settings(조직 admin이 누가 Resource Group을 만들 수 있고 어떤 멤버가 특정 조직 기능을 쓸 수 있는지 구성).

조직 admin은 이 페이지에서 Resource Groups를 만들고 관리할 수 있어요. 조직 설정에 따라 낮은 역할의 멤버도 Resource Groups를 만들 수 있습니다(아래 누가 Resource Groups를 만들 수 있나 참고).

Resource Group을 만들고 의미 있는 이름을 주면 그룹 페이지에 도착합니다. 네 탭으로 구성됩니다:

  • Overview: 그룹 요약(리포지토리 타입, 멤버 역할, 자동 포함 상태, 지출 한도)과 리소스·사용자 미리보기.
  • Resources: 검색·정렬·페이지네이션이 있는 그룹의 리포지토리·컬렉션 전체 목록과 그룹에 청구되는 Jobs. 리소스를 그룹에 추가하는 곳.
  • Users: 검색·정렬이 있는 그룹 멤버와 그 역할. 사용자를 추가하고 역할을 관리하는 곳.
  • Settings: 그룹의 자동 포함과 지출 한도 구성.

Resources와 Users 탭에서 그룹에 리포지토리와 사용자를 추가하기 시작할 수 있어요.

[!TIP] Resource Group에 사용자를 추가할 때 조직 이메일 도메인과 일치하는 조직 전용 이메일(예: [email protected])이 있으면 이메일 주소로 검색할 수 있어요.

리포지토리는 하나의 Resource Group에만 속할 수 있다는 점을 기억하세요. 다른 Resource Group에 이미 속한 리포지토리를 추가하려 하면 경고를 받습니다.

자동 참여 (Auto-join)

Auto-join은 조직 멤버를 지정된 역할로 Resource Group에 자동으로 추가합니다: auto-join을 활성화할 때 이미 조직에 있던 멤버와 앞으로 합류할 새 멤버 모두요.

수동 멤버십 관리 없이 전체 조직이 접근해야 하는 Resource Group에 유용합니다.

auto-join 활성화 (Enabling auto-join)

  • UI로: Resource Group의 Settings 탭을 열고 Auto-include org members 섹션에서 Automatically include all org members 옵션을 체크한 뒤 할당할 역할을 선택하세요. Users 탭도 이를 연결해 auto-include 켜짐 여부를 보여줍니다.
  • API로: Configure auto-join via API를 참고하세요.

기존 Resource Group에 auto-join을 활성화하면 선택한 범위와 일치하는 현재 조직 멤버가 구성된 역할로 즉시 그룹에 추가됩니다(backfill).

auto-join 범위 (Auto-join scope)

Auto-join은 다음에 적용될 수 있어요:

  • 모든 조직 멤버 (기본): Include no_access members를 체크하지 않으면 no_access 조직 역할의 멤버를 제외합니다.
  • no_access를 포함한 모든 조직 멤버: Include no_access members를 체크하면 no_access 조직 역할의 멤버를 포함해 모든 멤버를 포함합니다.

no_access 멤버가 수동이나 다른 프로비저닝 흐름으로 추가된 특정 Resource Groups에만 접근을 유지해야 한다면 Read+ members only를 사용하세요.

auto-join과 SCIM (Auto-join and SCIM)

Auto-join과 SCIM 관리는 같은 Resource Group에서 상호 배타적입니다. Auto-join은 조직 멤버를 자동으로 추가하는 반면, SCIM 관리는 IdP만 멤버십을 제어한다는 뜻입니다. 이 두 동작은 충돌하므로:

  • SCIM 그룹에 연결된 Resource Group에서는 auto-join을 활성화할 수 없어요.
  • auto-join이 활성화된 Resource Group에는 SCIM 그룹을 연결할 수 없습니다.

Resource Group을 auto-join에서 SCIM 관리로(또는 그 반대로) 전환하려면 먼저 현재 설정을 비활성화하세요.

누가 Resource Groups를 만들 수 있나 (Who can create Resource Groups)

기본적으로 조직 admin만 새 Resource Groups를 만들 수 있어요. 조직 admin은 Resource Groups 설정 페이지의 Access settings 탭에서 minimum member role required to create Resource Groups를 설정해 이를 변경할 수 있습니다.

사용 가능한 옵션:

  • Admins only (기본): 조직 admin만 Resource Groups를 만듭니다.
  • Write+: Write 또는 Admin 역할 멤버가 Resource Groups를 만들 수 있습니다.
  • Contributor+: Contributor, Write, Admin 역할 멤버가 Resource Groups를 만들 수 있어요.
  • Read+: no_access 조직 역할 멤버를 제외한 모든 조직 멤버가 Resource Groups를 만들 수 있습니다.

비-admin 멤버가 UI로 Resource Group을 만들면 자동으로 그 새로 만든 그룹의 admin으로 추가됩니다. API로는 다른 사람을 대신해 그룹을 만들 수 있으므로 자동으로 발생하지 않아요. 비-admin API 호출자는 그룹의 초기 멤버 목록에 admin 역할 사용자가 최소 한 명 포함해야 합니다.

세분화된 기능 접근 (Granular feature access)

[!WARNING] 이 기능은 Enterprise 플랜 이상에 포함됩니다.

조직 admin은 리포지토리 접근과 별개로 주어진 조직 기능을 누가 쓸 수 있는지도 제어할 수 있어요. 설정은 Resource Groups 설정 페이지의 Access settings 탭에 있습니다.

제한할 수 있는 기능:

  • Blog: 조직 블로그 아티클 작성·게시.
  • Collections: 조직 컬렉션 생성·편집.
  • Jobs: 조직에 청구되는 Jobs 실행·조회.
  • Inference Endpoints: 조직 소유 Inference Endpoints 생성·관리·호출.
  • Inference Providers: 조직에 청구되는 Inference Providers 요청.

각각에 대해 접근할 사람을 선택할 수 있어요:

  • Everyone (기본): 조직 역할에 따른 모든 멤버.
  • Org admins only: 조직 admin만 접근 유지.
  • Specific resource groups: 선택한 Resource Group의 멤버만 그룹 내 역할에 따라.

조직 admin은 어떤 옵션을 선택하든 항상 모든 기능에 접근할 수 있어요.

기능을 특정 resource groups로 제한하는 것은 기능을 쓸 수 있는 사람(누가) 을 제어하지, 어디서는 아닙니다. 선택한 그룹의 멤버는 조직 어디에서든 그 기능을 계속 사용할 수 있고(예: 어떤 resource group에도 속하지 않는 컬렉션 만들기), 다른 멤버는 그 기능에 완전히 접근하지 못합니다. 제한은 추가 권한을 부여하지 않습니다: 멤버가 할 수 있는 일은 여전히 조직 역할로 결정됩니다.

접근이 없는 멤버는 조직 컨텍스트에서 API와 UI 모두에서 그 기능을 더 이상 사용할 수 없습니다. API 요청은 인증 오류를 반환합니다. 개인 계정이나 다른 조직에서는 그들에게 아무것도 바뀌지 않습니다.

비용 귀속 (Cost attribution)

[!WARNING] 이 기능은 Enterprise 플랜 이상에 포함됩니다.

Resource Groups는 또한 컴퓨팅 서비스의 비용 귀속 단위로 작동합니다. 컴퓨팅이 resource group에 청구되면 비용이 그룹별로 별도 추적되어 팀 간 지출을 이해하기 쉬워집니다.

  • Spaces: 비용은 Space가 속한 resource group에 자동 귀속됩니다.
  • Jobs: namespace를 소유 조직으로 설정하고 resource_group_id(Python), --resource-group-id(CLI), resourceGroupId(HTTP 요청 본문)로 resource group의 ID를 전달하세요. Bill to a resource group 참고.
  • Inference Providers: X-HF-Bill-To 헤더(SDK의 bill_to 파라미터)로 resource group의 ID를 전달하세요. Billing for Team and Enterprise organizations 참고.
  • Inference Endpoints: 비용은 모델 리포지토리가 속한 resource group에 자동 귀속됩니다. 내장 Inference Endpoints 카탈로그에서 직접 인스턴스화한 엔드포인트는 현재 지원되지 않아요.

전용 API 엔드포인트로 resource groups의 비용 귀속 데이터를 가져올 수 있습니다.

지출 한도 (Spend limits)

[!WARNING] 이 기능은 Enterprise 플랜 이상에 포함됩니다.

비용 추적에 더해 상한을 둘 수 있어요. 조직 admin과 resource group admin은 그룹의 Settings 탭의 Spend limits 아래에서 월간 지출 한도를 설정할 수 있습니다.

두 종류의 한도(둘 다 USD로 표시):

  • Total (all products): 그룹의 결합 컴퓨팅 지출 상한.
  • total 위에 Inference Providers, Spaces, Jobs, Inference Endpoints 각각의 제품별 한도.

제한 없음은 필드를 비워두세요. total 한도와 제품별 한도가 모두 적용되면 둘 중 더 엄격한 쪽이 우선합니다.

한도는 현재 달력 월에 그룹에 귀속된 지출에 적용되므로, 한도에 도달한 그룹은 다음 달 초나 admin이 한도를 올리면 즉시 해제됩니다.

한도에 도달하면 어떻게 되나 (What happens when a limit is reached)

resource group에 청구되는 새 사용량은 인증 오류로 거부됩니다:

  • Inference Providers: 그룹에 청구되는 요청이 거부됩니다.
  • Jobs: 그룹에서 job 생성·재제출·재개가 거부됩니다. 예약된 job 포함.
  • Spaces: 그룹의 Space를 유료 하드웨어로 업그레이드하는 것이 거부됩니다.
  • Inference Endpoints: 그룹에 비용이 발생하는 엔드포인트 요청이 거부됩니다.

이미 그룹에서 실행 중인 워크로드도 한도에 도달한 직후 중지됩니다:

  • 유료 Spaces는 일시 중지됩니다. 무료 하드웨어의 Spaces는 그대로 두고, hardware grant에서 실행되는 Spaces도 그대로 둡니다.
  • Jobs는 Resource group spend limit reached를 중지 사유로 취소됩니다.

한도를 올리거나 새 달이 시작되면 멤버가 다시 새 워크로드를 시작할 수 있어요. 중지된 Spaces와 Jobs는 자동으로 재시작되지 않습니다.

지출 한도는 프로그래밍 방식으로도 설정할 수 있어요. Set spend limits via API를 참고하세요.

Resource Groups API

Hub API로 resource groups를 나열하고 사용자를 추가(또는 멤버의 org 역할·resource group 할당 변경)할 수 있어요. 전체 레퍼런스·예시·배치 워크플로는 Programmatic User Access Control Management 가이드를 참고하세요.

더 알아보기 (Learn more)

Resource Groups는 리포지토리·컬렉션을 그룹화해 팀별 접근을 제어하고, read/contributor/write/admin 역할로 권한을 세분화해요. auto-join, SCIM, 세분화된 기능 접근, 비용 귀속·지출 한도(Enterprise)까지 지원하니 조직 규모에 맞게 활용할 수 있습니다. 프로그래밍 관리와 비용 상세는 Programmatic User Access Control과 Jobs 가이드를 참고하세요.