paulononato/backstage
1
0
Fork 0
Code Issues Pull Requests Actions 35 Packages Projects Releases Wiki Activity

docs: add changeset files

Browse Source 
Signed-off-by: Camila Belo <camilaibs@gmail.com>
This commit is contained in:
Camila Belo
2024-02-01 19:28:12 +01:00
parent b75a2d984c
commit 3dc64e931e
6 changed files with 204 additions and 96 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.changeset/mighty-toys-laugh.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-react': minor
---
Add support to `configSchema` option on the `createEntityCardExtension` factory function.
.changeset/neat-eels-greet.md
+5
View File
@@ -0,0 +1,5 @@
---
'@backstage/plugin-catalog-graph': minor
---
Migrate plugin to the new frontend system, it is experimental and available via alpha subpath.
packages/app-next/app-config.yaml
+3 -1
View File
@@ -16,7 +16,9 @@ app:
config:
filter: kind:component has:links
- entity-card:linguist/languages
- entity-card:catalog-graph/entity-relations
- entity-card:catalog-graph/entity-relations:
config:
height: 300
# Entity page content
- entity-content:techdocs
plugins/catalog-graph/EXPERIMENTAL.md
+191 -95
View File
@@ -1,224 +1,320 @@
# catalog-graph
# Catalog Graph
> **Disclaimer:**
> [!WARNING]
> This documentation is made for those using the experimental new Frontend system.
> If you are not using the new Backstage frontend system, please go [here](./README.md).
Welcome to the catalog graph plugin! The catalog graph visualizes the relations
between entities, like ownership, grouping or API relationships.
The Catalog graph plugin helps you to visualize the relations between entities, like ownership, grouping or API relationships.
It comes with these features:
The plugin comes with these features:
- A card that displays the directly related entities to the current entity on the Catalog entity page. It can be customized, for example filtering for specific relations.
- Catalog entity relations graph card:
A card that displays the directly related entities to the current entity.
This card is for use on the entity page.
The card can be customized, for example filtering for specific relations.
<video src='https://user-images.githubusercontent.com/648527/133401912-aaedc36a-b70b-437e-8e5f-2a14b21962f0.mov' width=640>
<img src="./catalog-graph-entity-relations-card.png" width="600" />
- Catalog entity relations graph page:
A standalone page that can be added to your application providing a viewer for your entities and their relations.
The viewer can be used to navigate through the entities and filter for specific relations.
You can access it from the `EntityCatalogGraphCard`.
<video src='https://user-images.githubusercontent.com/648527/133403059-6584e469-23ab-41d2-a9e6-fd691a4e2737.mov' width=640>
- A standalone page that can be added to your application providing a viewer for your entity relations.
This viewer can be used to navigate through the entities and filter for specific relations, you can access it from the card "View Graph" action.
- `EntityRelationsGraph`:
A react component that can be used to build own customized entity relation graphs.
<img src="./catalog-graph-entity-relations-page.png" width="600" />
## Table of Content
- [Installation](#installation)
- [Customization](#customization)
- [Packages](#packages)
- [Routes](#routes)
- [Extensions](#extensions)
- [Catalog entity relations graph card](#catalog-entity-relations-graph-card)
- [Catalog entity relations graph page](#catalog-entity-relations-graph-page)
## Installation
This plugin installation requires the following steps:
> [!Note]
> This plugin only works if you're also using the [catalog](https://backstage.io/docs/features/software-catalog/) plugin, so make sure you've got it installed;
> [!IMPORTANT]
> In addition to installing this plugin, be sure to install the [Catalog](https://backstage.io/docs/features/software-catalog/) plugin, as the Catalog graph extends its capabilities.
1. Add the `@backstage/catalog-graph` dependency to your app `package.json` file and install it;
2. In your application's configuration file, enable the catalog entity relations graphic card extension so that the card begins to be presented on the catalog entity page:
```yaml
# app-config.yaml
app:
experimental:
# Auto discovering all plugins extensions
packages: all
extensions:
# This is required because the card is not enable by default once you install the plugin
- entity-card:catalog-graph/entity-relations
```
3. Then start the app, navigate to an entity's page and see the Relations graph there;
4. By clicking on the 'View Graph' card action, you will be redirected to the catalog entity relations page.
4. By clicking on the "View Graph" card action, you will be redirected to the catalog entity relations page.
## Routes
## Customization
The Catalog Graph plugin exposes routes that can be used to configure route bindings.
This plugin can be customized in two ways: via the `app-config.yaml` file or through code. The following sections will explain to you what kind of configurations are available for use, as well as how you can customize the plugin implementation.
| Key | Type | Description |
| --------------- | -------------- | ------------------------------------------ |
| `catalogGraph` | Regular route | Reference to the Catalog graph page route |
| `catalogEntity` | External route | Reference to the Catalog entity page route |
### Packages
With this, you can optionally associate the entity relations graph page to a different route other than the Catalog plugin's default entity page (for more information about route binding, see [this](https://backstage.io/docs/frontend-system/architecture/routes#binding-external-route-references) documentation).
The features of this plug-in can be discovered automatically as soon as you install it, but you can also configure the plug-in not to be enabled for certain [environments](https://backstage.io/docs/conf/writing/#configuration-files). See the examples below:
_Enabling auto discovering the plugin extensions in production_
```yaml
# example binding the catalog graph entity page
# app-config.production.yaml
# Overriding configurations for the local production environment
app:
experimental:
packages:
# Only the following packages will be included
include:
- '@backstage/plugin-catalog-graph'
```
_Disabling auto discovering the plugin extensions in development_
```yaml
# app-config.local.yaml
# Overriding configurations for the local development environment
app:
experimental:
packages:
# All but the following package will be included
exclude:
- '@backstage/plugin-catalog-graph'
```
For more options of package configurations, see [this](https://backstage.io/docs/frontend-system/architecture/app/#feature-discovery) documentation.
### Routes
The Catalog graph plugin exposes regular and external routes that can be used to configure route bindings.
| Key | Type | Description |
| --------------- | -------------- | --------------------------------------- |
| `catalogGraph` | Regular route | A route ref to the Catalog graph page. |
| `catalogEntity` | External route | A route ref to the Catalog entity page. |
As an example, here is an association between the external entity page and a different route other than the Catalog plugin's default entity page:
```yaml
# app-config.yaml
app:
routes:
bindings:
# example binding the external catalog graph to a regular route
# defaults to catalog.catalogEntity
catalog-graph.catalogEntity: <some-plugin-id>.<some-external-route-key>
catalog-graph.catalogEntity: <some-plugin-id>.<some-regular-route-key>
```
You can also point an external route from another plug-in to the Catalog chart page:
Additionally, it is possible to point a route from another plugin to the Catalog graph page:
```yaml
# app-config.yaml
app:
routes:
bindings:
<some-plugin-id>.<some-external-route-key>: catalog-graph.catalogEntity
# example binding a external route to the catalog graph page
<plugin-id>.<external-route-key>: catalog-graph.catalogGraph
```
## Extensions
Route binding is also possible through code. For more information, see [this](https://backstage.io/docs/frontend-system/architecture/routes#binding-external-route-references) documentation.
This plugin extensions are configurable through the `app-config.yaml` file and its implementation is also replaceable.
### Extensions
### Catalog Entity Relations Graph Card
The Catalog graphics plugin provides extensions for each of its features, see below how to customize these extensions:
A [Entity Card](https://backstage.io/docs/frontend-system/building-plugins/extension-types#entitycard---reference) extension renders the relation graph for a Catalog entity on the Catalog entity page. This extension has an action that redirects users to the Catalog entity's relations graph [page](#catalog-entity-relations-graph-page).
#### Catalog Entity Relations Graph Card
| kind | namespace | name | id |
| ----------- | ------------- | ---------------- | -------------------------------------------- |
| entity-card | catalog-graph | entity-relations | `entity-card:catalog-graph/entity-relations` |
An [entity card](https://backstage.io/docs/frontend-system/building-plugins/extension-types#entitycard---reference) extension that renders the relation graph for an entity on the Catalog entity page and has an action that redirects users to the more advanced [relations graph page](#catalog-entity-relations-graph-page).
#### Output
| kind | namespace | name | id | Default enabled |
| ----------- | ------------- | ---------------- | -------------------------------------------- | --------------- |
| entity-card | catalog-graph | entity-relations | `entity-card:catalog-graph/entity-relations` | No |
##### Output
A React component defined by the [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata/) type.
#### Inputs
##### Inputs
There are no inputs available for this extension.
#### Config
##### Config
The card configurations should be defined under the `app.extensions.entity-card:catalog-graph/entity-relations.config` key:
```yaml
# example configuring the card title
# app-config.yaml
app:
extensions:
# this is the extension id and it follows the naming pattern bellow:
# <extension-kind>/<plugin-namespace>:<extension-name>
- entity-card:catalog-graph/entity-relations:
config:
# example configuring the card title
# defaults to "Relations"
title: 'Entities Relations Graph'
```
See below the complete list of available configs:
| Key | Description | Type | Optional | Default value |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `filter` | A query to filter when to show the card based on the entity metadata, for more details [see](./https://github.com/backstage/backstage/pull/21480). | `string` | yes | - |
| `title` | The card title text. | `string` | yes | `'Relations'` |
| `variant` | The card layout variants. | `flex` \| `fullHeight` \| `gridItem` | yes | `'gridItem'` |
| `height` | The card height fixed size. | `number` | yes | - |
| `rootEntityNames` | A single our multiple compound root entity ref objects. | `{ kind: string, namespace: string, name: string }` \| `{ kind: string, namespace: string, name: string}[]` | yes | Defaults to the entity available in the entity page context |
| `kinds` | List of "kinds" used to filter which entities to show on the graph. | `string[]` | yes | Show all entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format#apiversion-and-kind-required) |
| `relations` | List of "relations" used to filter which entities to show on the graph. | `string[]` | yes | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations) |
| `maxDepth` | Amount of relationship levels. | `number` | yes | `1` |
| `unidirectional` | Shows only unidirectional relations. | `boolean` | yes | `true` |
| `mergeRelations` | Enable merging entity relation pairs. | `boolean` | yes | `true` |
| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` |
| `relationPairs` | A list of pairs of entity relations, used to define which relations are merged together and which the primary relation is. | `string[]` | yes | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations) |
| `zoom` | Controls zoom behavior of graph. | `enabled` \| `disabled` \| `enable-on-click` | yes | `'enabled'` |
| `curve` | A factory name for curve generators addressing both lines and areas. | `curveStepBefore` \| `curveMonotoneX` | yes | `'enable-on-click' ` |
| Key | Description | Type | Optional | Default value |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `filter` | A [text-based query](<(https://github.com/backstage/backstage/pull/21480)>) used to filter whether the extension should be rendered or not. | `string` | yes | - |
| `title` | The card title. text. | `string` | yes | `'Relations'` |
| `variant` | The card layout. variants. | `flex` \| `fullHeight` \| `gridItem` | yes | `'gridItem'` |
| `height` | The card height fixed. size. | `number` | yes | - |
| `rootEntityNames` | A single our multiple compound root entity ref objects. | `{ kind: string, namespace: string, name: string }` \| `{ kind: string, namespace: string, name: string}[]` | yes | Defaults to the entity available in the entity page context. |
| `kinds` | Restricted list of entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) to display in the graph. | `string[]` | yes | - |
| `relations` | Restricted list of entity [relations](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-relations) to display in the graph. | `string[]` | yes | - |
| `maxDepth` | A maximum number of levels of relations to display in the graph. | `number` | yes | `1` |
| `unidirectional` | Shows only relations that from the source to the target entity. | `boolean` | yes | `true` |
| `mergeRelations` | Merge the relations line into a single one. | `boolean` | yes | `true` |
| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` |
| `relationPairs` | A list of [pairs of entity relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations), used to define which relations are merged together and which the primary relation is. | `[string[], string[]]` | yes | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations). |
| `zoom` | Controls zoom behavior of graph. | `enabled` \| `disabled` \| `enable-on-click` | yes | `'enabled'` |
| `curve` | A factory name for curve generators addressing both lines and areas. | `curveStepBefore` \| `curveMonotoneX` | yes | `'enable-on-click' ` |
#### How to override the card extension
##### Disable
There is more than one option on where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides) to learn more about the recommendations.
The card is disabled by default when you install the plugin, but you can prevent future versions from enabling it by adding this configuration:
> [!Warning]
```yaml
# app-config.yaml
app:
extensions:
# this is the extension id and it follows the naming pattern bellow:
# <extension-kind>/<plugin-namespace>:<extension-name>
# example disbaling the graph card extension
- entity-card:catalog-graph/entity-relations: false
```
##### Override
Overriding the card extension allows you to modify how it is implemented.
> [!CAUTION]
> To maintain the same level of configuration, you should define the same or an extended configuration schema.
Here is an example overriding the card extension with a custom component:
```tsx
import { createExtensionOverrides } from '@backstage/backstage-plugin-api';
import { createExtensionOverrides, createSchemaFromZod } from '@backstage/backstage-plugin-api';
import { createEntityCardExtension } from '@backstage/plugin-catalog-react/alpha';
createExtensionOverrides(
export default createExtensionOverrides(
extensions: [
createEntityCardExtension({
// This namespace is necessary so the system knows that this extension will replace the default 'entity-relations' card extension that is provided by the 'catalog-graph' plugin
// These namespace and name are necessary so the system knows that this extension will replace the default 'entity-relations' card extension provided by the 'catalog-graph' plugin
namespace: 'catalog-graph',
name: 'entity-relations',
configSchema: createSchemaFromZod(z => z.object({
filter: z.string().optional(),
// Ommitting the rest of default configs for simplicity in this example
})),
loader: () => import('./components').then(m => <m.MyEntityRelationsCard />)
})
]
);
```
### Catalog Entity Relations Graph Page
For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides).
This page displays a more detailed relation graph for a Catalog entity. It contains a few filters that you can use to narrow down what's displayed.
#### Catalog Entity Relations Graph Page
| kind | namespace | name | id |
| ---- | ------------- | ---- | -------------------- |
| page | catalog-graph | - | `page:catalog-graph` |
A [page](https://backstage.io/docs/reference/frontend-plugin-api.createapiextension) extension that lets you customize the relations displayed for a Catalog entity in the graph viewer using a series of filters.
#### Output
| Kind | Namespace | Name | Id | Default enabled |
| ---- | ------------- | :--: | -------------------- | :-------------: |
| page | catalog-graph | - | `page:catalog-graph` | Yes |
##### Output
A React component defined by the [coreExtensionData.reactElement](https://backstage.io/docs/reference/frontend-plugin-api.coreextensiondata/) type.
#### Inputs
##### Inputs
There are no inputs available for this extension.
#### Config
##### Config
The page configurations should be defined under the `app.extensions.page:catalog-graph.config` key:
```yaml
# example configuring the page path
# app-config.yaml
app:
extensions:
# this is the extension id and it follows the naming pattern bellow:
# <extension-kind>/<plugin-namespace>:<extension-name>
- page:catalog-graph:
config:
# example configuring the page path
# defaults to "/catalog-graph"
path: '/entity-graph'
```
See below the complete list of available configs:
| Key | Description | Type | Optional | Default value |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- |
| `path` | The page route path. | `string` | true | '/catalog-graph' |
| `initialState` | The page initial state. | `{ selectedRelations?: string[],selectedKinds?: string[],rootEntityRefs?: string[],maxDepth?: number,unidirectional?: boolean,mergeRelations?: boolean,direction?: Direction,showFilters?: boolean,curve?: 'curveStepBefore' \| 'curveMonotoneX' }` | true | {} |
| `rootEntityNames` | A single our multiple compound root entity ref objects. | `{ kind: string, namespace: string, name: string }` \| `{ kind: string, namespace: string, name: string}[]` | yes | Defaults to the entity available in the entity page context |
| `kinds` | List of "kinds" used to filter which entities to show on the graph. | `string[]` | yes | Show all entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format#apiversion-and-kind-required) |
| `relations` | List of "relations" used to filter which entities to show on the graph. | `string[]` | yes | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations) |
| `maxDepth` | Amount of relationship levels. | `number` | yes | `1` |
| `unidirectional` | Shows only unidirectional relations. | `boolean` | yes | `true` |
| `mergeRelations` | Enable merging entity relation pairs. | `boolean` | yes | `true` |
| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` |
| `relationPairs` | A list of pairs of entity relations, used to define which relations are merged together and which the primary relation is. | `string[]` | yes | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations) |
| `zoom` | Controls zoom behavior of graph. | `enabled` \| `disabled` \| `enable-on-click` | yes | `'enabled'` |
| `curve` | A factory name for curve generators addressing both lines and areas. | `curveStepBefore` \| `curveMonotoneX` | yes | `'enable-on-click' ` |
| Key | Description | Type | Optional | Default value |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `path` | The page route path. | `string` | true | `'/catalog-graph' ` |
| `initialState` | The page filters initial state. | `{ selectedRelations?: string[],selectedKinds?: string[],rootEntityRefs?: string[],maxDepth?: number,unidirectional?: boolean,mergeRelations?: boolean,direction?: Direction,showFilters?: boolean,curve?: 'curveStepBefore' \| 'curveMonotoneX' }` | true | `{}` |
| `rootEntityNames` | A single our multiple compound root entity ref objects. | `{ kind: string, namespace: string, name: string }` \| `{ kind: string, namespace: string, name: string}[]` | yes | Defaults to the entity available in the entity page .context |
| `kinds` | Restricted list of entity [kinds](https://backstage.io/docs/features/software-catalog/descriptor-format/#contents) to display in the graph. | `string[]` | yes | - |
| `relations` | Restricted list of entity [relations](https://backstage.io/docs/features/software-catalog/descriptor-format/#common-to-all-kinds-relations) to display in the graph. | `string[]` | yes | - |
| `maxDepth` | A maximum number of levels of relations to display in the graph. | `number` | yes | `1` |
| `unidirectional` | Shows only relations that from the source to the target entity. | `boolean` | yes | `true` |
| `mergeRelations` | Merge the relations line into a single one. | `boolean` | yes | `true` |
| `direction` | Render direction of the graph. | `TB` \| `BT` \| `LR` \| `RL` | yes | `'LR'` |
| `relationPairs` | A list of [pairs of entity relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations), used to define which relations are merged together and which the primary relation is. | `[string[], string[]]` | yes | Show all entity [relations](https://backstage.io/docs/features/software-catalog/well-known-relations#relations). |
| `zoom` | Controls zoom behavior of graph. | `enabled` \| `disabled` \| `enable-on-click` | yes | `'enabled'` |
| `curve` | A factory name for curve generators addressing both lines and areas. | `curveStepBefore` \| `curveMonotoneX` | yes | `'enable-on-click' ` |
## How to override the page extension
##### Disable
There is more than one option on where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides) to learn more about the recommendations.
When you install the plugin, the page is automatically enabled, but you can disable it with the following setting:
> [!Warning]
> To maintain the same level of configuration, you should define the same or an extended configuration schema. Also remember to use the same default path so that applications that use the default path still point to the same page and the same route reference to avoid side effects on external plugins that expect this page to be associated with the default route reference.
```yaml
# app-config.yaml
app:
extensions:
# this is the extension id and it follows the naming pattern bellow:
# <extension-kind>/<plugin-namespace>:<extension-name>
# example disbaling the graph page extension
- page:catalog-graph: false
```
##### Override
Overriding the page extension allows you to modify how it is implemented.
> [!CAUTION]
> To maintain the same level of configuration, you need to define the same or an extended configuration schema. In order to avoid side effects on external plugins that expect this page to be associated with the default path and route reference, remember to use the same default path so that applications that use the default path still point to the same page and the same route reference.
Here is example overriding the page extension with a custom component:
```tsx
import { createExtensionOverrides, createPageExtension } from '@backstage/backstage-plugin-api';
import { createExtensionOverrides, createPageExtension, createSchemaFromZod } from '@backstage/backstage-plugin-api';
import { convertLegacyRouteRef } from '@backstage/core-compat-api';
import { catalogGraphRouteRef } from '@backstage/plugin-catalog-graph';
createExtensionOverrides(
export default createExtensionOverrides(
extensions: [
createPageExtension({
// Ommiting name since it is an index page
// This namespace is necessary so the system knows that this extension will replace the default 'entity-relations' card extension that is provided by the 'catalog-graph' plugin
// This namespace is necessary so the system knows that this extension will replace the default 'catalog-graph' page extension
namespace: 'catalog-graph',
defaultPath: '/catalog-graph',
routeRef: convertLegacyRouteRef(catalogGraphRouteRef),
loader: () => import('./components').then(m => <m.MyEntityRelationsPage />)
createSchemaFromZod(z => z.object({
path: z.string().default('/catalog-graph')
// Ommitting the rest of default configs for simplicity in this example
})),
loader: () => import('./components').then(m => <m.CustomEntityRelationsPage />)
})
]
);
```
For more information about where to place extension overrides, see the official [documentation](https://backstage.io/docs/frontend-system/architecture/extension-overrides).
plugins/catalog-graph/catalog-graph-entity-relations-card.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 231 KiB

plugins/catalog-graph/catalog-graph-entity-relations-page.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 155 KiB