<!-- Source: https://docs.squirro.com/en/latest/technical/workspaces/index.html -->
# Workspaces

The Workspaces feature, formerly known as tenants, offers administrators and engineers more flexibility for content management, and additional granularity for access rights and data management. This approach favours efficient resource utilization and allow multiple departments and business units to share a single Squirro cluster, while operating in isolated environments. Each workspace data is secured and invisible to other workspaces. A workspace can be created by a Workspace Manager.

Workspaces represents the actual “ACL boundaries” and it is the Workspace Manager’s responsibility to ensure that the users have the correct access rights to the workspaces and their associated projects.

For certain use cases where Squirro assets shall not be shared among projects, workspaces will have one project only (unless the Workspace Manager decides otherwise).

The following diagrams show how clusters, servers, workspaces, and projects relate to each other.

**Without Workspaces**

```text
┌─────────────────────────────────────────────────────┐
│                     CLUSTER                         │
│                                                     │
│   ┌─────────────────────────────────────────────┐   │
│   │              SERVER / INSTANCE              │   │
│   │  ┌───────────┐  ┌───────────┐  ┌─────────┐  │   │
│   │  │ Project A │  │ Project B │  │Project C│  │   │
│   │  └───────────┘  └───────────┘  └─────────┘  │   │
│   └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

**With Workspaces enabled**

```text
┌─────────────────────────────────────────────────────┐
│                     CLUSTER                         │
│                                                     │
│   ┌─────────────────────────────────────────────┐   │
│   │              SERVER / INSTANCE              │   │
│   │  ┌────────────────┐  ┌────────────────┐     │   │
│   │  │  WORKSPACE A   │  │  WORKSPACE B   │     │   │
│   │  │                │  │                │     │   │
│   │  │  ┌──────────┐  │  │  ┌──────────┐  │     │   │
│   │  │  │Project A1│  │  │  │Project B1│  │     │   │
│   │  │  └──────────┘  │  │  └──────────┘  │     │   │
│   │  │  ┌──────────┐  │  │  ┌──────────┐  │     │   │
│   │  │  │Project A2│  │  │  │Project B2│  │     │   │
│   │  │  └──────────┘  │  │  └──────────┘  │     │   │
│   │  └────────────────┘  └────────────────┘     │   │
│   └─────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

## Activation

> **Feature only available for new deployments**
>
> You must enable Workspaces directly after the installation of the Squirro Platform, before adding users and interacting with the user interface.

Squirro administrators can turn on the Workspaces feature using the `common.ini` configuration file.

1. Edit the `common.ini` configuration file.
2. Locate the `[security]` configuration block. If it doesn’t exist, create one at the end of the file.
3. Add the `workspaces = true` setting on a new line.
4. Save your edits.
5. Restart all the services using the `squirro_restart` command.

See the [Accessing Servers](../admin/operations/accessing-servers.md#admin-access) and [common.ini](../admin/configuration/config-files/common-ini.md#admin-common-ini) pages for more information.

Once activated, the system adapts the user interface and renames the Server space to Workspaces.

> **Workspaces requires single sign-on (SSO)**
>
> After successfully activating Workspaces on your instance, visit the [Squirro Support website](https://go.squirro.com/support) and submit a technical support request.

## Navigation

When navigating the Dashboards and Setup spaces, the project browser in the top left corner allows you to switch between projects or create new ones. The user interface groups projects by workspace and only displays the ones you have access to.

As a user with administrative rights, when navigating the Workspaces and Cluster spaces, the top left corner contains now a workspace selector.

## Permissions

### Inheritance

The separation of Cluster, Workspace and Project roles and permissions comes with some basic inheritance properties.

Cluster Admins are automatically Workspace Admins in all Workspaces.

Workspace Admins are automatically Project Admins in all projects contained inside that Workspace.

Cluster Admins are thus also automatically Project Admins in all projects.

Non-admin Cluster users can be Workspace Admins, and non-admin Workspace users can be Project Admins.

### Cluster Roles

Workspaces creates a new set of global permissions accessible under the Cluster space. The mapping of groups to Squirro roles in the SSO configuration determines the role of a user at the Cluster level.

The Cluster Owner role has the same permissions as any Cluster Admin and is thus not shown here.

Inviting members to the Cluster and changing Cluster Roles is handled by the SSO configuration.

| Permissions | Cluster Admin | Cluster User | Cluster Reader |
| --- | --- | --- | --- |
| Create new Workspaces |  |  |  |
| See all Workspaces in the Cluster |  |  |  |
| See all Workspaces in the Cluster for which they are also Workspace Admins |  |  |  |
| Delete Workspaces |  |  |  |

### Workspace Roles

Note that since Cluster Admins are Workspace Admins by inheritance, these users will have all the permissions in the following two tables.

We split Workspace permissions into two tables, depending on the Cluster role.

#### Cluster Users

| Permissions | Cluster User Workspace Admin | Cluster User Workspace User | Cluster User Workspace User - Restricted |
| --- | --- | --- | --- |
| Change account information |  |  |  |
| Access the instance API information |  |  |  |
| Access Workspaces they are Workspace Admins of |  |  |  |
| Rename Workspaces |  |  |  |
| Create Projects within a Workspace where the user has the indicated Workspace role |  |  |  |
| Create and upload pipelets |  |  |  |
| See Projects for which they are not members of |  |  |  |
| See Projects for which they are members of |  |  |  |
| Access the Squirro Monitoring space |  |  |  |

#### Cluster Readers

| Permissions | Cluster Reader Workspace Admin | Cluster Reader Workspace User | Cluster Reader Workspace User - Restricted |
| --- | --- | --- | --- |
| Change account information |  |  |  |
| Access the instance API information |  |  |  |
| Access Workspaces they are Workspace Admins of |  |  |  |
| Rename Workspaces |  |  |  |
| Create Projects within a Workspace where the user has the indicated Workspace role |  |  |  |
| Create and upload pipelets |  |  |  |
| See Projects for which they are not members of |  |  |  |
| See Projects for which they are members of |  |  |  |
| Access the Squirro Monitoring space |  |  |  |

### Project-Level Roles

Note that since Workspace Admins are Project Admins by inheritance, these users will have all the permissions in the following table.

| Permissions | Project Admin | Project Member | Project Reader |
| --- | --- | --- | --- |
| Read items |  |  |  |
| Manage Data sources |  |  |  |
| Manage dashboards |  |  |  |
| Manage saved searches |  |  |  |
| Manage project members |  |  |  |
| Delete project |  |  |  |

## Management

To manage the existing workspaces or create new ones, click the Spaces menu in the to right corner and click the Cluster icon, then select Workspaces in the left menu.

## Asset upload

The `squirro_asset` command from the Python toolbox requires the additional input argument `--workspace` when the Workspaces feature is enabled. The code snippet below shows how to upload a pipelet to the `workspace-squirro` workspace:

```bash
#!/usr/bin/env bash

CLUSTER="https://..."
TOKEN="..."
WORKSPACE="workspace-squirro"

squirro_asset -v pipelet upload \
    --token "$TOKEN" \
    --cluster "$CLUSTER" \
    --workspace "$WORKSPACE" \
    'pipelet.py' 'Country tagger'
```

After the pipelet is successfully uploaded, the pipelet can be added to any ingestion pipeline of any project within the `workspace-squirro` workspace.

[Learn more](../pipelets/workflow.md#pipelets-workflow)