forked from opensearch-project/OpenSearch-Dashboards
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Signed-off-by: Yulong Ruan <ruanyl@amazon.com>
- Loading branch information
Showing
1 changed file
with
171 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,171 @@ | ||
# Workspace | ||
Workspace is a pivotal feature within OpenSearch-Dashboards, empowering users to craft distinct workspaces | ||
by meticulously curating a selection of features and plugins tailored to specific use cases. This functionality | ||
not only facilitates clients in the systematic organization of visual assets, including saved_objects such as | ||
dashboards and visualizations, but also categorizes them logically within dedicated workspaces. This strategic | ||
approach enhances overall efficiency and manageability, making it an indispensable asset for OpenSearch-Dashboards | ||
users seeking precision and flexibility in their workflows. | ||
|
||
## Scopes | ||
In an OpenSearch cluster, when viewed from the perspective of OpenSearch Dashboards (OSD), data can be categorized | ||
into two primary types: | ||
|
||
1. OSD Metadata: This category includes critical OSD metadata, which is stored in a metadata store. Examples of OSD | ||
metadata includes visualizations, dashboards, index patterns, UI settings, etc. | ||
2. Other OpenSearch Indices: In addition to OSD metadata, an OpenSearch cluster may contain various other OpenSearch | ||
indices for storing data unrelated to OSD. | ||
|
||
The concept of a "workspace" in OSD is primarily concerned with the management and organization of OSD metadata (Type #1). | ||
Workspaces do not encompass the management of data stored by plugins that maintain their independent data stores within | ||
the OpenSearch cluster. If a plugin requires the creation of data specific to a workspace, it must store this data within | ||
the OSD metadata store using Saved Objects. Within OSD workspaces, our focus remains squarely on OSD metadata. | ||
|
||
## Workspace data model | ||
The Workspace data model defines the fundamental structure for managing isolated environments dedicated to metadata | ||
management within OpenSearch Dashboards. | ||
|
||
```typescript | ||
interface Workspace { | ||
id: string | ||
name: string | ||
description?: string | ||
features?: string[] | ||
reserved?: boolean | ||
} | ||
``` | ||
|
||
1. `id`: A unique identifier that distinguishes each workspace. | ||
2. `name`: The name of the workspace. | ||
3. `description`: A description providing context for the workspace. | ||
4. `features`: An array of application IDs associated with the workspace, derived from the plugins registered. These application IDs | ||
are used to filter and display the relevant plugins in the left navigation menu when accessing the workspace. It serves as a visual | ||
mechanism for organizing and presenting features. | ||
6. `reserved`: A boolean flag indicating whether the workspace is system-reserved. System-reserved workspaces may have certain operations | ||
restricted for end users. | ||
|
||
|
||
**Workspace object example 1:** | ||
```typescript | ||
{ | ||
id: "M5NqCu", | ||
name: "Sales team", | ||
description: "dashboards of sale analytics", | ||
features: ["dashboards", "visualize"], | ||
reserved: false | ||
} | ||
``` | ||
|
||
Example #1 represents a workspace typically created by a user, with the reserved flag set to false. This user-created workspace can be | ||
customized with specific features tailored to its purpose. | ||
|
||
**Workspace object example 2:** | ||
```typescript | ||
{ | ||
id: "management", | ||
name: "Management", | ||
description: "Management workspace for OSD admin", | ||
features: ["@management", "dataSources", "dev_tools"], | ||
reserved: true | ||
} | ||
``` | ||
|
||
Example #2 is a system-reserved workspace, automatically generated by the workspace plugin for the user. The reserved flag is set to true. | ||
This workspace includes the `@management` category, which includes all features within that category. The `@` symbol indicates that it is a | ||
category. The `management` is the category id which the plugins specified when register applications. | ||
|
||
## Associate saved objects with workspaces | ||
Saved objects, such as dashboards, visualizations, and index patterns, form the backbone of data visualization and analysis in OpenSearch Dashboards. | ||
However, as the volume of saved objects grows, keeping them organized becomes increasingly challenging. Grouping saved objects into distinct workspaces, | ||
each serving a specific purpose or team. This association not only simplifies the process of finding and accessing relevant saved objects but also | ||
enhances security and access control (Please ref to this [DOC](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633) for more details | ||
about access control). | ||
|
||
A new attribute, `workspaces`, is being added to saved objects which type is an array of string. A saved object can be associated with one | ||
or multiple workspaces. The saved objects(dashboards, visualizations, etc) will only be displayed in the associated workspaces. | ||
|
||
The follow example shows the dashboard object is associated with workspace which id is `M5NqCu` | ||
```typescript | ||
{ | ||
type: "dashboard", | ||
id: "da123f20-6680-11ee-93fa-df944ec23359", | ||
workspaces: ["M5NqCu"] | ||
} | ||
``` | ||
|
||
Saved object can also associated with multiple workspaces, this is useful in scenarios where a saved object is relevant | ||
to multiple teams, projects, or use cases. | ||
|
||
Consider the following example, where a visualization is associated with multiple workspaces: | ||
```typescript | ||
{ | ||
type: "visualization", | ||
id: "da123f20-6680-11ee-93fa-df944ec23359", | ||
workspaces: ["M5NqCu", "<TeamA-workspace-id>", "<Analytics-workspace-id>"] | ||
} | ||
``` | ||
By allowing saved objects to be linked with multiple workspaces, this enables users to share and collaborate on resources | ||
across various workspaces(teams). | ||
|
||
## Copy saved objects among workspaces | ||
While associating saved objects with multiple workspaces links a single object instance to multiple places, copying saved | ||
objects takes a different approach. When copying objects, it creates hard copies of the objects in the target workspace, | ||
regardless of their original workspaces. | ||
|
||
For example, if copy this object to `<target-workspace>` | ||
```typescript | ||
{ | ||
type: "visualization", | ||
id: "da123f20-6680-11ee-93fa-df944ec23359", | ||
workspaces: ["M5NqCu", "<TeamA-workspace-id>", "<Analytics-workspace-id>"] | ||
} | ||
``` | ||
Then a new object will be created with new `id` and associated with `<target-workspace>` | ||
```typescript | ||
{ | ||
type: "visualization", | ||
id: "<new-object-id>", | ||
workspaces: ["<target-workspace>"] | ||
} | ||
``` | ||
### Handling Dependencies | ||
A significant aspect of copying saved objects is the handling of dependencies. Many saved objects, particularly | ||
visual objects like dashboards and visualizations, often have a hierarchical structure with dependencies. | ||
For example, a dashboard may depend on multiple visualizations, and each visualization may rely on specific | ||
index pattern objects. | ||
|
||
The copying process is not limited to the saved object itself. Instead, it copies the entire dependency hierarchy | ||
associated with the saved object. For example: | ||
1. If the visualization depends on specific index pattern objects, these index pattern objects will also be duplicated | ||
in `<target-workspace>`. | ||
2. If the dashboard depends on multiple visualizations, those visualizations and their associated index patterns will | ||
be copied as well. | ||
|
||
This ensures that the copied saved object in <target-workspace> retains its functionality and context, with all necessary | ||
dependencies in place. | ||
|
||
## Reserved workspaces | ||
Reserved workspaces are created automatically by workspace plugin, they have pre-defined configurations, including features | ||
and permissions tailored to their intended purposes. Currently, workspace plugin creates three distinct reserved workspace: | ||
|
||
1. Global Workspace | ||
- **Purpose**: The Global Workspace serves as a centralized environment for managing resources and configurations that apply | ||
globally across OpenSearch Dashboards. | ||
- **Features**: It includes features that are accessible to all users, regardless of their specific teams or projects. | ||
- **Permissions**: All users have `read` and `write` permission to public workspace and its associated saved objects. | ||
2. Personal Workspace | ||
- **Purpose**: The Personal Workspace is designed to provide individual users with a dedicated space for their personal work. | ||
However, it's important to note that a **Personal Workspace will only be created if user/role information can be retrieved**. | ||
- **Features**: Users have the flexibility to configure their Personal Workspace according to their preferences and requirements. | ||
- **Permissions**: Access to the Personal Workspace is limited to the user who owns it, ensuring data privacy and personalization. | ||
3. Management Workspace | ||
- **Purpose**: The Management Workspace is dedicated to administrative tasks and configurations within OpenSearch Dashboards. | ||
- **Features**: It encompasses features and tools necessary for system administrators to manage OSD advanced settings, data sources | ||
, and other administrative functions such as security configuration, etc. | ||
- **Permissions**: Initially, access to the Management Workspace is set to public during initialization, administrators have the | ||
responsibility and privilege to restrict access and define permissions within the Management Workspace. | ||
|
||
|
||
|
||
|
||
|
||
|