Backend plugin for serving badges to the @backstage-community/plugin-badges
plugin.
Default implementation uses
badge-maker for creating the
badges, in SVG.
Currently, only entity badges are implemented. i.e. badges that may have entity specific information in them, and as such, are served from an entity specific endpoint.
Install the @backstage-community/plugin-badges-backend
package in your backend package:
# From your Backstage root directory
yarn --cwd packages/backend add @backstage-community/plugin-badges-backend
Add the plugin using the following default setup for
src/plugins/badges.ts
:
import {
createRouter,
createDefaultBadgeFactories,
} from '@backstage-community/plugin-badges-backend';
import { Router } from 'express';
import { PluginEnvironment } from '../types';
export default async function createPlugin(
env: PluginEnvironment,
): Promise<Router> {
return await createRouter({
config: env.config,
discovery: env.discovery,
badgeFactories: createDefaultBadgeFactories(),
tokenManager: env.tokenManager,
logger: env.logger,
identity: env.identity,
});
}
The createDefaultBadgeFactories()
returns an object with badge factories to
the badges-backend createRouter()
to forward to the default badge builder. To
customize the available badges, provide a custom set of badge factories. See
further down for an example of a custom badge factories function.
Finally, you have to make the following changes in src/index.ts
:
// 1. import the plugin
import badges from './plugins/badges';
...
const config = await loadBackendConfig({
argv: process.argv,
logger: rootLogger,
});
const createEnv = makeCreateEnv(config);
...
// 2. Create a PluginEnvironment for the Badges plugin
const badgesEnv = useHotMemoize(module, () => createEnv('badges'));
...
const apiRouter = Router();
...
// 3. Register the badges plugin in the router
apiRouter.use('/badges', await badges(badgesEnv));
...
apiRouter.use(notFoundHandler());
The Badges backend plugin has support for the new backend system, here's how you can set that up:
In your packages/backend/src/index.ts
make the following changes:
import { createBackend } from '@backstage/backend-defaults';
const backend = createBackend();
// ... other feature additions
+ backend.add(import('@backstage-community/plugin-badges-backend'));
backend.start();
Badges are created by classes implementing the BadgeBuilder
type. The default
badge builder uses badge factories to turn a BadgeContext
into a Badge
spec
for the badge-maker
to create the SVG image.
A set of default badge factories are defined in badges.ts as examples.
Additional badges may be provided in your application by defining custom badge factories, and provide them to the badge builder.
To provide custom badges, create a badge factories function, and use that when creating the badges backend router.
import type { Badge, BadgeContext, BadgeFactories } from '@backstage-community/plugin-badges-backend';
export const createMyCustomBadgeFactories = (): BadgeFactories => ({
<custom-badge-id>: {
createBadge: (context: BadgeContext): Badge | null => {
// ...
return {
label: 'my-badge',
message: 'custom stuff',
// ...
};
},
},
// optional: include the default badges
// ...createDefaultBadgeFactories(),
});
When you enable the obfuscation feature, the badges backend will obfuscate the entity names in the badge link. It's useful when you want your badges to be visible to the public, but you don't want to expose the entity names and also to protect your entity names from being enumerated.
To enable the obfuscation you need to activate the obfuscation
feature in the app-config.yaml
:
app:
badges:
obfuscate: true
/entity/:entityUuid/:badgeId
endpoint. The other endpoints are meant for trusted internal users and should not be publicly exposed.
Note that you cannot use env vars to set the
obfuscate
value. It must be a boolean value and env vars are always strings.
The badges backend api exposes two main endpoints for entity badges. The
/badges
prefix is arbitrary, and the default for the example backend.
-
/badges/entity/:namespace/:kind/:name/badge-specs
List all defined badges for a particular entity, in json format. See BadgeSpec from the frontend plugin for a type declaration. -
/badges/entity/:namespace/:kind/:name/badge/:badgeId
Get the entity badge as an SVG image. If theaccept
request header prefersapplication/json
the badge spec as JSON will be returned instead of the image.
-
/badges/entity/:namespace/:kind/:name/obfuscated
Get the obfuscatedentity url
.
Note that endpoint have a embedded authMiddleware to authenticate the user requesting this endpoint. It meant to be called from the frontend plugin.
-
/badges/entity/:entityUuid/:badgeId
Get the entity badge as an SVG image. If theaccept
request header prefersapplication/json
the badge spec as JSON will be returned instead of the image. -
/badge/entity/:entityUuid/badge-specs
List all defined badges for a particular entity, in json format. See BadgeSpec from the frontend plugin for a type declaration.