Tenants and management

A tenant is an allotment of users and resources within an organization. Organizations can leverage tenants for distinct purposes, such as development or production, and then share common resources across tenants. Each tenant has its own resources, users, and workloads. SambaStudio allows organizations to allocate resources across multiple tenants.

This document describes:

See Users and management for more information on SambaStudio user roles and management.

Structure and nomenclature

SambaStudio uses the following terminology in describing hardware, tenants, organizational structure, and users.

Organization

Organization describes an entity or customer using SambaStudio.

User

A user is part of an organization and can be assigned a predefined role. A user can be part of and assigned to multiple tenants. All users within the same tenant can view or manage projects and workloads present in the tenant.

Tenant

A tenant is an allotment of users and resources within an organization. Each tenant has its own resources, users, and workloads.

Default tenant

The default tenant is where all resources are allocated initially. During the SambaStudio installation, the default tenant (Default Tenant) is created and an organization administrator (OrgAdmin) is assigned to it.

When updating tenant RDUs and reallocation of resources is performed, resources will get removed from the selected tenant and assigned to the default tenant. The resources then can be added from the default tenant to another tenant.

Project

A project is a logical grouping of workloads and artifacts within a tenant.

Nodes and RDUs

A node describes the collection of SambaNova Systems' Reconfigurable Dataflow Units™ (RDUs) available per SambaNova hardware generation. For each SambaNova hardware generation (SN10, SN30, SN40L), a total of eight RDUs are available per node. The number of nodes per hardware configuration affects the the number of available RDUs. For example, if your SN10 hardware generation is configured with two nodes, you will have a total of 16 RDUs (eight RDUs per node).

If a job or endpoint requires more than one RDU to start, the RDUs must be available on the same node of the SambaNova hardware generation (SN10, SN30, SN40L).

Switching tenants

SambaStudio allows users to switch the active tenant they are using from any window in the platform. By switching tenants, users can view or manage projects and workloads that are present in multiple tenants.

A user must be assigned to more than one tenant by an organization administrator or tenant administrator in order to switch tenants.

  1. Click the tenant selection drop-down in the top menu bar. A list of your assigned tenants will display with the current tenant highlighted in blue and a checkmark. Only tenants assigned to you by your organization administrator or tenant administrator will be displayed.

    Tenant selection drop-down
    Figure 1. Tenant selection drop-down

  2. Select and click the destination tenant to switch. That will now be the active tenant.

RDUs available drop-down

The RDUs available drop-down provides a summary of the RDUs for the selected tenant (displayed immediately to the left). It can be viewed from any window in the platform. Hover over RDUs available in the top menu bar to view the drop-down summary.

The example image below displays the following:

  • There are 16 total RDUs available for the default tenant.

  • There are nine busy RDUs for the default tenant.

  • There are seven available RDUs for the default tenant.

  • There are no jobs running in the default tenant.

  • There is one live endpoint deployed in the default tenant.

  • The SambaStudio platform is configured with one SN10 hardware generation.

RDUs available drop-down
Figure 2. RDUs available drop-down for the default tenant

View node information

Click the hardware generation icon (SN10 in our example) to expand the drop-down to view its node activity. If your SambaStudio platform is configured with more than one hardware generation (SN10, SN30, SN40L), click each hardware generation icon to view its node activity.

The expanded drop-down image below displays the following:

  • Two nodes have been allocated to the default tenant. Each node has eight RDUs, for a total of 16 RDUs.

  • All eight RDUs are busy on Node 1.

  • One RDU is busy on Node 2, with seven RDUs available.

Expanded RDUs available
Figure 3. Expanded RDUs available

Tenant management using the GUI

An organization administrator (OrgAdmin) can click Tenant management from the left menu. The Tenant management window displays resource and allocation information available to an organization administrator (OrgAdmin).

Tenant management window
Figure 4. Tenant management window

Organizational resources

The Organizational resources section displays platform specific information.

  • Available nodes displays the number of available nodes in the SambaStudio platform.

  • Busy nodes displays the number of nodes that are currently busy performing tasks.

  • Total nodes displays the number of nodes that are available to perform new tasks.

Organizational resources
Figure 5. Organizational resources

Current allocations

The Current allocations section displays the current tenant configurations of the platform in a table and allows organization administrators (OrgAdmin) to manage tenant resources.

Click Create tenant to create a tenant using the GUI.

Click Update allocations to update the tenant allocations for a tenant using the GUI.

  • The Tenant name column displays the tenant name of each tenant.

  • The Allocated nodes column displays the number of nodes allocated to each tenant.

  • The Busy nodes column displays the number of nodes that are currently busy performing tasks of each tenant.

  • The Available nodes column displays the number of nodes of each tenant that are available to perform new tasks.

  • The Status column displays the current status of each tenant.

    • Creating displays when a new tenant is being created.

    • Updating displays when a tenant allocation is being updated.

    • Ready displays when a tenant has been setup, but has no nodes allocated to it.

    • Available displays when a tenant has been setup and has at least one node allocated to it.

    • Deleting displays when the tenant has been confirmed by an organization administrator (OrgAdmin) to be permanently deleted.

    • Failed displays when the process of creating, deleting, or updating a tenant fails.

  • The three dots open a drop-down menu that allows you to update allocations of the tenant in that row, or delete the tenant.

Current allocations
Figure 6. Current allocations

Tenant management using the CLI

Similar to the GUI, the SambaNova API (snapi) provides tenant management capabilities via the CLI.

List the available tenants using the CLI

The example below demonstrates how to view the available tenants using the snapi tenant list command.

This command is available to all user roles.
Example snapi tenant list command
$ snapi tenant list
NAME                    CREATED AT                                  LAST UPDATED                                STATUS
default                 2023-04-28 13:23:58.872154 +0000 UTC        2024-01-19 14:40:20.706376 +0000 UTC        Available
tenant1                 2023-04-28 13:37:10.398432 +0000 UTC        2024-01-20 07:44:07.661575 +0000 UTC        Ready
tenant3                 2023-05-02 09:40:33.767691 +0000 UTC        2023-11-10 13:18:41.811529 +0000 UTC        Ready

Tenant information using the CLI

You can use the snapi tenant info command to display information of a specific tenant.

This command is available to all user roles.

You will need to specify the tenant you wish to view for the --tenant input. The example command below displays information for the default tenant, including:

  • The assigned ID of the tenant.

  • The Name of the tenant.

  • Allocated nodes displays the number and generation version of nodes allocated to the tenant. In the example below, the default tenant has two SN10 nodes.

  • Busy nodes displays the number of nodes that are currently busy performing tasks of the tenant. In the example below, one of the two allocated SN10 nodes is busy.

  • Available nodes displays the number of nodes of the tenant that are available to perform new tasks. In the example below, one of the two allocated SN10 nodes is available.

  • Status displays the current status of the tenant.

    • Creating displays when the tenant is being created.

    • Updating displays when the allocation of the tenant is being updated.

    • Ready displays when the tenant has been setup, but has no nodes allocated to it.

    • Available displays when the tenant has been setup and has at least one node allocated to it.

    • Deleting displays when the tenant has been confirmed by an organization administrator (OrgAdmin) to be permanently deleted.

    • Failed displays when the process of creating, deleting, or updating a tenant fails.

Example snapi tenant info
$ snapi tenant info \
    --tenant default

         Tenant Info
         ============
ID                      : 0e6890c5-973c-4024-ac43-1c302aa81950
Name                    : default
Display Name            : default
Allocated Nodes          : {"SN10": 2}
Busy Nodes               : {"SN10": 1}
Available Nodes          : {"SN10": 1}
Created at              : 2023-04-28 13:23:58.872154 +0000 UTC
Last Updated            : 2024-01-19 14:40:20.706376 +0000 UTC
Status                  : Available

Create a tenant using the GUI

Organization administrators (OrgAdmin) can create a new tenant using the GUI by following the steps below.

  1. Click the Create tenant button. The Create new tenant box will open.

  2. Enter a name for the tenant in the Add tenant name field. Note that spaces are not accepted in this field.

  3. Click Create to complete the process. Click Cancel to stop the process and return to the Tenant management window.

Create new tenant
Figure 7. Create new tenant

Create a tenant using the CLI

The example below demonstrates how organization administrators (OrgAdmin) can create a tenant using the snapi tenant create command. You will need to specify a name for the tenant.

Example snapi tenant create
$ snapi tenant create \
	--name <name-for-new-tenant>

Update tenant resource allocations using the GUI

Organization administrators (OrgAdmin) can change the number of nodes allocated to a tenant using the GUI by following the steps below.

Resource allocations cannot be changed for the default tenant.

  1. Click the Update allocations button. The Update resource allocation box will open.

  2. Select the tenant you wish to manage from the Select a tenant drop-down.

  3. Change the number of nodes per SambaNova hardware generation version assigned to the tenant by inputting the number or clicking the up or down arrows.

    1. To remove a node, precede the number with a minus (-1) or click the down arrow.

    2. As shown in Figure 8, tenant1 currently has no nodes allocated to it.

    3. As shown in Figure 8, one node of the SN10 hardware generation version is being added for tenant1.

  4. Click Update to complete the process. Click Cancel to stop the process and return to the Tenant management window.

Update resource allocation
Figure 8. Update resource allocation

Update tenant RDUs using the CLI

The example snapi tenant update command below demonstrates how organization administrators (OrgAdmin) can update an existing tenant allocation using the CLI.

You will need to specify the following for the snapi tenant update command:

  • The tenant that will be updated for the --tenant input.

    • tenant1 is used in the example below.

  • The number of nodes to add or remove for the --rdu-nodes input.

    • We specified 1 node to be added in the example below.

    • To remove a node, precede the number with a minus (-1).

  • The SambaNova hardware generation (SN10, SN30, SN40L) that contains the --rdu-nodes for the --arch input.

    • We specified SN10 in the example below.

The snapi tenant update command below adds one SN10 node to tenant1.
Example snapi tenant update
$ snapi tenant update \
	--tenant tenant1 \
	--rdu-nodes 1 \
	--arch SN10

Delete a tenant using the GUI

Organization administrators (OrgAdmin) can delete a tenant using the GUI by following the steps below. Please be aware of the following considerations when deleting a tenant:

  • The default tenant cannot be deleted.

  • All jobs, endpoints, datasets, and models created in the tenant will be deleted.

  • Associated users will no longer have access to the tenant.

  • RDUs allocated to the tenant will be added to the default tenant.

  • Tenant deletion is irreversible.

Tenant deletion times vary and are dependent on the number of resources associated with the tenant.

  1. In the Current allocations table, click Delete tenant from the three dots drop-down in the row of the tenant you wish to delete.

    Delete tenant drop-down
    Figure 9. Delete tenant drop-down

    1. The Permanently delete this tenant box will open describing the associated actions of deleting the tenant.

  2. Click the acknowledgement statement checkbox and Confirm to proceed.

    Permanently delete tenant box
    Figure 10. Permanently delete this tenant box

  3. The Deleting tenant panel will display describing the steps of the tenant deletion process. The blue numerical circle indicates the step progress of the tenant deletion. Click anywhere in the SambaStudio screen to close the panel.

    Tenant deleting panel
    Figure 11. Deleting tenant panel

  4. The tenant status will change to Deleting. Click View to open the Deleting tenant panel and monitor the progress of the tenant deletion.

    View deleting tenant panel
    Figure 12. View deleting tenant panel

  5. The tenant will be removed from the Current allocations table when the deletion process is complete.

Delete a tenant using the CLI

The example commands below demonstrate how organization administrators (OrgAdmin) can delete a tenant using the snapi tenant delete command. Please be aware of the following considerations when deleting a tenant:

  • The default tenant cannot be deleted.

  • All jobs, endpoints, datasets, and models created in the tenant will be deleted.

  • Associated users will no longer have access to the tenant.

  • RDUs allocated to the tenant will be added to the default tenant.

  • Tenant deletion is irreversible.

Tenant deletion times vary and are dependent on the number of resources associated with the tenant.

The example snapi tenant delete command illustrates the following:

  • The command specifies user-workflows as the tenant to be deleted.

  • Similar to the GUI, the associated actions of deleting the tenant are described.

  • Additionally, the command prompts you to confirm that you want to proceed with deleting the tenant by entering yes.

Example snapi tenant delete
$ snapi tenant delete \
	--name user-workflows

Deleting a tenant entails four steps:
    • Step1: Unsharing Datasets and Models (Revoking access to all datasets and models shared with other
tenants)
    • Step2: Delete Jobs and Endpoints (Terminating all running jobs, live endpoints, and deleting them)
    • Step3: Delete Datasets and Models (Deleting all datasets and models associated with this tenant)
    • Step4: Tenant Deletion (Returning RDUs to the default tenant and deleting all traces of this tenant)

Are you sure you want to proceed? (yes/no):: yes

To return to the CLI prompt, press Ctrl+C
The tenant deletion process will continue in the background. You can view the status using the command: snapi
tenant deletion-progress <tenant-name>

--------------------------------
Tenant Deletion in Progress...
--------------------------------

[Progress] Steps: 1 -  Done  | 2 - Done | 3 - Done | 4 - Done

-------------------------------------------------------
Deletion of user-workflows Tenant Succesful
-------------------------------------------------------

Run snapi tenant delete --help for command options and information.

View tenant deletion progress using the CLI

Organization administrators (OrgAdmin) can view the deletion progress of a tenant by running the snapi tenant deletion-progress command. The example command below specifies user-workflows for the tenant.

Example snapi tenant deletion-progress
$ snapi tenant deletion-progress \
	--name user-workflows

Deleting a tenant entails four steps:
    • Step1: Unsharing Datasets and Models (Revoking access to all datasets and models shared with other
tenants)
    • Step2: Delete Jobs and Endpoints (Terminating all running jobs, live endpoints, and deleting them)
    • Step3: Delete Datasets and Models (Deleting all datasets and models associated with this tenant)
    • Step4: Tenant Deletion (Returning RDUs to the default tenant and deleting all traces of this tenant)

[Progress] Steps: 1 -  Done  | 2 - Done | 3 - In Progress | 4 - Not Started