리소스 그룹을 사용한 조직의 고급 액세스 제어

이 기능은 Team & Enterprise 플랜의 일부입니다.

Hugging Face 조직에서 Resource Groups을(를) 사용하여 특정 저장소에 대한 멤버의 액세스를 제어할 수 있습니다.

동작 원리는 무엇인가요?

Resource Groups는 조직 관리자가 관련된 저장소를 그룹으로 묶을 수 있도록 하여, 조직 내의 서로 다른 팀이 독립적인 저장소 집합으로 작업할 수 있게 합니다.

• 리소스: 그룹의 저장소 및 컬렉션입니다. 각 리소스는 단 하나의 Resource Group에만 속할 수 있으며, 적절한 권한을 가진 멤버에 의해 그룹 간에 이동할 수 있습니다.
• 멤버: 조직 멤버는 리포지토리에 액세스하려면 리소스 그룹에 추가되어야 합니다. 멤버는 여러 리소스 그룹에 속할 수 있습니다.

멤버는 각 Resource Group에서 역할을 지정받으며, 이 역할이 해당 그룹의 저장소에 대한 권한을 결정합니다. Resource Group에는 네 가지 서로 다른 역할이 있습니다:

• read: Resource Group 내 저장소에 대한 읽기 액세스를 부여합니다.
• contributor: 사용자가 생성한 저장소에 한정한 쓰기 권한을 제공합니다(즉, 사용자는 저장소를 생성한 후 해당 저장소만 수정할 수 있습니다). ‘Write’ 역할과 유사하지만, 사용자가 생성한 저장소로 범위가 제한됩니다.
• write: Resource Group의 모든 저장소에 대한 쓰기 액세스를 제공합니다. 사용자는 Resource Group의 모든 저장소를 생성, 삭제 또는 이름 변경할 수 있습니다.
• admin: 저장소에 대한 쓰기 권한 외에도 admin 멤버는 Resource Group을 관리할 수 있습니다. 다른 멤버의 역할을 추가, 제거 및 변경할 수 있습니다. 또한 Resource Group에 이미 존재하는 저장소를 관리할 수도 있습니다.
• inherit: Resource Group에서 멤버의 역할은 해당 멤버의 조직 역할과 동일합니다. 예를 들어, write 조직 역할을 가진 멤버가 inherit로 설정된 그룹에 추가되면, 그 그룹에서 write 액세스 권한을 얻습니다.

또한, Organization 관리자는 조직 내의 모든 리소스 그룹을 관리할 수 있습니다. 여기에는 모든 Resource Group으로 리포지토리를 이동하거나 제거하는 작업이 포함됩니다.

Resource Groups는 조직 내 비공개 저장소의 가시성에도 영향을 미칩니다:

• Resource Group의 일부인 private 저장소는 해당 Resource Group의 멤버에게만 표시됩니다.
• Public 저장소는 조직 내부와 외부의 누구나 볼 수 있습니다.
• Resource Group에 속한 개인 collections에도 동일한 가시성 규칙이 적용됩니다.

시작하기

Organization 설정으로 이동한 후, 왼쪽 메뉴의 “Resource Groups” 항목으로 이동합니다. 이 페이지는 두 개의 탭으로 나뉘어 있습니다. 그룹 자체를 나열하고 관리하는 Resource Groups 탭과, Organization 관리자가 Resource Groups를 생성할 수 있는 사용자와 특정 Organization 기능을 사용할 수 있는 멤버를 설정하는 Access settings 탭입니다.

Organization 관리자는 해당 페이지에서 Resource Groups를 생성하고 관리할 수 있습니다. Organization의 설정에 따라, 낮은 역할의 멤버도 Resource Groups 생성이 허용될 수 있습니다(아래 Resource Groups를 생성할 수 있는 사용자 참조).

Resource Group을 생성하고 의미 있는 이름을 부여하면 해당 그룹의 페이지로 이동합니다. 이 페이지는 네 개의 탭으로 구성됩니다:

• 개요: 그룹(리포지토리 유형, 멤버 역할, 자동 포함 상태 및 지출 한도)의 요약과 함께 해당 리소스 및 사용자의 미리보기.
• 리소스: 그룹의 저장소 및 컬렉션 전체 목록과 그룹에 청구된 Jobs를 검색, 정렬 및 페이지네이션으로 확인할 수 있습니다. 이 곳에서 그룹에 리소스를 추가합니다.
• 사용자: 검색 및 정렬 기능이 포함된 그룹의 멤버와 역할입니다. 사용자를 추가하고 역할을 관리하는 곳입니다.
• 설정: 그룹의 자동 포함 및 지출 한도 구성입니다.

Resources와 Users 탭에서 그룹에 저장소와 사용자를 추가하기 시작할 수 있습니다.

Resource Group에 사용자를 추가할 때, 사용자의 조직 전용 이메일(예: user@your-company.com)이 조직의 이메일 도메인과 일치하는 경우 이메일 주소로 검색할 수 있습니다.

리소스 그룹은 하나만 해당 리포지토리에 할당될 수 있습니다. 이미 다른 리소스 그룹에 속해 있는 리포지토리를 추가하려고 하면 경고가 표시됩니다.

자동 가입

Auto-join은 지정된 역할로 조직 멤버를 Resource Group에 자동으로 추가합니다. Auto-join이 활성화된 시점에 이미 조직에 속해 있던 멤버와, 향후 조직에 합류하는 모든 새 멤버가 대상입니다.

수동으로 멤버십을 관리할 필요 없이 조직 전체가 액세스할 수 있어야 하는 Resource Groups에 유용합니다.

자동 참여 활성화

• UI를 통해: Resource Group의 Settings 탭을 열고 Auto-include org members 섹션에서 Automatically include all org members 옵션을 선택한 후, 할당할 역할을 선택합니다. Users 탭에서도 해당 섹션으로 연결되며, 자동 포함이 켜져 있는지 꺼져 있는지 확인할 수 있습니다.
• API를 통한 방법: API를 통한 자동 가입 구성을 참조하세요.

기존 Resource Group에서 auto-join이 활성화되면, 선택된 범위에 해당하는 현재 조직 구성원은 설정된 역할로 즉시 추가됩니다(백필).

자동 조인 범위

Auto-join은 다음에 적용할 수 있습니다:

• 모든 조직 멤버(기본값): no_access 조직 역할을 가진 멤버를 제외하려면 no_access 멤버 포함을 선택 해제합니다.
• no_access를 포함한 모든 조직 멤버: no_access 조직 역할을 가진 멤버를 포함한 모든 멤버를 포함하려면 no_access 멤버 포함을 선택하세요.

no_access 멤버가 수동으로 또는 다른 프로비저닝 플로우를 통해 추가된 특정 Resource Group에 대한 액세스만 유지해야 하는 경우에만 Read+ members only를 사용하세요.

자동 가입 및 SCIM

Auto-join과 SCIM 관리는 동일한 Resource Group에서 상호 배타적입니다. Auto-join은 조직 구성원을 자동으로 추가하는 반면, SCIM 관리는 IdP가 구성원 자격을 제어하도록 하는 것을 의미합니다. 이 두 동작은 충돌하므로:

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

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

외부 초대

조직 외부의 사용자와 Resource Groups를 공유할 수 있습니다. 조직 관리자는 Resource Groups 설정 페이지의 Access settings 탭에서 External invitations 설정을 통해 이를 활성화합니다. 기본적으로 비활성화되어 있으며, managed users가 있는 조직에서는 사용할 수 없습니다.

초대된 사용자는 외부 협업자로 참여합니다:

• 기본적으로 no_access 조직 역할을 부여받으므로 해당 Resource Group의 리소스만 볼 수 있습니다.
• 리소스 그룹에서 read 또는 write 역할로 초대할 수 있습니다.
• 조직의 SSO로 로그인할 필요가 없습니다.

누군가를 초대하려면 Resource Group의 Users 탭을 열고 사용자 이름으로 추가합니다. 조직 구성원은 즉시 그룹에 가입하고, 외부 사용자는 초대장을 받습니다. 대기 중인 초대는 그룹의 사용자 목록에서 “Pending” 배지로 표시되며, 재전송하거나 취소할 수 있습니다. External 필터를 사용하면 외부 협업자만 나열할 수 있습니다.

외부 협업자와 저장소 공유

Resource group 관리자는 또한 Settings 페이지의 Share with external collaborators 섹션에서 private repository를 공유할 수 있습니다. 해당 섹션에는 이미 해당 repository의 Resource Group에 포함된 사용자가 나열되며, 외부 collaborator를 초대할 수 있습니다. 여기에 추가한 사용자는 해당 repository뿐만 아니라 Resource Group 내의 모든 리소스에 대한 액세스 권한을 얻습니다.

리포지토리가 아직 Resource Group에 속해 있지 않은 경우, Resource Group을 생성할 수 있는 멤버는 해당 섹션에서 Resource Group을 생성하고 동시에 협업자를 초대할 수 있습니다. 자동 포함(Auto-include)은 기본적으로 켜져 있습니다. 이 기능은 no_access 역할을 가진 멤버를 제외한 조직의 모든 멤버를 자동 가입(auto-join)을 통해 inherit 역할로 새 그룹에 추가하여, 해당 멤버들이 리포지토리에 대한 현재 접근 권한을 유지할 수 있도록 합니다. 이 기능을 끄면, Resource Group에 추가한 사용자 및 조직 관리자만 리포지토리를 볼 수 있습니다.

API를 통해 외부 초대도 관리할 수 있습니다: API를 통한 외부 협업자 초대.

Resource Groups를 생성할 수 있는 사용자

기본적으로 조직 관리자만 새로운 Resource Groups를 생성할 수 있습니다. 조직 관리자는 Resource Groups 설정 페이지의 Access settings 탭에서 Resource Groups 생성에 필요한 최소 멤버 역할을 설정하여 이를 변경할 수 있습니다.

사용 가능한 옵션은 다음과 같습니다:

• 관리자 전용(기본값): 조직 관리자만 리소스 그룹을 생성할 수 있습니다.
• Write+: Write 또는 Admin 역할을 가진 멤버는 Resource Groups를 생성할 수 있습니다.
• Contributor+: Contributor, Write 또는 Admin 역할을 가진 멤버는 Resource Groups를 생성할 수 있습니다.
• Read+: no_access 조직 역할을 가진 멤버를 제외한 모든 조직 멤버가 Resource Groups를 생성할 수 있습니다.

비관리자 멤버가 UI를 통해 Resource Group을 생성하면, 해당 멤버는 새로 생성된 그룹의 admin으로 자동으로 추가됩니다. API를 통한 생성에서는 자동으로 이루어지지 않으며, 이는 API 호출자가 다른 사람을 대신하여 그룹을 생성할 수 있기 때문입니다. 비관리자 API 호출자는 그룹의 초기 멤버 목록에 admin 역할을 가진 사용자를 최소 한 명 포함해야 합니다.

세부 기능 접근

이 기능은 Enterprise 플랜 이상에서 제공됩니다.

Org admins는 리포지토리 접근 권한과 별개로, 특정 조직 기능을 사용할 수 있는 사용자를 제어할 수도 있습니다. 이 설정은 Resource Groups 설정 페이지의 Access settings 탭에 있습니다.

다음 기능은 제한할 수 있습니다:

• Blog: 조직의 블로그 글 작성 및 게시.
• 컬렉션: 조직 컬렉션 생성 및 편집.
• Jobs: 조직에 청구되는 Jobs 실행 및 확인.
• Inference Endpoints: 조직이 소유한 Inference Endpoints를 생성, 관리 및 호출합니다.
• Inference Providers: 조직에 청구되는 Inference Providers 요청.

각 항목에 대해 액세스 권한을 가진 사용자를 선택할 수 있습니다:

• 모두(기본값): 조직 역할에 따라 조직의 모든 멤버.
• 조직 관리자만: 조직 관리자만 액세스를 유지합니다.
• 특정 리소스 그룹: 그룹 내 역할에 따라 선택된 리소스 그룹의 멤버만.

조직 관리자는 선택된 옵션과 관계없이 항상 모든 기능에 대한 액세스 권한을 유지합니다.

특정 리소스 그룹으로 기능을 제한하는 것은 누가 해당 기능을 사용할 수 있는지를 제어하는 것이지, 어디서 사용할 수 있는지를 제어하는 것이 아닙니다. 선택된 그룹의 멤버는 조직 내 어디에서든(예: 리소스 그룹에 속하지 않는 컬렉션 생성) 해당 기능을 계속 사용할 수 있으며, 다른 멤버는 해당 기능에 대한 접근 권한을 완전히 잃습니다. 이 제한은 추가 권한을 부여하지 않습니다. 멤버가 수행할 수 있는 작업은 여전히 해당 멤버의 조직 역할에 의해 결정됩니다.

접근 권한이 없는 멤버는 이제 조직 컨텍스트에서 해당 기능을 사용할 수 없으며, API와 UI 모두에서 동일하게 적용됩니다. API 요청은 인증 오류를 반환합니다. 해당 멤버의 개인 계정이나 다른 조직에서는 변경 사항이 없습니다.

비용 귀속

이 기능은 Enterprise 플랜 이상에서 제공됩니다.

Resource Groups는 또한 compute 서비스의 비용 귀속 단위로 사용됩니다. compute가 Resource Group에 청구되면 비용은 그룹별로 별도로 추적되므로, 팀 간 지출을 파악하기가 더 쉬워집니다.

• Spaces: 비용은 해당 Space가 속한 리소스 그룹에 자동으로 귀속됩니다.
• Jobs: 소유 조직을 namespace로 설정하고, Python에서는 resource_group_id, CLI에서는 --resource-group-id, HTTP 요청 본문에서는 resourceGroupId를 사용하여 리소스 그룹의 ID를 전달합니다. 리소스 그룹에 청구를 참조하세요.
• Inference Providers: X-HF-Bill-To 헤더(또는 SDK의 bill_to 파라미터)를 통해 리소스 그룹의 ID를 전달합니다. 팀 및 엔터프라이즈 조직의 청구를 참조하세요.
• Inference Endpoints: 비용은 모델 저장소가 속한 리소스 그룹에 자동으로 귀속됩니다. 내장된 Inference Endpoints 카탈로그에서 직접 인스턴스화된 엔드포인트는 현재 지원되지 않습니다.

전용 API 엔드포인트를 사용하여 리소스 그룹의 비용 귀속 데이터를 가져올 수 있습니다.

지출 한도

이 기능은 Enterprise 플랜 이상에서 제공됩니다.

비용 추적을 넘어 비용을 상한으로 제한할 수도 있습니다. 조직 관리자 및 리소스 그룹 관리자는 그룹의 Settings 탭에서 Spend limits 섹션을 통해 월별 지출 한도를 설정할 수 있습니다.

USD로 표시되는 두 가지 유형의 한도가 있습니다:

• 합계(모든 제품): 그룹의 총 합산 컴퓨트 지출을 제한합니다.
• 총 한도에 더해 Inference Providers, Spaces, Jobs, Inference Endpoints 각각에 대한 제품별 한도.

한도를 설정하지 않으려면 필드를 비워 두세요. 전체 한도와 제품별 한도가 모두 적용되는 경우, 두 값 중 더 엄격한 한도가 우선 적용됩니다.

한도는 현재 달력 월 기준으로 그룹에 귀속된 지출에 적용되므로, 한도에 도달한 그룹은 다음 달 초 또는 관리자가 한도를 상향 조정하는 시점에 즉시 차단이 해제됩니다.

한도가 도달되면 발생하는 일

리소스 그룹에 청구되는 새로운 사용량은 권한 오류로 거부됩니다:

• Inference Providers: 그룹에 청구되는 요청은 거부됩니다.
• Jobs: 그룹 내 작업 생성, 재제출 또는 재개는 거부되며, 예약된 작업도 포함됩니다.
• Spaces: 그룹 내 Space를 유료 하드웨어로 업그레이드하는 작업은 거부됩니다.
• Inference Endpoints: 그룹에 비용이 발생하는 엔드포인트에 대한 요청은 거부됩니다.

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

• 유료 Spaces는 일시 중지됩니다. 무료 하드웨어에서 실행되는 Spaces와 하드웨어 지원으로 실행되는 Spaces는 그대로 유지됩니다.
• Jobs는 Resource group spend limit reached를 중단 사유로 취소됩니다.

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

API를 통한 지출 한도 설정을 참고하여 프로그래밍 방식으로 지출 한도를 설정할 수도 있습니다.

Resource Groups API

Hub API를 통해 리소스 그룹을 나열하고 사용자를 추가하거나(또는 멤버의 조직 역할 및 리소스 그룹 할당을 변경)할 수 있습니다. 전체 참조, 예제 및 배치 워크플로에 대해서는 Programmatic User Access Control Management 가이드를 참고하세요.

Update on GitHub