Minor tweaks to software catalog docs
Signed-off-by: Tim Hansen <timbonicus@gmail.com>
This commit is contained in:
Tim Hansen
Binary file not shown.
|
Before Width: | Height: | Size: 8.8 KiB After Width: | Height: | Size: 21 KiB |
@@ -6,17 +6,17 @@ description: Documentation on Software Catalog Configuration
|
||||
|
||||
## Processors
|
||||
|
||||
The catalog makes use of so called processors to perform all kinds of ingestion
|
||||
tasks, such as reading raw entity data from a remote source, parsing it,
|
||||
transforming it, and validating it. These processors are configured under the
|
||||
`catalog.processors` key.
|
||||
The catalog has a concept of _processors_ to perform catalog ingestion tasks,
|
||||
such as reading raw entity data from a remote source, parsing it, transforming
|
||||
it, and validating it. These processors are configured under the
|
||||
`catalog.processors` configuration key.
|
||||
|
||||
### Processor: url
|
||||
|
||||
The `url` processor is responsible for fetching entity data from files in any
|
||||
external provider like GitHub, GitLab, Bitbucket, etc. The configuration of this
|
||||
processor lives under the top-level `integrations` key, as it is used by other
|
||||
parts of Backstage too.
|
||||
external provider like GitHub, GitLab, Bitbucket, etc. Unlike other processors,
|
||||
the configuration of this processor lives under the top-level `integrations`
|
||||
key, as it is used by other parts of Backstage too.
|
||||
|
||||
```yaml
|
||||
integrations:
|
||||
|
||||
@@ -35,8 +35,32 @@ we recommend that you name them `catalog-info.yaml`.
|
||||
|
||||
## Overall Shape Of An Entity
|
||||
|
||||
The following is an example of the shape of an entity as returned from the
|
||||
software catalog API.
|
||||
The following is an example of a descriptor file for a Component entity:
|
||||
|
||||
```yaml
|
||||
apiVersion: backstage.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: artist-web
|
||||
description: The place to be, for great artists
|
||||
labels:
|
||||
system: public-websites
|
||||
annotations:
|
||||
example.com/service-discovery: artistweb
|
||||
circleci.com/project-slug: github/example-org/artist-website
|
||||
tags:
|
||||
- java
|
||||
links:
|
||||
- url: https://admin.example-org.com
|
||||
title: Admin Dashboard
|
||||
icon: dashboard
|
||||
spec:
|
||||
type: website
|
||||
lifecycle: production
|
||||
owner: artist-relations-team
|
||||
```
|
||||
|
||||
This is the same entity as returned in JSON from the software catalog API:
|
||||
|
||||
```js
|
||||
{
|
||||
@@ -71,31 +95,6 @@ software catalog API.
|
||||
}
|
||||
```
|
||||
|
||||
The corresponding descriptor file that generated it may look as follows:
|
||||
|
||||
```yaml
|
||||
apiVersion: backstage.io/v1alpha1
|
||||
kind: Component
|
||||
metadata:
|
||||
name: artist-web
|
||||
description: The place to be, for great artists
|
||||
labels:
|
||||
system: public-websites
|
||||
annotations:
|
||||
example.com/service-discovery: artistweb
|
||||
circleci.com/project-slug: github/example-org/artist-website
|
||||
tags:
|
||||
- java
|
||||
links:
|
||||
- url: https://admin.example-org.com
|
||||
title: Admin Dashboard
|
||||
icon: dashboard
|
||||
spec:
|
||||
type: website
|
||||
lifecycle: production
|
||||
owner: artist-relations-team
|
||||
```
|
||||
|
||||
The root fields `apiVersion`, `kind`, `metadata`, and `spec` are part of the
|
||||
_envelope_, defining the overall structure of all kinds of entity. Likewise,
|
||||
some metadata fields like `name`, `labels`, and `annotations` are of special
|
||||
|
||||
@@ -10,8 +10,9 @@ outlined below.
|
||||
|
||||
## Installing @backstage/plugin-catalog
|
||||
|
||||
> **Note that if you used `npx @backstage/create-app`, the plugin may already be
|
||||
> present**
|
||||
> **Note that if you used `npx @backstage/create-app`, the plugin is already
|
||||
> installed and you can skip to
|
||||
> [adding entries to the catalog](#adding-entries-to-the-catalog)**
|
||||
|
||||
The catalog frontend plugin should be installed in your `app` package, which is
|
||||
created as a part of `@backstage/create-app`. To install the package, run:
|
||||
@@ -21,10 +22,6 @@ cd packages/app
|
||||
yarn add @backstage/plugin-catalog
|
||||
```
|
||||
|
||||
Make sure the version of `@backstage/plugin-catalog` matches the version of
|
||||
other `@backstage` packages. You can update it in `packages/app/package.json` if
|
||||
it doesn't.
|
||||
|
||||
### Adding the Plugin to your `packages/app`
|
||||
|
||||
Add the following entry to the head of your `packages/app/src/plugins.ts`:
|
||||
@@ -37,6 +34,7 @@ Next we need to install the two pages that the catalog plugin provides. You can
|
||||
choose any name for these routes, but we recommend the following:
|
||||
|
||||
```tsx
|
||||
// packages/app/src/App.tsx
|
||||
import {
|
||||
catalogPlugin,
|
||||
CatalogIndexPage,
|
||||
@@ -60,6 +58,7 @@ user can create components. In a typical setup the create component route will
|
||||
be linked to the Scaffolder plugin's template index page:
|
||||
|
||||
```ts
|
||||
// packages/app/src/App.tsx
|
||||
import { catalogPlugin } from '@backstage/plugin-catalog';
|
||||
import { scaffolderPlugin } from '@backstage/plugin-scaffolder';
|
||||
|
||||
@@ -76,6 +75,7 @@ const app = createApp({
|
||||
You may also want to add a link to the catalog index page to your sidebar:
|
||||
|
||||
```tsx
|
||||
// packages/app/src/sidebar.tsx
|
||||
import HomeIcon from '@material-ui/icons/Home';
|
||||
|
||||
// Somewhere within the <Sidebar>
|
||||
@@ -88,7 +88,7 @@ This is all that is needed for the frontend part of the Catalog plugin to work!
|
||||
|
||||
Since the catalog plugin currently ships with a sentry plugin `InfoCard`
|
||||
installed by default, you'll need to set `sentry.organization` in your
|
||||
`app-yaml.yaml`. For example:
|
||||
`app-config.yaml`. For example:
|
||||
|
||||
```yaml
|
||||
sentry:
|
||||
@@ -101,8 +101,9 @@ as that will conflict with the catalog routes.
|
||||
|
||||
## Installing @backstage/plugin-catalog-backend
|
||||
|
||||
> **Note that if you used `npx @backstage/create-app`, the plugin may already be
|
||||
> present**
|
||||
> **Note that if you used `npx @backstage/create-app`, the plugin is already
|
||||
> installed and you can skip to
|
||||
> [adding entries to the catalog](#adding-entries-to-the-catalog)**
|
||||
|
||||
The catalog backend should be installed in your `backend` package, which is
|
||||
created as a part of `@backstage/create-app`. To install the package, run:
|
||||
@@ -112,59 +113,12 @@ cd packages/backend
|
||||
yarn add @backstage/plugin-catalog-backend
|
||||
```
|
||||
|
||||
Make sure the version of `@backstage/plugin-catalog-backend` matches the version
|
||||
of other `@backstage` packages. You can update it in
|
||||
`packages/backend/package.json` if it doesn't.
|
||||
|
||||
### Adding the Plugin to your `packages/backend`
|
||||
|
||||
You'll need to add the plugin to the `backend`'s router. You can do this by
|
||||
creating a file called `packages/backend/src/plugins/catalog.ts` with the
|
||||
following contents to get you up and running quickly.
|
||||
|
||||
```ts
|
||||
import {
|
||||
createRouter,
|
||||
DatabaseEntitiesCatalog,
|
||||
DatabaseLocationsCatalog,
|
||||
DatabaseManager,
|
||||
HigherOrderOperations,
|
||||
LocationReaders,
|
||||
runPeriodically,
|
||||
} from '@backstage/plugin-catalog-backend';
|
||||
import { PluginEnvironment } from '../types';
|
||||
import { useHotCleanup } from '@backstage/backend-common';
|
||||
|
||||
export default async function createPlugin({
|
||||
logger,
|
||||
database,
|
||||
}: PluginEnvironment) {
|
||||
const locationReader = new LocationReaders(logger);
|
||||
|
||||
const db = await DatabaseManager.createDatabase(database, { logger });
|
||||
const entitiesCatalog = new DatabaseEntitiesCatalog(db);
|
||||
const locationsCatalog = new DatabaseLocationsCatalog(db);
|
||||
const higherOrderOperation = new HigherOrderOperations(
|
||||
entitiesCatalog,
|
||||
locationsCatalog,
|
||||
locationReader,
|
||||
db,
|
||||
logger,
|
||||
);
|
||||
|
||||
useHotCleanup(
|
||||
module,
|
||||
runPeriodically(() => higherOrderOperation.refreshAllLocations(), 10000),
|
||||
);
|
||||
|
||||
return await createRouter({
|
||||
entitiesCatalog,
|
||||
locationsCatalog,
|
||||
higherOrderOperation,
|
||||
logger,
|
||||
});
|
||||
}
|
||||
```
|
||||
creating a file called `packages/backend/src/plugins/catalog.ts` with contents
|
||||
matching
|
||||
[catalog.ts in the create-app template](https://github.com/backstage/backstage/blob/master/packages/create-app/templates/default-app/packages/backend/src/plugins/catalog.ts).
|
||||
|
||||
Once the `catalog.ts` router setup file is in place, add the router to
|
||||
`packages/backend/src/index.ts`:
|
||||
@@ -174,10 +128,9 @@ import catalog from './plugins/catalog';
|
||||
|
||||
const catalogEnv = useHotMemoize(module, () => createEnv('catalog'));
|
||||
|
||||
const service = createServiceBuilder(module)
|
||||
.loadConfig(configReader)
|
||||
/** several different routers */
|
||||
.addRouter('/catalog', await catalog(catalogEnv));
|
||||
const apiRouter = Router();
|
||||
/** several different routers */
|
||||
apiRouter.use('/catalog', await catalog(catalogEnv));
|
||||
```
|
||||
|
||||
### Adding Entries to the Catalog
|
||||
@@ -192,7 +145,7 @@ our example templates through static configuration. Add the following to the
|
||||
```yaml
|
||||
catalog:
|
||||
locations:
|
||||
# Backstage Example Component
|
||||
# Backstage Example Components
|
||||
- type: url
|
||||
target: https://github.com/backstage/backstage/blob/master/packages/catalog-model/examples/artist-lookup-component.yaml
|
||||
- type: url
|
||||
@@ -217,8 +170,9 @@ Finally, start up the backend with the new configuration:
|
||||
|
||||
```bash
|
||||
cd packages/backend
|
||||
# or `yarn dev` to run both frontend and backend
|
||||
yarn start
|
||||
```
|
||||
|
||||
If you've also set up the frontend plugin, so you should be ready to go browse
|
||||
the catalog at [localhost:3000](http://localhost:3000) now!
|
||||
If you've also set up the frontend plugin, you should be ready to go browse the
|
||||
catalog at [localhost:3000](http://localhost:3000) now!
|
||||
|
||||
@@ -108,8 +108,3 @@ domain would come with some documentation on how to accept payments for a new
|
||||
product or use-case, share the same entity types in their APIs, and integrate
|
||||
well with each other. Other domains could be “Content Ingestion”, “Ads” or
|
||||
“Search”.
|
||||
|
||||
## Links
|
||||
|
||||
- [Original RFC](https://github.com/backstage/backstage/issues/390)
|
||||
- [YAML file format](../../architecture-decisions/adr002-default-catalog-file-format.md)
|
||||
|
||||
@@ -24,10 +24,6 @@ cd packages/app
|
||||
yarn add @backstage/plugin-scaffolder
|
||||
```
|
||||
|
||||
Make sure the version of `@backstage/plugin-scaffolder` matches the version of
|
||||
other `@backstage` packages. You can update it in `packages/app/package.json` if
|
||||
it doesn't.
|
||||
|
||||
### Adding the Plugin to your `packages/app`
|
||||
|
||||
Add the following entry to the head of your `packages/app/src/plugins.ts`:
|
||||
@@ -71,10 +67,6 @@ cd packages/backend
|
||||
yarn add @backstage/plugin-scaffolder-backend
|
||||
```
|
||||
|
||||
Make sure the version of `@backstage/plugin-scaffolder-backend` matches the
|
||||
version of other `@backstage` packages. You can update it in
|
||||
`packages/backend/package.json` if it doesn't.
|
||||
|
||||
### Adding the Plugin to your `packages/backend`
|
||||
|
||||
You'll need to add the plugin to the `backend`'s router. You can do this by
|
||||
|
||||
@@ -265,7 +265,7 @@ The main two that are used are the following:
|
||||
```yaml
|
||||
output:
|
||||
remoteUrl: '{{ steps.publish.output.remoteUrl }}' # link to the remote repository
|
||||
entityRef: '{{ steps.register.output.entityRef }}' # link to the entitiy that has been ingested to the catalog
|
||||
entityRef: '{{ steps.register.output.entityRef }}' # link to the entity that has been ingested to the catalog
|
||||
```
|
||||
|
||||
### The templating syntax
|
||||
|
||||
Reference in New Issue
Block a user