Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add a new tab to the EntityPage for the Quarkus console #1154

Closed
wants to merge 3 commits into from
Closed

Add a new tab to the EntityPage for the Quarkus console #1154

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
b1f6b68
Adding a Table of contents to the dynamic-plugins.md file
cmoulliard Apr 3, 2024
e45d965
Add the Quarkus tab. Enhance the documentation
cmoulliard Apr 3, 2024
c0a6adb
Removing the TOC as github viewer proposes one by default
cmoulliard Apr 3, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions packages/app/src/components/catalog/EntityPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -293,6 +293,12 @@ export const entityPage = (
),
})}

{tab({
path: '/quarkus',
title: 'Quarkus',
mountPoint: 'entity.page.quarkus',
})}

{tab({
path: '/topology',
title: 'Topology',
Expand Down
123 changes: 97 additions & 26 deletions showcase-docs/dynamic-plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,36 @@
# Dynamic Plugins support

# Table of Contents

- [Overview](#overview)
- [How it works](#how-it-works)
- [Preparing dynamic plugins for the showcase](#preparing-dynamic-plugins-for-the-showcase)
- [Backend plugins](#backend-plugins)
- [Required code changes](#required-code-changes)
- [Note about the new backend system support](#note-about-the-new-backend-system-support)
- [Exporting the backend plugin as a dynamic plugin package](#exporting-the-backend-plugin-as-a-dynamic-plugin-package)
- [Publishing the dynamic backend plugin package to an NPM registry](#publishing-the-dynamic-backend-plugin-package-to-an-npm-registry)
- [About embedding dependencies in the plugin package](#about-embedding-dependencies-in-the-plugin-package)
- [Wrapping a third-party backend plugin to add dynamic plugin support](#wrapping-a-third-party-backend-plugin-to-add-dynamic-plugin-support)
- [Frontend plugins](#frontend-plugins)
- [Required code changes](#required-code-changes-1)
- [Exporting the plugin as a dynamic plugin package](#exporting-the-plugin-as-a-dynamic-plugin-package)
- [Wrapping a third-party frontend plugin to add dynamic plugin support](#wrapping-a-third-party-frontend-plugin-to-add-dynamic-plugin-support)
- [Installing a dynamic plugin package in the showcase](#installing-a-dynamic-plugin-package-in-the-showcase)
- [Local configuration](#local-configuration)
- [Helm deployment](#helm-deployment)
- [Dynamic plugins included in the Showcase container image](#dynamic-plugins-included-in-the-showcase-container-image)
- [Example of external dynamic backend plugins](#example-of-external-dynamic-backend-plugins)
- [Using a custom NPM registry](#using-a-custom-npm-registry)
- [Air Gapped Environment](#air-gapped-environment)
- [Plugin configuration](#plugin-configuration)
- [Frontend layout configuration](#frontend-layout-configuration)
- [Extend internal library of available icons](#extend-internal-library-of-available-icons)
- [Dynamic routes](#dynamic-routes)
- [Bind to existing plugins](#bind-to-existing-plugins)
- [Using mount points](#using-mount-points)
- [Provide additional Utility APIs](#provide-additional-utility-apis)

## Overview

This document describes how to enable the dynamic plugins feature in the Janus Backstage showcase application.
Expand Down Expand Up @@ -270,14 +301,18 @@ In order to add dynamic plugin support to a third-party front plugin, without to

- Create a `dynamic-plugins-root` folder at the root of the showcase application repository.

- In the `app-config.yaml` file, add the following entry:
- To use the `dynamic` plugins packaged within this project, generate and copy them to the `dynamic-plugins-root` using the following commands:

```yaml
dynamicPlugins:
rootDirectory: dynamic-plugins-root
```bash
yarn tsc
yarn build
yarn export-dynamic
yarn copy-dynamic-plugins ../dynamic-plugins-root
```

- Copy the dynamic plugin package to the `dynamic-plugins-root` folder with the following commands:
**Note**: Review the list of the dynamic plugins copied and keep the ones you need or use all of them !

- Copy your dynamic plugin package(s) to be tested/developed to the `dynamic-plugins-root` folder using the following commands:

```bash
pkg=<local dist-dynamic sub-folder or external package name of the dynamic plugin package>
Expand All @@ -288,10 +323,45 @@ In order to add dynamic plugin support to a third-party front plugin, without to

It will create a sub-folder named after the package name, and containing the dynamic plugin package.

- In the `app-config.local.yaml` file, add the following entry at the end:

```yaml
dynamicPlugins:
rootDirectory: dynamic-plugins-root
```

- Append next to this file the `frontend` [configurations](..%2Fdynamic-plugins.default.yaml) as they are not loaded automatically when backstage runs locally vs on ocp (as packaged within the backstage-showcase image):

```yaml
dynamicPlugins:
rootDirectory: qshift-dynamic-plugins-root
frontend:
# Your plugin config !

# Kubernetes, Topology, Tekton, etc config

# RBAC page in the app-provided Administration page
janus-idp.backstage-plugin-rbac:
dynamicRoutes:
- path: /admin/rbac
module: RbacPlugin
importName: RbacPage
mountPoints:
- mountPoint: admin.page.rbac/cards
module: RbacPlugin
importName: RbacPage
config:
layout:
gridColumn: '1 / -1'
width: 100vw
props:
useHeader: false
```

- Start the showcase application. During the initialization step it should have a log entry similar to the following:

```bash
backstage info loaded dynamic backend plugin '@scope/some-plugin-dynamic' from 'file:///showacase-root/dynamic-plugins-root/scope-some-plugin-dynamic-0.0.1'
backstage info loaded dynamic backend plugin '@scope/some-plugin-dynamic' from 'file:///showcase-root/dynamic-plugins-root/scope-some-plugin-dynamic-0.0.1'
```

### Helm deployment
Expand Down Expand Up @@ -617,26 +687,27 @@ Mount points are defined identifiers available across the applications. These po

The following mount points are available:

| Mount point | Description | Visible even when no plugins are enabled |
| ---------------------------- | ----------------------------------- | -------------------------------------------------------------- |
| `entity.page.overview` | Catalog entity overview page | YES for all entities |
| `entity.page.topology` | Catalog entity "Topology" tab | NO |
| `entity.page.issues` | Catalog entity "Issues" tab | NO |
| `entity.page.pull-requests` | Catalog entity "Pull Requests" tab | NO |
| `entity.page.ci` | Catalog entity "CI" tab | NO |
| `entity.page.cd` | Catalog entity "CD" tab | NO |
| `entity.page.kubernetes` | Catalog entity "Kubernetes" tab | NO |
| `entity.page.image-registry` | Catalog entity "Image Registry" tab | NO |
| `entity.page.monitoring` | Catalog entity "Monitoring" tab | NO |
| `entity.page.lighthouse` | Catalog entity "Lighthouse" tab | NO |
| `entity.page.api` | Catalog entity "API" tab | YES for entity of `kind: Component` and `spec.type: 'service'` |
| `entity.page.dependencies` | Catalog entity "Dependencies" tab | YES for entity of `kind: Component` |
| `entity.page.docs` | Catalog entity "Documentation" tab | YES for entity that satisfies `isTechDocsAvailable` |
| `entity.page.definition` | Catalog entity "Definitions" tab | YES for entity of `kind: Api` |
| `entity.page.diagram` | Catalog entity "Diagram" tab | YES for entity of `kind: System` |
| `search.page.types` | Search result type | YES, default catalog search type is available |
| `search.page.filters` | Search filters | YES, default catalog kind and lifecycle filters are visible |
| `search.page.results` | Search results content | YES, default catalog search is present |
| Mount point | Description | Visible even when no plugins are enabled |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `entity.page.overview` | Catalog entity overview page | YES for all entities |
| `entity.page.topology` | Catalog entity "Topology" tab | NO |
| `entity.page.quarkus` | Catalog entity "[Quarkus](https://github.com/q-shift/backstage-plugins/?tab=readme-ov-file#quarkus-console)" tab | NO |
| `entity.page.issues` | Catalog entity "Issues" tab | NO |
| `entity.page.pull-requests` | Catalog entity "Pull Requests" tab | NO |
| `entity.page.ci` | Catalog entity "CI" tab | NO |
| `entity.page.cd` | Catalog entity "CD" tab | NO |
| `entity.page.kubernetes` | Catalog entity "Kubernetes" tab | NO |
| `entity.page.image-registry` | Catalog entity "Image Registry" tab | NO |
| `entity.page.monitoring` | Catalog entity "Monitoring" tab | NO |
| `entity.page.lighthouse` | Catalog entity "Lighthouse" tab | NO |
| `entity.page.api` | Catalog entity "API" tab | YES for entity of `kind: Component` and `spec.type: 'service'` |
| `entity.page.dependencies` | Catalog entity "Dependencies" tab | YES for entity of `kind: Component` |
| `entity.page.docs` | Catalog entity "Documentation" tab | YES for entity that satisfies `isTechDocsAvailable` |
| `entity.page.definition` | Catalog entity "Definitions" tab | YES for entity of `kind: Api` |
| `entity.page.diagram` | Catalog entity "Diagram" tab | YES for entity of `kind: System` |
| `search.page.types` | Search result type | YES, default catalog search type is available |
| `search.page.filters` | Search filters | YES, default catalog kind and lifecycle filters are visible |
| `search.page.results` | Search results content | YES, default catalog search is present |

Note: Mount points within Catalog aka `entity.page.*` are rendered as tabs. They become visible only if at least one plugin contributes to them or they can render static content (see column 3 in previous table).

Expand Down