Merge pull request #281 from stakater/fix-console-docs

fix console docs

content/about/key-features.md

@@ -40,7 +40,7 @@ More details on [Quota](../crds-api-reference/quota.md)
 The showback functionality in Multi Tenant Operator (MTO) Console is a significant feature designed to enhance the management of resources and costs in multi-tenant Kubernetes environments. This feature focuses on accurately tracking the usage of resources by each tenant, and/or namespace, enabling organizations to monitor and optimize their expenditures.
 Furthermore, this functionality supports financial planning and budgeting by offering a clear view of operational costs associated with each tenant. This can be particularly beneficial for organizations that chargeback internal departments or external clients based on resource usage, ensuring that billing is fair and reflective of actual consumption.
 
-More details on [Showback](../explanation/console.md#showback)
+More details on [Showback](../console/showback.md)
 
 ### Hibernation
 
@@ -78,7 +78,7 @@ More details on [Mattermost](../how-to-guides/mattermost.md)
 
 Multi Tenant Operator Console is a comprehensive user interface designed for both administrators and tenant users to manage multi-tenant environments. The MTO Console simplifies the complexity involved in handling various aspects of tenants and their related resources. It serves as a centralized monitoring hub, offering insights into the current state of tenants, namespaces, templates and quotas. It is designed to provide a quick summary/snapshot of MTO's status and facilitates easier interaction with various resources such as tenants, namespaces, templates, and quotas.
 
-More details on [Console](../explanation/console.md)
+More details on [Console](../console/overview.md)
 
 ### Remote Development Namespaces
 

content/architecture/architecture.md

@@ -22,6 +22,6 @@ MTO consists of multiple controllers and components that work together to provid
 | Opencost-Gateway | Deployment | Opencost is an open-source cost management solution that provides cost tracking and reporting for the resources deployed on the cluster. It is also provisioned via Pilot Controller and is managed internally. |
 | Prometheus-Server | Deployment | Prometheus is an open-source monitoring and alerting solution that provides metrics and monitoring for the resources deployed on the cluster. It is also provisioned via Pilot Controller and is managed internally. |
 | Kube-State-Metrics | Deployment | Kube-State-Metrics is a service that listens to the Kubernetes API server and generates metrics about the state of the objects in the cluster. It is also provisioned via Pilot Controller and is managed internally. |
-| Showback | Cron-job | The Showback Cron-job is responsible for generating showback reports based on the resources present on the cluster by querying the Opencost-Gateway and storing the reports in the PostgreSQL database that can be viewed in the MTO Console on the [Showback page](../explanation/console.md#showback). |
+| Showback | Cron-job | The Showback Cron-job is responsible for generating showback reports based on the resources present on the cluster by querying the Opencost-Gateway and storing the reports in the PostgreSQL database that can be viewed in the MTO Console on the [Showback page](../console/showback.md). |
 | MTO-Gateway | Deployment | The MTO-Gateway is the backend service that provides the REST API for the MTO-Console. |
-| MTO-Console | Deployment | The MTO-Console is the user interface for the MTO system that provides a web-based interface for managing tenants, namespaces, sleep, and more. Details about the MTO-Console can be found [here](../explanation/console.md). |
+| MTO-Console | Deployment | The MTO-Console is the user interface for the MTO system that provides a web-based interface for managing tenants, namespaces, sleep, and more. Details about the MTO-Console can be found [here](../console/overview.md). |

content/changelog.md

@@ -59,8 +59,8 @@ Before upgrading to v1.1.0, perform the following steps:
 
 #### Features
 
-- Added [capacity planning](./explanation/console.md#capacity-planning) feature on MTO Console to view resource usage of tenants based in their request and limits
-- Added [hibernation](./explanation/console.md#hibernation) feature on MTO Console to view and manage hibernated namespaces and hibernate/unhibernate namespaces
+- Added [capacity planning](./console/capacity-planning.md) feature on MTO Console to view resource usage of tenants based in their request and limits
+- Added [hibernation](./console/hibernation.md) feature on MTO Console to view and manage hibernated namespaces and hibernate/unhibernate namespaces
 
 #### Enhancements
 

content/console/capacity-planning.md

@@ -0,0 +1,35 @@
+# Capacity Planning
+
+The Capacity Planning feature in the app provides insights into resource usage and allocation across the cluster to help manage computing resources efficiently. It consists of three main sections:
+
+## 1. Graphical Representation
+
+### a. Tenant Requests vs. Cluster Capacity
+
+This section displays bar charts that compare the current resource requests from tenants (like CPU and memory) with the total available cluster capacity. The charts visually represent how much of the cluster’s resources are currently being utilized versus what is available, helping identify over-utilization or under-utilization scenarios.
+
+### b. Quota Requests vs. Cluster Capacity
+
+Similar to the tenant requests, this section compares the quota requests against the total cluster capacity. It allows administrators to see if the quota assigned is in line with the cluster's actual capacity.
+
+![capacity-planning](../images/capacity_planning.png)
+
+## 2. Worker-pool Details
+
+A detailed table lists the worker nodes in the cluster, displaying each node’s CPU and memory capacity along with various labels that indicate the node’s configuration and role (e.g., worker, infra). This information helps in identifying resource distribution across nodes and managing workloads accordingly.
+
+![worker-pool](../images/worker_pool.png)
+
+The worker-pool labels dropdown is used to filter the table data and graph based on the selected labels. If the selected label is common amongst the worker nodes, the filtered result is a list of all the worker nodes that contain the selected labels and update graph for filtered worker nodes.
+
+If the label is specific for any worker node, selecting the label will filter the specific worker nodes containing the label and update the graph based on the filtered results.
+
+To clear the filter you can remove applied labels and choose **Apply Filter** action. If no label is selected, it will ask you to **PROCEED** or **CANCEL**. If you choose to proceed the filters will be cleared returning the table and graph to default view.
+
+![worker-pool-filtered](../images/worker_pool_filtered.png)
+
+## 3. Request Details
+
+This table provides a breakdown of the resource requests from different tenants, displaying both the requested resources (CPU and memory) and the allocated quotas. It helps to monitor if tenant requests align with the quotas set for each tenant, ensuring optimal resource management.
+
+![request-details](../images/request_details.png)

content/console/configuration.md

@@ -0,0 +1,135 @@
+# Configuration
+
+## User Roles and Permissions
+
+### Administrators
+
+Administrators have overarching access to the console, including the ability to view all namespaces and tenants. They have exclusive access to the IntegrationConfig, allowing them to view all the settings and integrations.
+
+![integration Config](../images/integrationConfig.png)
+
+### Tenant Users
+
+Regular tenant users can monitor and manage their allocated resources. However, they do not have access to the IntegrationConfig and cannot view resources across different tenants, ensuring data privacy and operational integrity.
+
+## Caching and Database
+
+MTO integrates a dedicated database to streamline resource management. Now, all resources managed by MTO are efficiently stored in a Postgres database, enhancing the MTO Console's ability to efficiently retrieve all the resources for optimal presentation.
+
+The implementation of this feature is facilitated by the Bootstrap controller, streamlining the deployment process. This controller creates the PostgreSQL Database, establishes a service for inter-pod communication, and generates a secret to ensure secure connectivity to the database.
+
+Furthermore, the introduction of a dedicated cache layer ensures that there is no added burden on the Kube API server when responding to MTO Console requests. This enhancement not only improves response times but also contributes to a more efficient and responsive resource management system.
+
+## Authentication and Authorization
+
+### Keycloak for Authentication
+
+MTO Console incorporates Keycloak, a leading authentication module, to manage user access securely and efficiently. Keycloak is provisioned automatically by our controllers, setting up a new realm, client, and a default user named `mto`.
+
+#### Benefits
+
+- Industry Standard: Offers robust, reliable authentication in line with industry standards.
+- Integration with Existing Systems: Enables easy linkage with existing Active Directories or SSO systems, avoiding the need for redundant user management.
+- Administrative Control: Grants administrators full authority over user access to the console, enhancing security and operational integrity.
+
+### PostgreSQL as Persistent Storage for Keycloak
+
+MTO Console leverages PostgreSQL as the persistent storage solution for Keycloak, enhancing the reliability and flexibility of the authentication system.
+
+It offers benefits such as enhanced data reliability, easy data export and import.
+
+#### Benefits
+
+- Persistent Data Storage: By using PostgreSQL, Keycloak's data, including realms, clients, and user information, is preserved even in the event of a pod restart. This ensures continuous availability and stability of the authentication system.
+- Data Exportability: Customers can easily export Keycloak configurations and data from the PostgreSQL database.
+- Transferability Across Environments: The exported data can be conveniently imported into another cluster or Keycloak instance, facilitating smooth transitions and backups.
+- No Data Loss: Ensures that critical authentication data is not lost during system updates or maintenance.
+- Operational Flexibility: Provides customers with greater control over their authentication data, enabling them to manage and migrate their configurations as needed.
+
+### Built-in module for Authorization
+
+The MTO Console is equipped with an authorization module, designed to manage access rights intelligently and securely.
+
+#### Benefits
+
+- User and Tenant Based: Authorization decisions are made based on the user's membership in specific tenants, ensuring appropriate access control.
+- Role-Specific Access: The module considers the roles assigned to users, granting permissions accordingly to maintain operational integrity.
+- Elevated Privileges for Admins: Users identified as administrators or members of the clusterAdminGroups are granted comprehensive permissions across the console.
+- Database Caching: Authorization decisions are cached in the database, reducing reliance on the Kubernetes API server.
+- Faster, Reliable Access: This caching mechanism ensures quicker and more reliable access for users, enhancing the overall responsiveness of the MTO Console.
+
+## Setting Up User Access in Keycloak for MTO Console
+
+This guide walks you through the process of adding new users in Keycloak and granting them access to Multi Tenant Operator (MTO) Console.
+
+### Accessing Keycloak Console
+
+- Log in to the OpenShift Console.
+- Go to the 'Routes' section within the 'multi-tenant-operator' namespace.
+
+![routes](../images/routes.png)
+
+- Click on the Keycloak console link provided in the Routes.
+- Login using the admin credentials (default: admin/admin).
+
+### Adding new Users in Keycloak
+
+- In the Keycloak console, switch to the `mto` realm.
+
+![realm](../images/realm.png)
+
+- Go to the `Users` section in the `mto` realm.
+- Follow the prompts to add a new user.
+
+![keycloak-new-user](../images/keycloak-new-user.png)
+
+- Once you add a new user, here is how the Users section would look like
+
+![keycloak-users](../images/keycloak-users.png)
+
+### Accessing MTO Console
+
+- Go back to the OpenShift Console, navigate to the Routes section, and get the URL for the MTO Console.
+- Open the MTO Console URL and log in with the newly added user credentials.
+
+Now, at this point, a user will be authenticated to the MTO Console. But in order to get access to view any Tenant resources, the user will need to be part of a Tenant.
+
+### Granting Access to Tenant Resources
+
+- Open Tenant CR: In the OpenShift cluster, locate and open the Tenant Custom Resource (CR) that you wish to give access to. You will see a YAML file similar to the following example:
+
+```yaml
+apiVersion: tenantoperator.stakater.com/v1beta3
+kind: Tenant
+metadata:
+  name: arsenal
+spec:
+  quota: small
+  accessControl:
+    owners:
+      users:
+        - [email protected]
+      groups:
+        - arsenal
+    editors:
+      users:
+        - [email protected]
+    viewers:
+      users:
+        - [email protected]
+```
+
+- Edit Tenant CR: Add the newly created user's email to the appropriate section (owners, editors, viewers) in the Tenant CR. For example, if you have created a user `[email protected]` and wish to add them as an editor, the edited section would look like this:
+
+```yaml
+editors:
+  users:
+    - [email protected]
+    - [email protected]
+```
+
+- Save Changes: Save and apply the changes to the Tenant CR.
+
+### Verifying Access
+
+Once the above steps are completed, you should be able to access the MTO Console now and see alpha Tenant's details along with all the other resources such as namespaces and templates that John has access to.

content/console/dashboard.md

@@ -0,0 +1,35 @@
+# Dashboard
+
+The dashboard serves as a centralized monitoring hub, offering insights into the current state of tenants, namespaces, and quotas. It is designed to provide a quick summary/snapshot of MTO resources' status. Additionally, it includes a Showback graph that presents a quick glance of the seven-day cost trends associated with the namespaces/tenants based on the logged-in user.
+
+By default, MTO Console will be disabled and has to be enabled by setting the below configuration in IntegrationConfig.
+
+```yaml
+components:
+    console: true
+    ingress:
+      ingressClassName: <ingress-class-name>
+      console:
+        host: tenant-operator-console.<hostname>
+        tlsSecretName: <tls-secret-name>
+      gateway:
+        host: tenant-operator-gateway.<hostname>
+        tlsSecretName: <tls-secret-name>
+      keycloak:
+        host: tenant-operator-keycloak.<hostname>
+        tlsSecretName: <tls-secret-name>
+    showback: true
+    trustedRootCert: <root-ca-secret-name>
+```  
+
+`<hostname>` : hostname of the cluster  
+`<ingress-class-name>` : name of the ingress class  
+`<tls-secret-name>` : name of the secret that contains the TLS certificate and key  
+`<root-ca-secret-name>` : name of the secret that contains the root CA certificate
+
+>Note: `trustedRootCert` and `tls-secret-name` are optional. If not provided, MTO will use the default root CA certificate and secrets respectively.
+
+Once the above configuration is set on the IntegrationConfig, MTO would start provisioning the required resources for MTO Console to be ready. In a few moments, you should be able to see the Console Ingress in the `multi-tenant-operator` namespace which gives you access to the Console.
+
+For more details on the configuration, please visit [here](../crds-api-reference/integration-config.md).
+![dashboard](../images/dashboard.png)

content/how-to-guides/hibernation-workflow.md → content/console/hibernation.md

@@ -1,7 +1,24 @@
-# Hibernation Workflow
+# Hibernation
 
 The main purpose of the Hibernation workflow is, controlling resource consumption dynamically while enabling efficient management of namespaces based on their usage patterns and requirements.
 
+## Namespace List
+
+Displays a list of namespaces associated with a selected tenant. The tenant filter allows users to view namespaces relevant to a specific tenant.
+
+### Status Columns
+
+- Sleeping: Indicates whether a namespace is currently in a "sleep" state, with a checkmark appearing for namespaces that are set to sleep.
+- Hibernated: Shows whether a namespace is in a "hibernated" state, marked similarly to the sleeping state.
+- Hibernation Interval: Provides details about the schedule for sleep and wake intervals for specific namespaces. The schedule is represented in a format like "Sleep Schedule: At 11 minutes past the hour, Wake Schedule: At 15 minutes past the hour."
+
+### Actions and Filters
+
+- APPLY SLEEP / HIBERNATE: A button to initiate the sleep or hibernation action based on the selected namespaces and applied filters.
+- Schedule Filters: Allows filtering namespaces by their hibernation schedule.
+
+![hibernation-table](../images/hibernation_table.png)
+
 ## Sleep Tab
 
 The "SLEEP" tab is active, indicating that namespaces can be put into sleep mode based on certain criteria.

content/console/namespaces.md

@@ -0,0 +1,5 @@
+# Namespaces
+
+Users can view all the namespaces that belong to their tenant, offering a comprehensive perspective of the accessible namespaces for tenant members. This section also provides options for detailed exploration.
+
+![namespaces](../images/namespaces.png)

content/console/overview.md

@@ -0,0 +1,13 @@
+# Overview
+
+This documentation is divided into the following sections to guide you through MTO’s Console capabilities:
+
+- [Dashboard](./overview.md) – Overview of the UI and how to navigate.
+- [Tenants](./tenants.md) – Managing and configuring tenants.
+- [Namespaces](./namespaces.md) – Creating and organizing namespaces.
+- [Hibernation](./hibernation.md) – Pausing workloads to optimize costs.
+- [Cost Analysis](./showback.md) – Monitoring usage and cost breakdowns.
+- [Quotas](./quotas.md) – Enforcing resource allocation policies.
+- [Templates](./templates.md) – Using templates to streamline namespace creation.
+- [Capacity Planning](./capacity-planning.md) – Strategies for managing cluster capacity efficiently.
+- [Configuration](./configuration.md) – Configuration of the console.