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

> [!WARNING]
> 이 기능은 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를 생성할 수 있는 사용자](#who-can-create-resource-groups) 참조).

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

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

    
    

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

    
    

> [!TIP]
> 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를 통한 자동 가입 구성](./programmatic-user-access-control#configure-auto-join-via-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](./enterprise-advanced-sso)가 있는 조직에서는 사용할 수 없습니다.

초대된 사용자는 [외부 협업자](./security-sso-user-management#external-collaborators)로 참여합니다:

- 기본적으로 `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을 생성할 수 있는](#who-can-create-resource-groups) 멤버는 해당 섹션에서 Resource Group을 생성하고 동시에 협업자를 초대할 수 있습니다. **자동 포함(Auto-include)**은 기본적으로 켜져 있습니다. 이 기능은 `no_access` 역할을 가진 멤버를 제외한 조직의 모든 멤버를 `inherit` 역할로 [자동 가입(auto-join)](#auto-join)하여 새로운 그룹에 추가하므로, 해당 멤버들은 리포지토리에 대한 현재 접근 권한을 유지합니다. 이 기능을 끄면, Resource Group에 추가한 사용자 및 조직 관리자만 리포지토리를 볼 수 있습니다.

API를 통해 외부 초대도 관리할 수 있습니다: [API를 통한 외부 협업자 초대](./programmatic-user-access-control#invite-external-collaborators-via-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 역할을 가진 사용자를 최소 한 명 포함해야 합니다.

## 세부 기능 접근

> [!WARNING]
> 이 기능은 Enterprise 플랜 이상에서 제공됩니다.

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

    
    

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

- **Blog**: 조직의 [블로그 글](./enterprise-blog-articles) 작성 및 게시.
- **컬렉션**: 조직 [컬렉션](./collections) 생성 및 편집.
- **Jobs**: 조직에 청구되는 [Jobs](./jobs) 실행 및 확인.
- **Inference Endpoints**: 조직이 소유한 Inference Endpoints를 생성, 관리 및 호출합니다.
- **Inference Providers**: 조직에 청구되는 [Inference Providers](/docs/inference-providers) 요청.

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

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

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

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

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

## 비용 귀속

> [!WARNING]
> 이 기능은 Enterprise 플랜 이상에서 제공됩니다.

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

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

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

## 지출 한도

> [!WARNING]
> 이 기능은 Enterprise 플랜 이상에서 제공됩니다.

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

    
    

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

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

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

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

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

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

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

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

- 유료 **Spaces**는 일시 중지됩니다. 무료 하드웨어에서 실행되는 Spaces와 [하드웨어 지원](./spaces-gpus)으로 실행되는 Spaces는 그대로 유지됩니다.
- **Jobs**는 `Resource group spend limit reached`를 중단 사유로 취소됩니다.

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

[API를 통한 지출 한도 설정](./programmatic-user-access-control#set-spend-limits-via-api)을 참고하여 프로그래밍 방식으로 지출 한도를 설정할 수도 있습니다.

## Resource Groups API

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