From 77c6e4ad354e3631476224617df6ad22fd18b37b Mon Sep 17 00:00:00 2001 From: Yulong Ruan Date: Sun, 8 Oct 2023 23:19:14 +0800 Subject: [PATCH 1/3] Add workspace documentation Signed-off-by: Yulong Ruan --- docs/plugins/workspace.md | 186 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 186 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..9b311e065a09 --- /dev/null +++ b/docs/plugins/workspace.md @@ -0,0 +1,186 @@ +# 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 be 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). + +## Non-workspace saved objects +While the introduction of workspaces in OSD provides a powerful framework for organizing and managing saved objects, it's +important to note that not all saved objects are necessarily associated with workspaces. Some saved objects, by their +nature or purpose, may exist independently of workspaces. + +For example, the global UI settings object. This object contains configurations and settings that apply globally across +OSD, affecting the overall user interface and user experience. These settings are not tied to any specific workspace +because they are intended to impact the entire OSD. Such objects won't have `workspaces` attribute. + +The coexistence of workspace-associated saved objects and those without workspace association ensures that OSD strikes +a balance between context-specific customization and system-wide consistency. + +## Duplicate saved objects among workspaces +While associating saved objects with multiple workspaces links a single object instance to multiple places, duplicating saved +objects takes a different approach. When duplicating objects, it creates hard copies of the objects in the target workspace, +regardless of their original workspaces. + +For example, if duplicate 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 duplicating 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 duplicating process is not limited to the saved object itself. The user has the flexibility to choose whether +or not to duplicate the entire dependency tree. If duplicating the entire dependency hierarchy, all dependencies +will be duplicated. 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 global 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, such as + index management, security configuration, snapshot management, 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. + +## Appendix +1. The PR the introduce [object access control](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/5083) +2. The [PR](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633/files)of the design doc for saved object access control + + + + From 7784896f7786297fd04962db368f571ce53df768 Mon Sep 17 00:00:00 2001 From: Yulong Ruan Date: Fri, 13 Oct 2023 09:49:38 +0800 Subject: [PATCH 2/3] update per comment Signed-off-by: Yulong Ruan --- docs/plugins/workspace.md | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/plugins/workspace.md b/docs/plugins/workspace.md index 9b311e065a09..e7321ee14233 100644 --- a/docs/plugins/workspace.md +++ b/docs/plugins/workspace.md @@ -1,10 +1,9 @@ # 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. +Workspace is a significant feature in OpenSearch-Dashboards, allowing users to create customized workspaces by +selecting specific features and plugins that align with their particular use cases. This feature helps users +organize visual assets, such as saved_objects like dashboards and visualizations, in a structured manner within +dedicated workspaces. This approach aims to improve efficiency and manageability, making it a valuable tool for +OpenSearch-Dashboards users who want a more precise and flexible workflow. ## Scopes In an OpenSearch cluster, when viewed from the perspective of OpenSearch Dashboards (OSD), data can be categorized @@ -119,7 +118,7 @@ The coexistence of workspace-associated saved objects and those without workspac a balance between context-specific customization and system-wide consistency. ## Duplicate saved objects among workspaces -While associating saved objects with multiple workspaces links a single object instance to multiple places, duplicating saved +While associating saved objects with multiple workspaces links a single object instance to multiple places, duplicating saved objects takes a different approach. When duplicating objects, it creates hard copies of the objects in the target workspace, regardless of their original workspaces. @@ -168,7 +167,7 @@ and permissions tailored to their intended purposes. Currently, workspace plugin 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. + - **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. @@ -179,8 +178,5 @@ and permissions tailored to their intended purposes. Currently, workspace plugin ## Appendix 1. The PR the introduce [object access control](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/5083) -2. The [PR](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633/files)of the design doc for saved object access control - - - - +2. The [PR](https://github.com/opensearch-project/OpenSearch-Dashboards/pull/4633/files) of the design doc for saved object access control +3. Future Vision for Dashboards: [Issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/4298) \ No newline at end of file From 16aa2fb6d2a5af1a791d49de3c95d378c8706e78 Mon Sep 17 00:00:00 2001 From: Yulong Ruan Date: Fri, 13 Oct 2023 10:04:23 +0800 Subject: [PATCH 3/3] rename workspace documentation file Signed-off-by: Yulong Ruan --- docs/plugins/workspace.md => src/plugins/workspace/README.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/plugins/workspace.md => src/plugins/workspace/README.md (100%) diff --git a/docs/plugins/workspace.md b/src/plugins/workspace/README.md similarity index 100% rename from docs/plugins/workspace.md rename to src/plugins/workspace/README.md