Wge 2693 - explorer documentation (#3610)

* basic scaffolding for explorer

* adding querying

* added getting started

* added getting started

* querying doc

* added queries faq

* removed unsused

* added initial configuration

* adding operations

* added configuration

* review before draft pr

* removed comment before merging

* removed comment related to users in collecting

website/docs/explorer/configuration.mdx

@@ -0,0 +1,81 @@
+---
+title: Configuration
+hide_title: true
+---
+
+import TierLabel from "./../_components/TierLabel";
+import AlphaWarning from "../_components/_alpha_warning.mdx";
+
+# Configuration <TierLabel tiers="Enterprise" />
+
+<AlphaWarning/>
+
+This page helps you to understand the options available to configure Explorer
+
+## Prerequisites
+Before using Explorer, please ensure that:
+- You have Weave Gitops Enterprise [v0.21.2](../../releases)
+
+## Setup
+
+Explorer is enabled via configuration through the feature flag  `enableExplorer` that you could
+configure in your Weave Gitops Enterprise helm release values file
+
+```yaml
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: weave-gitops-enterprise
+  namespace: flux-system
+spec:
+  # ... other spec components
+  values:
+    enableExplorer: true
+```
+
+## Configuration
+
+### Clusters
+
+Explorer watches the [GitopsClusters](https://docs.gitops.weave.works/docs/next/cluster-management/managing-existing-clusters/#connect-a-cluster)
+that you have connected to Weave Gitops Enterprise.
+
+### Kinds
+
+Explorer watches for the following kind resources out of the box:
+
+- RBAC: ClusterRole, Role, ClusterRoleBinding and RoleBinding
+- Flux Applications: Kustomizations, HelmRelease
+
+## Data Layer
+
+Explorer take a simple approach to manage resource views. It leverages a Data Store for caching the views and query them.
+The storage lifecycle is bounded to Weave Gitops Enterprise app and does not provide persistence guarantees.
+Instead, it requests data as required to the leaf clusters. In its simplest form, the data store used is [SQLite](https://sqlite.org/index.html).
+
+## Authentication and Authorization
+
+There are two main paths to consider within Explorer in the context of authentication and authorization (authN/authZ):
+
+1. The read or querying path is exercised when a weave gitops user queries the data.
+2. The write or collecting path is exercised to gather the resources from the leaf clusters.
+
+We look into them separately.
+
+## Authentication and Authorization for querying
+
+Explorer leverages existing authentication and authorization built-in the [application](https://docs.gitops.weave.works/docs/configuration/securing-access-to-the-dashboard/).
+It identifies for a user logged in the application: its identity and the access permissions via Kuberentes RBAC.
+Query results are filtered honouring the access determined via RBAC.
+
+## Authentication and Authorization for collecting
+
+As mentioned earlier, [GitopsClusters](https://docs.gitops.weave.works/docs/next/cluster-management/managing-existing-clusters/#connect-a-cluster)
+defines the connection and security context that Explorer leverages to collect data from leaf clusters.
+
+## Next Steps
+- See [querying](./querying.mdx) to deep dive in how to query.
+- See [operations](./operations.mdx) for day troubleshooting and operations.
+
+

website/docs/explorer/getting-started.mdx

@@ -0,0 +1,86 @@
+---
+title: Getting started
+hide_title: true
+---
+
+import TierLabel from "./../_components/TierLabel";
+import AlphaWarning from "../_components/_alpha_warning.mdx";
+
+# Getting started  <TierLabel tiers="Enterprise" />
+<AlphaWarning/>
+
+
+This guide shows you the basics steps to start using Explorer.
+
+## Pre-requisites
+
+Before using Explorer, please ensure that:
+
+- You have Weave Gitops Enterprise [v0.21.2](../../releases)
+- You have deployed an application.
+
+## Setup
+
+Explorer is enabled via configuration through the feature flag  `enableExplorer` that you could
+configure in your Weave Gitops Enterprise HelmRelease values:
+
+
+```yaml
+---
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: weave-gitops-enterprise
+  namespace: flux-system
+spec:
+  # ... other spec components
+  values:
+    enableExplorer: true
+```
+
+For a complete overview on the configuration you could see [configuration](./configuration.mdx).
+
+## Explorer UI
+
+Login to Weave Gitops and Explorer will be shown in the navigation menu `Explorer`.
+
+Explorer UI looks as follows:
+
+![explorer](imgs/explorer-ui.png)
+
+It has two main components:
+
+- A search dialog with filter to querying the platform resources
+- A table with the filtered resources.
+
+For a more detailed view on the UI you could see [querying](./querying.mdx).
+
+## Discovering Applications
+
+For this example we are using the application `podinfo` but you could use any other app that suits your scenario.
+
+There are two main ways to discover data:
+
+- Querying via the search dialog.
+- Filtering via the pre-built filter list.
+
+### Querying
+
+Just typing `podinfo` in the search dialog returns the applications that matches the term
+
+![podinfo app found](imgs/getting-started-querying-app.png)
+
+For more info on how querying works to query and advanced queries see [querying](./querying.mdx).
+
+### Filtering
+
+A set of queries are set as filters. For example, just select the filter `Failed` to get all the apps that are failing in
+a moment in time.
+
+![failed apps](imgs/getting-started-failed.png)
+
+## Next Steps
+Once you have an initial experience using explorer, you could
+
+- Deep dive in [querying](./querying.mdx) to see how it works and advanced queries.
+- See [configuration](./configuration.mdx) for the options that you could configure in explorer.

website/docs/explorer/intro.mdx

@@ -0,0 +1,43 @@
+---
+title: Introduction
+hide_title: true
+---
+
+import TierLabel from "./../_components/TierLabel";
+import AlphaWarning from "../_components/_alpha_warning.mdx";
+
+# Explorer <TierLabel tiers="Enterprise" />
+
+<AlphaWarning/>
+
+As platform engineer or as developer, your applications and platform services will likely span multiple kubernetes clusters
+or infrastructure components.  In order to manage and operate them you require a platform capability that
+allows you to discover the resources from a single place.
+
+Explorer is that capability that allows any platform user to discover platform resources from a single place
+across all your kubernetes clusters.
+
+![explorer](imgs/explorer-ui.png)
+
+## FAQ
+
+### Which journeys would be able to use explorer for?
+
+Explorer is better suited for journeys matching the discovery of resources across the platform resources inventory.
+
+### Which journeys would be better using other weave gitops capabilities for?
+
+If you have a particular resources you want to manage, weave gitops offers single resource experience
+for almost every resource.
+
+### Which Kinds does explorer support?
+
+The following resources are currently supported:
+
+- [HelmRelease](https://fluxcd.io/flux/components/helm/helmreleases/)
+- [Kustomizations](https://fluxcd.io/flux/components/kustomize/kustomization/)
+
+## Next Steps
+
+Now that you know what Explorer is, follow [getting started](../getting-started) to quickly have a feeling
+of what Explorer can do for you.

website/docs/explorer/operations.mdx

@@ -0,0 +1,25 @@
+---
+title: Operations
+hide_title: true
+---
+
+import TierLabel from "./../_components/TierLabel";
+import AlphaWarning from "../_components/_alpha_warning.mdx";
+
+# Operations <TierLabel tiers="Enterprise" />
+
+<AlphaWarning/>
+
+As platform engineer you could need to have a finer understanding on the underlying logic for Explorer. The following
+options are available to you to operate and troubleshoot it.
+
+## Debug Access Rules
+
+It is a debugging tool to make visible explorer authorization logic. You could find it as tab `Access Rules`  alongside
+the `Query` tab.
+
+![access rules](imgs/debug-access-rules.png)
+
+You could discover by `Cluster` and `Subject` the `Kinds` it is allowed to read. These are the rules that
+will be the source of truth doing authorization when a user does a query.
+

website/docs/explorer/querying.mdx

@@ -0,0 +1,142 @@
+---
+title: Querying
+hide_title: true
+---
+
+import TierLabel from "./../_components/TierLabel";
+import AlphaWarning from "../_components/_alpha_warning.mdx";
+
+# Querying <TierLabel tiers="Enterprise" />
+
+<AlphaWarning/>
+
+Explorer recommended way to discover resources is via its search dialog. This guide provides the background to understand
+it and set how to use it.
+
+## Schema
+
+Every resource is normalised to the following common schema:
+
+| __Key__                  | __Description__                                                     |
+| -----------------          | --------------                                                  |
+| Cluster                    | Name of cluster where the resource exists. As gitops cluster `<GitopsClusterNamespace,GitopsClusterName>`|
+| Namespace                  | Namespace name where the resource exists.|
+| Kind                  | Resource kubernetes type or [kind](https://kubernetes.io/docs/reference/using-api/api-concepts/#standard-api-terminology)|
+| Name                  | Resource name as specified in its manifest.|
+| Status                  | Resource health status. Indicates the status of its reconciliation.|
+| Message                  | Resource health status message. It extends status field with information about the status.|
+
+For a `podinfo` helm release from a cluster `default/progress-delivery-demo2-32` like this:
+
+```yaml
+apiVersion: helm.toolkit.fluxcd.io/v2beta1
+kind: HelmRelease
+metadata:
+  name: podinfo
+  namespace: flux-system
+spec:
+  chart:
+    spec:
+      chart: podinfo
+      interval: 1m
+      reconcileStrategy: ChartVersion
+      sourceRef:
+        kind: HelmRepository
+        name: podinfo
+      version: 6.0.0
+  interval: 1m
+status:
+  conditions:
+  - message: Release reconciliation succeeded
+    reason: ReconciliationSucceeded
+    status: "True"
+    type: Ready
+```
+
+The schema looks like
+
+| Cluster    | Namespace | Kind          | Name    | Status    | Message                 |
+|------------| ---------| ----------------|---------|----------|------------------------|
+|`default/progress-delivery-demo2-32` | `flux-system`   | `HelmRelease` | `podinfo` | `Success` | `Release reconciliation succeeded`  |
+
+And represented in the UI like
+
+![explorer](imgs/explorer-query-overview.png)
+
+## Querying
+
+Based on the previous schema you have two main modes to discover or filter the data
+
+1. Filter by key and value: when you know the pair <key,value> that you want to filter from.
+2. Filter by value: when you want to filter across keys or does not know the key
+
+:::info Matching
+
+For `key:value` filter the results would be those results where `key=value` exactly.
+:::
+
+
+### Filter by key and value
+
+You search with the format `key:value` indicating that you want to filter the resources matching the key and value.
+A couple of examples could be:
+
+- `kind:HelmRelease` to filter all helm releases.
+- `status:Failed` to find all failing resources.
+
+### Filter by value
+You search with a single term `value` indicating that you want to filter across the supported keys by values.
+The value would be search cross keys: `name`, `namespace` and `cluster` as synthatic sugar for `name:value` OR `namespace:value` OR `cluster:value`.
+
+An example cold be using `podinfo` that would translate into `name:podinfo` OR `namespace:podinfo` OR `cluster:podinfo`.
+
+### Operators
+
+#### AND
+
+You could refine filtered results by using AND semantics adding different filters.
+
+For example if you want to have all the resources within `flux-system` namespace from `management` cluster you could
+create a query like the following:
+
+![and query](imgs/explorer-query-and.png)
+
+with two sequential filters `namespace:flux-system` and `cluster:management` to achieve it.
+
+## FAQ
+
+Here a set of questions around querying to allow you get started by practice.
+
+### How can I discover resources from a cluster?
+
+You could use the single term with `clusterName` or `cluster:clusterName`
+
+For example for management cluster could be `management` or `cluster:management`
+
+![filter by cluster](imgs/explorer-query-filter-cluster.png)
+
+### How can I discover resources from a namespace?
+
+You could use the single term with `namespaceName` or `namespace:namespaceName`.
+
+### How can I discover applications?
+
+You should filter by kind where kind could be either HelmRelease or Kustomization like `kind:Kustomization` or `kind:HelmRelease`.
+You could also use the pre-built filters.
+
+![filter by kind](imgs/explorer-query-filter-kind.png)
+
+:::warning Exact Matching
+
+Remember that `key:value` is `key=value`
+- `kind:HelmRelease` returns all Helm Releases apps
+- `kind:helmrelease` wont return anything
+:::
+
+### How can I discover failed applications?
+
+You should filter by `status:Failed` to find the failing apps or use the pre-built filters.
+
+### How can I discover resources by name?
+
+You could use the single term with `resourceName` or `name:resourceName`.