From 780579bc84455e8dfac2bf1b8300b70418e65a15 Mon Sep 17 00:00:00 2001 From: Lenny Chen Date: Fri, 13 Dec 2024 12:44:42 -0800 Subject: [PATCH] docs: more workspace refactor work --- .../workspace/adding-a-new-workspace.md | 91 ++++++++++++------- .../workspace-mgmt/configure-rbac.md | 90 ++++++++++++++++++ .../workspace-mgmt/delete-workspace.md | 0 .../workspace/workspace-mgmt/resource-mgmt.md | 0 .../workspace-mgmt/restrict-images.md | 0 docs/docs-content/workspace/workspace.md | 60 +++++------- 6 files changed, 171 insertions(+), 70 deletions(-) create mode 100644 docs/docs-content/workspace/workspace-mgmt/configure-rbac.md create mode 100644 docs/docs-content/workspace/workspace-mgmt/delete-workspace.md create mode 100644 docs/docs-content/workspace/workspace-mgmt/resource-mgmt.md create mode 100644 docs/docs-content/workspace/workspace-mgmt/restrict-images.md diff --git a/docs/docs-content/workspace/adding-a-new-workspace.md b/docs/docs-content/workspace/adding-a-new-workspace.md index 2ee22e7ca7..bc9c370349 100644 --- a/docs/docs-content/workspace/adding-a-new-workspace.md +++ b/docs/docs-content/workspace/adding-a-new-workspace.md @@ -9,7 +9,7 @@ tags: ["workspace"] --- Palette enables multi-cluster management and governance capabilities by introducing Workspaces. This page teaches you -how to create a workspace in Palette. +how to create a workspace in Palette. All workspace settings can be updated after creation. ## Prerequisites @@ -65,44 +65,69 @@ how to create a workspace in Palette. ::: -7. Select the namespaces you want to include in the workspace. If the a cluster that is part of your workspace has that - namespace, the namespace and all resources that are scoped within it will be included in the workspace. You may use - regular expressions to match the names of namespaces. +7. Enter the namespaces you want to include in the workspace. If the a cluster that is part of your workspace has that + namespace, the namespace and all resources that are scoped within it will be included in the workspace. If any + cluster in the workspace is missing the namespace you entered, the namespace will be created on that cluster. You + must use the names of the namespaces exactly, not regular expressions. The regular expression entries are only used + for creating role bindings in a later step. -8. After selecting the namespaces, you can specify resource limits that each +8. After selecting the namespaces, you can specify resource limits that the workspace is allowed to consume in the + **Workspace Quota** section. The **Maximum CPU** and **Maximum Memory** allow you to specif the maximum amount of CPU + cores and memory that all resources in the entire workspace are allowed to consume. -9. - Configure the Cluster Role Binding (optional). Role bindings can be created on all workspace clusters. + You may also specify resource limits on specific namespaces. When you specify a namespace-based limit, it means that + namespace can get the resources you configured in each cluster. - - As step 2 of the new Workspace creation, select **Add Cluster Role Binding**. - - Provide the name of the role for which the cluster role binding needs to be created. The role should be - pre-existing or an in-built system role. Palette does not create cluster roles. - - Subjects for the cluster role binding can be groups, users, or service accounts. + For example, if you have two clusters `cluster1` and `cluster2`, and they each have a namespace called `default`. If + you impose a 2Gi memory limit on the namespace default, then the `default` namespace in both clusters will be able to + consume 2 Gi memory each. You must ensure that the namespaced-limits, when added together, do not exceed the total + workspace limit you configured. If we continue with the previous example, you imposed a workspace quota of 4 Gi + memory, then the `default` namespace cannot have more than 2 Gi of memory, since they are two such namespaces in the + workspace and both of them added together are allowed 4 Gi of memory. - | **Subject Type** | **Subject Name** | **Subject Namespace** | - | ------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | - | **User** | a valid path segment name | NA | - | **Group** | a valid path segment name | NA | - | **Service Account** | a valid path segment name | Granting super-user access to all service accounts
cluster-wide is strongly discouraged. Hence, grant a
role to all service accounts in a namespace. | +9. On the same **Namsespaces** page, you can optionally configure role bindings. When you configure a role binding for a + namespace, you are configuring the same role binding in that namespace in every cluster. Like in Kubernetes, you can + use either a role or a cluster role in a role binding. Similar to cluster role bindings, this action does not create + the roles or the subject for you. You must ensure that the corresponding role and subject referenced in the role + binding exists in the namespaces you configured. -10. Associate Namespaces + You can use Regular Expressions (regex) to create role bindings in multiple namespaces that match a certain pattern. + To do so, enter the regex in the namespace field. For example, `/palette-.*/` will match all namespaces that start + with `palette-`. When creating the role binding, you can select the regex as the namespace. - - Enter one or more namespaces that need to be part of the workspace. The combination of workspace and cluster is - unique across workspaces in a project. Palette ensures that all the namespaces are created for all the clusters in - the workspaces, in case they are not pre-existing. - - Add the resource quota for the namespaces by specifying CPU and Memory limits (optional). - - Configure the Role Binding (optional). The following information is required for each role binding: - - Select a namespace name or the Regex for namespaces for selecting multiple namespaces. - - Specific name for the role which is pre-existing - - Make the selection of Subjects from the dropdown list (User, Group, or ServiceAccount). For the subject - selected, provide a valid path segment name. For the subject, ServiceAccount select namespace name as granting - super-user access to all service accounts cluster-wide is strongly discouraged due to security concerns. - - Confirm the information provided to complete the configuration of role binding. + :::info + + Regex entries in the **Namespaces** field do not add the namespaces that match the regex to the workspace. You will + not be able to monitor resource usage, impose resource limits, or create backups unless you specifically add a + namespace by its name. + + ::: + + When you are finished, click **Next**. + +10. In the **Setting** page, you can schedule backups for select namespaces. These backups are created for each cluster + in the workspace. + + Like cluster backups in Palette, restoring a backup requires the source cluster to be available. When you restore a + back up, the namespaces that are backed up are restored to each cluster in the workspace. If you delete a cluster + from the workspace, that cluster's backup will not be restored. + + For more information about backups, refer to + [Backup and Restore](../clusters/cluster-management/backup-restore/backup-restore.md) + +11. Lastly, you can restrict certain container images from being loaded in the namespaces that are managed by the + workspace. To restrict images from being loaded by resources in a namespace, click **Add New Container Image**. + Select a namespace you want to restrict the image in, and enter the image URLs in a comma-separated list. When you + are done, click **Next**. + +12. Review your configurations and click **Finish Configuration** to create the workspace. + +## Validate + +1. Log in to [Palette](https://console.spectrocloud.com). -11. Settings +2. In the **Drop-Down Menu** at the top of the page, choose the project you created the workspace in. - - [Schedule Backups](../clusters/cluster-management/backup-restore/backup-restore.md) - set the backup and restore - policies. - - [Container Image](workload-features.md#restrict-container-images-to-a-workspace) - list out the container images - to be restricted within a Workspace namespace. +3. On the left **Main Menu**, click **Workspaces**. -Review and finish the configuration and complete the deployment. +4. Confirm the workspace has been created with the right configurations. diff --git a/docs/docs-content/workspace/workspace-mgmt/configure-rbac.md b/docs/docs-content/workspace/workspace-mgmt/configure-rbac.md new file mode 100644 index 0000000000..57f8f35ce0 --- /dev/null +++ b/docs/docs-content/workspace/workspace-mgmt/configure-rbac.md @@ -0,0 +1,90 @@ +--- +sidebar_label: "Configure RBAC in Workspaces" +title: "Configure RBAC in Workspaces" +description: "Learn how to configure RBAC in workspaces." +hide_table_of_contents: false +sidebar_custom_props: + icon: "workspaces" +tags: ["workspace", "rbac"] +--- + +Workspaces extends Kubernetes' native Role-Based Access Control (RBAC) model to allow you to create role bindings and +cluster role bindings at the workspace level, unifying authorization across different clusters. This page teaches you +how to create workspace-level role bindings and cluster role bindings. + +RBAC in workspaces is distinct from Palette RBAC. Palette RBAC regulates access to Palette resources such as clusters, +workspaces, and Edge hosts and its subjects are Palette users. Workspace RBAC is an extension of Kubernetes' native RBAC +model. It regulates access to Kubernetes objects in the clusters encompassed by the workspace, and its subjects are +Kubernetes users, groups and service accounts. + +| | Workspace RBAC | Palette RBAC | +| --------------------- | ----------------------------------------------- | -------------------------------------------------------- | +| Access control domain | Kubernetes clusters in the workspace. | Palette resources. | +| Subjects | Kubernetes users, groups, and service accounts. | Palette users and teams | +| Example resources | ConfigMaps, Secrets, Pods, StatefulSets, etc. | Cluster profiles, clusters, workspaces, Edge hosts, etc. | + +## Create Role Bindings in Namespaces in All Clusters + +You can create role bindings in the namespaces that are included in your workspace across all the clusters in your +namespace or use Regular Expressions (regex) to create role bindings in all namespaces that match the regex. + +### Prerequisites + +- An existing workspace. Refer to [Create a Workspace](../adding-a-new-workspace.md) to learn how to create a workspace. + +- You are logged in as a Palette user that has the permission to modify workspaces. For more information, refer to + [Permissions](../../user-management/palette-rbac/permissions.md). + +### Procedure + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. In the **Drop-Down Menu** at the top of the page, choose the project that has your workspace. + +3. On the left **Main Menu**, click **Workspaces**. + +4. Click on the workspace you want to update. + +5. In the upper-right corner, click **Settings**. Then click **Namespaces**. + +6. If the namespace where you want to include are already in the workspace, skip this step. + + At the top of the page, enter the namespace you want to create the role bindings in. Note that doing so will include + the namespace in the workspace and Palette users who have access to this workspace will be able to see its workloads + and resource consumption. + + Alternatively, enter a regex that match the namespaces where you want to create the role binding. Using regex will + not include all the namespaces that match the regex in the namespace. It will still allow you to create the role + bindings, but the workloads in those namespaces will not be visible. + +7. Click **Add New Binding**. + +8. In the **Namespace** field, select a namespace or the regex. Then enter the **Role type** and **Role name**. As is in + Kubernetes, you can use either a role or a cluster role to create a role binding. If you use a cluster role, the + privilege of the cluster role will still be limited to the namespace where the role binding exists only. + + :::info + + This action only creates the role bindings, but does not create the role or the subject referenced in the role + binding. Kubernetes allows you to create role bindings without creating the role or the subject, but the role binding + will have no effect until it can match with a role and a subject. You must make sure to create the role and the + subject in the namespaces or clusters yourself. + + ::: + +9. Then in the **Subject** fields, choose the type of the subject and enter the subject name. You can enter as many + subjects as you need. + +10: Click **Confirm**. + +### Validate + +1. Log in to [Palette](https://console.spectrocloud.com). + +2. In the **Drop-Down Menu** at the top of the page, choose the project that has your workspace. + +3. On the left **Main Menu**, click **Workspaces**. Select your workspace. + +4. Switch to the **Role Bindings** or **Cluster Role Bindings** tab. + +5. Search for an entry that starts with **spectro-on-demand-**. diff --git a/docs/docs-content/workspace/workspace-mgmt/delete-workspace.md b/docs/docs-content/workspace/workspace-mgmt/delete-workspace.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/docs-content/workspace/workspace-mgmt/resource-mgmt.md b/docs/docs-content/workspace/workspace-mgmt/resource-mgmt.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/docs-content/workspace/workspace-mgmt/restrict-images.md b/docs/docs-content/workspace/workspace-mgmt/restrict-images.md new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/docs-content/workspace/workspace.md b/docs/docs-content/workspace/workspace.md index 5a980cc4c8..0ac0a591b5 100644 --- a/docs/docs-content/workspace/workspace.md +++ b/docs/docs-content/workspace/workspace.md @@ -17,49 +17,35 @@ distributed environment. The following sections describe various aspects of multi-cluster management via workspaces. -## Namespace Management +## Namespace and Resource Management -Workspaces automate the creation and deletion of namespaces common to all clusters within the workspace. A workspace can -hold a set of namespaces. Spectro Cloud Palette will periodically reconcile the workspace definition and add/remove -namespaces if required from all clusters part of the workspace. +Workspaces in Spectro Cloud Palette automate the creation and management of namespaces across all clusters in the +workspace. This includes: -## Quota Control +- **Namespace Creation**: Creating namespaces across all clusters in your workspace if a cluster does not have a + specified namespace. +- **Resource Quotas**: Defining and enforcing CPU and memory usage limits within namespaces, applied uniformly across + all clusters in the workspace. -Usage quota in terms of CPU and memory usage limits is specified within the namespaces. Spectro Cloud Palette sets the -specified limits across all the clusters in the namespaces. +## Centralized Access Control -## Role Based Access Control(RBAC) +Workspaces simplify Role-Based Access Control (RBAC) by centralizing management of role bindings and cluster role +bindings. You can specifying role bindings and cluster role bindings within the workspace to automatically apply them to +all clusters, ensuring consistent and secure access policies across all clusters in a workspace. -Role bindings and cluster role bindings are specified within workspaces. Furthermore, these role bindings and cluster -role bindings are created in every cluster within the workspaces, thus enabling centralized RBAC. +## Visibility and Insights -## Utilization +Workspaces enhance operational visibility and provide actionable insights through: -Spectro Cloud Palette reports detailed resource utilization of workloads deployed in all the namespaces in the workspace -across clusters. In addition, the CPU and memory usage trends within the workspace provide valuable insights into the -consumption patterns of an application distributed across clusters. +- **Workload Visibility**: A centralized workload browser aggregates and displays workloads (pods, deployments, jobs, + stateful sets, etc.) across all namespaces and clusters in the workspace. +- **Resource Utilization**: Detailed reporting on CPU and memory usage trends across clusters to understand consumption + patterns. +- **Cost Attribution**: Calculating costs for workloads based on resource utilization, enabling internal charge-back or + show-back for teams or applications. -## Cost Attribution +## Backup and Disaster Recovery -Spectro Cloud Palette computes utilization costs for workloads deployed in all the namespaces that are part of the -workspace across all the clusters based on the detailed resource utilization data. This can be used for internal -charge-back or show-back purposes to determine the cost incurred by an application or team. - -## Workload Visibility - -Workspaces provide a workload browser to view all the workloads such as pods, deployment, jobs, stateful sets, etc., -deployed in all the namespaces that are part of the workspace across all the clusters. The workload browser aggregates -resources across clusters from relevant namespaces and presents them with centralized visibility. - -## Backup and Restore - -A workspace-based backup is similar to a cluster backup, with the additional coverage of multiple clusters, should the -workspace include more than one. The prerequisites and detailed instructions to backup and restore clusters are -specified on the [Backup and Restore](../clusters/cluster-management/backup-restore/backup-restore.md) page. - -## Regex for Namespaces - -Palette leverages [Regex Pattern matching](workload-features.md#regex-for-namespaces) to select multiple namespaces to -apply Role binding concurrently. When we have many namespaces to be configured for role binding, the user can provide a -Regex pattern matching multiple namespaces instead of giving a single namespace. This will help select all the -namespaces matching the given Regex pattern to be selected together for role binding. > +**Workspace-Based Backup**: extends cluster-level backups to include namespaces in all clusters within a workspace. For +detailed prerequisites and instructions, refer to the +[Backup and Restore](../clusters/cluster-management/backup-restore/backup-restore.md) page.