From 4436d8030eb6f4fac8db22edb4dd908e098e4ef7 Mon Sep 17 00:00:00 2001 From: Yulong Ruan Date: Sun, 8 Oct 2023 23:19:14 +0800 Subject: [PATCH] Add workspace documentation Signed-off-by: Yulong Ruan --- docs/plugins/workspace.md | 171 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 171 insertions(+) create mode 100644 docs/plugins/workspace.md diff --git a/docs/plugins/workspace.md b/docs/plugins/workspace.md new file mode 100644 index 000000000000..53f898fed098 --- /dev/null +++ b/docs/plugins/workspace.md @@ -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", "", ""] +} +``` +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 `` +```typescript +{ + type: "visualization", + id: "da123f20-6680-11ee-93fa-df944ec23359", + workspaces: ["M5NqCu", "", ""] +} +``` +Then a new object will be created with new `id` and associated with `` +```typescript +{ + type: "visualization", + id: "", + workspaces: [""] +} +``` +### 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 ``. +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 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. + + + + + +