diff --git a/README.md b/README.md index 06608ed7..51e4ee6a 100644 --- a/README.md +++ b/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 diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..a6aa4a5d --- /dev/null +++ b/docs/README.md @@ -0,0 +1,68 @@ +# 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** 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.19 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 and paginate resources](filter-resources.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). + +## Demo + + + +Add `docs/assets/getting-started-demo.mp4` after you record OperatorHub install, plugin enablement if needed, and **Administrator** → **GitOps**. diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 00000000..2759ba37 --- /dev/null +++ b/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) +- [Filter and paginate resources](filter-resources.md) +- [Troubleshooting](troubleshooting.md) +- [1.22 GA release notes](release-notes-ga.md) diff --git a/docs/admin-enable-plugin.md b/docs/admin-enable-plugin.md new file mode 100644 index 00000000..76767ed8 --- /dev/null +++ b/docs/admin-enable-plugin.md @@ -0,0 +1,38 @@ +# 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**. + +2. In the **Status** panel, click **Dynamic Plugins**. + + 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**. + + 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, AppProjects, ImageUpdaters, and Rollouts pages. + +## Disable the plugin + +Use the same **Console plugins** list and disable **gitops-plugin**. + +CLI: add or remove `gitops-plugin` in the `spec.plugins` list of `console.operator.openshift.io/cluster`. + +## Multi-instance configuration + +The plugin is cluster-wide. It is not one plugin per Argo CD instance. Resources from all instances appear by using the namespace selector. **View in Argo CD** opens the Argo CD UI for that application when a Route exists. diff --git a/docs/applications.md b/docs/applications.md new file mode 100644 index 00000000..4d512e5c --- /dev/null +++ b/docs/applications.md @@ -0,0 +1,47 @@ +# Applications in the GitOps Console + +The GitOps Console plugin shows key details of an Argo CD Application. You can view and create Applications directly from the OpenShift Container Platform web console. A **Graphical view** in the **Resources** tab of the Details page shows the application’s resources in a tree structure. + +> **IMPORTANT** +> +> The GitOps Console plugin displays the health status stored in the Application custom resource (CR). By default, this behavior depends on the configuration set by the Operator. If the Application CR does not contain the health status or the GitOps Console plugin does not display it correctly, set `controller.resource.health.persist: "true"` in the `argocd-cmd-params-cm` config map. + +## List page + +The Applications list page displays all Applications with the following features: + +* **Table columns**: name, namespace, sync status, health, revision, AppProject, and actions +* **Filtering**: Filter Applications by health status (Healthy, Progressing, Degraded, Missing) and sync status (Synced, OutOfSync, Unknown) +* **Sorting and search**: Sort columns and search by name +* **Pagination**: After filters and search, browse results in pages of 10, 20, 50, or 100 items (default 50). Page and page size are stored in the URL. See [Filter and paginate resources](filter-resources.md). +* **Create action**: Click **Create Application** to open the YAML editor with a starter template that includes repository URL, destination, and sync policy placeholders +* **Namespace view**: From the GitOps Operator namespace path, an optional control can list operands in all namespaces for operator-focused workflows + +## Details page + +The Application details page provides the following tabs: + +* **Details tab**: Displays summary information, health and sync indicators, revision links, destination and project information, conditions, toggles for automated sync, self-heal, and prune (when you have update permission), and detection of an Argo CD Route so you can open the Argo CD UI for the same application when routing is configured. +* **YAML tab**: Provides a live manifest editor for the Application resource. +* **Sources tab**: Displays repository sources with icons and metadata for Helm, Git, and OCI sources. The sources table supports pagination. +* **Resources tab**: Combines a resource table with an interactive topology graph: + * The graph shows immediate managed resources for the Application, not the full Argo CD resource tree. + * Use the Argo CD link on the tab to open the complete resource hierarchy in the Argo CD UI. + * Pan, zoom, and select resources in the graph; status filters apply to both table and graph. + * In list view, the resources table supports filtering, sorting, and pagination like other GitOps tables. See [Filter and paginate resources](filter-resources.md). + * Context-menu actions on graph nodes include viewing details, editing labels and annotations, deleting resources, and viewing resources in Argo CD. + * Related resources of the same kind can be grouped or ungrouped in the graph. +* **Sync Status tab**: Provides fine-grained sync and operation status information for the Application, including a paginated table of resources last synced. +* **History tab**: Displays the deployment and sync history for the Application in a paginated table (newest first by default; column sort keeps the selected direction). +* **Events tab**: Shows Kubernetes events for the Application object. + +## Additional features + +* **Favorites**: You can mark Applications as favorites based on console user settings. +* **Standard actions**: The page header provides access to standard actions such as editing labels, annotations, and deleting the Application. + +## View, sync, and rollback + +* **View**: Use the list page and the details tabs. +* **Sync**: The Application kebab does not include a **Sync** action. Use the automated, self-heal, and prune toggles on the **Details** tab, the Argo CD UI, the `argocd` CLI, or YAML. +* **Rollback**: The Application kebab does not include a **Rollback** action. Use the **History** tab as a reference, then the Argo CD UI or CLI. For Rollout rollback, see [Rollouts in the GitOps Console](rollouts.md). diff --git a/docs/applicationsets.md b/docs/applicationsets.md new file mode 100644 index 00000000..c9978872 --- /dev/null +++ b/docs/applicationsets.md @@ -0,0 +1,26 @@ +# ApplicationSets in the GitOps Console + +The GitOps Console plugin shows key details of Argo CD ApplicationSets. You can view and create ApplicationSets directly from the OpenShift Container Platform web console. A graphical view shows the applications managed by an ApplicationSet and the progressive sync flow from one step to the next. + +## List page + +The ApplicationSets list page follows the same list patterns as other custom resources: + +* **Table columns**: Standard columns for custom resources +* **Filtering**: Filter ApplicationSets by health status (Healthy, Error, Unknown) +* **Pagination**: After filters and search, browse results in pages of 10, 20, 50, or 100 items (default 50). See [Filter and paginate resources](filter-resources.md). +* **Create action**: Click **Create ApplicationSet** to open the YAML editor with a default ApplicationSet template + +> **NOTE** +> +> Creation uses the YAML editor. The console does not provide an ApplicationSet form wizard. + +## Details page + +The ApplicationSet details page provides the following tabs: + +* **Details tab**: Displays status information, generator counts, conditions, links to the Generators and Applications tabs, and shows the number of generated applications of related Applications. +* **YAML tab**: Provides a live manifest editor for the ApplicationSet resource. +* **Generators tab**: Provides a structured view of generator configuration, including list, merge, and union generators. +* **Applications tab**: Displays the list of applications generated by the ApplicationSet with a Graphical View showing visual representation of the generated applications, progressive sync visualization that shows the progressive sync flow from step to step when progressive sync is enabled, a filter widget to filter by health and sync status, and an applications table with the same rich columns, filtering, and pagination as the main Application list page. +* **Events tab**: Shows Kubernetes events for the ApplicationSet object. diff --git a/docs/appprojects-rbac.md b/docs/appprojects-rbac.md new file mode 100644 index 00000000..9e4264c1 --- /dev/null +++ b/docs/appprojects-rbac.md @@ -0,0 +1,38 @@ +# AppProjects in the GitOps Console + +The GitOps Console plugin provides summary details for Argo CD AppProjects. You can view and create project-scoped AppProjects directly from the OpenShift web console. + +## List page + +The AppProjects list page displays all project-scoped AppProjects with the following features: + +* **Table columns**: Standard columns for custom resources +* **Filtering**: Filter projects by Description, Applications, Project Type, Source Repositories, and Destinations +* **Pagination**: After filters and search, browse results in pages of 10, 20, 50, or 100 items (default 50). See [Filter and paginate resources](filter-resources.md). +* **Create action**: Click **Create AppProject** to open the YAML editor with a default AppProject template + +## Details page + +The AppProject details page provides the following tabs: + +* **Details tab**: Displays project summary, destinations, policies, and related metadata. +* **YAML tab**: Provides a live manifest editor for the AppProject resource. +* **Allow/Deny tab**: Displays resource allow and deny lists for cluster-scoped and namespace-scoped kinds. +* **Applications tab**: Shows Applications that belong to this project. The table provides the same experience as the main Application list, including filtering and pagination, scoped to this project. +* **Roles tab**: Displays Argo CD project roles and bindings in a paginated table. See [Filter and paginate resources](filter-resources.md). +* **Sync Windows tab**: Shows configured sync windows for the project in a paginated table. +* **Events tab**: Shows Kubernetes events for the AppProject object. + +## Mapping OpenShift RBAC to AppProject permissions + +OpenShift role-based access control (RBAC) and Argo CD AppProject rules both apply. + +OpenShift RBAC determines whether a user can get, list, create, update, patch, or delete GitOps custom resources in a namespace. The plugin uses Console access reviews. Without update permission, edit actions and sync-policy toggles are disabled. Without delete permission, delete is disabled. + +AppProject determines which Git repositories, destinations, and resource kinds Argo CD synchronizes. The **Roles** tab shows Argo CD project roles, not OpenShift RoleBindings. + +The plugin does not create OpenShift Roles from AppProject roles. Bind OpenShift users by using RoleBindings. + +* Opening a page requires OpenShift `get` and `list` permissions. +* Saving YAML requires OpenShift `update` permission. +* A successful Argo CD sync requires AppProject destinations, source repositories, and allow or deny lists to permit the resources. diff --git a/docs/assets/README.md b/docs/assets/README.md new file mode 100644 index 00000000..9a1898d2 --- /dev/null +++ b/docs/assets/README.md @@ -0,0 +1,6 @@ +Drop the getting-started demo here: + +* `getting-started-demo.mp4` (preferred), or +* `getting-started-demo.gif` + +Walkthrough to record: OperatorHub → install Red Hat OpenShift GitOps → enable gitops-plugin if needed → Administrator → GitOps and the five list pages. diff --git a/docs/filter-resources.md b/docs/filter-resources.md new file mode 100644 index 00000000..27b3b61a --- /dev/null +++ b/docs/filter-resources.md @@ -0,0 +1,52 @@ +# Filter and paginate resources + +The GitOps Console plugin provides filters to narrow the resource list based on specific properties. Large filtered lists use client-side pagination that matches the OpenShift web console list experience. The available filter options vary by resource type. + +## Prerequisites + +* You have access to the OpenShift web console. +* The GitOps Console plugin is enabled. + +## Filtering + +1. In the OpenShift web console, navigate to **GitOps** and select a resource type. + +2. On the list page, use the available filter controls to narrow the displayed resources. + + The following filters are available depending on the resource type: + + * **Applications**: Filter by health status (Healthy, Progressing, Degraded, Missing) and sync status (Synced, OutOfSync, Unknown). + * **ApplicationSets**: Filter by health status (Healthy, Error, Unknown). + * **AppProjects**: Filter by Description, Applications, Project Type, Source Repositories, and Destinations. + * **ImageUpdaters**: Filter by applications (Has Apps, No Apps) and ready status (Ready, Not Ready). + * **Rollouts**: Filter by rollout status (Healthy, Paused, Progressing, Degraded). + +3. Optional: Combine multiple filters to narrow the results further. + +4. To clear filters, click the **Clear all filters** link or remove individual filter selections. + +## Pagination + +List pages for Applications, ApplicationSets, AppProjects, ImageUpdaters, and Rollouts paginate rows after filters and search are applied. + +Pagination also applies to nested and details tables that use the same shared table: + +* The **Applications** tab on an ApplicationSet details page +* The **Applications** tab on an AppProject details page +* Application details: **Resources** (list view), **Sources**, **Sync Status** (resources last synced), and **History** +* AppProject details: **Roles** and **Sync Windows** +* ImageUpdater details: **Recent Updates** +* Rollout details: **Pods** + +### Behavior + +* **Page size**: Choose **10**, **20**, **50**, or **100** items per page. The default is **50**. There is no **All** option. +* **Controls**: Pagination appears above and below the table when the filtered list contains at least one row. +* **URL state**: The current page and page size are stored in the URL (`page` and `perPage`) so you can refresh or share the view. +* **Reset**: Changing filters, name or label search, or the selected namespace returns you to page 1. Changing the page size or sorting does not reset the page by itself; if the list shrinks, the page is clamped to the last valid page. +* **Client-side only**: Pagination runs in the browser on the already loaded and filtered list. It does not use Kubernetes API `limit` or `continue` tokens. + +## Verification + +* Verify that the resource list displays only items matching your selected filter criteria. +* Verify that the pagination controls show the correct total for the filtered list and that changing the page size updates the table. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..491188c9 --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,53 @@ +# Getting started + +Use the OpenShift web console to install GitOps, enable the Console plugin, and open the GitOps pages. + +## Prerequisites + +* You have access to an OpenShift Container Platform 4.19 or later cluster. +* You can log in to the web console with cluster-admin permission to install the Operator and enable the plugin. + +## Procedure + +### Install the OpenShift GitOps Operator + +1. In the web console, navigate to **Operators** → **OperatorHub**. + +2. In the **Filter by keyword** box, type **Red Hat OpenShift GitOps**. + +3. Click the **Red Hat OpenShift GitOps** tile, then click **Install**. + +4. Keep the default options unless your cluster requires otherwise, then click **Install**. + +5. Wait until **Operators** → **Installed Operators** shows the Operator as **Succeeded**. + +OperatorHub installs the Operator and deploys the Console plugin. You do not download a separate plugin binary. + +### Enable the GitOps Console plugin + +If **GitOps** is already in the navigation, skip this step. Otherwise follow [Enable the GitOps Console plugin](admin-enable-plugin.md). + +### Open the GitOps pages + +1. In the **Administrator** perspective, click **GitOps**. + +2. Verify that you can open the following pages: + + * **Applications** + * **ApplicationSets** + * **AppProjects** + * **ImageUpdaters** + * **Rollouts** + +ImageUpdaters and Rollouts appear when those CRDs are installed on the cluster. + +## Verification + +* After a browser refresh, **GitOps** remains in the navigation. +* You can open each list page and change the namespace. + +## Additional resources + +* [Enable the GitOps Console plugin](admin-enable-plugin.md) +* [Applications](applications.md) +* [Filter and paginate resources](filter-resources.md) diff --git a/docs/image-updaters.md b/docs/image-updaters.md new file mode 100644 index 00000000..c7a0e03b --- /dev/null +++ b/docs/image-updaters.md @@ -0,0 +1,20 @@ +# ImageUpdaters in the GitOps Console + +The GitOps Console plugin shows Argo CD Image Updater custom resources. You can view and create ImageUpdater resources from the OpenShift web console. The **ImageUpdaters** page is available when the ImageUpdater custom resource definition is installed on the cluster. + +## List page + +The ImageUpdaters list page displays ImageUpdater resources with the following features: + +* **Table columns**: name, namespace, applications matched, images managed, last checked, ready, labels, and actions +* **Filtering**: Filter by applications (Has Apps, No Apps) and ready status (Ready, Not Ready) +* **Pagination**: After filters and search, browse results in pages of 10, 20, 50, or 100 items (default 50). See [Filter and paginate resources](filter-resources.md). +* **Create action**: Click **Create ImageUpdater** to open the YAML editor with a starter template + +## Details page + +The ImageUpdater details page provides the following tabs: + +* **Details tab**: Displays ready status, applications matched, images managed, last checked and last updated times, observed generation, and conditions. +* **Recent Updates tab**: Displays updates from the last reconciliation cycle, including alias, image, new version, applications updated, time, and message, in a paginated table. See [Filter and paginate resources](filter-resources.md). +* **YAML tab**: Provides a live manifest editor for the ImageUpdater resource. diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 00000000..8626be98 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,44 @@ + + + + + Working with the GitOps Console plugin + + + + + + +
+ + + + + + diff --git a/docs/release-notes-ga.md b/docs/release-notes-ga.md new file mode 100644 index 00000000..da23a94f --- /dev/null +++ b/docs/release-notes-ga.md @@ -0,0 +1,20 @@ +# 1.22 GA release notes (draft) + +Use this text in the OpenShift GitOps 1.22 release notes and compatibility matrix. Do not include a Technology Preview statement for the Console plugin. + +GitOps Console plugin (General Availability):: +With this update, the GitOps Console plugin is generally available. After you install the Red Hat OpenShift GitOps Operator, you can manage Argo CD and Argo Rollouts resources from the OpenShift web console. This feature requires OpenShift Container Platform 4.19 or later. The plugin is enabled by default. ++ +This feature includes: ++ +* List and details pages for Applications, ApplicationSets, AppProjects, ImageUpdaters, and Rollouts +* Filters for health, sync, and resource-specific status +* Client-side pagination for list pages and details tables (10, 20, 50, or 100 items per page; default 50) after filters and search, with page state in the URL +* Graphical views for Applications and ApplicationSets +* Rollout topology in the OpenShift Console Topology view, including revision rollback +* YAML templates for creating resources +* Links between the OpenShift Console and the Argo CD UI ++ +Known limitations: The Application kebab does not include Sync or Rollback actions. ApplicationSet creation uses YAML, not a form. The Application resource graph shows immediate managed resources, not the full Argo CD tree. Pagination is client-side on the loaded result set and does not use Kubernetes API `limit` or `continue` tokens. + +Support matrix: Technology Preview in 1.21.0. General Availability in 1.22.0. diff --git a/docs/rollouts.md b/docs/rollouts.md new file mode 100644 index 00000000..54575b2f --- /dev/null +++ b/docs/rollouts.md @@ -0,0 +1,35 @@ +# Rollouts in the GitOps Console + +The GitOps Console plugin provides comprehensive details of Argo Rollouts instances in the cluster. You can view and create Rollout resources directly from the OpenShift web console. + +## List page + +The Rollouts list page displays all Argo Rollout resources with the following features: + +* **Table columns**: Standard columns for Rollout resources +* **Filtering**: Filter Rollouts by rollout status (Healthy, Paused, Progressing, Degraded) +* **Pagination**: After filters and search, browse results in pages of 10, 20, 50, or 100 items (default 50). See [Filter and paginate resources](filter-resources.md). +* **Create action**: Click **Create Rollout** to open the YAML editor with a default Rollout template + +## Topology integration + +The OpenShift Console Topology view shows the cluster’s Rollout instances. The Topology view provides: + +* Rollout Details and Overview sidebar tabs with information on the resource +* Context actions for Rollout resources +* Visual decorator on Rollout nodes + +## Details page + +The Rollout details page provides the following tabs: + +* **Details tab**: Displays replicas with inline scale controls when you have the required permissions, rollout status, conditions, strategy-specific sections for Canary or Blue-Green services, a link to open this workload in the Topology view, and related navigation helpers. +* **YAML tab**: Provides a live manifest editor for the Rollout resource. +* **Revisions tab**: Displays ReplicaSet and revision-oriented information for the rollout, including: + * Rollout status and strategy + * Revision history with ReplicaSet details + * Pod status and health + + This view provides the same information as the `oc argo rollouts get rollout` CLI command, including the functionality of the `--watch` option, allowing you to monitor rollout progress directly from the console. **Rollback** is available on a non-current revision when you have patch permission. +* **Pods tab**: Shows pods for the rollout with pod-level actions. The pods table supports filtering, sorting, and pagination. See [Filter and paginate resources](filter-resources.md). +* **Events tab**: Shows Kubernetes events for the Rollout object. diff --git a/docs/theme.css b/docs/theme.css new file mode 100644 index 00000000..14a6349b --- /dev/null +++ b/docs/theme.css @@ -0,0 +1,170 @@ +@import url("https://fonts.googleapis.com/css2?family=Red+Hat+Display:wght@400;700&family=Red+Hat+Text:wght@400;500;700&display=swap"); + +:root { + --theme-color: #0066cc; + --docs-text: #151515; + --docs-muted: #6a6e73; + --docs-border: #d2d2d2; + --docs-sidebar-active: #e7f1fa; + --docs-important: #ee2100; + --docs-note: #4e9fde; + --docs-warning: #ec7a09; +} + +body { + font-family: "Red Hat Text", Helvetica, Arial, sans-serif; + color: var(--docs-text); + background: #fff; +} + +.app-name-link, +.sidebar-nav, +.markdown-section { + font-family: "Red Hat Text", Helvetica, Arial, sans-serif; +} + +.app-name-link { + font-family: "Red Hat Display", Helvetica, Arial, sans-serif; + font-weight: 700; + color: var(--docs-text) !important; +} + +.sidebar { + background: #fff; + border-right: 1px solid var(--docs-border); + padding-top: 1.25rem; +} + +.sidebar ul li a { + color: #151515; + font-size: 14px; + line-height: 1.5; +} + +.sidebar ul li.active > a { + background: var(--docs-sidebar-active); + color: #002952 !important; + font-weight: 700; + border-left: 3px solid var(--theme-color); + padding-left: calc(1rem - 3px); +} + +.search input { + border: 1px solid var(--docs-border); + border-radius: 0; +} + +.markdown-section { + max-width: 52rem; + color: var(--docs-text); + font-size: 16px; + line-height: 1.6; +} + +.markdown-section h1, +.markdown-section h2, +.markdown-section h3 { + font-family: "Red Hat Display", Helvetica, Arial, sans-serif; + font-weight: 700; + color: #151515; + border-bottom: 0; +} + +.markdown-section h1 { + font-size: 2rem; + margin-bottom: 1.25rem; +} + +.markdown-section h2 { + font-size: 1.35rem; + margin-top: 2rem; +} + +.markdown-section strong { + font-weight: 700; +} + +.markdown-section ol { + list-style: decimal; + padding-left: 1.5rem; +} + +.markdown-section ol li { + margin: 0.65rem 0; +} + +.markdown-section ul li { + margin: 0.35rem 0; +} + +.markdown-section table { + border-collapse: collapse; + display: table; + width: 100%; +} + +.markdown-section th, +.markdown-section td { + border: 1px solid var(--docs-border); + padding: 0.5rem 0.75rem; + text-align: left; +} + +.markdown-section th { + background: #f0f0f0; +} + +.markdown-section pre, +.markdown-section code { + font-size: 0.9em; +} + +.markdown-section blockquote { + margin: 1.25rem 0; + padding: 0.85rem 1rem 0.85rem 1.1rem; + color: var(--docs-text); + background: #ee210015; + border: 0; + border-left: 4px solid var(--docs-important); +} + +.markdown-section blockquote p:first-child strong { + display: block; + color: var(--docs-important); + font-size: 0.85rem; + letter-spacing: 0.04em; + margin-bottom: 0.35rem; +} + +.markdown-section blockquote.note { + background: #4e9fde15; + border-left-color: var(--docs-note); +} + +.markdown-section blockquote.note p:first-child strong { + color: #151515; +} + +.markdown-section blockquote.warning { + background: #ec7a0915; + border-left-color: var(--docs-warning); +} + +.page_toc { + font-family: "Red Hat Text", Helvetica, Arial, sans-serif; + font-size: 13px; +} + +.page_toc .title { + font-weight: 700; + text-transform: uppercase; + letter-spacing: 0.04em; + color: var(--docs-muted); + font-size: 12px; +} + +@media (min-width: 1300px) { + .content { + padding-right: 14rem; + } +} diff --git a/docs/topology.md b/docs/topology.md new file mode 100644 index 00000000..c3ff3929 --- /dev/null +++ b/docs/topology.md @@ -0,0 +1,28 @@ +# Topology view + +The GitOps Console plugin includes graphical views for Applications, ApplicationSets, and Rollouts. + +## Application resource graph + +On an Application, open the **Resources** tab. + +The graph and table show immediate managed resources for the Application, not the full Argo CD resource tree. + +* Pan, zoom, and select resources. Status filters apply to both the table and the graph. +* Related resources of the same kind can be grouped or ungrouped. +* Context-menu actions on graph nodes include viewing details, editing labels and annotations, deleting resources, and viewing resources in Argo CD. +* Use the Argo CD link on the tab to open the complete resource hierarchy in the Argo CD UI. + +## ApplicationSet graphical view + +On an ApplicationSet, open the **Applications** tab. The graphical view shows generated applications. When progressive sync is enabled, you can show the progressive sync flow from one step to the next. + +## Rollouts in Developer Topology + +The OpenShift Console Topology view shows Rollout instances: + +* Rollout **Details** and **Overview** sidebar tabs +* Context actions for Rollout resources +* A visual decorator on Rollout nodes + +On a Rollout details page, use the Topology link to open this view. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..2a554796 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,48 @@ +# Troubleshooting + +## Prerequisites + +* You have access to the OpenShift web console. +* The GitOps Console plugin is enabled. + +## Common issues + +**GitOps is missing from the navigation** + +The plugin is disabled, the cluster is older than OpenShift 4.19, or the plugin pods are not running. See [Enable the GitOps Console plugin](admin-enable-plugin.md). Refresh the browser after you enable the plugin. + +**ImageUpdaters or Rollouts is missing** + +Those pages are shown only when the matching CRDs are installed. + +**Empty lists or disabled actions** + +The user lacks OpenShift RBAC on the GitOps custom resources. An AppProject can still block a sync after YAML saves. See [AppProjects](appprojects-rbac.md). + +**Health is Unknown or missing** + +The plugin reads health from the Application CR. Set `controller.resource.health.persist: "true"` in `argocd-cmd-params-cm`. + +**Application stays OutOfSync** + +Check **Sync Status**, **History**, conditions, and **Events**. There is no Application **Sync** button. Use the Argo CD UI, YAML, or the `argocd` CLI. + +**The Application graph looks incomplete** + +The graph shows immediate children only. Open Argo CD for the full tree. See [Topology](topology.md). + +**List pages are slow** + +Filtering and pagination run in the browser on the loaded list. Select a narrower namespace or tighten filters. See [Filter and paginate resources](filter-resources.md). + +**Pagination shows unexpected totals** + +Totals reflect the filtered list, not the full cluster inventory. Clear filters or search, then confirm the namespace selector. + +**ImageUpdater shows no recent updates** + +Nothing was recorded in the last cycle. Check **Ready** and conditions. + +**Rollout Rollback is disabled** + +You selected the current revision, or you cannot `patch` the Rollout. diff --git a/package.json b/package.json index 65393d8b..916aa918 100644 --- a/package.json +++ b/package.json @@ -18,7 +18,8 @@ "lint": "eslint ./src --fix", "test": "jest", "test:update": "jest --updateSnapshot", - "test:coverage": "jest --coverage" + "test:coverage": "jest --coverage", + "serve-docs": "npx --yes docsify-cli serve docs" }, "devDependencies": { "@dagrejs/dagre": "^1.1.8",