Merge pull request #271 from aali309/GITOPS-10081

Comprehensive docs for gitops-console-plugin

Signed-off-by: Atif Ali <atali@redhat.com>

Author: keithchong

README.md

@@ -1,6 +1,9 @@
 # OpenShift Console GitOps Plugin
 Based on [Openshift Console dynamic plugin](https://github.com/openshift/console/tree/master/frontend/packages/console-dynamic-plugin-sdk), this plugin implement the console elements for GitOps.
 
+## Documentation
+
+[docs/](docs/) provide description of what the UI does. Preview with `pnpm serve-docs` (http://localhost:3000).
 
 ## Building
 ### Option 1: Without running Console locally

docs/README.md

@@ -0,0 +1,63 @@
+# Working with the GitOps Console plugin
+
+The GitOps Console plugin extends the OpenShift Container Platform web console by adding GitOps resources. The plugin is available as part of the Red Hat OpenShift GitOps Operator and provides a console UI for managing Argo CD and Argo Rollouts custom resources.
+
+After you install the Red Hat OpenShift GitOps Operator, the OpenShift web console displays a **GitOps** navigation tab in the **Administrator** or **Core platform** perspective. The plugin is enabled by default. The GitOps navigation tab replaces the previous **Environments** tab and related pages in the **Developer** perspective.
+
+The GitOps navigation tab provides access to the following Argo CD and Argo Rollouts resources:
+
+* Applications
+* ApplicationSets
+* AppProjects
+* ImageUpdaters
+* Rollouts
+
+## Prerequisites
+
+* You have access to OpenShift Container Platform 4.18 or later.
+* You have installed the Red Hat OpenShift GitOps Operator.
+
+## GitOps resources in the web console
+
+Each GitOps resource provides list and details pages that follow the standard OpenShift web console experience.
+
+You can use these pages to:
+
+* View GitOps resources in a selected namespace
+* Create resources by using YAML templates
+* Edit labels and annotations
+* Filter resources by status, where applicable
+* Paginate large filtered lists and details tables (10, 20, 50, or 100 items per page; default 50)
+* Access related resources and events
+
+The GitOps Console plugin integrates with the console navigation, allowing you to navigate between related resources and access contextual actions for each resource type.
+
+### Search and YAML templates
+
+The GitOps Console plugin provides search and template capabilities:
+
+* **Search integration**: Search pages are enabled for Applications and ApplicationSets, allowing you to find instances from global search like other first-class resources.
+* **YAML templates**: Pre-configured YAML templates are registered for Applications, ApplicationSets, AppProjects, ImageUpdaters, and Rollouts. These templates provide starter configurations with placeholders to speed up resource creation from the console.
+
+## Additional resources
+
+* [Enable the GitOps Console plugin](admin-enable-plugin.md)
+* [Applications in the GitOps Console](applications.md)
+* [ApplicationSets in the GitOps Console](applicationsets.md)
+* [AppProjects in the GitOps Console](appprojects-rbac.md)
+* [ImageUpdaters in the GitOps Console](image-updaters.md)
+* [Rollouts in the GitOps Console](rollouts.md)
+* [Filter, search, and paginate resources](filter-resources.md)
+* [Graphs and topology views](topology.md)
+* [Getting started](getting-started.md)
+* [Troubleshooting](troubleshooting.md)
+
+## Preview this manual
+
+From the `gitops-console-plugin` repository root:
+
+```bash
+pnpm serve-docs
+```
+
+Open [http://localhost:3000](http://localhost:3000).

docs/_sidebar.md

@@ -0,0 +1,11 @@
+- [Working with the GitOps Console plugin](/)
+- [Getting started](getting-started.md)
+- [Enable the GitOps Console plugin](admin-enable-plugin.md)
+- [Applications in the GitOps Console](applications.md)
+- [ApplicationSets in the GitOps Console](applicationsets.md)
+- [AppProjects in the GitOps Console](appprojects-rbac.md)
+- [ImageUpdaters in the GitOps Console](image-updaters.md)
+- [Rollouts in the GitOps Console](rollouts.md)
+- [Graphs and topology views](topology.md)
+- [Filter, search, and paginate resources](filter-resources.md)
+- [Troubleshooting](troubleshooting.md)

docs/admin-enable-plugin.md

@@ -0,0 +1,99 @@
+# Enable the GitOps Console plugin
+
+The GitOps Console plugin is enabled by default after you install the Red Hat OpenShift GitOps Operator. If you disable the plugin, you can enable it manually.
+
+## Prerequisites
+
+* You have installed the Red Hat OpenShift GitOps Operator.
+* You have access to the OpenShift web console with cluster administrator permissions.
+
+## Procedure
+
+1. In the OpenShift web console, navigate to **Home** → **Overview**.
+
+   ![Home Overview in the OpenShift web console](assets/pics/enable-console-plugin-home-overview.png)
+
+2. In the **Status** panel, click **Dynamic Plugins**.
+
+   ![Status panel with Dynamic Plugins](assets/pics/enable-console-plugin-status-dynamic-plugins.png)
+
+   A popup appears with a link to view all dynamic plugins.
+
+3. Click **View all**.
+
+4. Under the **Console plugins** tab, find **gitops-plugin**.
+
+5. If the plugin is disabled, click **Enable**.
+
+   ![Console plugin enablement dialog for gitops-plugin](assets/pics/enable-console-plugin-enablement.png)
+
+   The browser might require a refresh. After refreshing, the page indicates that the plugin is **Enabled**.
+
+## Verification
+
+* Navigate to **GitOps** in the navigation menu and verify that you can access **Applications**, **ApplicationSets**, and **AppProjects**.
+* If the ImageUpdater and Rollout CRDs are installed on the cluster, also verify that you can access **ImageUpdaters** and **Rollouts**.
+
+  ![GitOps navigation with Applications, ApplicationSets, AppProjects, ImageUpdaters, and Rollouts](assets/pics/enable-console-plugin-verification-gitops-nav.png)
+
+## Disable the plugin
+
+Use the same **Console plugins** list and disable **gitops-plugin**.
+
+### Disable or enable with the CLI
+
+The console loads plugins listed in `spec.plugins` on `console.operator.openshift.io/cluster`.
+
+1. Check which plugins are enabled:
+
+   ```bash
+   oc get console.operator.openshift.io cluster -o jsonpath='{.spec.plugins}{"\n"}'
+   ```
+
+2. To enable **gitops-plugin**:
+
+   * If step 1 printed a JSON array (for example `["monitoring-plugin"]`), append **gitops-plugin**:
+
+     ```bash
+     PLUGIN_PATCH='[{"op":"add","path":"/spec/plugins/-","value":"gitops-plugin"}]'
+     oc patch console.operator.openshift.io cluster --type=json -p "${PLUGIN_PATCH}"
+     ```
+
+   * If step 1 printed nothing (or only `null`), `spec.plugins` is missing. Create the list:
+
+     ```bash
+     PLUGIN_PATCH='[{"op":"add","path":"/spec/plugins","value":["gitops-plugin"]}]'
+     oc patch console.operator.openshift.io cluster --type=json -p "${PLUGIN_PATCH}"
+     ```
+
+   Skip this step if `gitops-plugin` is already in the list from the previous command.
+
+3. To disable **gitops-plugin**, edit the Console operator and remove `gitops-plugin` from `spec.plugins`:
+
+   ```bash
+   oc edit console.operator.openshift.io cluster
+   ```
+
+   Example:
+
+   ```yaml
+   spec:
+     plugins:
+       - monitoring-plugin
+       # remove: - gitops-plugin
+   ```
+
+4. Refresh the browser after the change. The **GitOps** entry disappears from the navigation when the plugin is disabled.
+
+## Multi-instance configuration
+
+The GitOps Console plugin is cluster-scoped. A single plugin deployment serves all Argo CD instances on the cluster; you do not install a separate plugin for each instance.
+
+When multiple Argo CD instances exist in different namespaces, their resources appear together in the GitOps pages. Use the namespace selector to limit the view to one namespace or to browse across namespaces.
+
+The **View in Argo CD** action opens the selected application in the Argo CD user interface. This action requires a Route to the Argo CD server.
+
+## Related information
+
+* [Getting started](getting-started.md)
+* [Troubleshooting](troubleshooting.md)