diff --git a/docs/hub/enterprise-resource-groups.md b/docs/hub/enterprise-resource-groups.md index f545ea2f0b..508a65d886 100644 --- a/docs/hub/enterprise-resource-groups.md +++ b/docs/hub/enterprise-resource-groups.md @@ -9,12 +9,12 @@ Resource Groups allow organizations to enforce fine-grained access control to th screenshot of Hugging Face Resource Groups feature diff --git a/docs/hub/jobs-pricing.md b/docs/hub/jobs-pricing.md index 014e9dc5fc..ed3ba886d9 100644 --- a/docs/hub/jobs-pricing.md +++ b/docs/hub/jobs-pricing.md @@ -92,12 +92,12 @@ In this case the Job runs under the organization account, and you can see it in If your organization has [Resource Groups](./security-resource-groups) set up, you can attribute job costs to a specific resource group. To do so: 1. You must be a member of the resource group. -2. Pass the resource group's ID as the `namespace` when running the job. +2. Pass the resource group's ID as the `resourceGroupId` field when running the job. The `namespace` stays your organization's name, it identifies who is billed. You can find the resource group's ID in your organization's Resource Groups settings page. ```bash -hf jobs run --namespace ... +hf jobs run --namespace --resource-group-id ... ``` In Python: @@ -107,7 +107,8 @@ In Python: >>> run_job( ... image="python:3.12", ... command=["python", "-c", "print('Hello!')"], -... namespace="", +... namespace="", +... resource_group_id="", ... ) ``` diff --git a/docs/hub/security-resource-groups.md b/docs/hub/security-resource-groups.md index 936658bf50..145797e2dd 100644 --- a/docs/hub/security-resource-groups.md +++ b/docs/hub/security-resource-groups.md @@ -7,41 +7,54 @@ In your Hugging Face organization, you can use Resource Groups to control which ## How does it work? -Resource Groups allow organization administrators to group related repositories together, allowing different teams in your organization to work on independent sets of repositories. +Resource Groups allow organization administrators to **group related repositories together**, allowing different teams in your organization to work on independent sets of repositories. -A repository can belong to only one Resource Group. +- **Resources**: the group's repositories and collections. Each resource can belong to **only one** Resource Group, and can be moved between groups by members with the appropriate permissions. +- **Members**: organization members **need to be added** to a Resource Group to access its repositories. A member can belong to **several Resource Groups**. -Organization collections can also be assigned to a Resource Group, following the same rules as repositories: a collection can belong to only one Resource Group, and can be moved between groups by members with the appropriate permissions. +Members are assigned a **role** in each Resource Group that determines their permissions for the group's repositories. Four distinct roles exist for Resource Groups: -Organizations members need to be added to the Resource Group to access its repositories. An Organization Member can belong to several Resource Groups. +- `read`: Grants **read access** to repositories within the Resource Group. +- `contributor`: Provides **write rights limited to the repositories created by the user** (i.e., users can create repos and then modify only those repos). Similar to the 'Write' role, but limited to repos created by the user. +- `write`: Offers **write access to all repositories** in the Resource Group. Users can create, delete, or rename any repository in the Resource Group. +- `admin`: In addition to write permissions on repositories, admin members can **administer the Resource Group**: add, remove, and alter the roles of other members. They can also manage already existing repositories in a Resource Group. -Members are assigned a role in each Resource Group that determines their permissions for the group's repositories. Four distinct roles exist for Resource Groups: +In addition, Organization admins can manage **all resource groups** inside the organization. This includes moving repositories in and out of any Resource Group. -- `read`: Grants read access to repositories within the Resource Group. -- `contributor`: Provides extra write rights to the subset of the Organization's repositories created by the user (i.e., users can create repos and then modify only those repos). Similar to the 'Write' role, but limited to repos created by the user. -- `write`: Offers write access to all repositories in the Resource Group. Users can create, delete, or rename any repository in the Resource Group. -- `admin`: In addition to write permissions on repositories, admin members can administer the Resource Group — add, remove, and alter the roles of other members. They can also manage already existing repositories in a Resource Group. +Resource Groups also affect the visibility of private repositories inside the organization: -In addition, Organization admins can manage all resource groups inside the organization. This includes moving repositories in and out of any Resource Group. - -Resource Groups also affect the visibility of private repositories inside the organization. A private repository that is part of a Resource Group will only be visible to members of that Resource Group. Public repositories, on the other hand, are visible to anyone, inside and outside the organization. The same visibility rules apply to private collections that belong to a Resource Group. +- A **private** repository that is part of a Resource Group is only visible to **members of that Resource Group**. +- **Public** repositories are visible to **anyone**, inside and outside the organization. +- The same visibility rules apply to private **collections** that belong to a Resource Group. ## Getting started -Head to your Organization's settings, then navigate to the "Resource Group" entry in the left menu. The page is split in two tabs: **Resource Groups**, where the groups themselves are listed and managed, and **Access settings**, where org admins configure who can create Resource Groups and which members can use specific organization features. +Head to your Organization's settings, then navigate to the "Resource Groups" entry in the left menu. The page is split in two tabs: **Resource Groups**, where the groups themselves are listed and managed, and **Access settings**, where org admins configure who can create Resource Groups and which members can use specific organization features.
- - + The Resource Groups settings page +
Organization admins can create and manage Resource Groups from that page. Depending on the organization's settings, members with lower roles may also be allowed to create Resource Groups (see [Who can create Resource Groups](#who-can-create-resource-groups) below). -After creating a Resource Group and giving it a meaningful name, you can start adding repositories and users to it. +After creating a Resource Group and giving it a meaningful name, you land on the group's page. It is organized in four tabs: + +- **Overview**: a summary of the group (repository types, member roles, auto-include state and spend limit) along with a preview of its resources and users. +- **Resources**: the full list of the group's repositories and collections, as well as the Jobs billed to the group, with search, sorting and pagination. This is where you add resources to the group. +- **Users**: the group's members and their roles, with search and sorting. This is where you add users and manage their roles. +- **Settings**: the group's auto-include and spend limits configuration.
- - + The Overview tab of a resource group + +
+ +You can start adding repositories and users to the group from the **Resources** and **Users** tabs. + +
+ The Add resources modal +
> [!TIP] @@ -49,22 +62,22 @@ After creating a Resource Group and giving it a meaningful name, you can start a Remember that a repository can be part of only one Resource Group. You'll be warned when trying to add a repository that already belongs to another Resource Group. -
- - -
## Auto-join -Auto-join automatically adds **org members** to a Resource Group at a specified role — both members who are already in the org when auto-join is enabled, and any new members who join in the future. +Auto-join automatically adds **org members** to a Resource Group at a specified role: both members who are already in the org when auto-join is enabled, and any new members who join in the future. This is useful for Resource Groups that should be accessible to your entire organization without requiring manual membership management. ### Enabling auto-join -**Via the UI**: Open the Resource Group's settings page and check the **Auto-include org members** option, then select the role to assign. +- **Via the UI**: Open the Resource Group's **Settings** tab and check the **Automatically include all org members** option in the **Auto-include org members** section, then select the role to assign. The Users tab also links there, showing whether auto-include is on or off. +- **Via the API**: See [Configure auto-join via API](./programmatic-user-access-control#configure-auto-join-via-api). -**Via the API**: See [Configure auto-join via API](./programmatic-user-access-control#configure-auto-join-via-api). +
+ The Auto-include org members settings + +
When auto-join is enabled on an existing Resource Group, current org members matching the selected scope are **immediately added** to the group at the configured role (backfill). @@ -72,14 +85,14 @@ When auto-join is enabled on an existing Resource Group, current org members mat Auto-join can apply to: -- **All org members**: Include every member, including members with the `no_access` organization role. -- **Read+ members only**: Exclude members with the `no_access` organization role. +- **All org members**: check **Include no_access members** to include every member, including members with the `no_access` organization role. +- **Read+ members only** (default): leave **Include no_access members** unchecked to exclude members with the `no_access` organization role. Use **Read+ members only** when `no_access` members should keep access only to the specific Resource Groups where they are added manually or through another provisioning flow. ### Auto-join and SCIM -Auto-join and SCIM management are **mutually exclusive** on the same Resource Group. Auto-join adds org members automatically; SCIM management means only the IdP controls membership. These two behaviors conflict, so: +Auto-join and SCIM management are **mutually exclusive** on the same Resource Group. Auto-join adds org members automatically, while SCIM management means only the IdP controls membership. These two behaviors conflict, so: - You cannot enable auto-join on a Resource Group that is linked to a SCIM group. - You cannot link a SCIM group to a Resource Group that has auto-join enabled. @@ -91,10 +104,10 @@ To switch a Resource Group from auto-join to SCIM-managed (or vice versa), disab By default, only organization admins can create new Resource Groups. Org admins can change this by setting the **minimum member role required to create Resource Groups** in the **Access settings** tab of the Resource Groups settings page. The available options are: -- **Admins only** (default) — only org admins can create Resource Groups. -- **Write** — members with Write or Admin role can create Resource Groups. -- **Contributor** — members with Contributor, Write, or Admin role can create Resource Groups. -- **Read+** — any org member can create Resource Groups. +- **Admins only** (default): only org admins can create Resource Groups. +- **Write+**: members with Write or Admin role can create Resource Groups. +- **Contributor+**: members with Contributor, Write, or Admin role can create Resource Groups. +- **Read+**: any org member can create Resource Groups, except members with the `no_access` organization role. When a non-admin member creates a Resource Group through the UI, they are automatically added as an **admin** of that newly created group. Through the API, this does not happen automatically, since API callers may be creating groups on behalf of others. Non-admin API callers must include at least one user with the admin role in the group's initial member list. @@ -106,8 +119,8 @@ When a non-admin member creates a Resource Group through the UI, they are automa Org admins can also control who's allowed to use a given organization feature, separately from repository access. The setting lives on the **Access settings** tab of the Resource Groups settings page.
- - + The Granular feature access table +
The following features can be restricted: @@ -125,9 +138,11 @@ For each one, you can pick who has access: - **Org admins only**: only organization admins keep access. - **Specific resource groups**: only members of the selected Resource Groups depending on their role in the group. -Organization admins always keep access to every feature, whichever option is selected. If a feature is restricted to specific resource groups, associated resources must reside within those resource groups (only organization admins retain the ability to do so at the organization root level). +Organization admins always keep access to every feature, whichever option is selected. + +Restricting a feature to specific resource groups controls **who** can use the feature, not **where**. Members of the selected groups can keep using the feature anywhere in the organization (for example, creating a collection that belongs to no resource group), while other members lose access to the feature entirely. The restriction never grants extra permissions: what a member can do is still determined by their organization role. -Members without access can no longer use the feature in the organization's context, from the API as well as the UI — API requests return an authorization error. Nothing changes for them under their personal account or in another org. +Members without access can no longer use the feature in the organization's context, from the API as well as the UI. API requests return an authorization error. Nothing changes for them under their personal account or in another org. ## Cost attribution @@ -137,7 +152,7 @@ Members without access can no longer use the feature in the organization's conte Resource Groups also serve as a cost attribution unit for compute services. When compute is billed to a resource group, costs are tracked separately per group, making it easier to understand spending across teams. - **Spaces**: cost is automatically attributed to the resource group the Space belongs to. -- **Jobs**: pass the resource group's ID as the `namespace` when creating a job. See [Bill to a resource group](./jobs-pricing#bill-to-a-resource-group). +- **Jobs**: pass the resource group's ID as the `resourceGroupId` field when creating a job. See [Bill to a resource group](./jobs-pricing#bill-to-a-resource-group). - **Inference Providers**: pass the resource group's ID via the `X-HF-Bill-To` header (or `bill_to` parameter in the SDK). See [Billing for Team and Enterprise organizations](/docs/inference-providers/pricing#billing-for-team-and-enterprise-organizations). - **Inference Endpoints**: cost is automatically attributed to the resource group the model repository belongs to. Endpoints instantiated directly from the built-in Inference Endpoints catalog aren't supported at this time. @@ -148,7 +163,12 @@ You can use the Enterprise plan and above. -On top of tracking costs, you can cap them. Organization admins and resource group admins can set monthly spending limits on the group's page in the Resource Groups settings, from the **Spend limits** card. +On top of tracking costs, you can cap them. Organization admins and resource group admins can set monthly spending limits in the group's **Settings** tab, under **Spend limits**. + +
+ The Spend limits settings + +
Two kinds of limits are available, both expressed in USD: @@ -157,7 +177,7 @@ Two kinds of limits are available, both expressed in USD: Leave a field empty for no limit. When a total limit and a per-product limit both apply, the stricter of the two wins. -Limits apply to the spend attributed to the group for the current calendar month, so a group that hit its limit is unblocked at the beginning of the next month — or as soon as an admin raises the limit. +Limits apply to the spend attributed to the group for the current calendar month, so a group that hit its limit is unblocked at the beginning of the next month, or as soon as an admin raises the limit. ### What happens when a limit is reached